react-native-msal

Live Demo (Web)

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

Table of Contents

• Install
• Setup
• Use
  • PublicClientApplication class
  • B2C Applications
• Example app
• Migrating between major versions

Install

Requires React Native >=0.61

Stable version: $ yarn add react-native-msal

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

Don't forget to run npx pod-install after!

Setup

Expo

Follow the Expo setup guide

Non-expo

Follow the Android setup guide and the iOS setup guide

Use

import PublicClientApplication from 'react-native-msal';
import type { MSALConfiguration /*, etc */ } from 'react-native-msal';

const config: MSALConfiguration = {
  auth: {
    clientId: 'your-client-id',
    // This authority is used as the default in `acquireToken` and `acquireTokenSilent` if not provided to those methods.
    // Defaults to 'https://login.microsoftonline.com/common'
    authority: 'https://<authority url>',
  },
};
const scopes = ['scope1', 'scope2'];

// Initialize the public client application:
const pca = new PublicClientApplication(config);
try {
  await pca.init();
} catch (error) {
  console.error('Error initializing the pca, check your config.', error);
}

// Acquiring a token for the first time, you must call pca.acquireToken
const params: MSALInteractiveParams = { scopes };
const result: MSALResult | undefined = await pca.acquireToken(params);

// On subsequent token acquisitions, you can call `pca.acquireTokenSilent`
// Force the token to refresh with the `forceRefresh` option
const params: MSALSilentParams = {
  account: result!.account, // or get this by filtering the result from `pca.getAccounts` (see below)
  scopes,
  forceRefresh: true,
};
const result: MSALResult | undefined = await pca.acquireTokenSilent(params);

// Get all accounts for which this application has refresh tokens
const accounts: MSALAccount[] = await pca.getAccounts();

// Retrieve the account matching the identifier
const account: MSALAccount | undefined = await pca.getAccount(result!.account.identifier);

// Remove all tokens from the cache for this application for the provided account
const success: boolean = await pca.removeAccount(result!.account);

// Same as `pca.removeAccount` with the exception that, if called on iOS with the `signoutFromBrowser` option set to true, it will additionally remove the account from the system browser
const params: MSALSignoutParams = {
  account: result!.account,
  signoutFromBrowser: true,
};
const success: boolean = await pca.signOut(params);

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 let us know.

Example App

As mentioned above, the example app demonstrates a B2C implementation

To run the example locally, first clone the repo and run $ yarn to bootstrap the project. 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.

Migrating between major versions

See migration instructions in the CHANGELOG.

CHANGELOG

4.0.0-beta.6

Breaking changes

• acquireToken, acquireTokenSilent, and getAccount may return Promise<undefined>. This matches what the underlying native libraries return.
• The Android msal_config.json file that was previously required is no longer needed and is ignored. You can safely delete this file. All options are now configurable in the config object which is passed to the PublicClientApplication constructor
• The PublicClientApplication constructor no longer takes a second init boolean argument, and initialization must be done manually by calling the init method:

  -const pca = new PublicClientApplication(config, false)
  +const pca = new PublicClientApplication(config) // No longer initializes client. You must do this manually 👇
  try {
    await pca.init();
  } catch (error) {
    console.log("problem in configuration/setup:", error)
  }

• A new maven repository is required to be added to your project build.gradle (if you are using Expo this is done automatically for you):

  allProjects {
    repositories {
      // ...
      maven {
        url "https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1"
      }
    }
  }

Features

• Now supports Expo apps through a config plugin! To configure, please follow the Expo setup guide

3.0.0

Breaking changes

Default export

Default exported class renamed from MSALClient to PublicClientApplication and constructor now accepts an MSALConfiguration object instead of a clientId string.

-import MSALClient from 'react-native-msal';
+import MSALClient, { MSALConfiguration } from 'react-native-msal';
-const msalClient = new MSALClient(clientId);
+const config: MSALConfiguration = {
+    auth: {
+        clientId,
+    },
+};
+const msalClient = new MSALClient(config);

MSALAccount and accountIdentifier properties

The MSALAccount definition has been modified to include a new Claims dictionary. All methods that previously consumed the identifier from this type should now provide the entire MSALAccount object instead.

const result = msalClient.acquireTokenSilent({
  authority,
  scopes,
- accountIdentifier: account.identifier,
+ account,
});

signOut method

The signout method has been renamed signOut and authority removed from the MSALSignoutParams.

-await msalClient.signout({
-  authority,
+await msalClient.signOut({

removeAccount method

MSALRemoveAccountParams has been removed and so the removeAccount method only requires the account.

-await msalClient.removeAccount({
+await msalClient.removeAccount(
-  authority,
   account,
-})
+)

Webview parameters

ios_prefersEphemeralWebBrowserSession has moved from acquireToken() and signOut() parameters into the new webviewParameters in MSALInteractiveParams and MSALSignoutParams respectively.

-ios_prefersEphemeralWebBrowserSession: true,
+webviewParameters: {
+  ios_prefersEphemeralWebBrowserSession: true,
+},

expiresOn

MSALResult.expiresOn now returns a value in seconds instead of milliseconds.

MSALResult interface

The result returned from an acquireToken or acquireTokenSilent call no longer has an authority property.

Azure AD B2C usage

See example/src/b2cClient.ts, but at the very least, knownAuthorities should be added to the initial client constructor.

Testing

You'll need to mock the PublicClientApplication class for testing purposes. One way to do this:

// yourtestfile.test.ts
import PublicClientApplication from 'react-native-msal';
jest.mock('react-native-msal');

const MockPublicClientApplication = PublicClientApplication as jest.MockedClass<PublicClientApplication>;

it('Creates a mock instance without calling native functions', () => {
  const mockPca = new MockPublicClientApplication({ auth: { clientId: '1234' } });
  expect(MockPublicClientApplication).toHaveBeenCalledTimes(1);
  expect(mockPca).not.toBeNull();
});