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

update docs

This commit is contained in:
AJ ONeal 2017-02-21 15:32:45 -07:00
parent 1d97d05eaa
commit 4eb078424a
3 changed files with 201 additions and 1051 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
README.md
View File

@ -12,16 +12,151 @@ Also, instead of complicated (or worse - insecure) CLI and Desktop login methods
you can easily integrate an OAuth3 flow (or broker) into any node.js app (i.e. Electron, Node-Webkit) you can easily integrate an OAuth3 flow (or broker) into any node.js app (i.e. Electron, Node-Webkit)
with 0 pain. with 0 pain.
Installation If you have no idea what you're doing
------------ ------------
**Easy Install** for Web Apps (including Mobile): (people who know what they're doing should skip ahead to the tl;dr instructions)
1. In your web site / web app folder create a folder called `assets` 1. Create a folder for your project named after your app, such as `example.com/`
2. Inside of `assets` create another folder called `org.oauth3` 2. Inside of the folder `example.com/` a folder called `assets/`
3. Download [oauth.js-v1.zip](https://git.daplie.com/Daplie/oauth3.js/repository/archive.zip?ref=v1) 3. Inside of the folder `example.com/assets` a folder called `org.oauth3/`
4. Double-click to unzip the folder. 4. Download [oauth.js-v1.zip](https://git.daplie.com/Daplie/oauth3.js/repository/archive.zip?ref=v1)
5. Copy `oauth3.js` and `oauth3.browser.js` to `assets/org.oauth3` 5. Double-click to unzip the folder.
6. Copy the file `oauth3.core.js` into the folder `example.com/assets/org.oauth3/`
7. Copy the folder `well-known` into the folder `example.com/`
8. Rename the folder `well-known` to `.well-known` (when you do this, it become invisible, that's okay)
9. Add `<script src="assets/org.oauth3/oauth3.core.js"></script>` to your `index.html`
9. Add `<script src="app.js"></script>` to your `index.html`
10. Create files in `example.com` called `app.js` and `index.html` and put this in it:
`index.html`:
```html
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<input type="url" placeholder="ex: https://oauth3.org" class="js-provider-uri">
<button type="button" class="js-login">Login</button>
<button type="button" class="js-logout">Logout</button>
<script src="https://code.jquery.com/jquery-3.1.1.js"
integrity="sha256-16cdPddA6VdVInumRGo6IbivbERE8p7CQR3HzTBuELA="
crossorigin="anonymous"></script>
<script src="assets/org.oauth3/oauth3.core.js"></script>
<script src="app.js"></script>
</body>
</html>
```
`app.js`:
```js
var OAUTH3 = window.OAUTH3;
var auth = OAUTH3.create(window.location); // use window.location to set Client URI (your app's id)
// this is any OAuth3-compatible provider, such as oauth3.org
// in v1.1.0 we'll add backwards compatibility for facebook.com, google.com, etc
//
function onChangeProvider(_providerUri) {
// example https://oauth3.org
return auth.setProvider(providerUri);
}
// This opens up the login window for the specified provider
//
function onClickLogin() {
return auth.authenticate().then(function (session) {
console.info('Authentication was Successful:');
console.log(session);
// You can use the PPID (or preferrably a hash of it) as the login for your app
// (it securely functions as both username and password which is known only by your app)
// If you use a hash of it as an ID, you can also use the PPID itself as a decryption key
//
console.info('Secure PPID (aka subject):', session.token.sub);
return auth.request({
url: 'https://oauth3.org/api/org.oauth3.provider/inspect'
, session: session
}).then(function (resp) {
console.info("Inspect Token:");
console.log(resp.data);
});
}, function (err) {
console.error('Authentication Failed:');
console.log(err);
});
}
// This opens up the logout window
//
function onClickLogout() {
return auth.logout().then(function () {
localStorage.clear();
console.info('Logout was Successful');
}, function (err) {
console.error('Logout Failed:');
console.log(err);
});
}
// initialize the provider to be oauth3.org (or any compatible provider)
//
onChangeProvider('oauth3.org');
$('body').on('click', '.js-login', onClickLogin);
$('body').on('click', '.js-logout', onClickLogout);
$('body').on('change', 'input.js-provider-uri', onChangeProvider);
```
Copy the `example.com/` folder to your webserver.
Example
-------
If you had a simple website / webapp for `example.com` with only the most necessary files,
it might look like this:
```
example.com
│
│
├── .well-known (hidden)
│   └── oauth3
│   ├── callback.html
│   ├── directives.json
│   └── index.html
├── assets
│   └── org.oauth3
│   └── oauth3.core.js
│
│
├── css
│   └── main.css
├── index.html
└── js
└── app.js
```
Installation (if you know what you're doing)
------------
**Advanced Installation with `git`** **Advanced Installation with `git`**
@ -63,40 +198,13 @@ ln -sf ../bower_components/oauth3/.well-known/oauth3 .well-known/oauth3
ln -sf ../bower_components/oauth3 assets/org.oauth3 ln -sf ../bower_components/oauth3 assets/org.oauth3
``` ```
Example
-------
If you had a simple website / webapp for `example.com` with only the most necessary files,
it might look like this:
```
example.com
│
│
├── .well-known
│   └── oauth3
│   ├── callback.html
│   ├── directives.json
│   └── index.html
├── assets
│   └── org.oauth3
│   └── oauth3.implicit.js
│
│
├── css
│   └── main.css
├── index.html
└── js
└── app.js
```
Usage Usage
----- -----
Update your HTML to include the the following script tag: Update your HTML to include the the following script tag:
```html ```html
<script src="assets/org.oauth3/oauth3.implicit.js"></script> <script src="assets/org.oauth3/oauth3.core.js"></script>
``` ```
You can create a very simple demo application like this: You can create a very simple demo application like this:
@ -169,13 +277,46 @@ We've created an `Oauth3` service just for you:
You can include that in addition to the standard file or, You can include that in addition to the standard file or,
if you don't want an extra request, just paste it into your `app.js`. if you don't want an extra request, just paste it into your `app.js`.
Stable API Simple API
----------
We include a small wrapper function of just a few lines in the bottom of `oauth3.core.js`
which exposes a `create` method to make using the underlying library require typing fewer keystrokes.
```
auth = OAUTH3.create(location); // takes a location object, such as window.location
// to create the Client URI (your app's id)
// and save it to an internal state
promise = auth.init(location); // set and fetch your own site/app's configuration details
// promises your site's config
promise = auth.setProvider(url); // changes the Provider URI (the site you're logging into),
// promises the provider's config // gets the config for that site (from their .well-known/oauth3),
// and caches it in internal state as the default
promise = auth.authenticate(); // opens login window for the provider and returns a session
// (must be called after the setProvider promise has completed)
promise = auth.authorize(permissions); // authenticates (if not authenticated) and opens a window to
// authorize a particular scope (contacts, photos, whatever)
promise = auth.request({ url, method, data }); // make an (authorized) request to a provider's resource
// (contacts, photos, whatever)
promise = auth.logout(); // opens logout window for the provider
auth.session(); // returns the current session, if any
```
Real API
---------- ----------
<!-- hooks --> <!-- hooks -->
``` ```
OAUTH3.utils.clientUri(window.location); // produces the default `client_uri` of your app (also used as `client_id`) OAUTH3.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.discover(providerUri, { client_id: clientUri }); // Promises the config file for the provider and caches it in memory.
@ -203,7 +344,7 @@ OAUTH3.urls
<!-- TODO request(providerUri, opts) --> <!-- TODO request(providerUri, opts) -->
<!-- TODO login/logout(directives, opts) ? --> <!-- TODO login/logout(directives, opts) ? -->
Staging API Core API (staging)
---------- ----------
These APIs are NOT yet public, stable APIs, but they are good to be aware of These APIs are NOT yet public, stable APIs, but they are good to be aware of
@ -217,13 +358,24 @@ Public utilities for browser and node.js:
OAUTH3.jwt OAUTH3.jwt
.decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl } .decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl }
OAUTH3.utils OAUTH3
.query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true .query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true
.scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts' .scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'
.uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect' .uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'
.url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect' .url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'
.url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api' .url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'
.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii) ```
Issuer API (staging)
-------------------
These additional methods are
```
OAUTH3
.query.parse('#/?foo=bar&baz=qux'); // { access_token: '...', debug: 'true' }
.scope.parse('profile,contacts'); // [ 'profile', 'contacts' ]
.url.redirect(clientParams, grants, tokenOrError); // securely redirect to client (or give security or other error)
``` ```
Internal API Internal API
@ -236,11 +388,12 @@ This APIs will absolutely change before they are made public
OAUTH3.jwt OAUTH3.jwt
.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl) .freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
OAUTH3.utils OAUTH3
.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect' .url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'
._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob
.randomState(); // a 128-bit crypto-random string .randomState(); // a 128-bit crypto-random string
._insecureRandomState(); // a fallback for randomState() in old browsers ._insecureRandomState(); // a fallback for randomState() in old browsers
._base64.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)
._base64.decodeUrlSafe(b64); // makes base64 safe for window.atob and then calls atob
OAUTH3._browser // a collection of things a browser needs to perform requests OAUTH3._browser // a collection of things a browser needs to perform requests
``` ```

6
oauth3.core.js
View File

@ -937,7 +937,7 @@
location = OAUTH3._browser.window.location; location = OAUTH3._browser.window.location;
} }
return { var result = {
_clientUri: OAUTH3.clientUri(location) _clientUri: OAUTH3.clientUri(location)
, _providerUri: null , _providerUri: null
, init: function (location) { , init: function (location) {
@ -1003,6 +1003,10 @@
return OAUTH3.logout(this._providerUri, opts); return OAUTH3.logout(this._providerUri, opts);
} }
}; };
result.authenticate = result.login;
result.authorize = result.login;
result.expire = result.logout;
return result;
}; };
}('undefined' !== typeof exports ? exports : window)); }('undefined' !== typeof exports ? exports : window));

1008
oauth3.implicit.js
View File

File diff suppressed because it is too large Load Diff

1
oauth3.implicit.js Symbolic link
View File

@ -0,0 +1 @@
oauth3.core.js