-
Notifications
You must be signed in to change notification settings - Fork 142
Single Sign on (SSO)
MSAL supports Single Sign-on(SSO) between applications and browsers.
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.
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.
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.
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.
MSAL supports SSO sharing through iOS keychain access groups.
To enable SSO across your applications you need to do the following:
- Ensure all your applications user the same Client ID or Application ID.
- Ensure that all of your applications share the same signing certificate from Apple so that you can share keychains
- Request the same keychain entitlement for each of your applications.
- Tell the MSAL SDKs about the shared keychain you want us to use.
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
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.
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
Using a default webView type, MSAL based applications and Safari will have SSO. To see more about web views MSAL supports, please visit wiki
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:
- 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>
- Add following schemes to your app's Info.plist under LSApplicationQueriesSchemes:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>msauth</string>
<string>msauthv2</string>
</array>
- 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
- Customizing Browsers and WebViews
- Logging
- Sovereign clouds
- B2C
- Auth Telemetry (coming soon)
- MSAL questions, bugs and issues (coming soon)
- Redirect URIs
- Requesting individual claims
- Keychain cache
- SSL issues
- iOS 13 and macOS 10.15 support
- Releases
- Roadmap (coming soon)