143 lines
3.9 KiB
Markdown
143 lines
3.9 KiB
Markdown
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:
|
|
|
|
* `querystringify(query)`
|
|
* `stringifyscope(scope)`
|
|
|
|
URL generation:
|
|
|
|
* `authorizationCode`
|
|
* `authorizationRedirect`
|
|
* `implicitGrant`
|
|
* `loginCode`
|
|
* `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
|
|
----------
|
|
|
|
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.oauth.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 (elimitate #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.
|