Single Sign on (SSO)

MSAL supports Single Sign-on(SSO) between applications and browsers.

• Silent SSO between multiple apps

This type of SSO is supported between multiple apps distributed by the same Apple Developer. It provides silent SSO by reading refresh tokens written by other apps from the keychain and exchanging them for the access tokens silently.

• Silent SSO between ADAL and MSAL based apps

MSAL Objective-C supports migration and SSO with ADAL Objective-C based apps. This type of SSO is supported between apps distributed by the same Apple Developer.

• SSO between MSAL and Safari

This type of SSO is achieved through ASWebAuthenticationSession and allows utilizing user's existing sign in state from other apps and Safari browser. It's not limited to apps distributed by the same Apple Developer, but it requires some user interaction.

• SSO through Authentication broker

Microsoft provides applications for every mobile platform that enable SSO across applications from different vendors if mobile device is registered with AAD. These applications are called brokers. This type of SSO requires installation of the broker application on end user device.

Silent SSO between multiple apps

MSAL supports SSO sharing through iOS keychain access groups.

To enable SSO across your applications you need to do the following:

1. Ensure all your applications user the same Client ID or Application ID.
2. Ensure that all of your applications share the same signing certificate from Apple so that you can share keychains
3. Request the same keychain entitlement for each of your applications.
4. Tell the MSAL SDKs about the shared keychain you want us to use.

Using the same Client ID / Application ID for all the applications in your suite of apps

In order for the Microsoft Identity platform to know that it's allowed to share tokens across your applications, each of your applications will need to share the same Client ID or Application ID. This is the unique identifier that was provided to you when you registered your first application in the portal.

You may be wondering how you will identify different apps to the Microsoft Identity service if it uses the same Application ID. The answer is with the Redirect URIs. Each application can have multiple Redirect URIs registered in the onboarding portal. Each app in your suite will have a different redirect URI. An example of how this looks is below:

App1 Redirect URI: msauthcom.contoso.mytestapp1://auth

App2 Redirect URI: msauthcom.contoso.mytestapp2://auth

App3 Redirect URI: msauthcom.contoso.mytestapp3://auth

....

These are nested under the same client ID / application ID and looked up based on the redirect URI you return to us in your SDK configuration.

+-------------------+
|                   |
|  Client ID        |
+---------+---------+
          |
          |           +-----------------------------------+
          |           |  App 1 Redirect URI               |
          +----------^+                                   |
          |           +-----------------------------------+
          |
          |           +-----------------------------------+
          +----------^+  App 2 Redirect URI               |
          |           |                                   |
          |           +-----------------------------------+
          |
          +----------^+-----------------------------------+
                      |  App 3 Redirect URI               |
                      |                                   |
                      +-----------------------------------+

Note: The format of redirect uris must be compatible with MSAL support format, which is documented in our Wiki

Create keychain sharing between applications

Enabling keychain sharing is beyond the scope of this document and covered by Apple in their document Adding Capabilities. What is important is that you decide what you want your keychain to be called and add that capability across all your applications.

When you do have entitlements set up correctly you should see a file in your project directory entitled entitlements.plist that contains something that looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>keychain-access-groups</key>
    <array>
        <string>$(AppIdentifierPrefix)com.myapp.mytestapp</string>
        <string>$(AppIdentifierPrefix)com.myapp.mycache</string>
    </array>
</dict>
</plist>

Once you have the keychain entitlement enabled in each of your applications, and you are ready to use SSO, tell the MSAL about your keychain by configuring MSALPublicClientApplication with your keychain access group:

NSError *error = nil;
MSALPublicClientApplicationConfig *configuration = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<my-client-id>"];
configuration.cacheConfig.keychainSharingGroup = @"my.keychain.group";
    
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:configuration error:&error];

Warning

When you share a keychain across your applications any application can delete users or worse delete all the tokens across your application. This is particularly disastrous if you have applications that rely on the tokens to do background work. Sharing a keychain means that you must be very careful in any and all remove operations through the Microsoft Identity SDKs.

That's it! The Microsoft Identity SDK will now share credentials across all your applications. The account list will also be shared across application instances.

SSO between ADAL and MSAL based apps

There're some additional steps you might need to take to achieve cross-app SSO between ADAL and MSAL based apps. Those are described in a separate Wiki

SSO between MSAL and Safari

Using a default webView type, MSAL based applications and Safari will have SSO. To see more about web views MSAL supports, please visit wiki

SSO through Authentication broker

MSAL provides support for brokered authentication with Microsoft Authenticator starting with version 0.3.0. In addition to providing SSO for AAD registered devices, Microsoft Authenticator also helps your application to comply with conditional access policies.

Please follow these steps to enable SSO through Authentication broker for your app:

1. Register a broker compatible Redirect URI format for the application. Broker compatible Redirect URI format is msauth.<app.bundle.id>://auth. Please replace <app.bundle.id> with your application's bundle ID.

<key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>

2. Add following schemes to your app's Info.plist under LSApplicationQueriesSchemes:

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
     <string>msauthv2</string>
</array>

3. Add the following to your AppDelegate.m file to handle callbacks:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options`
{
    return [MSALPublicClientApplication handleMSALResponse:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

More information about AAD authentication brokers and MSAL can be found here