coolaj86/oauth3.js
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update README

Browse Source
This commit is contained in:
AJ ONeal 2017-02-15 10:50:53 -07:00
parent 394f01d84e
commit 53b5e30dc2
1 changed files with 44 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
README.md
View File

@ -147,21 +147,29 @@ Stable API
<!-- hooks --> <!-- hooks -->
* `OAUTH3.utils.clientUri(window.location);` produces the default `client_uri` of your app (also used as `client_id`) ```
* `OAUTH3.discover(providerUri, { client_id: clientUri });` Promises the config file for the provider and caches it in memory. OAUTH3.utils.clientUri(window.location); // produces the default `client_uri` of your app (also used as `client_id`)
* `OAUTH3.implicitGrant(providerUri, { client_id: clientUri })` returns a `session` with `session.token.sub` as the secure ppid.
* `debug: true` will cause the windows to not refresh automatically OAUTH3.discover(providerUri, { client_id: clientUri }); // Promises the config file for the provider and caches it in memory.
* `windowType: 'popup'` will use a popup window to ask user for new permissions, if any
* `windowType: 'background'` will automatically log the user in (if all permissions have been accepted) OAUTH3.implicitGrant(providerUri, { client_id: clientUri }) // returns a `session` with `session.token.sub` as the secure ppid.
* `OAUTH3.request({ method: 'GET', url: '', session: '', data: '' })` make an authenticated request to a resource // debug: true - will cause the windows to not refresh automatically
* `OAUTH3.logout(providerUri, { client_id: clientUri, session: session })` opens a popup to confirm logout from the provider // windowType: 'popup' - will use a popup window to ask user for new permissions, if any
* Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this // windowType: 'background' - will automatically log the user in (if all permissions have been accepted)
* `OAUTH3.urls.discover(providerUri, { client_id: clientUri })` generates a correctly parameterized url
* `OAUTH3.urls.implicitGrant(directives, { client_id: clientUri })` generates a correctly parameterized url OAUTH3.request({ method: 'GET', url: '', session: '', data: '' }) // make an authenticated request to a resource
* `OAUTH3.urls.refreshToken(directives, opts)` generates a correctly parameterized url
* `opts.client_id = clientUri` OAUTH3.logout(providerUri, { client_id: clientUri, session: session }) // opens a popup to confirm logout from the provider
* `opts.access_token = <jwt>` // Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this
* `opts.refresh_token = <jwt>`
OAUTH3.urls
.discover(providerUri, { client_id: clientUri }) // generates a correctly parameterized url
.implicitGrant(directives, { client_id: clientUri }) // generates a correctly parameterized url
.refreshToken(directives, opts) // generates a correctly parameterized url
// opts.client_id = clientUri
// opts.access_token = <jwt>
// opts.refresh_token = <jwt>
```
<!-- TODO implicit grant broker --> <!-- TODO implicit grant broker -->
<!-- TODO logout specific user --> <!-- TODO logout specific user -->
@ -178,16 +186,18 @@ DO NOT rely on them. Many of them WILL change (we just wanted to publish with th
Public utilities for browser and node.js: Public utilities for browser and node.js:
* `OAUTH3.jwt` ```
* `OAUTH3.jwt.decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl } OAUTH3.jwt
.decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl }
* `OAUTH3.utils` OAUTH3.utils
* `OAUTH3.utils.query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true` .query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true
* `OAUTH3.utils.scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'` .scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'
* `OAUTH3.utils.uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'` .uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'
* `OAUTH3.utils.url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'` .url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'
* `OAUTH3.utils.url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'` .url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'
* `OAUTH3.utils.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)` .atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)
```
Internal API Internal API
------------ ------------
@ -195,16 +205,18 @@ Internal API
This APIs will absolutely change before they are made public This APIs will absolutely change before they are made public
(at the very least the leading `_` will be removed) (at the very least the leading `_` will be removed)
* `OAUTH3.jwt` ```
* `OAUTH3.jwt.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl) OAUTH3.jwt
.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
* `OAUTH3.utils` OAUTH3.utils
* `OAUTH3.utils.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'` .url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'
* `OAUTH3.utils._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob` ._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob
* `OAUTH3.utils.randomState(); // a 128-bit crypto-random string` .randomState(); // a 128-bit crypto-random string
* `OAUTH3.utils._insecureRandomState(); // a fallback for randomState() in old browsers` ._insecureRandomState(); // a fallback for randomState() in old browsers
* `OAUTH3._browser` a collection of things a browser needs to perform requests OAUTH3._browser // a collection of things a browser needs to perform requests
```
Roadmap Roadmap
------- -------