react-native-app-auth

What is react-native-app-auth?

The react-native-app-auth package is a React Native bridge for the AppAuth-iOS and AppAuth-Android SDKs for communicating with OAuth 2.0 and OpenID Connect providers. It allows developers to authenticate users and obtain access tokens for accessing protected resources.

What are react-native-app-auth's main functionalities?

Authorization Code Flow

This feature allows you to perform the Authorization Code Flow, which is a common OAuth 2.0 flow for obtaining access tokens. The code sample demonstrates how to configure the authorization request and handle the response.

{
  "import": "import { authorize } from 'react-native-app-auth';",
  "config": "const config = {\n  issuer: 'https://accounts.google.com',\n  clientId: 'YOUR_CLIENT_ID',\n  redirectUrl: 'com.yourapp:/oauth2redirect',\n  scopes: ['openid', 'profile']\n};",
  "authorize": "authorize(config).then(result => console.log(result)).catch(error => console.error(error));"
}

Token Refresh

This feature allows you to refresh an access token using a refresh token. The code sample shows how to use the refresh function to obtain a new access token.

{
  "import": "import { refresh } from 'react-native-app-auth';",
  "refreshToken": "refresh(config, { refreshToken: 'YOUR_REFRESH_TOKEN' }).then(result => console.log(result)).catch(error => console.error(error));"
}

Revoke Token

This feature allows you to revoke an access or refresh token. The code sample demonstrates how to revoke a token using the revoke function.

{
  "import": "import { revoke } from 'react-native-app-auth';",
  "revokeToken": "revoke(config, { tokenToRevoke: 'YOUR_ACCESS_TOKEN', sendClientId: true }).then(() => console.log('Token revoked')).catch(error => console.error(error));"
}

Other packages similar to react-native-app-auth

react-native-oauth

react-native-oauth is another package for handling OAuth authentication in React Native apps. It supports multiple OAuth providers and offers a simpler API for common authentication tasks. However, it may not be as actively maintained or as feature-rich as react-native-app-auth, which is specifically designed to work with the AppAuth SDKs.

react-native-firebase

react-native-firebase provides a comprehensive suite of tools for integrating Firebase services into React Native apps, including authentication. While it offers OAuth support through Firebase Authentication, it is more focused on Firebase's ecosystem and may not provide the same level of customization for OAuth flows as react-native-app-auth.

README

React Native App Auth

React Native bridge for AppAuth-iOS and AppAuth-Android SDKS for communicating with OAuth 2.0 and OpenID Connect providers.

This library should support any OAuth provider that implements the OAuth2 spec and it has been tested with:

• Identity Server4 (Example configuration)
• Google (Example configuration)

The library uses auto-discovery which mean it relies on the the .well-known/openid-configuration endpoint to discover all auth endpoints automatically. It will be possible to extend the library later to add custom configuration.

Why you may want to use this library

AppAuth is a mature OAuth client implementation that follows the best practices set out in RFC 8252 - OAuth 2.0 for Native Apps including using SFAuthenticationSession and SFSafariViewController on iOS, and Custom Tabs on Android. WebViews are explicitly not supported due to the security and usability reasons explained in Section 8.12 of RFC 8252.

AppAuth also supports the PKCE ("Pixy") extension to OAuth which was created to secure authorization codes in public clients when custom URI scheme redirects are used.

Supported methods

See Usage for example configurations, and the included Example application for a working sample.

authorize

This is the main function to use for authentication. Invoking this function will do the whole login flow and returns the access token, refresh token and access token expiry date when successful, or it throws an error when not successful.

import AppAuth from 'react-native-app-auth';

const appAuth = new AppAuth(config);
const result = await appAuth.authorize(scopes);
// returns accessToken, accessTokenExpirationDate and refreshToken

refresh

This method will refresh the accessToken using the refreshToken. Some auth providers will also give you a new refreshToken

const result = await appAuth.refresh(refreshToken, scopes);
// returns accessToken, accessTokenExpirationDate and (maybe) refreshToken

revokeToken

This method will revoke a token. The tokenToRevoke can be either an accessToken or a refreshToken

// note, sendClientId=true will only be required when using IdentityServer
const result = await appAuth.revokeToken(tokenToRevoke, sendClientId);

Getting started

npm install react-native-app-auth --save
react-native link react-native-app-auth

Then follow the Setup steps to configure the native iOS and Android projects.

If you are not using react-native link, perform the Manual installation steps instead.

Manual installation

iOS

• In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
• Go to node_modules ➜ react-native-app-auth and add RNAppAuth.xcodeproj
• In XCode, in the project navigator, select your project. Add libRNAppAuth.a to your project's Build Phases ➜ Link Binary With Libraries
• Run your project (Cmd+R)<

Android

• Open up android/app/src/main/java/[...]/MainActivity.java

• Add import com.reactlibrary.RNAppAuthPackage; to the imports at the top of the file
• Add new RNAppAuthPackage() to the list returned by the getPackages() method

• Append the following lines to android/settings.gradle:

  include ':react-native-app-auth'
  project(':react-native-app-auth').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-app-auth/android')
  

• Insert the following lines inside the dependencies block in android/app/build.gradle:

    compile project(':react-native-app-auth')
  

Setup

iOS Setup

To setup the iOS project, you need to perform three steps:

• Install native dependencies
• Register redirect URL scheme
• Define openURL callback in AppDelegate

Install native dependencies

This library depends on the native AppAuth-ios project. To keep the React Native library agnostic of your dependency management method, the native libraries are not distributed as part of the bridge.

AppAuth supports three options for dependency management.

CocoaPods

With CocoaPods, add the following line to your Podfile:

pod 'AppAuth', '>= 0.91'

Then run pod install. Note that version 0.91 is the first of the library to support iOS 11.

Carthage

With Carthage, add the following line to your Cartfile:

github "openid/AppAuth-iOS" "master"

Then run carthage bootstrap.

Static Library

You can also use AppAuth-iOS as a static library. This requires linking the library and your project and including the headers. Suggested configuration:

• Create an XCode Workspace.
• Add AppAuth.xcodeproj to your Workspace.
• Include libAppAuth as a linked library for your target (in the "General -> Linked Framework and Libraries" section of your target).
• Add AppAuth-iOS/Source to your search paths of your target ("Build Settings -> "Header Search Paths").

Register redirect URL scheme

If you intend to support iOS 10 and older, you need to define the supported redirect URL schemes in your Info.plist as follows:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.your.app.identifier</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>io.identityserver.demo</string>
    </array>
  </dict>
</array>

• CFBundleURLName is any globally unique string. A common practice is to use your app identifier.
• CFBundleURLSchemes is an array of URL schemes your app needs to handle. The scheme is the beginning of your OAuth Redirect URL, up to the scheme separator (:) character.

Define openURL callback in AppDelegate

You need to have a property in your AppDelegate to hold the auth session, in order to continue the authorization flow from the redirect. To add this, open AppDelegate.h in your project and add the following lines:

+ @protocol OIDAuthorizationFlowSession;

  @interface AppDelegate : UIResponder <UIApplicationDelegate>
+ @property(nonatomic, strong, nullable) id<OIDAuthorizationFlowSession> currentAuthorizationFlow;
  @property (nonatomic, strong) UIWindow *window;
  @end

The authorization response URL is returned to the app via the iOS openURL app delegate method, so you need to pipe this through to the current authorization session (created in the previous instruction). To do this, open AppDelegate.m and add an import statement:

#import "AppAuth.h"

And in the bottom of the class, add the following handler:

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<NSString *, id> *)options {
  if ([_currentAuthorizationFlow resumeAuthorizationFlowWithURL:url]) {
    _currentAuthorizationFlow = nil;
    return YES;
  }
  return NO;
}

Android Setup

To setup the Android project, you need to perform two steps:

• Install Android support libraries
• Add redirect scheme manifest placeholder

Install Android support libraries

This library depends on the AppAuth-Android project. The native dependencies for Android are automatically installed by Gradle, but you need to add the correct Android Support library version to your project:

• Add the Google Maven repository in your android/build.gradle

  repositories {
    google()
  }
  

• Make sure the appcompat version in android/app/build.gradle matches the one expected by AppAuth. If you generated your project using react-native init, you may have an older version of the appcompat libraries and need to upgdrade:

  dependencies {
    compile "com.android.support:appcompat-v7:25.3.1"
  }
  

• If necessary, update the compileSdkVersion to 25:

  android {
    compileSdkVersion 25
  }
  

Add redirect scheme manifest placeholder

To capture the authorization redirect, add the following property to the defaultConfig in android/app/build.gradle:

android {
  defaultConfig {
    manifestPlaceholders = [
      appAuthRedirectScheme: 'io.identityserver.demo'
    ]
  }
}

The scheme is the beginning of your OAuth Redirect URL, up to the scheme separator (:) character.

Usage

import AppAuth from 'react-native-app-auth';

// initialise the client with your configuration
const appAuth = new AppAuth({
  issuer: '<YOUR_ISSUER_URL>',
  clientId: '<YOUR_CLIENT_ID',
  redirectUrl: '<YOUR_REDIRECT_URL>',
});

// use the client to make the auth request and receive the authState
try {
  const scopes = ['profile'];
  const result = await appAuth.authorize(scopes);
  // result includes accessToken, accessTokenExpirationDate and refreshToken
} catch (error) {
  console.log(error);
}

See example configurations for different providers below.

Identity Server 4

This library supports authenticating for Identity Server 4 out of the box. Some quirks:

• In order to enable refresh tokens, offline_access must be passed in as a scope variable
• In order to revoke the access token, we must sent client id in the method body of the request. This is not part of the OAuth spec.

// Note "offline_access" scope is required to get a refresh token
const scopes = ["openid", "profile", "offline_access"];
const appAuth = new AppAuth({
  issuer: "https://demo.identityserver.io",
  clientId: "native.code",
  redirectUrl: "io.identityserver.demo:/oauthredirect"
});

// Log in to get an authentication token
const authState = await appAuth.authorize(scopes);

// Refresh token
const refreshedState = appAuth.refresh(authState.refreshToken, scopes);

// Revoke token, note that Identity Server expects a client id on revoke
const sendClientIdOnRevoke = true;
await appAuth.revokeToken(refreshedState.refreshToken, sendClientIdOnRevoke);

Google

Full support out of the box.

const scopes = ["openid", "profile"];
const appAuth = new AppAuth({
  issuer: "https://accounts.google.com",
  clientId: "GOOGLE_OAUTH_APP_GUID.apps.googleusercontent.com",
  redirectUrl: "com.googleusercontent.apps.GOOGLE_OAUTH_APP_GUID:/oauth2redirect/google"
});

// Log in to get an authentication token
const authState = await appAuth.authorize(scopes);

// Refresh token
const refreshedState = appAuth.refresh(authState.refreshToken, scopes);

// Revoke token
await appAuth.revokeToken(refreshedState.refreshToken);

Contributors

Thanks goes to these wonderful people (emoji key):

Kadi Kraman 💻 📖 🚇 ⚠️ 👀 💡	Jani Eväkallio 💡 📖 ⚠️ 👀 🤔	Phil Plückthun 📖 👀 🤔	Imran Sulemanji 🤔 👀	JP 🤔 👀	Matt Cubitt 🤔 👀

This project follows the all-contributors specification. Contributions of any kind are welcome!