From 4bd983e1542500f745cd8eec0e5d414b2d3abc77 Mon Sep 17 00:00:00 2001
From: coolaj86 <coolaj86@gmail.com>
Date: Mon, 7 Aug 2017 22:04:47 +0000
Subject: [PATCH] Update 'README.md'

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d3133ac..ab1b908 100644
--- a/README.md
+++ b/README.md
@@ -257,6 +257,15 @@ According to browser policy, `window.open` may not be used asynchronously (no pr
 
 The authorization dialog may be opened from a hidden iFrame. If the user is signed in and has already authorized the app a token will be granted. Otherwise an error will be issued.
 
+An error would look like this:
+
+```
+https://azp.tld/.well-known/oauth3/callback.html#/
+  ?error=enoauth@oauth3.org
+  &error_description=Not already authorized
+  &error_uri=https://oauth3.org/errors/enoauth@oauth3.org
+  &debug=false
+```
 
 ### Step 1
 
@@ -270,6 +279,9 @@ https://smithfam.net/#/authorization_dialog/
   &client_uri=azp.tld
   &client_id=azp.tld
   &subject=jane@smithfam.net
+  &jwk_kty=<<EC>>
+  &jwk_kid=<<thumbprint of key>>
+  &jwk_XXX=<<property XXX of jwk>>
   &redirect_uri=<<encodeURIComponent('https://azp.tld/.well-known/oauth3/callback.html')>>
   &debug=false
 ```
@@ -282,7 +294,9 @@ In OAuth3 `client_uri` replaces `client_id` and so `client_id` is only necessary
 
 `subject` is optional, but allows the issuer to skip the step of asking the user for their username / email.
 
-TODO It should also be possible to pass qualifiers for the security requirements of the azp (recency of login, mfa requirements, etc).
+TODO It should also be possible to pass qualifiers (acr) for the security requirements of the azp (recency of login, mfa requirements, etc).
+
+TODO `jwk`. should be optional. It may be used to publish a public key such that the application may generate its own tokens, if the issuer supports it.
 
 
 ### Step 2 (determine subject / get username/email)
@@ -301,4 +315,38 @@ It is recommended to avoid using passwords and to instead use device-based authe
 
 In the reference implementation the user is sent an email with a login code or the device generates a new public/private keypair.
 
-### step 4 (authorize / grant)
\ No newline at end of file
+### step 4 (authorize / grant)
+
+A JWT (token) with the following properties will be generated:
+
+```
+{ "jti": "<<nonce>>"
+, "iat": <<issued at unix timestamp in seconds>>
+, "amr": "pwd@oauth3.org"
+, "laa": <<last authentication at unix timestamp in seconds>>
+, "exp": <<expiry unix timestamp in seconds>>
+, "sub": "<<psuedonymous pairwise identifier>>"
+, "iss": "smithfam.net"
+, "azp": "azp.tld"
+, "aud": "azp.tld"
+, "scp": "auth@oauth3.org,domains@oauth3.org"
+, "ttl": 0 /* cannot be renewed even before exp */
+} 
+```
+
+It isn't necessary to have a refresh token because the token can be refreshed through a hidden iframe in a browser in the same way it was acquired the first time.
+
+However, where the issuer supports refresh tokens, they must have the additional property of `renew: true`
+
+The token will be passed back to the application in the following form:
+
+```
+https://azp.tld/.well-known/oauth3/callback.html#/
+  ?access_token=<<token>>
+  &token_type=<<Bearer>>
+  &refresh_token=<<refresh_token>>
+  &expires_in=<<token.exp - now>>
+  &scope=<<token.scp>>
+  &state=<<params.state>>
+  &debug=false
+```
\ No newline at end of file