flutter_msal_mobile 1.0.0

Flutter plugin project for MSAL mobile.

Project Requirements

• Flutter version greater than 3.7.0
• Android minSdkVersion of at least 24
• iOS version of at least 14.0

Installation

Add the following to your pubspec.yaml

dependencies:
  flutter_msal: ^1.0.0

Android Setup

1. Open android > app > src > main > AndroidManifest.xml.
2. Add BrowserTabActivity to your AndroidManifest.xml file.
   • [your-base64-signature-hash] should be replaced with the base64 signature hash you generated while setting up your Android app in the Azure app registration.
   • [your-package-name] should be replaced with the Android package name you entered when setting up the Android app in your Azure app registration.

<activity android:name="com.microsoft.identity.client.BrowserTabActivity">
    <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:host="[your-package-name]"
            android:path="/[your-base64-signature-hash]"
            android:scheme="msauth" />
    </intent-filter>
</activity>

3. Make sure your Android app has internet access by adding the following just above <application>

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

4. Create a new JSON file in your Flutter project and populate it with the configuration that was generated for you by Azure when you added the Android platform to your app registration. The file can be called anything and placed anywhere in your project. This was added as assets/auth_config.json in the example project. The default configuration provided by Azure should look something like this:

{
  "client_id" : "00000000-0000-0000-0000-000000000000",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "msauth://[your-package-name]/[my-url-encoded-base64-signature-hash]",
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
       "type": "AzureADMultipleOrgs",
       "tenant_id": "organizations"
      }
    }
  ]
}

5. Add the JSON asset file to the pubspec.yaml file.

assets
    - assets/auth_config.json

iOS Setup

1. Add "ios_redirect_uri" value to the auth_config.json file created during the Android setup.

{
  "client_id" : "<app-registration-client-id>",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "msauth://<your-package-name>/<url-encoded-package-signature-hash>",
  "ios_redirect_uri": "msauth.<your-ios-bundle-identifier>://auth",
  "account_mode": "SINGLE",
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
       "type": "AzureADMyOrg",
       "tenant_id": "organizations"
      }
    }
  ],
  "logging": {
    "pii_enabled": false
  }
}

2. Set the iOS platform target version to a version >= 14.0 by opening the properties window of the Runner.xcodeproj file in Xcode.
3. In the Signing and Capabilities section, add the Keychain Sharing capability.
4. Add com.microsoft.adalcache as a keychain group.
5. Add the following to the Info.plist file in <dict> by right clicking the file and opening as source. Replace [your-bundle-identifier] with the iOS bundle identifier identified during the iOS platform setup portion of the app registration setup.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[your-bundle-identifier]</string>
        </array>
    </dict>
</array>

6. Add the following to the Info.plist in <dict> to enable the use of Microsoft Authenticator if available:

<array>
    <string>msauthv2</string>
    <string>msauthv3</string>
</array>

Usage

Import flutter_msal package

import 'package:flutter_msal/flutter_msal.dart';

Initialize MSAL, replace [clientId], [scopes], [tenantId], [authority] with yours.

    FlutterMsal.init(
      clientId: [clientId],
      scopes: [scopes],
      androidConfig: AndroidConfig(
        configFilePath: 'assets/msal_config.json',
        tenantId: [tenantId],
      ),
      iosConfig: IosConfig(authority: [authority]),
    )

APIs

Sign in and get token

await msal.acquireToken().then((MsalUser result) {
    print('access token (truncated): ${result.accessToken}');
})

Get token silently

await msal.acquireTokenSilent().then((MsalUser result) {
    print('access token (truncated): ${result.accessToken}');
})

Sign out

await msal.signOut()

Error Handling

This package provides a set of custom exceptions to simplify error handling when working with MSAL authentication. The main exception types you may encounter are:

1. MsalException: A general exception for authentication errors.
2. MsalUserCanceledException: Thrown when the user cancels the authentication process.
3. MsalUiRequiredException: Indicates that a UI prompt is needed to complete authentication.

To handle these exceptions effectively, you can use a catchError block in your code as shown below:

await msal.acquireToken().then((MsalUser user) {
    if (user != null) {
        print('current account id: ${result.oid}');
    }
}).catchError((exception) {
    if (exception is MsalUserCanceledException) {
        print('User cancelled the request: ${exception.errorMessage}');
    } else if (exception is MsalUiRequiredException) {
        print('UI prompt required to acquire token: ${exception.errorMessage}');
    } else if (exception is MsalException) {
        print('General MSAL error: ${exception.errorMessage}');
    } else {
        print('An unexpected exception occurred.');
    }
});

This approach enables you to provide tailored responses based on the specific exception type, making it easier to handle user cancellations, required UI prompts, and other authentication errors.