Set gemspec metadata
Update links to use code.deeden.co.uk
Add a more detailed usage example
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:
gem 'indieauth-token-verification'
And then execute:
$ bundle
Or install it yourself as:
$ gem install indieauth-token-verification
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.
# 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 MissingTokenEndpointError
and MissingDomainError
mentioned above, there are other errors which will be raised in certain circumstances...
IndieAuth::TokenVerification::AccessTokenMissingError
- when the access token is missingIndieAuth::TokenVerification::ForbiddenUserError
- when the token endpoint reports an errorIndieAuth::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 tokenThe 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 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.
The gem is available as open source under the terms of the MIT License.
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.