Add OAuth2.0 Authorization Server Metadata documentation

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)