Update 'README.md'

2017-08-07 20:01:18 +00:00 · 2017-08-07 20:01:18 +00:00 · 56c94687de
parent 88c0bd8207
commit 56c94687de
1 changed files with 102 additions and 2 deletions
--- 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
-```
+```
+
+### 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.