oauth3.js/README.md

471 lines
15 KiB
Markdown
Raw Normal View History

2017-01-18 03:46:01 +00:00
oauth3.js
=========
2017-02-13 19:35:48 +00:00
The world's smallest, fastest, and most secure OAuth3 (and OAuth2) JavaScript implementation
(Yes! works in browsers and node.js with no extra dependencies or bloat and no hacks!)
Instead of bloating your webapp and ruining the mobile experience,
you can use a single, small javascript file for all OAuth3 providers
(and almost all OAuth2 providers) with a seamless experience.
2017-02-13 19:35:48 +00:00
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.
2017-02-21 22:32:45 +00:00
If you have no idea what you're doing
2017-02-13 19:35:48 +00:00
------------
2017-02-21 22:32:45 +00:00
(people who know what they're doing should skip ahead to the tl;dr instructions)
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 [oauth3.js-v1.zip](https://git.daplie.com/OAuth3/oauth3.js/repository/archive.zip?ref=v1)
2017-02-21 22:32:45 +00:00
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>
```
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
`app.js`:
```js
var OAUTH3 = window.OAUTH3;
var auth = OAUTH3.create(window.location); // use window.location to set Client URI (your app's id)
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
// 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 oauth3.setIdentityProvider(providerUri);
2017-02-21 22:32:45 +00:00
}
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
// This opens up the login window for the specified provider
//
function onClickLogin() {
2017-02-13 19:35:48 +00:00
return oauth3.authenticate().then(function (session) {
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
console.info('Authentication was Successful:');
console.log(session);
2017-02-13 19:35:48 +00:00
// You can use the PPID (or preferably a hash of it) as the login for your app
2017-02-21 22:32:45 +00:00
// (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);
2017-02-13 19:35:48 +00:00
return oauth3.request({
2017-02-21 22:32:45 +00:00
url: 'https://oauth3.org/api/org.oauth3.provider/inspect'
, session: session
}).then(function (resp) {
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
console.info("Inspect Token:");
console.log(resp.data);
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
});
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
}, function (err) {
console.error('Authentication Failed:');
console.log(err);
});
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
}
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
// This opens up the logout window
//
function onClickLogout() {
return oauth3.logout().then(function () {
2017-02-21 22:32:45 +00:00
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);
2017-02-13 19:35:48 +00:00
```
2017-02-21 22:32:45 +00:00
Copy the `example.com/` folder to your webserver.
2017-02-15 18:09:08 +00:00
Example
-------
If you had a simple website / webapp for `example.com` with only the most necessary files,
it might look like this:
```
example.com
2017-02-21 22:32:45 +00:00
├── .well-known (hidden)
2017-02-15 18:09:08 +00:00
│   └── oauth3
│   ├── callback.html
│   ├── directives.json
│   └── index.html
├── assets
│   └── org.oauth3
2017-02-21 22:32:45 +00:00
│   └── oauth3.core.js
2017-02-15 18:09:08 +00:00
├── css
│   └── main.css
├── index.html
└── js
└── app.js
```
2017-02-21 22:32:45 +00:00
Installation (if you know what you're doing)
------------
**Advanced Installation with `git`**
```bash
# Navigate to your web site or web app
pushd /path/to/your/web/app
# clone the project as assets/org.oauth3
mkdir -p assets
2017-06-14 19:55:29 +00:00
git clone git@git.daplie.com:OAuth3/oauth3.js.git assets/org.oauth3
pushd assets/org.oauth3
2017-02-21 22:32:45 +00:00
git checkout v1
popd
# symlink `.well-known/oauth3` to `assets/org.oauth3/.well-known/oauth3`
mkdir -p .well-known
ln -sf ../assets/org.oauth3/.well-known/oauth3 .well-known/oauth3
```
**Advanced Installation with `bower`**
```bash
# Install to bower_components
bower install oauth3
# create a `.well-known` folder and an `assets` folder
mkdir -p .well-known assets
# symlink `.well-known/oauth3` to `bower_components/oauth3/.well-known/oauth3`
ln -sf ../bower_components/oauth3/.well-known/oauth3 .well-known/oauth3
# symlink `assets/org.oauth3` to `bower_components/oauth3`
ln -sf ../bower_components/oauth3/.well-known/oauth3 .well-known/oauth3
ln -sf ../bower_components/oauth3 assets/org.oauth3
```
2017-02-13 19:35:48 +00:00
Usage
-----
2017-02-14 23:19:21 +00:00
Update your HTML to include the the following script tag:
2017-02-13 19:35:48 +00:00
2017-02-14 23:19:21 +00:00
```html
2017-02-21 22:32:45 +00:00
<script src="assets/org.oauth3/oauth3.core.js"></script>
2017-02-13 19:35:48 +00:00
```
2017-02-14 23:19:21 +00:00
You can create a very simple demo application like this:
```javascript
var providerUri;
2017-02-19 04:48:46 +00:00
var opts = { client_uri: OAUTH3.utils.clientUri(window.location) };
2017-02-14 23:19:21 +00:00
// 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) {
providerUri = _providerUri;
2017-02-19 04:48:46 +00:00
return OAUTH3.discover(providerUri, opts); // just to cache
2017-02-14 23:19:21 +00:00
}
// This opens up the login window for the specified provider
//
function onClickLogin() {
return OAUTH3.implicitGrant(providerUri, opts).then(function (session) {
console.info('Authentication was Successful:');
console.log(session);
// You can use the PPID (or preferably a hash of it) as the login for your app
2017-02-14 23:19:21 +00:00
// (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 OAUTH3.request({
url: 'https://oauth3.org/api/org.oauth3.provider/inspect_token'
, session: session
}).then(function (resp) {
2017-02-13 19:35:48 +00:00
2017-02-14 23:19:21 +00:00
console.info("Inspect Token:");
console.log(resp.data);
});
}, function (err) {
console.error('Authentication Failed:');
console.log(err);
});
}
// initialize the provider to be oauth3.org (or any compatible provider)
//
onChangeProvider('oauth3.org');
2017-02-13 19:35:48 +00:00
```
2017-02-14 23:19:21 +00:00
2017-07-07 17:45:37 +00:00
A user's e-mail can be passed into the clientParams object as `clientParams.subject`.
To auto-populate the e-mail input of the login popup, make sure the input has the class `js-oauth3-email`.
Example:
```js
if (clientParams.subject) {
$('.js-oauth3-email').val(clientParams.subject);
$('.js-authn-show').prop('disabled', false);
}
```
2017-02-14 23:19:21 +00:00
### Compatibility with Frameworks and Libraries
**jQuery**:
You're all set. Nothing else is needed.
**Angular 1**:
We've created an `Oauth3` service just for you:
```html
<script src="assets/org.oauth3/oauth3.ng.js"></script>
2017-02-13 19:35:48 +00:00
```
2017-02-14 23:19:21 +00:00
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`.
2017-02-13 19:35:48 +00:00
2017-02-21 22:32:45 +00:00
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.
```
oauth3 = 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
2017-02-21 22:32:45 +00:00
promise = oauth3.init(location); // set and fetch your own site/app's configuration details
2017-02-21 22:32:45 +00:00
// promises your site's config
promise = oauth3.setIdentityProvider(url); // changes the Identity 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
2017-02-21 22:32:45 +00:00
promise = oauth3.setResourceProvider(url); // changes the Resource Provider URI (the site you're getting stuff from)
2017-02-21 22:32:45 +00:00
promise = oauth3.setProvider(url); // changes the both Identity and Resource Provider URI together
2017-02-21 22:32:45 +00:00
promise = oauth3.authenticate(); // opens login window for the provider and returns a session
// (must be called after the setIdentityProvider promise has completed)
2017-02-21 22:32:45 +00:00
promise = oauth3.authorize(permissions); // authenticates (if not authenticated) and opens a window to
// authorize a particular scope (contacts, photos, whatever)
2017-02-21 22:32:45 +00:00
promise = oauth3.request({ url, method, data }); // make an (authorized) request to a provider's resource
// (contacts, photos, whatever)
promise = oauth3.logout(); // opens logout window for the provider
oauth3.session(); // returns the current session, if any
2017-02-21 22:32:45 +00:00
```
Real API
2017-02-13 19:35:48 +00:00
----------
2017-02-14 23:19:21 +00:00
<!-- hooks -->
2017-02-15 17:50:53 +00:00
```
2017-02-21 22:32:45 +00:00
OAUTH3.clientUri(window.location); // produces the default `client_uri` of your app (also used as `client_id`)
2017-02-15 17:50:53 +00:00
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>
```
2017-02-14 23:19:21 +00:00
<!-- TODO implicit grant broker -->
<!-- TODO logout specific user -->
<!-- TODO request(providerUri, opts) -->
<!-- TODO login/logout(directives, opts) ? -->
2017-02-21 22:32:45 +00:00
Core API (staging)
2017-02-14 23:19:21 +00:00
----------
These APIs are NOT yet public, stable APIs, but they are good to be aware of
and may help with debugging.
DO NOT rely on them. Many of them WILL change (we just wanted to publish with things as they are).
2017-01-18 03:46:01 +00:00
Public utilities for browser and node.js:
2017-02-15 17:50:53 +00:00
```
OAUTH3.jwt
.decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl }
2017-02-21 22:32:45 +00:00
OAUTH3
2017-02-15 17:50:53 +00:00
.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'
2017-02-21 22:32:45 +00:00
```
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)
2017-02-15 17:50:53 +00:00
```
2017-01-18 03:46:01 +00:00
2017-02-14 23:19:21 +00:00
Internal API
------------
This APIs will absolutely change before they are made public
(at the very least the leading `_` will be removed)
2017-02-15 17:50:53 +00:00
```
OAUTH3.jwt
.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
2017-02-14 23:19:21 +00:00
2017-02-21 22:32:45 +00:00
OAUTH3
2017-02-15 17:50:53 +00:00
.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'
.randomState(); // a 128-bit crypto-random string
._insecureRandomState(); // a fallback for randomState() in old browsers
2017-02-21 22:32:45 +00:00
._base64.atob('<non-urlsafe-base64-string>'); // '<binary-string>' (typically json ascii)
._base64.decodeUrlSafe(b64); // makes base64 safe for window.atob and then calls atob
2017-02-14 23:19:21 +00:00
2017-02-15 17:50:53 +00:00
OAUTH3._browser // a collection of things a browser needs to perform requests
```
2017-02-13 19:35:48 +00:00
Roadmap
-------
* v1.0 - "implicit grant" authorization with examples
* popup
* iframe
* documentation
* v1.1 - cleanup
* in-flow discovery
* smallest possible size
* inline windowing (non-promisable callback)
* async set/get
* logout
* v1.2 - features
* "authorization code" flow
* "broker" flow
* v1.3 - features
* remove grants
2017-02-14 23:19:21 +00:00
URL generation:
* `authorizationCode`
* `authorizationRedirect`
* `implicitGrant`
* `loginCode`
* `resourceOwnerPassword`
URI vs URL
----------
See <https://danielmiessler.com/study/url-uri/#gs.=MngfAk>
Since we do not require the `protocol` to be specified, it is a URI
However, we do have a problem of disambiguation since a URI may look like a `path`:
1. https://example.com/api/org.oauth3.provider
2. example.com/api/org.oauth3.provider/ (not unique)
3. /api/org.oauth3.provider
4. api/org.oauth3.provider (not unique)
Therefore anywhere a URI or a Path could be used, the URI must be a URL.
We eliminate #2.
As a general rule I don't like rules that sometimes apply and sometimes don't,
so I may need to rethink this. However, there are cases where including the protocol
can be very ugly and confusing and we definitely need to allow relative paths.
A potential work-around would be to assume all paths are relative (eliminate #4 instead)
and have the path always key off of the base URL - if oauth3 directives are to be found at
https://example.com/username/.well-known/oauth3/directives.json then /api/whatever would refer
to https://example.com/username/api/whatever.