From aae1320d7b9c1db04b7ce6ced1956e7da280b551 Mon Sep 17 00:00:00 2001 From: coolaj86 Date: Mon, 7 Aug 2017 20:46:30 +0000 Subject: [PATCH] Update 'README.md' --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b363f53..bc8629c 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,16 @@ Just a quick intro to vocabulary that will be explained more thoroughly later on * **audience** (**aud**) - the service or device that exchanges tokens for goods or services. In the old-world model this is Facebook, Twitter, etc * **authorized party** (**azp**) - the service or device that uses tokens to accomplish the subject's goals. In the old-world model this is a site that has a "Login with Facebook" button +### Scopes + +Scopes are federated schemas. Any issuer may act as the agent of the subject to authorize any azp for any audience. To make this possible scopes are defined as `<>@<>` (i.e. dns@oauth3.org) and can be discovered as `https://aud.tld/.well-known/scopes@oauth3.org/<>@<>.json`. + +Examples of well-known scope-schemas: + +* authn@oauth3.org +* domains@oauth3.org +* dns@oauth3.org + ## There are 4 potential Identity Delegation styles The following are just sample UX to show the difference in the styles. Typically, a single UX can encompass all 4 styles. @@ -231,4 +241,41 @@ Example **callback uri** on the azp: **Step 5** -The UI should be updated with the name and icon specified in the issuer directives, if any. \ No newline at end of file +The UI should be updated with the name and icon specified in the issuer directives, if any. + +## OAuth3 Token Issuance, Endpoints, and Process + +For an issuer such as smithfam.net the directives must specify that the `authorization_dialog` endpoint is `https://smithfam.net/#/authorization_dialog/` + +### First Token Grant / First Login + +Once the issuer has been discovered the azp must store any state about the subject or application and construct a url to place in an anchor tag that will either redirect the window to the issuer directly, or open a popup window by using the `_target` attribute. + +According to browser policy, `window.open` may not be used asynchronously (no promises or requests), if it is used. + +Example **authorization dialog** url (using the example above): + +``` +https://smithfam.net/#/authorization_dialog/ + ?response_type=token + &scope=authn@oauth3.org + &state=<> + &client_uri=azp.tld + &client_id=azp.tld + &subject=jane@smithfam.net + &redirect_uri=<> + &debug=false +``` + +NOTE: `redirect_uri` itself may also contain URI-encoded components + +In OAuth3 `client_uri` replaces `client_id` and so `client_id` is only necessary for OAuth2 backwards compatibility and for applications that need multiple ids or otherwise require manual registration. + +`scope` is optional. Generally speaking scopes should be defined as part of subsequent authorization, not initial authentication. + +`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). + + +### Pre-Authorized Token Grant / Subsequent Logins \ No newline at end of file