coolaj86
/
OAUTH3-SPEC
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update 'README.md'

This commit is contained in:
AJ ONeal 2017-08-07 20:01:18 +00:00
parent 88c0bd8207
commit 56c94687de
1 changed files with 102 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
README.md
View File

@ -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.
@ -132,3 +132,103 @@ The site receiving the url parameters (**azp**) must have its own `directives.js
```
https://azp.tld/.well-known/oauth3/callback.html
```
### 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=<<state>>
&redirect_uri=<<encodeURIComponent("https://azp.tld/.well-known/oauth3/callback.html#/")>>
&response_type=rpc
&_method=GET
&_pathname=<<encodeURIComponent(".well-known/oauth3/directives.json")>>
&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=<<params.state>>
&directives=<<OAUTH3._base64.encodeUrlSafe(JSON.stringify(directives))>>
&debug=<<params.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
<html>
<body>
<script>
(function () {
'use strict';
var params = OAUTH3.query.parse(window.location.hash);
window.parent['--oauth3-callback-' + params.state](params);
window.close();
}());
</script>
</body>
</html>
```
**Step 5**
The UI should be updated with the name and icon specified in the issuer directives, if any.