README.md

angular-oauth2

AngularJS OAuth2 authentication module written in ES6.

Currently angular-oauth2 only uses the Resouce Owner Password Credential Grant, i.e, using a credentials combination (username, password), we'll request an access token (using grant_type='password') which, in case of success, will typically return a response such as:

{
  "access_token": "foobar",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "foobiz"
}

Internally we'll automatically store it as a cookie and it will be used in every request adding an Authorization header: Authorization: 'Bearer foobar'.

---

Installation

Choose your preferred method:

• Bower: bower install angular-oauth2
• NPM: npm install --save angular-oauth2
• Download: angular-oauth2

Usage

1. Download angular-oauth2 dependencies.

• angular
• angular-cookies
• query-string

If you're using bower they will be automatically downloaded upon installing this library.

2. Include angular-oauth2 and dependencies.

<script src="<VENDOR_FOLDER>/angular/angular.min.js"></script>
<script src="<VENDOR_FOLDER>/angular-cookies/angular-cookies.min.js"></script>
<script src="<VENDOR_FOLDER>/query-string/query-string.js"></script>
<script src="<VENDOR_FOLDER>/angular-oauth2/dist/angular-oauth2.min.js"></script>

3. Configure OAuth (required) and OAuthToken (optional):

angular.module('myApp', ['angular-oauth2'])
  .config(['OAuthProvider', function(OAuthProvider) {
    OAuthProvider.configure({
      baseUrl: 'https://api.website.com',
      clientId: 'CLIENT_ID',
      clientSecret: 'CLIENT_SECRET' // optional
    });
  }]);

4. Catch OAuth errors and do something with them (optional):

angular.module('myApp', ['angular-oauth2'])
  .run(['$rootScope', '$window', 'OAuth', function($rootScope, $window, OAuth) {
    $rootScope.$on('oauth:error', function(event, rejection) {
      // Ignore `invalid_grant` error - should be catched on `LoginController`.
      if ('invalid_grant' === rejection.data.error) {
        return;
      }

      // Refresh token when a `invalid_token` error occurs.
      if ('invalid_token' === rejection.data.error) {
        return OAuth.getRefreshToken();
      }

      // Redirect to `/login` with the `error_reason`.
      return $window.location.href = '/login?error_reason=' + rejection.data.error;
    });
  }]);

API

OAuthProvider

Configuration defaults:

OAuthProvider.configure({
  baseUrl: null,
  clientId: null,
  clientSecret: null,
  grantPath: '/oauth2/token',
  revokePath: '/oauth2/revoke'
});

OAuth

Check authentication status:

/**
 * Verifies if the `user` is authenticated or not based on the `token`
 * cookie.
 *
 * @return {boolean}
 */

OAuth.isAuthenticated();

Get an access token:

/**
 * Retrieves the `access_token` and stores the `response.data` on cookies
 * using the `OAuthToken`.
 *
 * @param {object} user - Object with `username` and `password` properties.
 * @param {object} config - Optional configuration object sent to `POST`.
 * @return {promise} A response promise.
 */

OAuth.getAccessToken(user, options);

Refresh access token:

/**
 * Retrieves the `refresh_token` and stores the `response.data` on cookies
 * using the `OAuthToken`.
 *
 * @return {promise} A response promise.
 */

OAuth.getRefreshToken()

Revoke access token:

/**
 * Revokes the `token` and removes the stored `token` from cookies
 * using the `OAuthToken`.
 *
 * @return {promise} A response promise.
 */

OAuth.revokeToken()

NOTE: An event oauth:error will be sent everytime a responseError is emitted:

• { status: 400, data: { error: 'invalid_request' }
• { status: 400, data: { error: 'invalid_grant' }
• { status: 401, data: { error: 'invalid_token' }
• { status: 401, headers: { 'www-authenticate': 'Bearer realm="example"' } }

OAuthTokenProvider

OAuthTokenProvider uses angular-cookies to store the cookies. Check the available options.

Configuration defaults:

OAuthTokenProvider.configure({
  name: 'token',
  options: {
    secure: true
  }
});

OAuthToken

If you want to manage the token yourself you can use OAuthToken service. Please check the OAuthToken source code to see all the available methods.

Contributing & Development

Contribute

Found a bug or want to suggest something? Take a look first on the current and closed issues. If it is something new, please submit an issue.

Develop

It will be awesome if you can help us evolve angular-oauth2. Want to help?

1. Fork it.
2. npm install.
3. Do your magic.
4. Run the tests: gulp test.
5. Build: gulp build
6. Create a Pull Request.

The source files are written in ES6.

Reference

• http://tools.ietf.org/html/rfc2617
• http://tools.ietf.org/html/rfc6749
• http://tools.ietf.org/html/rfc6750
• https://tools.ietf.org/html/rfc7009