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 -->
* `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.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
* `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.request({ method: 'GET', url: '', session: '', data: '' })` make an authenticated request to a resource
* `OAUTH3.logout(providerUri, { client_id: clientUri, session: session })` opens a popup to confirm logout from the provider
* Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this
* `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.urls.refreshToken(directives, opts)` generates a correctly parameterized url
* `opts.client_id = clientUri`
* `opts.access_token = <jwt>`
* `opts.refresh_token = <jwt>`
```
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.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
// 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.request({ method: 'GET', url: '', session: '', data: '' }) // make an authenticated request to a resource
OAUTH3.logout(providerUri, { client_id: clientUri, session: session }) // opens a popup to confirm logout from the provider
// Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this
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 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:
* `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.query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true`
* `OAUTH3.utils.scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'`
* `OAUTH3.utils.uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'`
* `OAUTH3.utils.url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'`
* `OAUTH3.utils.url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'`
* `OAUTH3.utils.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)`
OAUTH3.utils
.query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true
.scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'
.uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'
.url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'
.url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'
.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)
```
Internal API
------------
@ -195,16 +205,18 @@ Internal API
This APIs will absolutely change before they are made public
(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.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'`
* `OAUTH3.utils._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob`
* `OAUTH3.utils.randomState(); // a 128-bit crypto-random string`
* `OAUTH3.utils._insecureRandomState(); // a fallback for randomState() in old browsers`
OAUTH3.utils
.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'
._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob
.randomState(); // a 128-bit crypto-random string
._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
-------