search

fullstackreact / react-native-oauth

A react-native wrapper for social authentication login for both Android and iOS
https://fullstackreact.com
MIT License
802 stars 214 forks source link

readme

react-native-oauth

The react-native-oauth library provides an interface to OAuth 1.0 and OAuth 2.0 providers with support for the following providers for React Native apps:

TL;DR;

This library cuts out the muck of dealing with the OAuth 1.0 and OAuth 2.0 protocols in react-native apps. The API is incredibly simple and straight-forward and is intended on getting you up and running quickly with OAuth providers (such as Facebook, Github, Twitter, etc).

import OAuthManager from 'react-native-oauth';

const manager = new OAuthManager('firestackexample')
manager.configure({
  twitter: {
    consumer_key: 'SOME_CONSUMER_KEY',
    consumer_secret: 'SOME_CONSUMER_SECRET'
  },
  google: {
    callback_url: `io.fullstack.FirestackExample:/oauth2redirect`,
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_SECRET'
  }
});

// ...
manager.authorize('google', {scopes: 'profile email'})
.then(resp => console.log('Your users ID'))
.catch(err => console.log('There was an error'));

Help

Due to other time contraints, I cannot continue to work on react-native-oauth for the time it deserves. If you're interested in supporting this library, please help! It's a widely used library and I'd love to continue supporting it. Looking for maintainers!

Features

Installation

Install react-native-oauth in the usual manner using npm:

npm install --save react-native-oauth

As we are integrating with react-native, we have a little more setup to integrating with our apps.

iOS setup

Important: This will not work if you do not complete all the steps:

RCTLinkingManager

Since react-native-oauth depends upon the RCTLinkingManager (from react-native core), we'll need to make sure we link this in our app.

In your app, add the following line to your HEADER SEARCH PATHS:

$(SRCROOT)/../node_modules/react-native-oauth/ios/OAuthManager
$(SRCROOT)/../node_modules/react-native/Libraries/LinkingIOS

Next, navigate to the neighboring "Build Phases" section of project settings, find the "Link Binary with Library" drop down, expand it, and click the "+" to add libOAuthManager.a to the list.

Make sure to Update your AppDelegate.m as below, otherwise it will not work.

Automatically with rnpm

To automatically link our react-native-oauth client to our application, use the rnpm tool. rnpm is a React Native package manager which can help to automate the process of linking package environments.

react-native link react-native-oauth

Note: due to some restrictions on iOS, this module requires you to install cocoapods. The process has been semi-automated through using the above react-native link command.

Once you have linked this library, run the following command in the root directory:

(cd ios && pod install)

Open in xcode the created .xcworkspace in the ios/ directory (NOT THE .xproj file) when it's complete.

When working on iOS 10, we'll need to enable Keychain Sharing Entitlement in Capabilities of the build target of io.fullstack.oauth.AUTH_MANAGER.

Handle deep linking loading

Required step

We'll need to handle app loading from a url with our app in order to handle authentication from other providers. That is, we'll need to make sure our app knows about the credentials we're authenticating our users against when the app loads after a provider is authenticated against.

iOS setup

We need to add a callback method in our ios/AppDelegate.m file and then call our OAuthManager helper method. Let's load the ios/AppDelegate.m file and add the following all the way at the bottom (but before the @end):

// Add the import at the top:
#import "OAuthManager.h"
// ...
@implementation AppDelegate
// ...
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
  return [OAuthManager handleOpenUrl:application
                             openURL:url
                   sourceApplication:sourceApplication
                          annotation:annotation];
}

In addition, we'll need to set up the handlers within the iOS app. Add the following line somewhere in your application:didFinishLaunchingWithOptions: method, like so:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  NSURL *jsCodeLocation;

  jsCodeLocation = [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index.ios" fallbackResource:nil];

  // other existing setup here

  // ADD THIS LINE SOMEWHERE IN THIS FUNCTION
  [OAuthManager setupOAuthHandler:application];
  // ...

  [self.window makeKeyAndVisible];
  return YES;
}

When our app loads up with a request that is coming back from OAuthManager and matches the url pattern, OAuthManager will take over and handle the rest and storing the credentials for later use.

Adding URL schemes

In order for our app to load through these callbacks, we need to tell our iOS app that we want to load them. In order to do that, we'll have to create some URL schemes to register our app. Some providers require specific schemes (mentioned later).

These URL schemes can be added by navigating to to the info panel of our app in Xcode (see screenshot).

Let's add the appropriate one for our provider. For instance, to set up twitter, add the app name as a URL scheme in the URL scheme box.

Android setup

After we link react-native-oauth to our application, we're ready to go. Android integration is much simpler, thanks to the in-app browser ability for our apps. react-native-oauth handles this for you.

One note, all of the callback urls follow the scheme: http://localhost/[provider_name]. Make sure this is set as a configuration for each provider below (documented in the provider setup sections).

Make sure you add the following to your android/build.gradle file:

maven { url "https://jitpack.io" }

For instance, an example android/build.gradle file would look like this:

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
  // ...
}

allprojects {
    repositories {
        mavenLocal()
        jcenter()
        maven { url "https://jitpack.io" } // <~ ADD THIS LINE
        maven {
            url "$rootDir/../node_modules/react-native/android"
        }
    }
}

Creating the manager

In our JS, we can create the manager by instantiating a new instance of it using the new method and passing it the name of our app:

const manager = new OAuthManager('firestackexample')

We need to pass the name of our app as the oauth manager uses this to create callback keys. This must match the URL route created in your iOS app. For instance, above we created a URL scheme for Twitter. Pass this as the string in the OAuthManager constructor.

Configuring our providers

Providers, such as Facebook require some custom setup for each one. The following providers have been implemented and we're working on making more (and making it easier to add more, although the code is not impressively complex either, so it should be relatively simple to add more providers).

In order to configure providers, the react-native-oauth library exports the configureProvider() method, which accepts two parameters and returns a promise:

  1. The provider name, such as twitter and facebook
  2. The provider's individual credentials

For instance, this might look like:

const config =  {
  twitter: {
    consumer_key: 'SOME_CONSUMER_KEY',
    consumer_secret: 'SOME_CONSUMER_SECRET'
  },
  facebook: {
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
}
// Create the manager
const manager = new OAuthManager('firestackexample')
// configure the manager
manager.configure(config);

The consumer_key and consumer_secret values are generally provided by the provider development program. In the case of twitter, we can create an app and generate these values through their development dashboard.

Implemented providers

The following list are the providers we've implemented thus far in react-native-oauth and the required keys to pass when configuring the provider:

Twitter (iOS/Android)

To authenticate against twitter, we need to register a Twitter application. Register your twitter application (or create a new one at apps.twitter.com).

Once you have created one, navigate to the application and find the Keys and Access Tokens. Take note of the consumer key and secret:

For the authentication to work properly, you need to set the Callback URL. It doesn't matter what you choose as long as its a valid url.

Twitter's URL scheme needs to be the app name (that we pass into the constructor method). Make sure we have one registered in Xcode as the same name:

Add these values to the authorization configuration to pass to the configure() method as:

const config =  {
  twitter: {
    consumer_key: 'SOME_CONSUMER_KEY',
    consumer_secret: 'SOME_CONSUMER_SECRET'
  }
}

Facebook (iOS/Android)

To add facebook authentication, we'll need to have a Facebook app. To create one (or use an existing one), navigate to developers.facebook.com/.

Find or create an application and find the app id. Take note of this app id. Next, navigate to the Settings panel and find your client_secret.

Before we leave the Facebook settings, we need to tell Facebook we have a new redirect url to register. Navigate to the bottom of the page and add the following into the bundle ID field:

fb{YOUR_APP_ID}

For instance, my app ID in this example is: 1745641015707619. In the Bundle ID field, I have added fb1745641015707619.

For Android, you will also need to set the redirect url to http://localhost/facebook in the Facebook Login settings.

We'll need to create a new URL scheme for Facebook and (this is a weird bug on the Facebook side) the facebook redirect URL scheme must be the first one in the list. The URL scheme needs to be the same id as the Bundle ID copied from above:

Back in our application, add the App ID and the secret as:

const config =  {
  facebook: {
    client_id: 'YOUR_APP_ID',
    client_secret: 'YOUR_APP_SECRET'
  }
}

Google (iOS)

To add Google auth to our application, first we'll need to create a google application. Create or use an existing one by heading to the developers.google.com/ page (or the console directly at https://console.developers.google.com).

We need to enable the Identity Toolkit API API. Click on Enable API and add this api to your app. Once it's enabled, we'll need to collect our credentials.

Navigate to the Credentials tab and create a new credential. Create an iOS API credential. Take note of the client_id and the iOS URL scheme. In addition, make sure to set the bundle ID as the bundle id in our application in Xcode:

Take note of the iOS URL Scheme. We'll need to add this as a URL scheme in our app. In the Info panel of our app target (in Xcode), add the URL scheme:

Finally, add the client_id credential as the id from the url page as well as the ios scheme (with any path) in our app configuration:

const config =  {
  google: {
    callback_url: `[IOS SCHEME]:/google`,
    client_id: 'YOUR_CLIENT_ID'
  }
}

Google (Android)

To set up Google on Android, follow the same steps as before, except this time instead of creating an iOS API, create a web api credential. Make sure to add the redirect url at the bottom (it defaults to http://localhost/google):

When creating an Android-specific configuration, create a file called config/development.android.js. React Native will load it instead of the config/development.js file automatically on Android.

Github (iOS/Android)

Adding Github auth to our application is pretty simple as well. We'll need to create a web application on the github apps page, which can be found at https://github.com/settings/developers. Create one, making sure to add two apps (one for iOS and one for Android) with the callback urls as:

Take note of the client_id and client_secret

The iOS URL Scheme is the same as the twitter version, which means we'll just add the app name as a URL scheme (i.e. firestackexample).

Add the client_id and client_secret credentials to your configuration object:

const config =  {
  github: {
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
}

Slack

We'll need to create an app first. Head to the slack developer docs at https://slack.com/developers.

Click on the Getting Started button:

From here, find the create an app link:

Take note of the client_id and the client_secret. We'll place these in our configuration object just like so:

const config =  {
  slack: {
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
}

Lastly, Slack requires us to add a redirect_url.

For iOS: the callback_url pattern is ${app_name}://oauth, so make sure to add your redirect_url where it asks for them before starting to work with the API.

for Android: the callback_url pattern is http://localhost/slack. Be sure to add this to your list of redirect urls.

Authenticating against our providers

We can use the manager in our app using the authorize() method on the manager.

The authorize method takes two arguments (the first one is required):

For example:

manager.authorize('twitter')
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

This method returns a promise that is resolved once the authentication has been completed. You'll get access to the authentication keys in the resp object.

The resp object is set as follows:

{
  status: "ok",
  response: {
    authorized: true, (boolean)
    uuid: "UUID", (user UUID)
    credentials: {
      access_token: "access token",
      refresh_token: "refresh token",
      type: 1
    }
  }
}

The second argument accepts an object where we can ask for additional scopes, override default values, etc.

manager.authorize('google', {scopes: 'email,profile'})
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

Calling a provider's API

We can use OAuthManager to make requests to endpoints from our providers as well. For instance, let's say we want to get a user's time line from twitter. We would make the request to the url https://api.twitter.com/1.1/statuses/user_timeline.json

If our user has been authorized for thi request, we can execute the request using the credentials stored by the OAuthManager.

The makeRequest() method accepts 3 parameters:

  1. The provider we're making a request to
  2. The url (or path) we want to make the request
  3. Any additional options

We can pass a list of options for our request with the last argument. The keys OAuthManager recognizes are:

  1. params - The query parameters
  2. method - The http method to make the request with.

Available HTTP methods:

const userTimelineUrl = 'https://api.twitter.com/1.1/statuses/user_timeline.json';
manager
  .makeRequest('twitter', userTimelineUrl)
  .then(resp => {
    console.log('Data ->', resp.data);
  });

"me" represents the authenticated user, in any call to the Google+ API

const googleUrl = 'https://www.googleapis.com/plus/v1/people/me';
manager
  .makeRequest('google', googleUrl)
    .then(resp => {
      console.log('Data -> ', resp.data);
    });

It's possible to use just the path as well. For instance, making a request with Facebook at the /me endpoint can be:

manager
  .makeRequest('facebook', '/me')
  .then(resp => {
    console.log('Data ->', resp.data);
  });

To add more data to our requests, we can pass a third argument:

manager
  .makeRequest('facebook', '/me', {
    headers: { 'Content-Type': 'application/java' },
    params: { email: 'me+rocks@ari.io' }
  })
  .then(resp => {
    console.log('Data ->', resp.data);
  });

Getting authorized accounts

Since OAuthManager handles storing user accounts, we can query it to see which accounts have already been authorized or not using savedAccounts():

manager.savedAccounts()
  .then(resp => {
    console.log('account list: ', resp.accounts);
  })

deauthorize()

We can deauthorize() our user's from using the provider by calling the deauthorize() method. It accepts a single parameter:

  1. The provider we want to remove from our user credentials.
manager.deauthorize('twitter');

Adding your own providers

To add your own providers you can use the addProvider() method and fill in your provider details:

manager.addProvider({
    'name_of_provider': {
        auth_version: '2.0',
        authorize_url: 'https://provider.dev/oauth',
        access_token_url: 'https://provider.dev/oauth/token',
        callback_url: ({app_name}) => `${app_name}://oauth`,
    }
});

Contributing

This is open-source software and we can make it rock for everyone through contributions.

git clone https://github.com/fullstackreact/react-native-oauth.git
cd react-native-oauth
npm install

TODOS: