From 7a0b1e9cad04806bf4be5c7380e75aaf03ebec2c Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Thu, 13 Dec 2018 16:32:00 +0100 Subject: Add OAuth2.0 Authorization Server Metadata documentation --- docs/oauth2/endpoints/endpoints.rst | 6 ++-- oauthlib/oauth2/rfc6749/endpoints/metadata.py | 42 +++++++++++++++++++++------ 2 files changed, 37 insertions(+), 11 deletions(-) diff --git a/docs/oauth2/endpoints/endpoints.rst b/docs/oauth2/endpoints/endpoints.rst index 8068ec4..0dd2da0 100644 --- a/docs/oauth2/endpoints/endpoints.rst +++ b/docs/oauth2/endpoints/endpoints.rst @@ -10,12 +10,14 @@ certain users resources to a client, to supply said client with a token embodying this authorization and to verify that the token is valid when the client attempts to access the user resources on their behalf. + .. toctree:: :maxdepth: 2 authorization introspect token + metadata revocation resource @@ -29,5 +31,5 @@ later (but it's applicable to all other web frameworks libraries). The main purpose of the endpoint in OAuthLib is to figure out which grant type or token to dispatch the request to. -Then, you can extend your OAuth implementation by proposing introspect or -revocation endpoints. +Then, you can extend your OAuth implementation by proposing introspect, +revocation and/or providing metadata endpoints. diff --git a/oauthlib/oauth2/rfc6749/endpoints/metadata.py b/oauthlib/oauth2/rfc6749/endpoints/metadata.py index 6d77b9f..ad56c42 100644 --- a/oauthlib/oauth2/rfc6749/endpoints/metadata.py +++ b/oauthlib/oauth2/rfc6749/endpoints/metadata.py @@ -32,14 +32,13 @@ class MetadataEndpoint(BaseEndpoint): `OpenID Connect Discovery 1.0` in a way that is compatible with OpenID Connect Discovery while being applicable to a wider set of OAuth 2.0 use cases. This is intentionally parallel to the way - that `OAuth 2.0 Dynamic Client Registration Protocol` [RFC7591] + that OAuth 2.0 Dynamic Client Registration Protocol [`RFC7591`_] generalized the dynamic client registration mechanisms defined by - `OpenID Connect Dynamic Client Registration 1.0` + OpenID Connect Dynamic Client Registration 1.0 in a way that is compatible with it. - .. _`OpenID Connect Discovery 1.0`: http://openid.net/specs/openid-connect-discovery-1_0.html - .. _`OAuth 2.0 Dynamic Client Registration Protocol`: https://tools.ietf.org/html/rfc7591 - .. _`OpenID Connect Dynamic Client Registration 1.0`: https://openid.net/specs/openid-connect-registration-1_0.html + .. _`OpenID Connect Discovery 1.0`: https://openid.net/specs/openid-connect-discovery-1_0.html + .. _`RFC7591`: https://tools.ietf.org/html/rfc7591 """ def __init__(self, endpoints, claims={}, raise_errors=True): @@ -127,18 +126,19 @@ class MetadataEndpoint(BaseEndpoint): """ Authorization servers can have metadata describing their configuration. The following authorization server metadata values - are used by this specification. More details can be found in `RFC8414` : + are used by this specification. More details can be found in + `RFC8414 section 2`_ : issuer REQUIRED authorization_endpoint URL of the authorization server's authorization endpoint - [RFC6749]. This is REQUIRED unless no grant types are supported + [`RFC6749#Authorization`_]. This is REQUIRED unless no grant types are supported that use the authorization endpoint. token_endpoint - URL of the authorization server's token endpoint [RFC6749]. This + URL of the authorization server's token endpoint [`RFC6749#Token`_]. This is REQUIRED unless only the implicit grant type is supported. scopes_supported @@ -151,26 +151,50 @@ class MetadataEndpoint(BaseEndpoint): jwks_uri registration_endpoint response_modes_supported + grant_types_supported + OPTIONAL. JSON array containing a list of the OAuth 2.0 grant + type values that this authorization server supports. The array + values used are the same as those used with the "grant_types" + parameter defined by "OAuth 2.0 Dynamic Client Registration + Protocol" [`RFC7591`_]. If omitted, the default value is + "["authorization_code", "implicit"]". + token_endpoint_auth_methods_supported + token_endpoint_auth_signing_alg_values_supported + service_documentation + ui_locales_supported + op_policy_uri + op_tos_uri + revocation_endpoint + revocation_endpoint_auth_methods_supported + revocation_endpoint_auth_signing_alg_values_supported + introspection_endpoint + introspection_endpoint_auth_methods_supported + introspection_endpoint_auth_signing_alg_values_supported + code_challenge_methods_supported Additional authorization server metadata parameters MAY also be used. Some are defined by other specifications, such as OpenID Connect - Discovery 1.0 [OpenID.Discovery]. + Discovery 1.0 [`OpenID.Discovery`_]. .. _`RFC8414 section 2`: https://tools.ietf.org/html/rfc8414#section-2 + .. _`RFC6749#Authorization`: https://tools.ietf.org/html/rfc6749#section-3.1 + .. _`RFC6749#Token`: https://tools.ietf.org/html/rfc6749#section-3.2 + .. _`RFC7591`: https://tools.ietf.org/html/rfc7591 + .. _`OpenID.Discovery`: https://openid.net/specs/openid-connect-discovery-1_0.html """ claims = copy.deepcopy(self.initial_claims) self.validate_metadata(claims, "issuer", is_required=True, is_issuer=True) -- cgit v1.2.1 From bc53c6189a1096fd1f112be42f372d70465ab4ac Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Thu, 13 Dec 2018 17:15:18 +0100 Subject: Add metadata documentation with quick example --- docs/oauth2/endpoints/metadata.rst | 72 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/oauth2/endpoints/metadata.rst diff --git a/docs/oauth2/endpoints/metadata.rst b/docs/oauth2/endpoints/metadata.rst new file mode 100644 index 0000000..d44e8b7 --- /dev/null +++ b/docs/oauth2/endpoints/metadata.rst @@ -0,0 +1,72 @@ +=================== +Metadata endpoint +=================== + +OAuth2.0 Authorization Server Metadata (`RFC8414`_) endpoint provide the metadata of your authorization server. Since the metadata results can be a combination of OAuthlib's Endpoint (see :doc:`preconfigured_servers`), the MetadataEndpoint's class takes a list of Endpoints in parameter, and aggregate the metadata in the response. + +See below an example of usage with `bottle-oauthlib`_ when using a `LegacyApplicationServer` (password grant) endpoint: + +.. code-block:: python + + import bottle + from bottle_oauthlib.oauth2 import BottleOAuth2 + from oauthlib import oauth2 + + app = bottle.Bottle() + app.authmetadata = BottleOAuth2(app) + + oauthlib_server = oauth2.LegacyApplicationServer(oauth2.RequestValidator()) + app.authmetadata.initialize(oauth2.MetadataEndpoint([oauthlib_server], claims={ + "issuer": "https://xx", + "token_endpoint": "https://xx/token", + "revocation_endpoint": "https://xx/revoke", + "introspection_endpoint": "https://xx/tokeninfo" + })) + + + @app.get('/.well-known/oauth-authorization-server') + @app.authmetadata.create_metadata_response() + def metadata(): + pass + + + if __name__ == "__main__": + app.run() # pragma: no cover + + +Sample response's output: + + +.. code-block:: javascript + + $ curl -s http://localhost:8080/.well-known/oauth-authorization-server|jq . + { + "issuer": "https://xx", + "token_endpoint": "https://xx/token", + "revocation_endpoint": "https://xx/revoke", + "introspection_endpoint": "https://xx/tokeninfo", + "grant_types_supported": [ + "password", + "refresh_token" + ], + "token_endpoint_auth_methods_supported": [ + "client_secret_post", + "client_secret_basic" + ], + "revocation_endpoint_auth_methods_supported": [ + "client_secret_post", + "client_secret_basic" + ], + "introspection_endpoint_auth_methods_supported": [ + "client_secret_post", + "client_secret_basic" + ] + } + + +.. autoclass:: oauthlib.oauth2.MetadataEndpoint + :members: + + +.. _`RFC8414`: https://tools.ietf.org/html/rfc8414 +.. _`bottle-oauthlib`: https://github.com/thomsonreuters/bottle-oauthli -- cgit v1.2.1