Update user documentation (#121)

* Add text about new `token_auth`/`access_control` decorators.
* Add info about Client Credentials Grant support.

Author: infohash

README.md

@@ -6,9 +6,10 @@
 
 This Flask extension provides simple OpenID Connect authentication, backed by [pyoidc](https://github.com/rohe/pyoidc).
 
-["Authorization Code Flow"](http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth), as well as
-["Implicit Flow"](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth) and 
-["Hybrid Flow"](https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth), is supported.
+["Authorization Code Flow"](http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth),
+["Implicit Flow"](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth),
+["Hybrid Flow"](https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth),
+["Client Credentials Flow"](https://oauth.net/2/grant-types/client-credentials/) are supported.
 
 ## Getting started
 Read [the documentation](https://flask-pyoidc.readthedocs.io/) or have a look at the

docs/conf.py

@@ -55,4 +55,3 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-

docs/configuration.md

@@ -1,50 +1,93 @@
 # Configuration
 
-## Provider and client configuration
+Both static and dynamic provider configuration discovery, as well as static and dynamic client registration, is
+supported. The different modes of provider configuration can be combined with any of the client registration modes.
 
-Both static and dynamic provider configuration discovery, as well as static
-and dynamic client registration, is supported. The different modes of provider configuration can be combined with any
-of the client registration modes.
+## Client Configuration
 
-### Provider configuration
+### Static Client Registration
 
-#### Dynamic provider configuration
+If you have already registered a client with the provider, specify the client credentials directly:
+```python
+from flask_pyoidc.provider_configuration import ProviderConfiguration, ClientMetadata
+
+client_metadata = ClientMetadata(client_id='client1', client_secret='secret1')
+```
+
+**Note: The redirect URIs registered with the provider MUST include the URI specified in
+[`OIDC_REDIRECT_URI`](#flask-configuration).**
+
+
+### Dynamic Client Registration
+
+To dynamically register a new client for your application, the required client registration info can be specified:
+
+```python
+from flask_pyoidc.provider_configuration import ProviderConfiguration, ClientRegistrationInfo
+
+client_registration_info = ClientRegistrationInfo(client_name='Test App', contacts=['[email protected]'])
+```
+
+## Provider configuration
+
+### Dynamic provider configuration
 
 To use a provider which supports dynamic discovery it suffices to specify the issuer URL:
 ```python
 from flask_pyoidc.provider_configuration import ProviderConfiguration
 
-config = ProviderConfiguration(issuer='https://op.example.com', [client configuration])
+# If you are using Static Client Configuration, then specify client_metadata
+# as shown above.
+provider_config = ProviderConfiguration(issuer='https://idp.example.com',
+                                        client_metadata=client_metadata)
+
+# If you are using Dynamic Client Registration, then specify
+# client_registration_info as shown above.
+provider_config = ProviderConfiguration(issuer='https://idp.example.com',
+                                        client_registration_info=client_registration_info)
 ```
 
-#### Static provider configuration
+### Static provider configuration
 
 To use a provider not supporting dynamic discovery, the static provider metadata can be specified:
 ```python
 from flask_pyoidc.provider_configuration import ProviderConfiguration, ProviderMetadata
 
-provider_metadata = ProviderMetadata(issuer='https://op.example.com',
-                                     authorization_endpoint='https://op.example.com/auth',
-                                     jwks_uri='https://op.example.com/jwks',
-                                     userinfo_endpoint='https://op.example.com/userinfo')
-config = ProviderConfiguration(provider_metadata=provider_metadata, [client configuration])
+provider_metadata = ProviderMetadata(issuer='https://idp.example.com',
+                                     authorization_endpoint='https://idp.example.com/auth',
+                                     token_endpoint='https://idp.example.com/token',
+                                     introspection_endpoint='https://idp.example.com/introspect',
+                                     userinfo_endpoint='https://idp.example.com/userinfo',
+                                     end_session_endpoint='https://idp.example.com/logout',
+                                     jwks_uri='https://idp.example.com/certs',
+                                     registration_endpoint='https://idp.example.com/registration'
+                                     )
+# As shown earlier, if you are using Static Client Configuration, then specify
+# client_metadata.
+provider_config = ProviderConfiguration(provider_metadata=provider_metadata,
+                                        client_metadata=client_metadata)
+
+# If you are using Dynamic Client Registration, then specify
+# client_registration_info.
+provider_config = ProviderConfiguration(provider_metadata=provider_metadata,
+                                        client_registration_info=client_registration_info)
 ```
 
 See the OpenID Connect specification for more information about the
 [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
 
-As mentioned in OpenID Connect specification, `userinfo_endpoint` is optional. If it's
-not provided, no userinfo request will be done and `flask_pyoidc.UserSession.userinfo` will be set to `None`.  
+As mentioned in OpenID Connect specification, `userinfo_endpoint` is optional. If it's not provided, no userinfo
+request will be done and `flask_pyoidc.UserSession.userinfo` will be set to `None`.  
 
-#### Customizing authentication request parameters
+### Customizing authentication request parameters
 To customize the [authentication request parameters](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest),
 use `auth_request_params` in `ProviderConfiguration`:
 ```python
 auth_params = {'scope': ['openid', 'profile']} # specify the scope to request
-config = ProviderConfiguration([provider/client config], auth_request_params=auth_params)
+provider_config = ProviderConfiguration([provider/client config], auth_request_params=auth_params)
 ```
 
-#### Session refresh
+### Session refresh
 
 If your provider supports the `prompt=none` authentication request parameter, this extension can automatically refresh
 user sessions. This ensures that the user attributes (OIDC claims, user being active, etc.) are kept up-to-date without
@@ -53,43 +96,36 @@ refreshes:
 ```python
 from flask_pyoidc.provider_configuration import ProviderConfiguration
 
-config = ProviderConfiguration(session_refresh_interval_seconds=1800, [provider/client config])
+provier_config = ProviderConfiguration(session_refresh_interval_seconds=1800, [provider/client config])
 ```
 
 **Note: The user will still be logged out when the session expires (as set in the Flask session configuration).**
 
-### Client configuration
-
-#### Static client registration
+## Client Credentials Flow
+The [Client Credentials](https://tools.ietf.org/html/rfc6749#section-4.4) grant type is used by clients to obtain an access token outside of the context of a user.
 
-If you have already registered a client with the provider, specify the client credentials directly:
-```python
-from flask_pyoidc.provider_configuration import ProviderConfiguration, ClientMetadata
+This is typically used by clients to access resources about themselves rather than to access a user's resources.
 
-client_metadata = ClientMetadata(client_id='cl41ekfb9j', client_secret='m1C659wLipXfUUR50jlZ')
-config = ProviderConfiguration([provider configuration], client_metadata=client_metadata)
-```
-
-**Note: The redirect URIs registered with the provider MUST include the URI specified in 
-[`OIDC_REDIRECT_URI`](#flask-configuration).**
-
-#### Dynamic client registration
-
-To dynamically register a new client for your application, the required client registration info can be specified:
+Client can obtain access token by using `client_credentials_grant`.
 
 ```python
-from flask_pyoidc.provider_configuration import ProviderConfiguration, ClientRegistrationInfo
+auth = OIDCAuthentication({'default': provider_config}, app)
 
-client_registration_info = ClientRegistrationInfo(client_name='Test App', contacts=['[email protected]'])
-config = ProviderConfiguration([provider configuration], client_registration_info=client_registration_info)
+client_credentials_response = auth.clients['default'].client_credentials_grant()
+access_token = resp.get('access_token')
 ```
 
+Use the obtained `access_token` to access your web service APIs.
+If your API endpoints are protected with `@auth.token_auth` or
+`@auth.access_control`, `access_token` will be verfied by token introspection
+before allowing access.
+
 ## Flask configuration
 
 The application using this extension **MUST** set the following configuration parameters:
 
-* `SECRET_KEY`: This extension relies on [Flask sessions](http://flask.pocoo.org/docs/quickstart/#sessions), which
-   requires [`SECRET_KEY`](http://flask.pocoo.org/docs/config/#builtin-configuration-values).
+* `SECRET_KEY`: This extension relies on [Flask sessions](https://flask.palletsprojects.com/en/2.0.x/quickstart/#sessions), which
+   requires [`SECRET_KEY`](https://flask.palletsprojects.com/en/2.0.x/config/#builtin-configuration-values).
 * `OIDC_REDIRECT_URI`: The URI used as redirect URI to receive authentication responses. This extension will add a url
    rule to handle all requests to the specified endpoint, so make sure the domain correctly points to your app and that
    the URL path is not already used in the app.
@@ -98,9 +134,9 @@ This extension also uses the following configuration parameters:
 * `OIDC_SESSION_PERMANENT`: If set to `True` (which is the default) the user session will be kept until the configured
   session lifetime (see below). If set to `False` the session will be deleted when the user closes the browser.
 * `PERMANENT_SESSION_LIFETIME`: Control how long a user session is valid, see
-  [Flask documentation](http://flask.pocoo.org/docs/1.0/config/#PERMANENT_SESSION_LIFETIME) for more information.
+  [Flask documentation](https://flask.palletsprojects.com/en/2.0.x/config/#PERMANENT_SESSION_LIFETIME) for more information.
 
-#### Legacy configuration parameters
+### Legacy configuration parameters
 The following parameters have been deprecated:
 * `OIDC_REDIRECT_DOMAIN`: Set the domain (which may contain port number) used in the redirect_uri to receive
   authentication responses. Defaults to the `SERVER_NAME` configured for Flask.

docs/quickstart.md

@@ -1,6 +1,5 @@
 # Quickstart
 
-To add authentication to one of your endpoints use the `oidc_auth` decorator:
 ```python
 import flask
 from flask import Flask, jsonify
@@ -14,20 +13,35 @@ app.config.update(
     OIDC_REDIRECT_URI = 'https://example.com/redirect_uri',
     SECRET_KEY = ...
 )
-config = ProviderConfiguration(...)
-auth = OIDCAuthentication({'default': config}, app)
 
-@app.route('/login')
-@auth.oidc_auth('default')
-def index():
-    user_session = UserSession(flask.session)
-    return jsonify(access_token=user_session.access_token,
-                   id_token=user_session.id_token,
-                   userinfo=user_session.userinfo)
+# Static Client Registration
+# If you have already registered a client with the provider, specify the client
+# credentials directly:
+client_metadata = ClientMetadata(
+    client_id='client1',
+    client_secret='secret1',
+    post_logout_redirect_uris=['https://example.com/logout'])
+
+# Static provider configuration
+# To use a provider not supporting dynamic discovery, the static provider
+# metadata can be specified:
+provider_metadata = ProviderMetadata(
+    issuer='https://idp.example.com',
+    authorization_endpoint='https://idp.example.com/auth',
+    token_endpoint='https://idp.example.com/token',
+    introspection_endpoint='https://idp.example.com/introspect',
+    userinfo_endpoint='https://idp.example.com/userinfo',
+    end_session_endpoint='https://idp.example.com/logout',
+    jwks_uri='https://idp.example.com/certs',
+    registration_endpoint='https://idp.example.com/registration')
+
+provider_config = ProviderConfiguration(provider_metadata=provider_metadata,
+                                        client_metadata=client_metadata)
+
+auth = OIDCAuthentication({'default': provider_config}, app)
 ```
 
-You can also use a Flask application factory:
-
+You can also use Flask application factory:
 ```python
 config = ProviderConfiguration(...)
 auth = OIDCAuthentication({'default': config})
@@ -42,6 +56,86 @@ def create_app():
     return app
 ```
 
+## OIDC
+
+To add authentication to your endpoints use the `oidc_auth` decorator:
+```python
+@app.route('/api')
+@auth.oidc_auth('default')
+def index():
+    user_session = UserSession(flask.session)
+    return jsonify(access_token=user_session.access_token,
+                   id_token=user_session.id_token,
+                   userinfo=user_session.userinfo)
+```
+
+## Token Based Authorization
+
+To add token based authorization to your endpoints use the `token_auth`
+decorator. It allows you to call your endpoint with curl and REST API clients
+given "Authorization Bearer <access_token>" field is present in the request
+header. Token based authorization is backed by token introspection so ensure
+that Identity Provider's introspection endpoint is provided.
+```python
+provider_metadata = ProviderMetadata(
+    ...,
+    introspection_endpoint='https://idp.example.com/introspect',
+    ...)
+
+@app.route('/api')
+@auth.token_auth('default')
+def index():
+    current_token_identity = auth.current_token_identity
+    ...
+
+# Optionally, you can specify scopes required by your endpoint.
+@app.route('/api')
+@auth.token_auth('default',
+                 scopes_required=['read', 'write'])
+def index():
+    current_token_identity = auth.current_token_identity
+    ...
+```
+To obtain information about the token, use `auth.current_token_identity` inside
+your endpoint. `current_token_identity` persists for current request only.
+
+## OIDC & Token Based Authorization
+
+If you want to apply both oidc based authentication and token based
+authorization on your endpoint, you can use `access_control` decorator.
+```python
+# If you are using Static Provider Configuration, add introspection_endpoint
+# in ProviderMetadata.
+provider_metadata = ProviderMetadata(
+    ...,
+    introspection_endpoint='https://idp.example.com/introspect',
+    ...)
+
+@app.route('/api')
+@auth.access_control('default')
+def index():
+    current_identity = None
+    if auth.current_token_identity:
+        current_identity = auth.current_token_identity
+    else:
+        current_identity = UserSession(flask.session)
+    ...
+
+# Optionally, you can specify scopes required by your endpoint.
+@app.route('/api')
+@auth.access_control('default',
+                     scopes_required=['read', 'write'])
+def index():
+    current_identity = None
+    if auth.current_token_identity:
+        current_identity = auth.current_token_identity
+    else:
+        current_identity = UserSession(flask.session)
+    ...
+```
+
+---
+
 After a successful login, this extension will place three things in the user session (if they are received from the
 provider):
 * [ID Token](http://openid.net/specs/openid-connect-core-1_0.html#IDToken)
@@ -56,25 +150,17 @@ In addition to this documentation, you may have a look on a
 To allow users to login with multiple different providers, configure all of them in the `OIDCAuthentication`
 constructor and specify which one to use by name for each endpoint:
 ```python
-from flask_pyoidc import OIDCAuthentication
-from flask_pyoidc.provider_configuration import ProviderConfiguration
-
-app = Flask(__name__)
-app.config.update(
-    OIDC_REDIRECT_URI = 'https://example.com/redirect_uri',
-    SECRET_KEY = ...
-)
 auth = OIDCAuthentication({'provider1': ProviderConfiguration(...), 'provider2': ProviderConfiguration(...)}, app)
 
 @app.route('/login1')
 @auth.oidc_auth('provider1')
 def login1():
-    pass
+    ...
 
 @app.route('/login2')
 @auth.oidc_auth('provider2')
 def login2():
-    pass
+    ...
 ```
 
 ## User logout
@@ -84,11 +170,11 @@ To support user logout, use the `oidc_logout` decorator:
 @app.route('/logout')
 @auth.oidc_logout
 def logout():
-    return 'You\'ve been successfully logged out!'
+    return "You've been successfully logged out!"
 ```
 
 If the logout view is mounted under a custom endpoint (other than the default, which is 
-[the name of the view function](http://flask.pocoo.org/docs/1.0/api/#flask.Flask.route)), or if using Blueprints, you
+[the name of the view function](https://flask.palletsprojects.com/en/2.0.x/api/#flask.Flask.route)), or if using Blueprints, you
 must specify the full URL in the Flask-pyoidc configuration using `post_logout_redirect_uris`:
 ```python
 ClientMetadata(..., post_logout_redirect_uris=['https://example.com/post_logout']) # if using static client registration