indieauth-token-verification

IndieAuth::TokenVerification

Verify an IndieAuth access token against a token endpoint, ensuring that the scope required is one of those associated with the token.

Installation

Add this line to your application's Gemfile:

gem 'indieauth-token-verification'

And then execute:

$ bundle

Or install it yourself as:

$ gem install indieauth-token-verification

Configuration

Use of the gem requires two environment variables to be specified, TOKEN_ENDPOINT, and DOMAIN.

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.

Usage

# 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")

Errors

As well as MissingTokenEndpointError and 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 me value in the response does not match the DOMAIN
• IndieAuth::TokenVerification::InsufficentScopeError - when the scope requested is not granted by the access token

A more detailed usage example

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

Development

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.

Contributing

Bug reports can be added at https://code.deeden.co.uk/indieauth-token-verification/issues, while patches are welcome at https://code.deeden.co.uk/indieauth-token-verification/patches.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

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.