oauth2: add overview of finding endpoints

1 files changed, 70 insertions, 0 deletions

diff --git a/yuck.md b/yuck.md
index 7039850..b544a21 100644
--- a/yuck.md
+++ b/yuck.md
@@ -298,6 +298,76 @@ Booksite -> Alice: Your book!
 ~~~
 
 
+## Finding protocol endpoints
+
+The OAuth2 protocol requires the client to make certain requests to
+the authorization server to get access and refresh tokens. We can
+assume that the client knows the address of the authorization server,
+but it still needs to find the actual complete URLs to the endpoints.
+
+In the original OAuth 2.0 specification, this was left unspecified.
+Each client needed to have inherent knowledge of the endpoints for each
+authorization server. RFC8414 [@rfc8414] adds a way for the client to find the
+endpoints automatically, once it knows the authorization server
+location.
+
+The process is complex enough that we won't go into all the details
+here. In the simple, straightforward case given an authorization
+server at `https://server.example.com`, the client retrieves the JSON
+document at the following URL:
+
+> `https://server.example.com/.well-known/oauth-authorization-server`
+
+The JSON document might look like the following:
+
+~~~json
+{
+  "issuer": "https://server.example.com",
+  "authorization_endpoint": "https://server.example.com/authorize",
+  "token_endpoint": "https://server.example.com/token",
+  "token_endpoint_auth_methods_supported": [
+    "client_secret_basic",
+    "private_key_jwt"
+  ],
+  "token_endpoint_auth_signing_alg_values_supported": [
+    "RS256",
+    "ES256"
+  ],
+  "userinfo_endpoint": "https://server.example.com/userinfo",
+  "jwks_uri": "https://server.example.com/jwks.json",
+  "registration_endpoint": "https://server.example.com/register",
+  "scopes_supported": [
+    "openid",
+    "profile",
+    "email",
+    "address",
+    "phone",
+    "offline_access"
+  ],
+  "response_types_supported": [
+    "code",
+    "code token"
+  ],
+  "service_documentation": "http://server.example.com/service_documentation.html",
+  "ui_locales_supported": [
+    "en-US",
+    "en-GB",
+    "en-CA",
+    "fr-FR",
+    "fr-CA"
+  ]
+}
+~~~
+
+Some of the complexity we elide here involves compatibility with the
+OpenID Connect protocol, and extending the OIDC approach. There is
+also provisions for dealing with multiple authorization servers on the
+same URL, or server that aren't rooted at the base of the domain.
+There is also a possibility of using digitally signed metadata, as a
+signed JSON Web Token. For all of this, detailed reading of the RFC
+specification is needed to get all correct. Here we aim at giving an
+overview.
+
 # The OIDC 1.0 protocol: authorization code
 
 FIXME: write this