WIP cleanup and doc

This commit is contained in:
AJ ONeal 2017-02-13 14:35:48 -05:00
parent a449358dd6
commit 3bded28847
4 changed files with 133 additions and 18 deletions

101
README.md
View File

@ -1,6 +1,88 @@
oauth3.js oauth3.js
========= =========
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 seemless experience.
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
------------
**Easy Install** for Web Apps (including Mobile):
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`
**Advanced Installation with `git`**
```
# Navigate to your web site or web app
pushd /path/to/your/web/app
# clone the project as assets/org.oauth3
mkdir -p assets
git clone git@git.daplie.com:Daplie/oauth3.js.git assets/org.oauth3
pushd assests/org.oauth3
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`**
```
# 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
```
Usage
-----
Update your HTML to include the the following script tags:
```
<script src="assets/org.oauth3/oauth3.js"></script>
<script src="assets/org.oauth3/oauth3.browser.js"></script>
```
If you use jQuery you should also include
```
<script src="assets/org.oauth3/oauth3.jquery.js"></script>
```
Stable API
----------
Public utilities for browser and node.js: Public utilities for browser and node.js:
* `querystringify(query)` * `querystringify(query)`
@ -14,6 +96,25 @@ URL generation:
* `loginCode` * `loginCode`
* `resourceOwnerPassword` * `resourceOwnerPassword`
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
URI vs URL URI vs URL
---------- ----------

View File

@ -13,7 +13,8 @@
} }
var browser = exports.OAUTH3_BROWSER = { var browser = exports.OAUTH3_BROWSER = {
clientUri: function (location) { window: window
, clientUri: function (location) {
return OAUTH3_CORE.normalizeUri(location.host + location.pathname); return OAUTH3_CORE.normalizeUri(location.host + location.pathname);
} }
, discover: function (providerUri, opts) { , discover: function (providerUri, opts) {
@ -133,12 +134,21 @@
, frameRequest: function (url, state, opts) { , frameRequest: function (url, state, opts) {
var promise; var promise;
if ('background' === opts.type) { if (!opts.windowType) {
opts.windowType = 'popup';
}
if ('background' === opts.windowType) {
promise = browser.insertIframe(url, state, opts); promise = browser.insertIframe(url, state, opts);
} else if ('popup' === opts.type) { } else if ('popup' === opts.windowType) {
promise = browser.openWindow(url, state, opts); promise = browser.openWindow(url, state, opts);
} else if ('inline' === opts.windowType) {
// callback function will never execute and would need to redirect back to current page
// rather than the callback.html
url += '&original_url=' + browser.window.location.href;
promise = browser.window.location = url;
} else { } else {
throw new Error("login framing method not specified or not type yet implemented"); throw new Error("login framing method options.windowType not specified or not type yet implemented");
} }
return promise.then(function (params) { return promise.then(function (params) {
@ -254,7 +264,7 @@
// //
// Logins // Logins
// //
, requests: { , authn: {
authorizationRedirect: function (providerUri, opts) { authorizationRedirect: function (providerUri, opts) {
// TODO get own directives // TODO get own directives
@ -483,14 +493,14 @@
, code: data.code , code: data.code
, access_token: data.accessToken , access_token: data.access_token
, expires_at: data.expiresAt , expires_at: data.expires_at
, expires_in: data.expiresIn , expires_in: data.expires_in
, scope: data.scope , scope: data.scope
, refresh_token: data.refreshToken , refresh_token: data.refresh_token
, refresh_expires_at: data.refreshExpiresAt , refresh_expires_at: data.refresh_expires_at
, refresh_expires_in: data.refreshExpiresIn , refresh_expires_in: data.refresh_expires_in
}); });
if ('token' === scope.appQuery.response_type) { if ('token' === scope.appQuery.response_type) {
@ -535,6 +545,7 @@
}, 50); }, 50);
} }
}; };
browser.requests = browser.authn;
Object.keys(browser).forEach(function (key) { Object.keys(browser).forEach(function (key) {
if ('requests' === key) { if ('requests' === key) {

View File

@ -233,7 +233,7 @@
console.log(grantResults); console.log(grantResults);
if (grantResults.data.error) { if (grantResults.data.error) {
window.alert('grantResults: ' + grantResults.data.errorDescription || grantResults.data.error.message); window.alert('grantResults: ' + grantResults.data.error_description || grantResults.data.error.message);
return; return;
} }

View File

@ -27,6 +27,7 @@
}; };
// TODO move recase out // TODO move recase out
/*
oauth3._recaseRequest = function (recase, req) { oauth3._recaseRequest = function (recase, req) {
// convert JavaScript camelCase to oauth3/ruby snake_case // convert JavaScript camelCase to oauth3/ruby snake_case
if (req.data && 'object' === typeof req.data) { if (req.data && 'object' === typeof req.data) {
@ -44,6 +45,7 @@
} }
return resp; return resp;
}; };
*/
oauth3.hooks = { oauth3.hooks = {
checkSession: function (preq, opts) { checkSession: function (preq, opts) {
@ -193,9 +195,9 @@
// TODO simplify (nix recase) // TODO simplify (nix recase)
oauth3.provideRequest = function (rawRequest, opts) { oauth3.provideRequest = function (rawRequest, opts) {
opts = opts || {}; opts = opts || {};
var Recase = exports.Recase || require('recase'); //var Recase = exports.Recase || require('recase');
// TODO make insensitive to providing exceptions // TODO make insensitive to providing exceptions
var recase = Recase.create({ exceptions: {} }); //var recase = Recase.create({ exceptions: {} });
function lintAndRequest(preq) { function lintAndRequest(preq) {
function goGetHer() { function goGetHer() {
@ -236,9 +238,10 @@
return lintAndRequest(req, opts); return lintAndRequest(req, opts);
} }
req = oauth3._recaseRequest(recase, req); //req = oauth3._recaseRequest(recase, req);
return lintAndRequest(req, opts).then(function (res) { return lintAndRequest(req, opts).then(function (res) {
return oauth3._recaseResponse(recase, res); //return oauth3._recaseResponse(recase, res);
return res;
}); });
}; };
@ -295,10 +298,10 @@
var prequest = core.urls.loginCode(directive, opts); var prequest = core.urls.loginCode(directive, opts);
return oauth3.request(prequest).then(function (res) { return oauth3.request(prequest).then(function (res) {
// result = { uuid, expiresAt } // result = { uuid, expires_at }
return { return {
otpUuid: res.data.uuid otpUuid: res.data.uuid
, otpExpires: res.data.expiresAt , otpExpires: res.data.expires_at
}; };
}); });
}); });