Usage¶
Invenio module that implements OAuth 2 server.
Protecting your REST API with authentication¶
If you want to have your REST API endpoints protected using OAuth you
should register their blueprint inside the API app
(InvenioOAuth2ServerREST) which by default includes a before_request
hook.
This hook will, if there is an OAuth token, verify it and set the current user
accordingly. It is important to highlight that this configuration allows
either authenticated clients or anonymous clients.
In case you need to allow access to a resource only for authenticated clients, you should use the require_api_auth decorator which requires OAuth2 login:
@app.route('/api/resource', methods=['GET'])
@require_api_auth()
def index():
return 'Protected resource'
However, protecting your resources only with authentication is not
recommended. Instead, you should add an extra layer using always
scopes. This is because,
basically, any client that owns a token has control over every user resource.
Therefore, using scopes gives a fine-grain control. Here an example using
the default email_scope
:
from invenio_oauth2server.scopes import email_scope
from flask_login import current_user
@app.route('/api/email', methods=['GET'])
@require_api_auth()
@require_oauth_scopes(email_scope.id_)
def index():
return current_user.email
Delegating rights via scopes¶
As mentioned before, the recommended way to protect your endpoints is to use fine-grain control with scopes. Invenio-OAuth2Server offers the possibility to create new ones:
from invenio_oauth2server.models import Scope
homepage_read = Scope('homepage:read',
help_text='Access to the homepage',
group='test')
Next, you should add them to setup.py
entrypoints so they get initialized
at start up:
setup(
...
entry_points={
'invenio_oauth2server.scopes': [
'homepage_read = path.to.scopes.file:homepage_read',
]
}
...
)
And then, they can be used in your application:
from path.to.scopes.file import homepage_read
@app.route('/', methods=['GET'])
@require_api_auth()
@require_oauth_scopes(homepage_read.id_)
def index():
return 'Front page content.'
So, finally, with this example, we would allow any authenticated client with
rights to use the homepage_scope
to read the homepage but, prevent from
reading the email if they do not have rights for using the email_scope
.
To test this features you can build your own application or use the provided example app as boilerplate.
Access control¶
It is important to remember that the usage of authentication and scopes is not enough in most of the cases so access control need to be configured as well. For more information about access control in Invenio you can visit Invenio-Access documentation.