About

This project provides an implementation of an client-side (implicit grant)

OAuth 2.0 authorization flow.

Features

* Retrieval of a user's token using popups using the promise-based

``Token.getTokenByPopup()`` function, that presents the user with the

authorization endpoint and returns the token asynchronously.

(Implementation detail: A successfully obtained access token is handed back

to the parent window via ``window.opener.postMessage`` and the source and

origin of the sending window are verified by the parent.)

* Access token verification using ``Token.verifyAsync``, by requesting token

information from the authorization server, verifying that the token

is valid and that it was generated by the current client (to prevent the

confused deputy problem).

* Storage and retrieval of tokens via the `Token.get` and `Token.set`

calls in the `Token` service.

* A preconfigured module for use with Google authentication. Check out the

`example/js/demo.js <example/js/demo.js>`_ and

`example/demo.html <example/js/demo.html>`_ for an example.

Demo

1. Run a static file server in the root directory (the one this file is in)

on ``localhost:9000``. Python 2.X: ``python -m SimpleHTTPServer 9000``.

2. Navigate to http://localhost:9000/example/demo.html.

Google authentication quickstart

1. Create a project in the `Google APIs Console`_. In the "API Access" tab

of the console, create an OAuth 2.0 client ID. When prompted, set the

following settings:

* **Application Type**: Web application.

* **Site or Hostname**: The location at which you'll host these files.

2. Edit authorized redirect URIs and JavaScript origins to match where you

will be hosting your site. For example, let's say you're planning to

host your site at https://example.com/. In that case, you might upload

the `angular-oauth` code to https://example.com/angular-oauth/. You would

then set your client ID settings accordingly:

* **Authorized Redirect URIs**:

https://example.com/angular-oauth/oauth2callback.html

* **Authorized JavaScript Origins**: https://example.com

3. Add ``googleOauth`` as a dependency to your app.

4. Configure the ``TokenProvider`` with the following minimal settings:

* `clientId`: (Required.) The client ID of your application, as given

by your authentication server.

* `redirectUri`: (Required.) The URI to redirect back to. You normally

have to configure your authorization server to ensure that it redirects

back to this point.

* `scopes`: (Optional.) A list of scope tokens to describe the scope

of the access request (more concretely, what information will be

requested.) The scopes available for a given service are probably

documented by the authorization server.

For example::

5. After doing this, you can inject the ``Token`` service and enjoy its methods:

* Request a token with ``Token.getTokenByPopup()``, which returns a

promise that resolves to an object with an ``access_token`` item.

* Verify that this is a valid token for your application by calling

``Token.verifyAsync(accessToken)``, which returns a promise that

resolves to the response of `Google's TokenInfo service`_.

* If you're able to verify the token, persist it in the browser using

``Token.set(accessToken)``.

* Then when you need that token (e.g., to authorize a web service call),

call ``Token.get()``.

.. _Google APIs Console: https://code.google.com/apis/console/

.. _Google's TokenInfo service: https://developers.google.com/accounts/docs/OAuth2UserAgent#validatetoken

Roadmap

This is a work in progress! Don't use it in production. Here's some of what's

yet to be done:

* Security. While some mechanisms have been implemented to prevent token

stealing, the project needs a systematic review of weaknesses. Some things

to look out for are outlined in the OAuth specification, which also links

to other resources.

I also don't have intimate knowledge of the browser security model. The

isolation of ``localStorage``.

* Testing. Still lacking some confidence in this area, but soon enough

I'll need to do something about the lack of tests.

* Customization. Users may not always want to use popups. Perhaps taking

over the entire browser window is more appropriate in some cases. (The

reason for focusing on popup support is that tokens may expire, and ideally

reauthentication should be able to occur without interrupting the state of

the application.)

* Browser compatibility and fault-tolerance.

* I've tested all of one browser (Chrome).

* The library currently depends on ``localStorage`` and doesn't take

alternative measures if it's not available.

* Unexpected behaviors are not handled gracefully. For example, if the

user opens the callback page, they aren't presented with a friendly

message explaining what might have happened. Ideally, the popup would

notify the parent when it's closed (if that's even possible when the

site in the popup has a different origin.)

* It would be nice to support more authorization servers out of the box.

<html lang="en" ng-app="demo" ng-controller="DemoCtrl">

<meta charset="utf-8">

<title>Client-side authentication demo</title>

<input type="checkbox" id="askApproval" ng-model="askApproval" />

<label for="askApproval">Always ask me for approval (even if I've already given it)</label>

<div>

<button ng-click="authenticate()">Authenticate</button>

</div>

<div ng-show="accessToken" style="display: none">

<h1>You're authenticated!</h1>

<h2>Access token</h2>

<pre>{{accessToken}}</pre>

<div ng-show="expiresIn">

<h2>Expiry</h2>

<p>Expires in {{expiresIn}} seconds.</p>

</div>

</div>

<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.1.4/angular.js"></script>

<script src="js/demo.js"></script>

<script src="../src/js/googleOauth.js"></script>

<script src="../src/js/angularOauth.js"></script>

angular.module('demo', ['googleOauth']).

config(function(TokenProvider) {

// Demo configuration for the "angular-oauth demo" project on Google.

// Log in at will!

TokenProvider.extendConfig({

clientId: '191261111313.apps.googleusercontent.com',

redirectUri: 'http://localhost:9000/src/oauth2callback.html',

scopes: ["https://www.googleapis.com/auth/userinfo.email"]

});

}).

controller('DemoCtrl', function($scope, $window, Token) {

$scope.accessToken = Token.get();

$scope.authenticate = function() {

var extraParams = $scope.askApproval ? {approval_prompt: 'force'} : {};

Token.getTokenByPopup(extraParams)

.then(function(params) {

// Success getting token from popup.

var accessToken = params.access_token;

$scope.accessToken = accessToken;

$scope.expiresIn = params.expires_in;

// Verify the token before setting it, to avoid the confused deputy problem.

Token.verifyAsync(accessToken).

then(function(data) {

Token.set(accessToken);

}, function() {

alert("Failed to verify token.")

});

}, function() {

// Failure getting token from popup.

alert("Failed to get token from popup.");

});

};

});