Merge pull request #31 from stashenergy/beta

v3

CHANGELOG.md

@@ -0,0 +1,80 @@
+# CHANGELOG
+
+## [3.0.0](https://github.com/stashenergy/react-native-msal/compare/v2.0.3...v3.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.
+
+```diff
+-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.
+
+```diff
+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`.
+
+```diff
+-await msalClient.signout({
+-  authority,
++await msalClient.signOut({
+```
+
+#### `removeAccount` method
+
+`MSALRemoveAccountParams` has been removed and so the `removeAccount` method only requires the `account`.
+
+```diff
+-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.
+
+```diff
+-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](https://github.com/stashenergy/react-native-msal/blob/beta/example/src/b2cClient.ts), but at the very least, `knownAuthorities` should be added to the initial client constructor.

README.md

@@ -1,6 +1,7 @@
 # react-native-msal
 
 [![npm latest version](https://img.shields.io/npm/v/react-native-msal/latest.svg)](https://www.npmjs.com/package/react-native-msal)
+[![npm beta version](https://img.shields.io/npm/v/react-native-msal/beta.svg)](https://www.npmjs.com/package/react-native-msal)
 ![ci status](https://github.com/stashenergy/react-native-msal/workflows/CI/badge.svg)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 
@@ -14,83 +15,123 @@ Requires React Native >=0.61
 
 `$ yarn add react-native-msal`
 
-## Common setup
+## Setup
 
-1. Register your application in the Azure Portal
-2. Set up redirect URLs for your application in the portal. You will need one for both iOS and Android. They will have the following patterns:
-   - iOS: `msauth.<BUNDLE_ID>://auth`.
-     - ex: `msauth.com.example://auth`
-   - Android: `msauth://<PACKAGE>/<BASE64_URL_ENCODED_PACKAGE_SIGNATURE>`
-     - ex: `msauth://com.example/Xo8WBi6jzSxKDVR4drqm84yr9iU%3D`
-     - Get your package signature from your `.keystore` file, or from the Google Play Console if you have automatic app signing turned on.
-       - See the [MSAL FAQ](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki/MSAL-FAQ#redirect-uri-issues) for instructions on how to get the package signature from your `.keystore` file.
-       - 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`.
-   - Paste the base64 signature hash into the "Signature hash" field in the portal, and a redirect uri will be generated for you.
+### Common Setup
 
-## Android Setup
+Before setting up your React Native app, you must register your application in the Azure Portal.
 
-1. Follow steps **2 and 3** of the [Using MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-android#using-msal) section of the Android MSAL docs.
-   **IMPORTANT**: For Step 2, you **MUST** create a file in your assets folder (`android/app/src/main/assets`) named `msal_config.json` containing your MSAL configuration. If you don't have an `assets` folder already, you will have to create one
+### Android Setup
 
-## iOS Setup
+1. Register a redirect URI for your application for Android in the Azure Portal. It will have the following pattern: `msauth://<PACKAGE>/<BASE64_URL_ENCODED_PACKAGE_SIGNATURE>`.
+   - Get your package signature from your `.keystore` file, or from the Google Play Console if you have automatic app signing turned on.
+     - See the [MSAL FAQ](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki/MSAL-FAQ#redirect-uri-issues) for instructions on how to get the package signature from your `.keystore` file.
+     - 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`.
+     - Paste the base64 signature hash into the "Signature hash" field in the portal, and a redirect uri will be generated for you.
+1. Create your MSAL configuration file as described [here](https://github.com/AzureAD/microsoft-authentication-library-for-android#step-2-create-your-msal-configuration-file). **IMPORTANT**: You **MUST** create a file in your assets folder (`android/app/src/main/assets`) named `msal_config.json` containing your MSAL configuration. If you don't have an `assets` folder already, you will need to create one.
+1. Configure your `AndroidManifest.xml` file as described [here](https://github.com/AzureAD/microsoft-authentication-library-for-android#step-3-configure-the-androidmanifestxml).
 
-1. Follow the steps detailed in the [Configuring MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-objc#configuring-msal) section of the iOS MSAL docs
+### iOS Setup
+
+Follow the steps as described [here](https://github.com/AzureAD/microsoft-authentication-library-for-objc#configuring-msal). 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. Add a keychain group to your project Capabilities called `com.microsoft.adalcache`
+1. Add your application's redirect URI scheme to your `Info.plist` file, which will be in the format of msauth.[BUNDLE_ID]
+1. Add LSApplicationQueriesSchemes to allow making call to Microsoft Authenticator if installed.
+1. Add the provided code in your AppDelegate.m to handle MSAL callbacks
 
 ## Usage
 
-See example usage in [`App.tsx` in the example app](./example/src/App.tsx)
+### `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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+const res: boolean = await pca.removeAccount(result.account);
+```
+
+Alternatively, you can call the `signOut` method:
 
 ```typescript
-import MSALClient from 'react-native-msal';
-
-const clientId = '<clientId>';
-const authority = '<authority>';
-const scopes = ['scope'];
-const msalClient = new MSALClient(clientId);
-
-// The first time signing in you must use this call to perform an interactive login
-// Use the token from result.accessToken to call your API
-// See when the token expires with result.expiresOn
-// Store result.account.identifier for acquiring tokens silently or clearing the token cache
-const result = await msalClient.acquireToken({
-  authority,
-  scopes,
-});
-
-// Acquire a token silently
-// You may specify `forceRefresh: true` to force acquiring a brand new token
-const result = await msalClient.acquireTokenSilent({
-  authority,
-  scopes,
-  accountIdentifier: result.account.identifier,
-});
-
-// Removes all tokens from the cache for this application for the provided account
-// A call to acquireToken will be required for acquiring subsequent access tokens
-await msalClient.removeAccount({
-  authority,
-  accountIdentifier: result.account.identifier,
-});
-
-// Removes all tokens from the cache for this application for the provided account
-// Additionally, this will remove the account from the system browser
-// A call to acquireToken will be required for acquiring subsequent access tokens
-// Only available on iOS platform, falls back to `removeAccount` on Android
-await msalClient.signout({
-  authority,
-  accountIdentifier: result.account.identifier,
-});
+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](./example/src/b2cClient.ts) 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`](./example/src/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, first:
 
 1. `yarn bootstrap`
-2. Add the redirect URLs in your tenant:
+2. Register the redirect URLs in your tenant:
    - Android: `msauth://com.example/P6akJ4YYsuUDahjqGra9mAflzdA%3D`
    - iOS: `msauth.com.example://auth`
-3. Update the `msalConfig` object in `App.tsx` with your details
+3. Update the `b2cConfig` object in `msalConfig.ts` with your details
 
 ### Android
 
@@ -100,3 +141,7 @@ To run the example, first:
 ### iOS
 
 1. `yarn example ios`
+
+## Migrating from v2 to v3
+
+See breaking changes in [CHANGELOG.md](CHANGELOG.md#300).

android/build.gradle

@@ -8,7 +8,7 @@ buildscript {
   }
 
   dependencies {
-    classpath 'com.android.tools.build:gradle:3.5.3'
+    classpath 'com.android.tools.build:gradle:4.0.1'
     // noinspection DifferentKotlinGradleVersion
     classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
   }