Merge pull request #704 from oauthlib/doc-oidc

Improved OIDC documentation

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

docs/oauth2/oidc/authcode.rst

@@ -0,0 +1,6 @@
+OpenID Authorization Code
+-------------------------
+
+.. autoclass:: oauthlib.openid.connect.core.grant_types.AuthorizationCodeGrant
+    :members:
+    :inherited-members:

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:

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 </oauth2/endpoints/authorization>`
+   * :doc:`Introspect endpoint </oauth2/endpoints/introspect>`
+   * :doc:`Token endpoint </oauth2/endpoints/token>`
+   * :doc:`Revocation endpoint </oauth2/endpoints/revocation>`
+   * :doc:`Resource endpoint </oauth2/endpoints/resource>`

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

docs/oauth2/oidc/hybrid.rst

@@ -0,0 +1,6 @@
+OpenID Hybrid
+-------------
+
+.. autoclass:: oauthlib.openid.connect.core.grant_types.HybridGrant
+    :members:
+    :inherited-members:

docs/oauth2/oidc/implicit.rst

@@ -0,0 +1,6 @@
+OpenID Implicit
+---------------
+
+.. autoclass:: oauthlib.openid.connect.core.grant_types.ImplicitGrant
+    :members:
+    :inherited-members:

docs/oauth2/oidc/userinfo.rst

@@ -0,0 +1,7 @@
+========================
+OpenID UserInfo endpoint
+========================
+
+
+.. autoclass:: oauthlib.openid.connect.core.endpoints.userinfo.UserInfoEndpoint
+    :members:

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 </oauth2/server>`. 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 </oauth2/oidc/userinfo>` 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:

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 @@ def _handler_for_request(self, request):
         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 @@ def _handler_for_request(self, request):
         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 @@ def _handler_for_request(self, request):
         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)