Xamarin iOS Specifics

Xamarin iOS specific considerations

On Xamarin iOS, there are several considerations that you must take into account when using MSAL.NET

1. Override and implement the OpenUrl function in the AppDelegate
2. Enable Keychain groups
3. Enable token cache sharing
4. Enable Keychain access

Implement OpenUrl

First you need to override the OpenUrl method of the FormsApplicationDelegate derived class and call AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs.

public override bool OpenUrl(UIApplication app, NSUrl url, NSDictionary options)
{
    AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url);
    return true;
}

You will also need to define a URL scheme, require permissions for your app to call another app, have a specific form for the redirect URL, and register this redirect URL in the Azure portal

Enable KeyChain Groups

In order to make the token cache work and have the AcquireTokenSilentAsync work, multiple steps must be followed :

1. Enable Keychain access in your Entitlements.plist file and specify the Keychain Groups in your bundle identifier.
2. Select Entitlements.plist file for the Custom Entitlements field in the iOS project options window's Bundle Signing View.
3. When signing a certificate, make sure XCode uses the same Apple Id.

Enable token cache sharing across iOS applications

From MSAL 2.x, you can specify a Keychain Security Group to use for persisting the token cache across multiple applications. This enables you to share the token cache between several applications having the same keychain security group including those developed with ADAL.NET, MSAL.NET Xamarin.iOS applications, and native iOS applications developed with ADAL.objc or MSAL.objc).

Sharing the token cache allows single sign-on between all of the applications that use the same Keychain Security Group.

To enable this, you need to set the PublicClientApplication.iOSKeychainSecurityGroup property to the same value in all of the applications.

An example of this would be:

PublicClientApplication.iOSKeychainSecurityGroup = "com.microsoft.msalrocks";

Note: KeychainSecurityGroup Property Deprecated

Previously, from MSAL 2.x, developers were forced to include the TeamId prefix when using the KeychainSecurityGroup property, which will change between dogfood and development time.

Now, from MSAL 2.7.x, when using the new iOSKeychainSecurityGroup property, MSAL will resolve the TeamId prefix during runtime. When using this property, the value should not contain the TeamId prefix.

Use the new iOSKeychainSecurityGroup property, which does not require developers to provide the TeamId, as the previous KeychainSecurityGroup property is now obsolete.

Enable keychain access

From MSAL 2.x and ADAL 4.x, the TeamId is used to access the keychain, this enables the authentication libraries to provide Single Sign-On (SSO) between applications of the same publisher.

What is the TeamIdentifierPrefix (TeamId)? It is a unique identifier (company or personal) in the App Store. The AppId is unique for an app. If you have more than one app, the TeamId for all the apps will be the same, but the AppId will be different. The keychain access group is prefixed by TeamId automatically for each group by the system. It's how the OS enforces that apps from the same publisher can access the shared keychain.

When initializing the PublicClientApplication, if you receive an MsalClientException with the message: TeamId returned null from the iOS keychain..., you will need to do the following in the iOS Xamarin app:

• In VS, under Debug tab, go to nameOfMyApp.iOS Properties...

• Then go to iOS Bundle Signing

• Under Custom Entitlements, click the ... and select the Entitlements.plist file from your app

• In the csproj file of the iOS app, you should have this line now included: <CodesignEntitlements>Entitlements.plist</CodesignEntitlements>

• Rebuild the project.

This is in addition to enabling keychain access in the Entitlements.plist file, using either the below access group or your own:

<?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.microsoft.adalcache</string>
  </array>
</dict>
</plist>

Sample illustrating Xamarin iOS specific properties

More details are provided in the iOS Specific Considerations paragraph of the following sample's readme.md file:

Sample	Platform	Description
https://github.com/Azure-Samples/active-directory-xamarin-native-v2	Xamarin iOS, Android, UWP	A simple Xamarin Forms app showcasing how to use MSAL to authenticate MSA and Azure AD via the AAD V2.0 endpoint, and access the Microsoft Graph with the resulting token.