capacitor-msal-broker

A Capacitor plugin for Microsoft Authentication Library (MSAL) with broker support for iOS and Android. This plugin enables authentication through Microsoft Authenticator app, which is required for Intune MDM/MAM and Conditional Access compliance.

Features

• ✅ Native MSAL authentication on iOS and Android
• ✅ Broker authentication via Microsoft Authenticator / Company Portal
• ✅ Intune/Conditional Access compliance
• ✅ Single Sign-On (SSO) support
• ✅ Silent token acquisition
• ✅ Keychain sharing for SSO across apps (iOS)
• ✅ Same TypeScript API for both platforms

Requirements

• Capacitor 7.x
• iOS 14.0+
• Android API 24+ (Android 7.0)
• Microsoft Authenticator app installed (for broker authentication)

Installation

npm install @rageshpikalmunde/capacitor-msal-broker
npx cap sync

iOS Setup

1. Configure URL Schemes in Info.plist

Add the following to your ios/App/App/Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>msauthv2</string>
    <string>msauthv3</string>
    <string>msauth</string>
</array>

2. Configure Keychain Sharing in Entitlements

Add the following to your ios/App/App/App.entitlements:

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)com.microsoft.adalcache</string>
</array>

3. Azure Portal Configuration

In your Azure AD App Registration:

1. Go to Authentication → Platform configurations → iOS/macOS
2. Add your Bundle ID
3. Configure the redirect URI: msauth.<your-bundle-id>://auth

Android Setup

1. Add MSAL Maven Repository

Add the Microsoft MSAL Maven repository to your app's android/build.gradle (project-level):

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
            name 'Duo-SDK-Feed'
        }
    }
}

2. Configure AndroidManifest.xml

Add the following to your app's android/app/src/main/AndroidManifest.xml inside <application>:

<activity
    android:name="com.microsoft.identity.client.BrowserTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="msauth"
            android:host="<your-package-name>"
            android:path="/<base64-signature-hash>" />
    </intent-filter>
</activity>

Replace <your-package-name> with your app's package name (e.g., com.example.myapp) and <base64-signature-hash> with your app's Base64-encoded signature hash.

Tip: To get your signature hash, run:

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

3. Azure Portal Configuration

In your Azure AD App Registration:

1. Go to Authentication → Platform configurations → Add a platform → Android
2. Enter your package name and signature hash
3. The redirect URI will be auto-generated: msauth://<package-name>/<signature-hash>

4. Broker Setup (Optional)

For broker authentication (Intune/Conditional Access):

• Install Microsoft Authenticator or Intune Company Portal on the device
• The plugin automatically detects and uses the broker when brokerEnabled: true (default)

Usage

Initialize

import { MsalBroker } from '@rageshpikalmunde/capacitor-msal-broker';
import { Capacitor } from '@capacitor/core';

await MsalBroker.initialize({
  clientId: 'your-azure-client-id',
  tenant: 'organizations', // or specific tenant ID
  authorityUrl: 'https://login.microsoftonline.com/organizations',
  scopes: ['User.Read', 'email'], // Don't include openid, profile, offline_access
  redirectUri: Capacitor.getPlatform() === 'ios'
    ? 'msauth.com.your.bundleid://auth'
    : 'msauth://com.your.packagename/Base64SignatureHash',
  brokerEnabled: true,
  keychainGroup: 'com.microsoft.adalcache', // iOS only, ignored on Android
});

Important: Do not include openid, profile, or offline_access in scopes - MSAL adds these automatically on both platforms.

Login (Interactive)

try {
  const result = await MsalBroker.login();
  console.log('Access Token:', result.accessToken);
  console.log('User:', result.account.username);
} catch (error) {
  console.error('Login failed:', error);
}

Get Accounts

const { accounts } = await MsalBroker.getAccounts();
if (accounts.length > 0) {
  console.log('Found account:', accounts[0].username);
}

Acquire Token Silently

try {
  const result = await MsalBroker.acquireTokenSilently({
    identifier: account.identifier,
    forceRefresh: false,
  });
  console.log('Token:', result.accessToken);
} catch (error) {
  // Silent auth failed, use interactive login
  const result = await MsalBroker.login();
}

Logout

await MsalBroker.logout();

API Reference

initialize(options: MsalBrokerInitOptions): Promise<{ success: boolean }>

Initialize MSAL with your configuration.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | clientId | string | Yes | Azure AD Application (client) ID | | tenant | string | No | Tenant ID or 'organizations'/'common' | | authorityUrl | string | No | Authority URL | | scopes | string[] | No | OAuth scopes to request | | redirectUri | string | No | Redirect URI configured in Azure | | brokerEnabled | boolean | No | Enable broker authentication (default: true) | | keychainGroup | string | No | Keychain group for SSO (iOS only) | | knownAuthorities | string[] | No | List of known authorities |

login(options?: MsalBrokerLoginOptions): Promise<MsalBrokerAuthResult>

Perform interactive login.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loginHint | string | No | Pre-fill username | | prompt | string | No | Prompt behavior: 'selectAccount', 'login', 'consent', 'none' |

acquireTokenSilently(options: MsalBrokerSilentOptions): Promise<MsalBrokerAuthResult>

Acquire token silently for an existing account.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | identifier | string | Yes | Account identifier | | forceRefresh | boolean | No | Force token refresh |

getAccounts(): Promise<{ accounts: MsalBrokerAccount[] }>

Get all cached accounts.

logout(): Promise<{ success: boolean }>

Sign out and clear cached tokens.

Types

interface MsalBrokerAuthResult {
  accessToken: string;
  idToken: string;
  expiresOn: number; // Unix timestamp in seconds
  scopes: string[];
  authority: string;
  uniqueId: string;
  account: MsalBrokerAccount;
}

interface MsalBrokerAccount {
  identifier: string;
  username: string;
  environment: string;
  homeAccountId: string;
  isSSOAccount: boolean;
  idTokenClaims?: Record<string, unknown>;
}

Troubleshooting

iOS

Error -50000: Reserved scopes

Remove openid, profile, and offline_access from your scopes array. MSAL iOS adds these automatically.

Error -51112: Broker not responding

1. Ensure Microsoft Authenticator is installed
2. Verify your redirect URI matches Azure Portal configuration
3. Check that keychain sharing is properly configured

Keychain errors (-25300)

Ensure your entitlements include the correct keychain access groups with $(AppIdentifierPrefix) prefix.

Android

MSAL initialization fails

1. Ensure the MSAL Maven repository is added to your project-level build.gradle
2. Verify the redirect URI format: msauth://<package-name>/<signature-hash>
3. Check that the signature hash matches what's registered in Azure AD

BrowserTabActivity not found

Ensure you've added the BrowserTabActivity intent filter to your AndroidManifest.xml with the correct scheme, host, and path.

Broker not working on Android

1. Install Microsoft Authenticator or Intune Company Portal
2. Ensure brokerEnabled: true is set in initialize()
3. Verify the redirect URI is registered as a broker redirect in Azure AD

Build error: MSAL dependency not found

Add the Azure DevOps Maven repository to your project:

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

Platform Differences

| Feature | iOS | Android | | ---------------------- | ---------------------------------- | -------------------------------------------- | | Redirect URI format | msauth.<bundle-id>://auth | msauth://<package>/<signature-hash> | | Broker apps | Microsoft Authenticator | Microsoft Authenticator / Company Portal | | Keychain sharing | Supported via keychainGroup | N/A (shared preferences handled by MSAL) | | isSSOAccount | Reported by MSAL | Always false | | SSO | Via keychain sharing | Via broker (Authenticator / Company Portal) |

License

MIT