From bc53c6189a1096fd1f112be42f372d70465ab4ac Mon Sep 17 00:00:00 2001
From: Jonathan Huot <jonathan.huot@thomsonreuters.com>
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