oauth2: add HTTP examples for client credentials grant

1 files changed, 98 insertions, 0 deletions

diff --git a/yuck.md b/yuck.md
index b544a21..5fc047c 100644
--- a/yuck.md
+++ b/yuck.md
@@ -368,6 +368,104 @@ 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.
 
+## HTTP transactions
+
+This chapter shows examples of the actual HTTP transactions to
+implement the OAuth protocol. The examples use HTTP/1.1, for
+simplicity, but translating them to newer versions of HTTP should be
+straightforward.
+
+The examples assume that the server is `auth.example.com` and that the
+token endpoint is `/token` on that server.
+
+### Client credentials grant
+
+The client credentials grant is quite simple: the client sends a
+request, the server checks that it's a valid request, and responds
+either with an error or an access token.
+
+The client makes a POST request to the _token_ endpoint, with an HTML
+form-encoded body that specifies that it wants to use the client
+credentials grant. Specifically, it sets `grant_type` to
+`client-credentials`. No other form fields are needed.
+
+The client provides its credentials as using [HTTP Basic Auth][], in
+the `Authorization` header.
+
+~~~{.numberLines}
+POST /token HTTP/1.1
+Host: auth.example.com
+Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials
+~~~
+
+The response uses HTTP status codes to indicate success or failure. A
+200 status code means success. A 400 series status code means failure.
+
+~~~
+HTTP/1.1 200 OK
+Content-Type: application/json;charset=UTF-8
+Cache-Control: no-store
+Pragma: no-cache
+
+{
+  "access_token":"2YotnFZFEjr1zCsicMWpAA",
+  "token_type":"bearer",
+  "expires_in":3600,
+}
+~~~
+
+In the sample response above, the token is a bearer token, which
+means the client should use it in requests with the `Authorization`
+header:
+
+~~~
+Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
+~~~
+
+In the sample response above, the token is valid for an hour. After
+that it expires and the resource server should refuse it. The token
+may become invalid earlier.
+
+Note that for client credentials grants no refresh token is returned,
+it would be fairly pointless. The client can just get a new access
+token the same way it got the first one.
+
+[HTTP Basic Auth]: https://tools.ietf.org/html/rfc7617
+
+### Error responses
+
+A token request can fail for a variety of reasons. The 400 status code
+is used for anything the client did wrong. Other HTTP status codes are
+used for other errors, as specified by HTTP. For example, if the
+server has an internal problem, 500 is returned.
+
+For OAuth, a 400 response returns a more detailed indication about
+what the client did wrong, in the `error` field in the JSON body of
+the response. RFC 6749 lists the [error codes][] and other fields. For
+example, if the client has the wrong credentials, the response would
+look something like this:
+
+~~~{.numberLines}
+HTTP/1.1 400 Bad Request
+Content-Type: application/json;charset=UTF-8
+Cache-Control: no-store
+Pragma: no-cache
+
+{
+   "error":"invalid_client"
+}
+~~~
+
+The client can use the detailed error code to inform what it should do
+about the error. Few, if any, errors warrant the client re-trying the
+request, especially soon, but it might alert a human, or just log the
+failure.
+
+[error codes]: https://tools.ietf.org/html/rfc6749#section-5.2
+
 # The OIDC 1.0 protocol: authorization code
 
 FIXME: write this