The Microsoft Authentication Library (MSAL) for macOS and iOS supports Single Sign-on (SSO) between macOS/iOS apps and browsers. This article covers the following SSO scenarios:
Easily check which versions of mac OS, iOS, iPadOS, or watchOS are compatible with your Mac model or iDevice. Guide includes OS X 10.8.x to macOS 11.0.x. OS X Yosemite Simulator remix by ellistomas; Mac OS X Sierra (10.12.0) by -Apple-Inc; Mac OS X 10.7 by PigVenomPV; OS X Yosemite X Kirby Simulator by honnybean; Mac OS Simulator by ownh; What a mac does. By Youtuberfan153; OS X Yosemite Simulator remix by ZAWSZEANONIM; OS X El Capitan Simulator 2 by Jethrochannz; OS X Yosemite Simulator.
This type of SSO works between multiple apps distributed by the same Apple Developer. It provides silent SSO (that is, the user isn't prompted for credentials) by reading refresh tokens written by other apps from the keychain, and exchanging them for access tokens silently.
Microsoft provides apps, called brokers, that enable SSO between applications from different vendors as long as the mobile device is registered with Azure Active Directory (AAD). This type of SSO requires a broker application be installed on the user's device.
- SSO between MSAL and Safari
SSO is achieved through the ASWebAuthenticationSession class. It uses existing sign-in state from other apps and the Safari browser. It's not limited to apps distributed by the same Apple Developer, but it requires some user interaction.
If you use the default web view in your app to sign in users, you'll get automatic SSO between MSAL-based applications and Safari. To learn more about the web views that MSAL supports, visit Customize browsers and WebViews.
Important
This type of SSO is currently not available on macOS. MSAL on macOS only supports WKWebView which doesn't have SSO support with Safari.
- Silent SSO between ADAL and MSAL macOS/iOS apps
MSAL Objective-C supports migration and SSO with ADAL Objective-C-based apps. The apps must be distributed by the same Apple Developer.
See SSO between ADAL and MSAL apps on macOS and iOS for instructions for cross-app SSO between ADAL and MSAL-based apps.
Silent SSO between apps
MSAL supports SSO sharing through iOS keychain access groups.
To enable SSO across your applications, you'll need to do the following steps, which are explained in more detail below:
- Ensure that all your applications use 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 if it's different from the default one.
Use the same Client ID and Application ID
For the Microsoft identity platform to know which applications can share tokens, those applications 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.
The way the Microsoft identity platform tells apps that use the same Application ID apart is by their 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. For example:
App1 Redirect URI: msauth.com.contoso.mytestapp1://auth
App2 Redirect URI: msauth.com.contoso.mytestapp2://auth
App3 Redirect URI: msauth.com.contoso.mytestapp3://auth
Important
The format of redirect uris must be compatible with the format MSAL supports, which is documented in MSAL Redirect URI format requirements.
Setup keychain sharing between applications
Refer to Apple's Adding Capabilities article to enable keychain sharing. What is important is that you decide what you want your keychain to be called and add that capability to all of your applications that will be involved in SSO.
When you have the entitlements set up correctly, you'll see a entitlements.plist file in your project directory that contains something like this example:
Add a new keychain group
Add a new keychain group to your project Capabilities. The keychain group should be:
com.microsoft.adalcacheon iOScom.microsoft.identity.universalstorageon macOS.
For more information, see keychain groups.
Configure the application object
Once you have the keychain entitlement enabled in each of your applications, and you're ready to use SSO, configure MSALPublicClientApplication with your keychain access group as in the following example:
Objective-C:
Swift:
Warning
When you share a keychain across your applications, any application can delete users or even all of the tokens across your application.This is particularly impactful if you have applications that rely on tokens to do background work.Sharing a keychain means that you must be very careful when your app uses Microsoft identity SDK remove operations.
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 through Authentication broker on iOS
MSAL provides support for brokered authentication with Microsoft Authenticator. Microsoft Authenticator provides SSO for AAD registered devices, and also helps your application follow Conditional Access policies.
The following steps are how you enable SSO using an authentication broker for your app:
Register a broker compatible Redirect URI format for the application in your app's Info.plist. The broker compatible Redirect URI format is
msauth.<app.bundle.id>://auth. Replace `<app.bundle.id>`` with your application's bundle ID. For example:Add following schemes to your app's Info.plist under
LSApplicationQueriesSchemes:Add the following to your
AppDelegate.mfile to handle callbacks:Objective-C:
Swift:
If you are using Xcode 11, you should place MSAL callback into the SceneDelegate file instead.If you support both UISceneDelegate and UIApplicationDelegate for compatibility with older iOS, MSAL callback would need to be placed into both files.
Objective-C:
Swift:
Next steps
Learn more about Authentication flows and application scenarios
The Z shell (also known as zsh) is a Unix shell that is built on top of bash(the default shell for macOS) with additional features. It's recommended to usezsh over bash. It's also highly recommended to install a framework withzsh as it makes dealing with configuration, plugins and themes a lot nicer.
We've also included an env.sh file where we store our aliases, exports, pathchanges etc. We put this in a separate file to not pollute our mainconfiguration file too much. This file is found in the bottom of this page.
Install zsh using Homebrew:
Now you should install a framework, we recommend to use Oh My Zshor Prezto. Note that you shouldpick one of them, not use both.
The configuration file for zsh is called .zshrc and lives in your homefolder (~/.zshrc).
Oh My Zsh
Oh My Zsh is an open source,community-driven framework for managing your zsh configuration. It comeswith a bunch of features out of the box and improves your terminal experience.
Install Oh My Zsh:
The installation script should set zsh to your default shell, but if itdoesn't you can do it manually:
Configuration
The out-of-the-box configuration is usable but you probably want to customiseit to suit your needs. The Official Wikicontains a lot of useful information if you want to deep dive into what youcan do with Oh My Zsh, but we'll cover the basics here.
To apply the changes you make you need to either start new shell instanceor run:
Plugins
Add plugins to your shell by adding the name of the plugin to the pluginarray in your .zshrc.
You'll find a list of all plugins on the Oh My Zsh Wiki.Note that adding plugins can cause your shell startup time to increase.
Themes
Changing theme is as simple as changing a string in your configuration file.The default theme is robbyrussell. Just change that value to change theme,and don't forget to apply your changes.
You'll find a list of themes with screenshots on theOh My Zsh Wiki.
Prezto
Prezto is a configuration frameworkfor zsh; it enriches the command line interface environment with sanedefaults, aliases, functions, auto completion, and prompt themes.
Install Prezto:
Next create your ~/.zshrc by running:
For more information on customisation visit the GitHub repository forPrezto.
Modules
Add modules to Prezto by editing ~/.zpreztorc and adding the modules asstrings to the list:
And don't forget to apply your changes by starting a new shell instance.
Themes
To list all available themes run:
Then open up your config file (~/.zpreztorc) and change to the theme you want:
env.sh
To include env.sh, open ~/.zshrc and add the following:
Mac Os Mojave
This file comes with some pre-defined settings, they are all optional.Please review them before you use them as your configuration. These are justexamples to show you what you can customise in your shell.