Verify an IndieAuth access token against a token endpoint, ensuring that the scope required is one of those associated with the token.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install indieauth-token-verification
Use of the gem requires two environment variables to be specified,
TOKEN_ENDPOINT specifies the token endpoint to be used to validate the access token. Failure to specify
TOKEN_ENDPOINT will result in a
IndieAuth::TokenVerification::MissingTokenEndpointError error being raised.
DOMAIN specifies the domain we expect to see in the response from the validated token. It should match that specified when the token was first generated. Failure to specify
DOMAIN will result in a
IndieAuth::TokenVerification::MissingDomainError error being raised.
# Verify the provided access token, with no scope requirement IndieAuth::TokenVerification.new(access_token).verify # Verify the provided access token, requiring a particular scope IndieAuth::TokenVerification.new(access_token).verify("media")
As well as
MissingDomainError mentioned above, there are other errors which will be raised in certain circumstances...
IndieAuth::TokenVerification::AccessTokenMissingError- when the access token is missing
IndieAuth::TokenVerification::ForbiddenUserError- when the token endpoint reports an error
IndieAuth::TokenVerification::IncorrectMeError- when the
mevalue in the response does not match the
IndieAuth::TokenVerification::InsufficentScopeError- when the scope requested is not granted by the access token
The following is a more detailed example of how the gem could be used. This example comes from a project that is actually making use of the gem in production. Most of the code involves dealing with the various errors raised by the gem and ensuring that errors are sent back with the appropriate status and error codes.
send_error (which isn't defined here) returns a JSON response with the appropriate data and halts execution.
def verify_token(scope = nil) access_token = request.env['HTTP_AUTHORIZATION'] || params['access_token'] || '' IndieAuth::TokenVerification.new(access_token).verify(scope) rescue IndieAuth::TokenVerification::AccessTokenMissingError send_error(status: 401, error: 'unauthorized', description: 'Access token missing or empty') rescue IndieAuth::TokenVerification::MissingDomainError send_error(status: 400, error: 'invalid_request', description: 'DOMAIN is not specified') rescue IndieAuth::TokenVerification::MissingTokenEndpointError send_error(status: 400, error: 'invalid_request', description: 'TOKEN_ENDPOINT is not specified') rescue IndieAuth::TokenVerification::ForbiddenUserError send_error(status: 403, error: 'forbidden', description: 'User does not have permission') rescue IndieAuth::TokenVerification::IncorrectMeError send_error(status: 401, error: 'insufficient_scope', description: 'The "me" value does not match the expected DOMAIN') rescue IndieAuth::TokenVerification::InsufficentScopeError send_error(status: 401, error: 'insufficient_scope', description: 'The scope of this token does not meet the requirements for this request') end
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/srushe/indieauth-token-verification. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.