diff --git a/README.md b/README.md index 4c7024a..b363f53 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ In this flow the subject and the identity issuer can be manually selected indepe Why you would want this: You want to support every possible OAuth3 use case. -## OAuth3 Issuer Discovery Endpoints +## OAuth3 Issuer Discovery Endpoint and Process Any site (**iss**) which supports OAuth3 (oauth3.org, for example) can be discovered automatically and all configuration details can be taken care of without human intervention. @@ -131,4 +131,104 @@ The site receiving the url parameters (**azp**) must have its own `directives.js ``` https://azp.tld/.well-known/oauth3/callback.html -``` \ No newline at end of file +``` + +### Native Flow + +**Step 1** + +The subject types their subject address, such as jane@smithfam.net, into an input field + +**Step 2** + +A native application should simply request `https://smithfam.net/.well-known/oauth3/directives.json`, according to our example above. + +**Step 3** + +The UI should be updated with the name and icon specified in the issuer directives, if any. + +### Browser Flow + +**Step 1** + +The subject types their subject address, such as jane@smithfam.net, into an input field + +**Step 2** + +The azp will discover `smithfam.net` (according to our example in step 1). + +First it must check if it itself is smithfam.net. If it is, it will retrieve `/.well-known/oauth3/directives.json` directly. + +Otherwise the azp generates a random state and creates a callback function to receive the response from the subject's local user-agent at `https://smithfam.net/.well-known/oauth3/#/`, bypassing the need to round-trip to the server in most cases. It may be opened in a hidden iframe and must have the appropriate hashquery parameters, including the state. + +Example **callback function**: + +``` +var state = OAUTH3.utils.randomState(); +window['--oauth3-callback-' + state] = function (params) { + // handle response hashquery parameters +}; +``` + +Example **discovery url**: + +``` +https://smithfam.net/.well-known/oauth3/#/ + ?action=directives + &state=<> + &redirect_uri=<> + &response_type=rpc + &_method=GET + &_pathname=<> + &debug=false +``` + +The debug parameter's behavior is defined by the issuer, but should cause automatic redirects to be replaced with manual intervention (such as clicking a link to continue) and provide information helpful for debugging. + +**Step 3** + +The issuer (smithfam.net) will receive the query request for `directives.json` and respond with base64-encoded json to the azp's `callback.html`. + +The issuer should application cache all files necessary for responding to this request and may also cache the contents of `directives.json` so that no requests are made to the server in the normal case. + +The `redirect_uri` in our example was specified as `https://azp.tld/.well-known/oauth3/callback.html#/`, so we'll continue to use that. + +``` +https://azp.tld/.well-known/oauth3/callback.html#/ + ?state=<> + &directives=<> + &debug=<> +``` + +This url replaces the current window (currently loaded at the discovery url). + +**Step 4** + +The hidden frame that the azp had opened has now been redirected to its `callback.html`. It should pass the parameters back to the original program and continue the user flow. + +Example **callback uri** on the azp: + +`https://azp.tld/.well-known/oauth3/callback.html` +```html + + + + + +``` + +**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