Skip to content

Latest commit

 

History

History
194 lines (143 loc) · 5.22 KB

README.md

File metadata and controls

194 lines (143 loc) · 5.22 KB
Raw

angular-oauth2 Build Status

AngularJS OAuth2 authentication module written in ES6.

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.

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.min.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',
  storage:'cookies', // options: 'cookies', 'localstorage', 'sessionstorage'
  options: {
    secure: true // optional, is valid if you're using cookies storage
  }
});

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. bower install
  4. Do your magic.
  5. Run the tests: gulp test.
  6. Build: gulp build
  7. Create a Pull Request.

The source files are written in ES6.

Reference