From b106da72cb62232dd71a595f1f559dd666e05c9d Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Fri, 22 Jan 2021 10:30:29 +0200
Subject: oauth2: add overview of finding endpoints

---
 bibliography.yaml | 16 +++++++++++++
 yuck.md           | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/bibliography.yaml b/bibliography.yaml
index e16b69e..74d0e9d 100644
--- a/bibliography.yaml
+++ b/bibliography.yaml
@@ -26,4 +26,20 @@ references:
   title: OAuth 2.0 for native apps
   publisher: IETF
   url: https://tools.ietf.org/html/rfc8252
+
+- id: rfc8414
+  type: webpage
+  author:
+    - family: Jones
+      given: M.
+    - family: Sakimura
+      given: N.
+    - family: Bradley
+      given: J.
+  issued:
+    - year: 2018
+      month: 6
+  title: OAuth 2.0 Authorization Server Metadata
+  publisher: IETF
+  url: https://tools.ietf.org/html/rfc8414
 ...
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
-- 
cgit v1.2.1