From ab0de9e28db812eb204f12335b07d91361b16676 Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Mon, 28 Oct 2019 16:10:22 +0100 Subject: Improved OIDC documentation --- docs/oauth2/oidc.rst | 17 +++++---- docs/oauth2/oidc/authcode.rst | 6 ++++ docs/oauth2/oidc/dispatchers.rst | 24 +++++++++++++ docs/oauth2/oidc/endpoints.rst | 21 +++++++++++ docs/oauth2/oidc/grants.rst | 41 ++++++++++++++++++++++ docs/oauth2/oidc/hybrid.rst | 6 ++++ docs/oauth2/oidc/implicit.rst | 6 ++++ docs/oauth2/oidc/userinfo.rst | 7 ++++ docs/oauth2/oidc/validator.rst | 33 ++++++++++++----- .../openid/connect/core/grant_types/dispatchers.py | 17 ++++++--- 10 files changed, 160 insertions(+), 18 deletions(-) create mode 100644 docs/oauth2/oidc/authcode.rst create mode 100644 docs/oauth2/oidc/dispatchers.rst create mode 100644 docs/oauth2/oidc/endpoints.rst create mode 100644 docs/oauth2/oidc/grants.rst create mode 100644 docs/oauth2/oidc/hybrid.rst create mode 100644 docs/oauth2/oidc/implicit.rst create mode 100644 docs/oauth2/oidc/userinfo.rst diff --git a/docs/oauth2/oidc.rst b/docs/oauth2/oidc.rst index d062386..a3810a6 100644 --- a/docs/oauth2/oidc.rst +++ b/docs/oauth2/oidc.rst @@ -1,16 +1,21 @@ OpenID Connect ============== -OpenID Connect represents a substantial set of behaviors and interactions built on the foundations of OAuth2. OAuthLib supports -OpenID Connect `Authentication flows`_ when the initial grant type request's ``scope`` parameter contains ``openid``. Clients wishing -to provide this support must implement several new features within their ``RequestValidator`` subclass. +OpenID Connect represents a substantial set of behaviors and +interactions built on the foundations of OAuth2. OAuthLib supports +OpenID Connect `Authentication flows`_ when the initial grant type +request's ``scope`` parameter contains ``openid``. Providers wishing +to provide this support must implement a couple of new features within +their ``RequestValidator`` subclass. + +A new userinfo endpoint can also be implemented to fulfill the core of OIDC. .. _`Authentication flows`: http://openid.net/specs/openid-connect-core-1_0.html#Authentication .. toctree:: :maxdepth: 2 - oidc/id_tokens oidc/validator - - + oidc/endpoints + oidc/grants + oidc/id_tokens diff --git a/docs/oauth2/oidc/authcode.rst b/docs/oauth2/oidc/authcode.rst new file mode 100644 index 0000000..11c4a62 --- /dev/null +++ b/docs/oauth2/oidc/authcode.rst @@ -0,0 +1,6 @@ +OpenID Authorization Code +------------------------- + +.. autoclass:: oauthlib.openid.connect.core.grant_types.AuthorizationCodeGrant + :members: + :inherited-members: diff --git a/docs/oauth2/oidc/dispatchers.rst b/docs/oauth2/oidc/dispatchers.rst new file mode 100644 index 0000000..f4d395e --- /dev/null +++ b/docs/oauth2/oidc/dispatchers.rst @@ -0,0 +1,24 @@ +Dispatchers +----------- + +.. contents:: + :depth: 2 + +Authorization Request +^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: oauthlib.openid.connect.core.grant_types.ImplicitTokenGrantDispatcher + :members: + :inherited-members: + + +.. autoclass:: oauthlib.openid.connect.core.grant_types.AuthorizationCodeGrantDispatcher + :members: + :inherited-members: + +Token Request +^^^^^^^^^^^^^ + +.. autoclass:: oauthlib.openid.connect.core.grant_types.AuthorizationTokenGrantDispatcher + :members: + :inherited-members: diff --git a/docs/oauth2/oidc/endpoints.rst b/docs/oauth2/oidc/endpoints.rst new file mode 100644 index 0000000..51cd1e9 --- /dev/null +++ b/docs/oauth2/oidc/endpoints.rst @@ -0,0 +1,21 @@ +OpenID Provider Endpoints +========================= + +Endpoints in OpenID Connect Core adds a new UserInfo Endpoint. All +existing OAuth2.0 endpoints are common to both protocols. + +.. toctree:: + :maxdepth: 2 + + userinfo + +See also the related endpoints from OAuth2.0: + +.. hlist:: + :columns: 1 + + * :doc:`Authorization endpoint ` + * :doc:`Introspect endpoint ` + * :doc:`Token endpoint ` + * :doc:`Revocation endpoint ` + * :doc:`Resource endpoint ` diff --git a/docs/oauth2/oidc/grants.rst b/docs/oauth2/oidc/grants.rst new file mode 100644 index 0000000..aa1f70f --- /dev/null +++ b/docs/oauth2/oidc/grants.rst @@ -0,0 +1,41 @@ +=========== +Grant types +=========== + +The OpenID Connect specification adds a new `Hybrid` flow and adds +variants to the existing `Authorization Code` and `Implicit` +flows. They share the same principle: having `openid` in the scope and +a combination of new `response_type` values. + + +.. list-table:: OpenID Connect "response_type" Values + :widths: 50 50 + :header-rows: 1 + + * - "response_type" value + - Flow + * - `code` + - Authorization Code Flow + * - `id_token` + - Implicit Flow + * - `id_token token` + - Implicit Flow + * - `code id_token` + - Hybrid Flow + * - `code token` + - Hybrid Flow + * - `code id_token token` + - Hybrid Flow + + +Special Dispatcher classes have been made to dynamically route the HTTP +requests to either an OAuth2.0 flow or an OIDC flow. It basically +checks the presence of `openid` scope in the parameters. + +.. toctree:: + :maxdepth: 2 + + dispatchers + authcode + implicit + hybrid diff --git a/docs/oauth2/oidc/hybrid.rst b/docs/oauth2/oidc/hybrid.rst new file mode 100644 index 0000000..6a6c2e7 --- /dev/null +++ b/docs/oauth2/oidc/hybrid.rst @@ -0,0 +1,6 @@ +OpenID Hybrid +------------- + +.. autoclass:: oauthlib.openid.connect.core.grant_types.HybridGrant + :members: + :inherited-members: diff --git a/docs/oauth2/oidc/implicit.rst b/docs/oauth2/oidc/implicit.rst new file mode 100644 index 0000000..08cef20 --- /dev/null +++ b/docs/oauth2/oidc/implicit.rst @@ -0,0 +1,6 @@ +OpenID Implicit +--------------- + +.. autoclass:: oauthlib.openid.connect.core.grant_types.ImplicitGrant + :members: + :inherited-members: diff --git a/docs/oauth2/oidc/userinfo.rst b/docs/oauth2/oidc/userinfo.rst new file mode 100644 index 0000000..7ba4fbf --- /dev/null +++ b/docs/oauth2/oidc/userinfo.rst @@ -0,0 +1,7 @@ +======================== +OpenID UserInfo endpoint +======================== + + +.. autoclass:: oauthlib.openid.connect.core.endpoints.userinfo.UserInfoEndpoint + :members: diff --git a/docs/oauth2/oidc/validator.rst b/docs/oauth2/oidc/validator.rst index 17f5825..a04e12e 100644 --- a/docs/oauth2/oidc/validator.rst +++ b/docs/oauth2/oidc/validator.rst @@ -1,7 +1,16 @@ -OpenID Connect -========================================= +Creating a Provider +============================================= -Migrate your OAuth2.0 server into an OIDC provider +.. contents:: + :depth: 2 + +1. Create an OIDC provider +----------------------- +If you don't have an OAuth2.0 Provider, you can follow the instructions at +:doc:`OAuth2.0 Creating a Provider `. Then, follow the +migration step below. + +2. Migrate your OAuth2.0 provider into an OIDC provider ---------------------------------------------------- If you have a OAuth2.0 provider running and want to upgrade to OIDC, you can @@ -19,13 +28,21 @@ Into from oauthlib.openid import Server from oauthlib.openid import RequestValidator -Then, you have to implement the new RequestValidator methods as shown below. -Note that a new UserInfo endpoint is defined and need a new controller into your webserver. +Then, you have to implement the new `RequestValidator` methods as +shown below. Note also that a new :doc:`UserInfo endpoint ` can be defined +and needs a new controller into your webserver. -RequestValidator Extension ----------------------------------------------------- +3. Extend RequestValidator +-------------------------- -A couple of methods must be implemented in your validator subclass if you wish to support OpenID Connect: +A couple of methods must be implemented in your validator subclass if +you wish to support OpenID Connect: .. autoclass:: oauthlib.openid.RequestValidator :members: + +4. Preconfigured all-in-one servers +----------------------------------- + +.. autoclass:: oauthlib.openid.connect.core.endpoints.pre_configured.Server + :members: diff --git a/oauthlib/openid/connect/core/grant_types/dispatchers.py b/oauthlib/openid/connect/core/grant_types/dispatchers.py index 541467a..e6a9259 100644 --- a/oauthlib/openid/connect/core/grant_types/dispatchers.py +++ b/oauthlib/openid/connect/core/grant_types/dispatchers.py @@ -9,8 +9,10 @@ class Dispatcher: class AuthorizationCodeGrantDispatcher(Dispatcher): """ - This is an adapter class that will route simple Authorization Code requests, those that have response_type=code and a scope - including 'openid' to either the default_grant or the oidc_grant based on the scopes requested. + This is an adapter class that will route simple Authorization Code + requests, those that have `response_type=code` and a scope including + `openid` to either the `default_grant` or the `oidc_grant` based on + the scopes requested. """ def __init__(self, default_grant=None, oidc_grant=None): self.default_grant = default_grant @@ -26,16 +28,20 @@ class AuthorizationCodeGrantDispatcher(Dispatcher): return handler def create_authorization_response(self, request, token_handler): + """Read scope and route to the designated handler.""" return self._handler_for_request(request).create_authorization_response(request, token_handler) def validate_authorization_request(self, request): + """Read scope and route to the designated handler.""" return self._handler_for_request(request).validate_authorization_request(request) class ImplicitTokenGrantDispatcher(Dispatcher): """ - This is an adapter class that will route simple Authorization Code requests, those that have response_type=code and a scope - including 'openid' to either the default_grant or the oidc_grant based on the scopes requested. + This is an adapter class that will route simple Authorization + requests, those that have `id_token` in `response_type` and a scope + including `openid` to either the `default_grant` or the `oidc_grant` + based on the scopes requested. """ def __init__(self, default_grant=None, oidc_grant=None): self.default_grant = default_grant @@ -51,9 +57,11 @@ class ImplicitTokenGrantDispatcher(Dispatcher): return handler def create_authorization_response(self, request, token_handler): + """Read scope and route to the designated handler.""" return self._handler_for_request(request).create_authorization_response(request, token_handler) def validate_authorization_request(self, request): + """Read scope and route to the designated handler.""" return self._handler_for_request(request).validate_authorization_request(request) @@ -87,5 +95,6 @@ class AuthorizationTokenGrantDispatcher(Dispatcher): return handler def create_token_response(self, request, token_handler): + """Read scope and route to the designated handler.""" handler = self._handler_for_request(request) return handler.create_token_response(request, token_handler) -- cgit v1.2.1