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)
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`
2. Inside of `assets` create another folder called `org.oauth3`
3. Download [oauth.js-v1.zip](https://git.daplie.com/Daplie/oauth3.js/repository/archive.zip?ref=v1)
4. Double-click to unzip the folder.
5. Copy `oauth3.js` and `oauth3.browser.js` to `assets/org.oauth3`
1. Create a folder for your project named after your app, such as `example.com/`
2. Inside of the folder `example.com/` a folder called `assets/`
3. Inside of the folder `example.com/assets` a folder called `org.oauth3/`
4. Download [oauth.js-v1.zip](https://git.daplie.com/Daplie/oauth3.js/repository/archive.zip?ref=v1)
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`**
@ -63,40 +198,13 @@ ln -sf ../bower_components/oauth3/.well-known/oauth3 .well-known/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
-----
Update your HTML to include the the following script tag:
```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:
@ -169,13 +277,46 @@ We've created an `Oauth3` service just for you:
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`.
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 -->
```
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.
@ -203,7 +344,7 @@ OAUTH3.urls
<!-- TODO request(providerUri, 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
@ -217,13 +358,24 @@ Public utilities for browser and node.js:
OAUTH3.jwt
.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
.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)
```
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
@ -236,11 +388,12 @@ This APIs will absolutely change before they are made public
OAUTH3.jwt
.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'
._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob
.randomState(); // a 128-bit crypto-random string
._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
```

6
oauth3.core.js
View File

@ -937,7 +937,7 @@
location = OAUTH3._browser.window.location;
}
return {
var result = {
_clientUri: OAUTH3.clientUri(location)
, _providerUri: null
, init: function (location) {
@ -1003,6 +1003,10 @@
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));

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