react-native-msal

react-native-msal

Live Demo (Web)

https://stashenergy.github.io/react-native-msal/

Getting started

Stable version: $ yarn add react-native-msal
Beta version : $ yarn add react-native-msal@beta

Requires React Native >=0.61

Setup

Common Setup

Before setting up your React Native app, you must register your application in the Azure Portal.

Android Setup

1. Register a redirect URI for your application for Android in the Azure Portal. It will have the following pattern: msauth://<PACKAGE_NAME>/<BASE64_URL_ENCODED_PACKAGE_SIGNATURE>.
   1. Navigate to your tenant in the Azure Portal.
   2. Under "Platform configurations", click "Add a platform".
   3. Click "Android".
   4. Enter your app's Package Name and Signature Hash. There are instructions on how to get both. See the MSAL FAQ for more details on how to get the Signature Hash. If you have Automatic App Signing turned on, you will find a SHA1 hash in your Google Play Console, under Release Management > App Signing > App Signing Certificate. To convert that to a base64 encoded string use the following command:
      $ echo -n "<YOUR_SHA1_SIGNATURE>" | openssl dgst -binary -sha1 | openssl base64
   5. Click "Configure".
   6. Copy the generated MSAL Configuration to a new asset file called msal_config.json located in your assets folder (android/app/src/main/assets). More details about the configuration file found here.
      Note: as of this writing the copiable config in the portal is messed up. Only use the JSON object portion of the config.
   7. Also in your msal_config.json, add the property: "account_mode": "MULTIPLE". This is required to use this library.
2. Configure your AndroidManifest.xml file as described here. This involves requesting a couple of permissions and configuring an intent filter using your Redirect URI.
   Note: The android:path attribute value sould start with a forward slash (/) and the Signature Hash should NOT be URL encoded.

iOS Setup

Follow the steps as described here. Steps include:

1. Register a redirect URI for your application for iOS in the Azure Portal. It should be in the following format: msauth.[BUNDLE_ID]://auth
   1. Navigate to your tenant in the Azure Portal.
   2. Under "Platform configurations", click "Add a platform".
   3. Click "iOS / macOS".
   4. Enter your app's Bundle ID.
   5. Click "Configure".
   6. Click "Done"
2. Add a keychain group to your project Capabilities called com.microsoft.adalcache
3. Add your application's redirect URI scheme to your Info.plist file, which will be in the format of msauth.[BUNDLE_ID]
4. Add LSApplicationQueriesSchemes to allow making call to Microsoft Authenticator if installed.
5. Add the provided code in your AppDelegate.m to handle MSAL callbacks. Make sure you #import <MSAL/MSAL.h>

Usage

PublicClientApplication class

This class is designed to be a thin wrapper around the native functionality of the Android and iOS MSAL libraries.

Creating an instance

const config: MSALConfiguration = {
  auth: {
    clientId: 'your-client-id',
    // authority: 'default-authority',
  },
};
const pca = new PublicClientApplication(config);

If you don't provide an authority, the common one will be used. This authority will be used as the default for calls to acquireToken and acquireTokenSilent.

Signing in interactively

const params: MSALInteractiveParams = {
  scopes: ['scope1', 'scope2'],
};
const result: MSALResult = await pca.acquireToken(params);

You must use this method before any calls to acquireTokenSilent. Use the accessToken from the MSALResult to call your API. Store the account from the result for acquiring tokens silently or for removing the account.

Acquiring tokens silently

const params: MSALSilentParams = {
  scopes: ['scope1', 'scope2'],
  account: result.account,
  // forceRefresh: true,
};
const result = await pca.acquireTokenSilent(params);

You can force the token to refresh with the forceRefresh option

Listing all accounts for which the application has refresh tokens

const accounts: MSALAccount[] = await pca.getAccounts();

Instead of storing the account from a MSALResult for an acquireTokenSilent method call, you can filter the MSALAccount[] result for a particular account and use it.

Signing out

const res: boolean = await pca.removeAccount(result.account);

Alternatively, you can call the signOut method:

const params: MSALSignoutParams = {
  account: result.account,
  // signoutFromBrowser: true
};
const res: boolean = await pca.signOut(params);

On Android, this is the same as removeAccount, but on iOS, if you call it with signoutFromBrowser: true, it will sign you out of the browser as well.

B2C Applications

The PublicClientApplication class is a bit too bare bones for dealing with a B2C application, and you will need to write a bit of code to get the desired behavior.

To address this issue, the example app that is included in this repository includes a B2CClient class which contains a lot of the functionality you will need for a B2C app. You can copy this class right into your own React Native app and modify it to your liking. You can see it being used in the example's App.tsx

If you would like to see this class included in the library itself, please create an issue requesting so.

Example

As mentioned above, the example app demonstrates a B2C implementation

To run the example locally, first clone the repo and run $ yarn bootstrap to install the depedencies. Then run the following for the desired platform:

iOS: $ yarn example ios
Android: $ yarn example android
Web: $ yarn example web (the example app is also running live here)

If you want to run the example using your own Azure application information:

1. Register the redirect URLs in your tenant:
   • Android: msauth://com.example/Xo8WBi6jzSxKDVR4drqm84yr9iU%3D
   • iOS: msauth.com.example://auth
   • Web (SPA): http://localhost:19006
2. Update the b2cConfig and b2cScopes variables in msalConfig.ts with your details.
3. Update the msal_config.json Android asset file with your details.

Migrating from v2 to v3

See breaking changes in CHANGELOG.md.