README.md

jquery-cordova-oauth2

jQuery plugin for doing Oauth2 login in a Cordova App

This jquery plugin can be used to perform Oauth2 login in Cordova app, it uses Cordova In-App-Browser Plugin to perform Oauth2 login flow and returns access_token or error in callback, along with actual response from the Oauth2 service.

Features

• Supports Oauth2 authorization code grant flow (server explicit)

• Supports Oauth2 implicit grant flow (client implicit)

  [Implicit grant is recomended for Cordova apps since it does not require app to store client_secret]

Usage

    $.oauth2({
        auth_url: '',           // required
        response_type: '',      // required  - "code"/"token"
        token_url: '',          // required for response_type ="code"
        logout_url: '',         // recommended if available
        client_id: '',          // required
        client_secret: '',      // required for response_type ="code"
        redirect_uri: '',       // required - any dummy url http://www.yourcompany.com
        other_params: {}         // optional params object for scope, state, ...
    }, function(token, response){
        // do something with token or response
    }, function(error, response){
        // do something with error object
    }); 

Example Oauth2 Calls:

1) Facebook Oauth2 (Implicit grant): Notice that token_url and client_secret is not required for Implicit grant and logout_url is not specified since facebook does not not have a logout url. Facebook also required a special display parameter to be passed in the URL, this is specified in the other_params. The first callback function will return the access_token which can be passed to another function to save and make other API calls. The second callback function handle any errors.

    $.oauth2({
        auth_url: 'https://www.facebook.com/dialog/oauth',
        response_type: 'token',
        client_id: 'CLIENT-ID-FROM-FACEBOOK',
        redirect_uri: 'http://www.yourwebsite.com/redirect',
        other_params: {scope: 'basic_info', display: 'popup'}
    }, function(token, response){
        makeAPICalls(token);
    }, function(error, response){
        alert(error);
    }); 

2) Google Oauth2 (Implicit grant): Notice that token_url and client_secret is not required for Implicit grant and logout_url is specified, this will make sure that Google logout is called before showing Google login option.

    $.oauth2({
        auth_url: 'https://accounts.google.com/o/oauth2/auth',
        response_type: 'token',
        logout_url: 'https://accounts.google.com/logout',
        client_id: 'CLIENT-ID-FROM-GOOGLE',
        redirect_uri: 'http://www.yourwebsite.com/redirect',
        other_params: {scope: 'profile'}
    }, function(token, response){
        makeAPICalls(token);
    }, function(error, response){
        alert(error);
    }); 

3) LinkedIn Oauth2 (Authorization code grant): This example show how to make LinkedIn Oauth2 call, notice the scope parameter is sepcified in the other_params option as an object, linkedIn also requires state parameter, this is also specified in the other_params.

WARNING: Authorization code grant is not recomended for Cordova apps since the client_secret is exposed in the code and anyone can unpack an Adroid APK for example and get your client_secret. Always check if the service supports Implicit grant type of Oauth2 and use it instead of authorization code grant for your Cordova app.

    $.oauth2({
        auth_url: 'https://www.linkedin.com/uas/oauth2/authorization',
        response_type: 'code',
        token_url: 'https://www.linkedin.com/uas/oauth2/accessToken',
        client_id: 'CLIENT-ID-FROM-LINKEDIN',
        client_secret: 'CLIENT-SECRET-FROM-LINKEDIN',
        redirect_uri: 'http://www.yourwebsite.com/redirect',
        other_params: {scope: 'r_basicprofile', state: 'somethingrandom1234'}
    }, function(token, response){
        makeAPICalls(token);
    }, function(error, response){
        alert(error);
    }); 

How to build app and test?

1. Build App using Intel XDK:

• Download this repo.
• Download and install Intel XDK.
• Open Intel XDK > New Project > Import and point to this folder.
• Open index.html in editor and update Oauth2 options (client_id, client_secret, ...) for the service you want to test.
• Add In-App-Browser Cordova plugin from the project settings.
• Test in the Intel XDK Emulator.
• Build your Cordova app by going to Build tab in Intel XDK.
• Install App on device.

2. Build App using Phonegap build:

• Download this repo.
• Open index.html in any editor and update Oauth2 options (client_id, client_secret, ...) for the service you want to test.
• Zip files index.html, cordova.oauth2.js and config.xml.
• Upload the zip in http://build.phonegap.com to build Cordova App.
• Install App on device.

3. Build App using Cordova CLI:

• Download this repo.
• Follow intructions to build app using Cordova CLI
• Add In-App-Browser Cordova plugin
• Install App on device.

Services Tested

These Oauth2 services have been tested with this plugin sucessfully:

• Google
• Facebook
• Instagram
• Foursquare
• LinkedIn

here is example code

* Let me know if any service is not working, feel free to send any pull-request for improvements.