Merge branch 'master' into dry-up-codedry-up-code

3 files changed, 109 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/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
diff --git a/oauthlib/oauth2/rfc6749/endpoints/metadata.py b/oauthlib/oauth2/rfc6749/endpoints/metadata.py
index 60c846b..936e878 100644
--- a/oauthlib/oauth2/rfc6749/endpoints/metadata.py
+++ b/oauthlib/oauth2/rfc6749/endpoints/metadata.py
@@ -33,14 +33,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):
@@ -146,18 +145,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
@@ -170,26 +170,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)