jQuery OAuth

A $.ajax wrapper for OAuth 2 access and refresh token management for use in a SPA.

What

This is a library for storing access token client side and use it for $.ajax requests. Secondly, it is a library for requesting new access tokens upon expiration.

Guide

I have written an extensive blog post about writing a web app using Lumen that utilizes this library for client side management of tokens.

Building a web app with Lumen web API and OAuth2 authentication

Dependencies

• jQuery 1.5+
• store.js 1.3.17

Features

• Stores access token client side using store.js for persistence between refreshes
• Adds authorization header to ajax requests
• Adds CSRF token to header requests if provided to protect access token
• When access token expires all 401 requests are buffered and fired after a new access token is generated by using refresh token server side
• Works with AMD modules

Installation

Can be installed via bower package

bower install --save jquery-oauth-spiria

... or by NPM

npm install --save jquery-oauth-spiria

... or by grabbing a zip of the latest release

Usage

OAuth has to be implemented server side. If using Laravel, I recommend the great library oauth-server-laravel by Luca Degasperi (@lucadegasperi).

Have an endpoint that issues access tokens. Remember do NOT send client_id and client_secret with the request. Send the request to a proxy endpoint that sends the request to the OAuth endpoint. Remember do NOT save the refresh token client side. Save this as an encrypted httponly cookie and use a proxy to send this to the OAuth endpoint when refreshing access tokens.

Example of resource owner implementation in a SPA

Somewhere where things are initialised

define([/*other dependencies,*/ "jquery-oauth", function(jqOAuth){
	/* other initialisation */

	var csrfToken = $("input[name='_token']").val();	

	var auth = new jqOAuth({
        csrfToken: csrfToken,
        tokenName : 'WebServiceUsingOauth' ,
            // Optional. You might want to set a name for your jquery-oauth instance if
            // you intend on having multiple instances for multiple web services.
            // This name will be used for store.js's storage. 
        filters: {
            url : function(url) {
                // The ajax's request url is received to determine whether or not
                // the Authorization header should be added.
                // Returning true will add the header.
            }
        },
        events: {
            login: function() {
                // User is hereby logged in and the 
                // access token will be added to subsequent
                // $.ajax calls, until a new token cannot 
                // be acquired or auth.logout() is called.
            },
            logout: function() {
                // auth.logout() has been called and the 
                // authorization headers are removed from 
                // $.ajaxSettings. Tokens are removed from
                // localStorage.
            },
            tokenExpiration: function() {
	            // this event is fired when 401 calls are 
	            // received from the server. Has to return 
	            // an ajax promise. 
	            // New tokens are set with auth.setAccessToken()
	            
                return $.post("/refresh-token-proxy-endpoint").success(function(response){
                    auth.setAccessToken(response.accessToken, response.accessTokenExpiration);
                });
            }
        }
    });
});

Login form (when form is submitted)

$.ajax({
   url: "/access-token-proxy-endpoint",
   method: "POST",
   data: {
       username: "username-from-a-form",
       password: "password-from-a-form"
   },
   statusCode: {
       200: function(response) {
           auth.login(response.accessToken, response.accessTokenExpiration);
       },
       401: function() {
           alert("The username or password were not correct. Try again.");
       }
   }
});

Logout

auth.logout();

API

These calls are available through auth

define(['jquery-oauth'], function(auth){
    // The access token and expiration in seconds
    // Sets authorization headers and stores tokens
    auth.login(accessToken, accessTokenExpiration);

   // Removes headers from $.ajax and tokens from localStorage
   auth.logout();

   // Initialize library
   var auth = new jqOAuth({
       csrfToken: "token" //CSRF token,
       events: {
           logout: function(){},
           login:  function(){},
           tokenExpiration: function(){}
       }	
   });

   // Sets new tokens - should be used with tokenExpiration event
   auth.setAccessToken(accessToken, accessTokenExpiration);

   // Checks for tokens
   auth.hasAccessToken();
   auth.hasAccessTokenExpiration();
});

Thank you

The library addresses OAuth problems in general. Many of these are outlined in this great article: OAuth2 with Angular the right way

Also, the refresh token functionality takes great inspiration in this great AngularJS library: angular-http-auth

So thank you Jeremy Marc (@jeremymarc) and Witold Szczerba (@witoldsz)

License

Copyright © 2015 Esben Petersen & Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.