search

oauthjs / angular-oauth2

AngularJS OAuth2
MIT License
595 stars 187 forks source link
angular authentication oauth2

readme

angular-oauth2 Build Status

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:

Usage

1. Download angular-oauth2 dependencies.

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

2. Include angular-oauth2 and dependencies.
<script src="https://github.com/oauthjs/angular-oauth2/raw/master/<VENDOR_FOLDER>/angular/angular.min.js"></script>
<script src="https://github.com/oauthjs/angular-oauth2/raw/master/<VENDOR_FOLDER>/angular-cookies/angular-cookies.min.js"></script>
<script src="https://github.com/oauthjs/angular-oauth2/raw/master/<VENDOR_FOLDER>/query-string/query-string.js"></script>
<script src="https://github.com/oauthjs/angular-oauth2/raw/master/<VENDOR_FOLDER>/angular-oauth2/dist/angular-oauth2.min.js"></script>
3. Configure OAuth (optional) 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
    });
  }]);

You can also configure OAuth service in a .run() block, in case you retrieve the Oauth server configuration from a ajax request.

angular.module('myApp', ['angular-oauth2'])
  .run(['OAuth', function(OAuth) {
    OAuth.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

Update configuration defaults:

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

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:

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