msal_flutter 0.0.5

MSAL Wrapper Library for Flutter #

Please note this product is in very early alpha release and subject to change and bugs.

The Microsoft Authentication Library Flutter Wrapper is a wrapper that uses that MSAL libraries for Android and IOS. Currently only the public client application functionality is supported, using the implicit workflow. If you have a requirement for additional functionality however please let me know.

Setup #

To use MSAL Flutter in your library, first setup an Azure AD B2C tenant and mobile client if you have not done so already, for which detailed instructions can be found at https://docs.microsoft.com/en-us/azure/active-directory-b2c/

Flutter #

Import the Msal Flutter package into your flutter application by adding it to the list of dependencies in your pubsec.yaml file.

dependencies:
    msal_flutter: ^0.0.1

Android (Kotlin) #

This section is mostly copied and modified from the official android MSAL library github repository. Visit the repository for more details.

  1. Give youyr app internet permissions
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  1. In your AndroidManifest.xml file add the following intent filter, replacing the placeholder for your azure b2c application's client id where indicated below.
<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:scheme="msal[YOUR-CLIENT-ID]"
            android:host="auth" />
    </intent-filter>
</activity>
  1. In your MainActivity.kt import the following libraries
import uk.co.moodio.msal_flutter.MsalFlutterPlugin
import android.content.Intent
  1. In your MainActivity.kt file add the following function within the MainActivity class
  override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
      super.onActivityResult(requestCode, resultCode, data)
      Log.d("MsalAuth","Activity resulted")
      MsalFlutterPlugin.handleInteractiveRequestRedirect(requestCode, resultCode, data)
  }

iOS (Swift) #

This section is mostly copied and modified from Step 1 from the official android MSAL library github repository. Visit the repository for more details.

  1. Add your URL scheme for callbacks to your Info.plist file, replacing the placeholder for your azure b2c application's client id where indicated below.
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE-ID]</string>
        </array>
    </dict>
</array>
  1. Open the app's iOS project in xcode, click on the Runner app to open up the configuration, and under capabilities, expand Keychain Sharing and add the keychain group com.microsoft.adalcache

  2. Import the MSAL library in your AppDelegate.swift by adding the following at the top of the file

import MSAL

  1. Add the following function to your AppDelegate class
override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {    
guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
    return false
}  
return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
}

How To Use #

  1. In flutter, import the package import 'package:msal_flutter/msal_flutter.dart';
  1. create a new instance of the object, providing your client id, and optionally the authority to authenticate again.

    With default authority:

    PublicClientApplication("YOUR-CLIENT-ID");

    Specifying authroity:

    PublicClientApplication("YOUR-CLIENT-ID", authority: "https://login.microsoftonline.com/tfp/[[YOUR-TENANT]/[YOUR-FLOW]");

    If this is null the default authority will be used, as defined by the relevant MSAL library implementation, which currently is the common endpoint.

  2. To retrieve a token interactivity, call the acquireToken function passing the scopes you wish to acquire the token for. Note that this function will throw an error on failure and should be surrounded by a try catch block as per the example below

    DO NOT include the openid or user_impersonation scopes which are added by default

try{
    String token = await pca.acquireToken(["https://msalfluttertest.onmicrosoft.com/msalbackend/user_impersonation"]);
} on MsalException {
    //error handling logic here
}
  1. Once a user has logged in atleast once, to retrieve a token silently call the acquireTokenSilent function, passing the scopes you wish to acquire the token for. Note that this function will throw an error on failure and should be surrounded by a try catch block as per the example below

    DO NOT include the openid or user_impersonation scopes which are added by default

try{
    String token = await pca.acquireTokenSilent(["https://msalfluttertest.onmicrosoft.com/msalbackend/user_impersonation"]);
} on MsalException{
    // error handling logic here
}

List of exceptions that can be thrown #

ExceptionDescription
MsalExceptionBase exception, inhertied by all other exceptions. Used for general or unknwon errors
MsalInvalidConfigurationExceptionConfiguration error in setting up Public Client Application, such as invalid clientid or authority
MsalInvalidScopeExceptionInvalid scope or no scope supplied. Currently only supported in android
MsalNoAccountExceptionUser has not previously logged, has logged out or refresh token has expired and and acquire token silently cannot be performed
MsalUserCancelledExceptionLogin request cancelled by user. Only currently supported in Android, for iOS a MsalException is thrown instead

0.0.5 #

  • Added new custom exception for returning and handling login errors.

0.0.4 #

  • added swift version to podspec
  • added change log for 0.0.3
  • testing changes to ensure easier compatiability with new flutter projects
  • fixes to the readme documentation

0.0.3 #

  • Removed errors from displaying in returned error message in anticipation to change error handling to throw exceptions

0.0.2 #

  • Removed unused pub dependency
  • Removed unused resources
  • removed intent filter from plugin which was pointing to example app client id

0.0.1 #

  • Initial release includes the basic functionality and api for a PublicClientApplication capable of getting tokens interactivity and silently for a single user account at a time

example/README.md

msal_flutter_example #

Demonstrates how to use the msal_flutter plugin.

Getting Started #

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  msal_flutter: ^0.0.5

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:msal_flutter/msal_flutter.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
47
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
72
Learn more about scoring.

We analyzed this package on Aug 18, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.4

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Format lib/src/msal_exception.dart.

Run flutter format to format lib/src/msal_exception.dart.

Format lib/src/public_client_application.dart.

Run flutter format to format lib/src/public_client_application.dart.

Maintenance suggestions

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.6 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test