2017-01-17 22:46:01 -05:00
|
|
|
oauth3.js
|
|
|
|
|
=========
|
|
|
|
|
|
2017-11-10 11:50:09 -07:00
|
|
|
| *oauth3.js*
|
|
|
|
|
| [issuer.html](https://git.oauth3.org/OAuth3/issuer.html)
|
|
|
|
|
| [issuer.rest.walnut.js](https://git.oauth3.org/OAuth3/issuer.rest.walnut.js)
|
2017-11-13 10:52:00 -07:00
|
|
|
| [issuer.srv](https://git.oauth3.org/OAuth3/issuer.srv)
|
2017-11-10 11:50:09 -07:00
|
|
|
| Sponsored by [Daplie](https://daplie.com)
|
|
|
|
|
|
2017-02-13 14:35:48 -05: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
|
2017-03-07 14:54:08 -07:00
|
|
|
(and almost all OAuth2 providers) with a seamless experience.
|
2017-02-13 14:35:48 -05: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 15:32:45 -07:00
|
|
|
If you have no idea what you're doing
|
2017-02-13 14:35:48 -05:00
|
|
|
------------
|
|
|
|
|
|
2017-02-21 15:32:45 -07: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/`
|
2017-11-09 15:25:19 -07:00
|
|
|
3. Inside of the folder `example.com/assets` a folder called `oauth3.org/`
|
2017-11-10 12:47:29 -07:00
|
|
|
4. Download [oauth3.js-v1.zip](https://git.oauth3.org/OAuth3/oauth3.js/repository/archive.zip?ref=v1)
|
2017-02-21 15:32:45 -07:00
|
|
|
5. Double-click to unzip the folder.
|
2017-11-09 15:25:19 -07:00
|
|
|
6. Copy the file `oauth3.core.js` into the folder `example.com/assets/oauth3.org/`
|
2017-02-21 15:32:45 -07:00
|
|
|
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)
|
2017-11-09 15:25:19 -07:00
|
|
|
9. Add `<script src="assets/oauth3.org/oauth3.core.js"></script>` to your `index.html`
|
2017-02-21 15:32:45 -07:00
|
|
|
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>
|
2017-11-09 15:25:19 -07:00
|
|
|
<script src="assets/oauth3.org/oauth3.core.js"></script>
|
2017-02-21 15:32:45 -07:00
|
|
|
<script src="app.js"></script>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
```
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07: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 14:35:48 -05:00
|
|
|
|
|
|
|
|
|
2017-02-21 15:32:45 -07: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
|
2017-06-14 22:39:26 +00:00
|
|
|
return oauth3.setIdentityProvider(providerUri);
|
2017-02-21 15:32:45 -07:00
|
|
|
}
|
2017-02-13 14:35:48 -05:00
|
|
|
|
|
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
// This opens up the login window for the specified provider
|
|
|
|
|
//
|
|
|
|
|
function onClickLogin() {
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
return oauth3.authenticate().then(function (session) {
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
console.info('Authentication was Successful:');
|
|
|
|
|
console.log(session);
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-03-07 14:54:08 -07:00
|
|
|
// You can use the PPID (or preferably a hash of it) as the login for your app
|
2017-02-21 15:32:45 -07: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 14:35:48 -05:00
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
return oauth3.request({
|
2017-11-09 15:25:19 -07:00
|
|
|
url: 'https://oauth3.org/api/issuer@oauth3.org/inspect'
|
2017-02-21 15:32:45 -07:00
|
|
|
, session: session
|
|
|
|
|
}).then(function (resp) {
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
console.info("Inspect Token:");
|
|
|
|
|
console.log(resp.data);
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
});
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
}, function (err) {
|
|
|
|
|
console.error('Authentication Failed:');
|
|
|
|
|
console.log(err);
|
|
|
|
|
});
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
}
|
2017-02-13 14:35:48 -05:00
|
|
|
|
|
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
// This opens up the logout window
|
|
|
|
|
//
|
|
|
|
|
function onClickLogout() {
|
|
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
return oauth3.logout().then(function () {
|
2017-02-21 15:32:45 -07: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 14:35:48 -05:00
|
|
|
```
|
|
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
Copy the `example.com/` folder to your webserver.
|
|
|
|
|
|
|
|
|
|
|
2017-02-15 11:09:08 -07: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 15:32:45 -07:00
|
|
|
├── .well-known (hidden)
|
2017-02-15 11:09:08 -07:00
|
|
|
│ └── oauth3
|
|
|
|
|
│ ├── callback.html
|
|
|
|
|
│ ├── directives.json
|
|
|
|
|
│ └── index.html
|
|
|
|
|
├── assets
|
|
|
|
|
│ └── org.oauth3
|
2017-02-21 15:32:45 -07:00
|
|
|
│ └── oauth3.core.js
|
2017-02-15 11:09:08 -07:00
|
|
|
│
|
|
|
|
|
│
|
|
|
|
|
├── css
|
|
|
|
|
│ └── main.css
|
|
|
|
|
├── index.html
|
|
|
|
|
└── js
|
|
|
|
|
└── app.js
|
|
|
|
|
```
|
|
|
|
|
|
2017-02-21 15:32:45 -07: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 13:55:29 -06:00
|
|
|
git clone git@git.daplie.com:OAuth3/oauth3.js.git assets/org.oauth3
|
2017-03-07 14:54:08 -07:00
|
|
|
pushd assets/org.oauth3
|
2017-02-21 15:32:45 -07: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 14:35:48 -05:00
|
|
|
Usage
|
|
|
|
|
-----
|
|
|
|
|
|
2017-02-14 16:19:21 -07:00
|
|
|
Update your HTML to include the the following script tag:
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-14 16:19:21 -07:00
|
|
|
```html
|
2017-02-21 15:32:45 -07:00
|
|
|
<script src="assets/org.oauth3/oauth3.core.js"></script>
|
2017-02-13 14:35:48 -05:00
|
|
|
```
|
|
|
|
|
|
2017-02-14 16:19:21 -07: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 16:19:21 -07: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 16:19:21 -07: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);
|
|
|
|
|
|
2017-03-07 14:54:08 -07:00
|
|
|
// You can use the PPID (or preferably a hash of it) as the login for your app
|
2017-02-14 16:19:21 -07: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({
|
2017-08-10 20:54:34 +00:00
|
|
|
url: 'https://oauth3.org/api/issuer@oauth3.org/inspect_token'
|
2017-02-14 16:19:21 -07:00
|
|
|
, session: session
|
|
|
|
|
}).then(function (resp) {
|
2017-02-13 14:35:48 -05:00
|
|
|
|
2017-02-14 16:19:21 -07: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 14:35:48 -05:00
|
|
|
```
|
2017-02-14 16:19:21 -07:00
|
|
|
|
2017-07-07 11:45:37 -06: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 16:19:21 -07: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 14:35:48 -05:00
|
|
|
```
|
|
|
|
|
|
2017-08-10 20:35:24 +00:00
|
|
|
```js
|
|
|
|
|
// Require the module as 'oauth3.org'
|
|
|
|
|
var app = angular.module('myAppName', [ 'ui.router', 'oauth3.org' ]);
|
|
|
|
|
|
|
|
|
|
// Require services and other submodules in the form {modulename}@oauth3.org
|
|
|
|
|
app.controller('authCtrl', [ '$scope', 'azp@oauth3.org', function ($scope, Oauth3) { /* ... */ } ]);
|
|
|
|
|
|
|
|
|
|
// For backwards compatibility with older angular applications that rely on string-name introspection
|
|
|
|
|
// you can also use the camel case version of the names in the format {Modulename}Oauth3
|
|
|
|
|
app.controller('authCtrl', function ($scope, AzpOauth3) { /* ... */ });
|
|
|
|
|
```
|
|
|
|
|
|
2017-02-14 16:19:21 -07: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 14:35:48 -05:00
|
|
|
|
2017-02-21 15:32:45 -07: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.
|
|
|
|
|
|
|
|
|
|
```
|
2017-06-14 22:39:26 +00:00
|
|
|
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 15:32:45 -07:00
|
|
|
|
2017-08-10 20:35:24 +00:00
|
|
|
promise = oauth3.init(opts); // set and fetch your own site/app's configuration details
|
|
|
|
|
// promises your site's config // opts = { location, session, issuer, audience }
|
2017-02-21 15:32:45 -07:00
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
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 15:32:45 -07:00
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
promise = oauth3.setResourceProvider(url); // changes the Resource Provider URI (the site you're getting stuff from)
|
2017-02-21 15:32:45 -07:00
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
promise = oauth3.setProvider(url); // changes the both Identity and Resource Provider URI together
|
2017-02-21 15:32:45 -07:00
|
|
|
|
2017-06-14 22:39:26 +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 15:32:45 -07:00
|
|
|
|
2017-06-14 22:39:26 +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 15:32:45 -07:00
|
|
|
|
2017-08-10 21:15:54 +00:00
|
|
|
promise = oauth3.request({ url, method, data }); // make an (authorized) arbitrary request to an audience's resource
|
2017-06-14 22:39:26 +00:00
|
|
|
// (contacts, photos, whatever)
|
|
|
|
|
|
2017-08-10 21:15:54 +00:00
|
|
|
promise = oauth3.api(apiname, opts); // make an (authorized) well-known api call to an audience
|
|
|
|
|
// See https://labs.daplie.com/docs/ for API schemas
|
|
|
|
|
// Ex: oauth3.api('dns.list', { sld: 'daplie', tld: 'com' });
|
|
|
|
|
|
|
|
|
|
// TODO
|
|
|
|
|
api = await oauth3.package(audience, schemaname); // make an (authorized) well-known api call to an audience
|
|
|
|
|
// Ex: api = await oauth3.package('domains.daplie.com', 'dns@oauth3.org');
|
|
|
|
|
// api.list({ sld: 'mydomain', tld: 'com' });
|
|
|
|
|
|
|
|
|
|
|
2017-06-14 22:39:26 +00:00
|
|
|
promise = oauth3.logout(); // opens logout window for the provider
|
|
|
|
|
|
|
|
|
|
oauth3.session(); // returns the current session, if any
|
2017-02-21 15:32:45 -07:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Real API
|
2017-02-13 14:35:48 -05:00
|
|
|
----------
|
|
|
|
|
|
2017-02-14 16:19:21 -07:00
|
|
|
<!-- hooks -->
|
|
|
|
|
|
2017-02-15 10:50:53 -07:00
|
|
|
```
|
2017-02-21 15:32:45 -07:00
|
|
|
OAUTH3.clientUri(window.location); // produces the default `client_uri` of your app (also used as `client_id`)
|
2017-02-15 10:50:53 -07: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 16:19:21 -07:00
|
|
|
|
|
|
|
|
<!-- TODO implicit grant broker -->
|
|
|
|
|
<!-- TODO logout specific user -->
|
|
|
|
|
<!-- TODO request(providerUri, opts) -->
|
|
|
|
|
<!-- TODO login/logout(directives, opts) ? -->
|
|
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
Core API (staging)
|
2017-02-14 16:19:21 -07: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-17 22:46:01 -05:00
|
|
|
Public utilities for browser and node.js:
|
|
|
|
|
|
2017-02-15 10:50:53 -07:00
|
|
|
```
|
|
|
|
|
OAUTH3.jwt
|
|
|
|
|
.decode('<urlSafeBase64-encoded-json-web-token>'); // { iat, iss, aud, sub, exp, ttl }
|
|
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
OAUTH3
|
2017-02-15 10:50:53 -07: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 15:32:45 -07: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 10:50:53 -07:00
|
|
|
```
|
2017-01-17 22:46:01 -05:00
|
|
|
|
2017-02-14 16:19:21 -07: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 10:50:53 -07:00
|
|
|
```
|
|
|
|
|
OAUTH3.jwt
|
|
|
|
|
.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
|
2017-02-14 16:19:21 -07:00
|
|
|
|
2017-02-21 15:32:45 -07:00
|
|
|
OAUTH3
|
2017-02-15 10:50:53 -07: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 15:32:45 -07: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 16:19:21 -07:00
|
|
|
|
2017-02-15 10:50:53 -07:00
|
|
|
OAUTH3._browser // a collection of things a browser needs to perform requests
|
|
|
|
|
```
|
2017-02-07 14:19:57 -05:00
|
|
|
|
2017-02-13 14:35:48 -05: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 16:19:21 -07:00
|
|
|
URL generation:
|
|
|
|
|
|
|
|
|
|
* `authorizationCode`
|
|
|
|
|
* `authorizationRedirect`
|
|
|
|
|
* `implicitGrant`
|
|
|
|
|
* `loginCode`
|
|
|
|
|
* `resourceOwnerPassword`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2017-02-07 14:19:57 -05:00
|
|
|
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`:
|
|
|
|
|
|
2017-08-10 20:54:34 +00:00
|
|
|
1. https://example.com/api/issuer@oauth3.org
|
|
|
|
|
2. example.com/api/issuer@oauth3.org/ (not unique)
|
|
|
|
|
3. /api/issuer@oauth3.org
|
|
|
|
|
4. api/issuer@oauth3.org (not unique)
|
2017-02-07 14:19:57 -05:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2017-03-07 14:54:08 -07:00
|
|
|
A potential work-around would be to assume all paths are relative (eliminate #4 instead)
|
2017-02-07 14:19:57 -05:00
|
|
|
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.
|
