| Documentation | Code Samples | Library Reference | Support | Feedback |
|---|---|---|---|---|
| MSAL iOS and macOS documentation | • Microsoft Entra ID (workforce samples) • Microsoft Entra External ID (customer samples) |
SDK reference | Get support | Feedback |
The Microsoft Authentication Library (MSAL) for iOS and macOS is an auth SDK that can be used to seamlessly integrate authentication into your apps using industry standard OAuth2 and OpenID Connect. It allows you to sign in users or apps with Microsoft identities. These identities include Microsoft Entra ID work and school accounts, personal Microsoft accounts, social accounts, and customer accounts.
Using MSAL for iOS and macOS, you can acquire security tokens from the Microsoft identity platform to authenticate users and access secure web APIs for their applications. The library supports multiple authentication scenarios, such as single sign-on (SSO), Conditional Access, and brokered authentication.
MSAL iOS and macOS also provides native authentication APIs that allow applications to implement a native experience with end-to-end customizable flows in their applications. With native authentication, users are guided through a rich, native, sign-up and sign-in journey without leaving the app. The native authentication feature is available for mobile (iOS) and desktop (macOS) apps on External ID for customers. It is recommended to always use the most up-to-date version of the SDK.
To use MSAL iOS and macOS in your application, you need to register your application in the Microsoft Entra Admin center and configure your project. Since the SDK supports both browser-delegated and native authentication experiences, follow the steps in the one of these quickstarts based on your scenario.
-
For browser-delegated authentication scenarios, refer to the quickstart, Sign in users and call Microsoft Graph from an iOS or macOS app.
-
For native authentication scenarios, refer to the Microsoft Entra External ID sample guides, for iOS sample app or macOS sample app
The Azure Active Directory Authentication Library (ADAL) for Objective-C has been deprecated effective June 2023. Follow the ADAL to MSAL migration guide for iOS and macOS to avoid putting your app's security at risk.
let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
let scopes = ["your-scope1-here", "your-scope2-here"]
if let application = try? MSALPublicClientApplication(configuration: config) {
let viewController = ... // Pass a reference to the view controller that should be used when getting a token interactively
let webviewParameters = MSALWebviewParameters(authPresentationViewController: viewController)
let interactiveParameters = MSALInteractiveTokenParameters(scopes: scopes, webviewParameters: webviewParameters)
application.acquireToken(with: interactiveParameters, completionBlock: { (result, error) in
guard let authResult = result, error == nil else {
print(error!.localizedDescription)
return
}
// Get access token from result
let accessToken = authResult.accessToken
// You'll want to get the account identifier to retrieve and reuse the account for later acquireToken calls
let accountIdentifier = authResult.account.identifier
})
}
else {
print("Unable to create application.")
}NSError *msalError = nil;
MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
NSArray<NSString *> *scopes = @[@"your-scope1-here", @"your-scope2-here"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];
MSALViewController *viewController = ...; // Pass a reference to the view controller that should be used when getting a token interactively
MSALWebviewParameters *webParameters = [[MSALWebviewParameters alloc] initWithAuthPresentationViewController:viewController];
MSALInteractiveTokenParameters *interactiveParams = [[MSALInteractiveTokenParameters alloc] initWithScopes:scopes webviewParameters:webParameters];
[application acquireTokenWithParameters:interactiveParams completionBlock:^(MSALResult *result, NSError *error) {
if (!error)
{
// You'll want to get the account identifier to retrieve and reuse the account
// for later acquireToken calls
NSString *accountIdentifier = result.account.identifier;
NSString *accessToken = result.accessToken;
}
else
{
// Check the error
}
}];The master branch has been copied over to main branch. The master branch will contain updates only until version 1.2.14, for further releases please refer to 'main' branch instead of 'master'.
For browser-delegated authentication:
You can use CocoaPods to install MSAL by adding it to your Podfile under target:
use_frameworks!
target 'your-target-here' do
pod 'MSAL'
end
For native-authentication:
To use the native authentication capabilities provided by MSAL in your iOS or macOS application, you need to specify native-auth as subspec for the MSAL dependency as follows:
use_frameworks!
target 'your-target-here' do
pod 'MSAL/native-auth'
end
Note: If you're using the native-auth subspec, you must include the use_frameworks! setting in your Podfile.
You can use Carthage to install MSAL by adding it to your Cartfile:
github "AzureAD/microsoft-authentication-library-for-objc" "main"
You can add MSAL as a swift package dependency.
For MSAL version 1.1.14 and above, distribution of MSAL binary framework as a Swift package is available.
- For your project in Xcode, click File → Swift Packages → Add Package Dependency...
- Choose project to add dependency in
- Enter : https://github.com/AzureAD/microsoft-authentication-library-for-objc as the package repository URL
- Choose package options with :
- Rules → Branch : main (For latest MSAL release)
- Rules → Version → Exact : [release version >= 1.1.14] (For a particular release version)
For any issues, please check if there is an outstanding SPM/Xcode bug. Workarounds for some bugs we encountered :
- If you have a plugin in your project you might encounter CFBundleIdentifier collision. Each bundle must have a unique bundle identifier error. Workaround
- While archiving, error : “IPA processing failed” UserInfo={NSLocalizedDescription=IPA processing failed}. Workaround
- For a macOS app, “Command CodeSign failed with a nonzero exit code” error. Workaround
If you choose to manually integrate MSAL for iOS and macOS into your Xcode project, follow the guidance in the official documentation on how to add package dependencies to your application.
If your project is managed in a git repository you can include MSAL as a git submodule. First check the GitHub Releases Page for the latest release tag. Replace <latest_release_tag> with that version.
git submodule add https://github.com/AzureAD/microsoft-authentication-library-for-objc msalcd msalgit checkout tags/<latest_release_tag>git submodule update --init --recursivecd ..git add msalgit commit -m "Use MSAL git submodule at <latest_release_tag>"git push
After installation, please follow the official MSAL iOS and macOS documentation on Microsoft Learn to complete the following steps:
- Configure your project to use MSAL
- Configure authority for different identities
- Configure redirect URIs
- Acquire tokens
For more information on common usage patterns, error handling and debugging, logging, telemetry, and other library functionalities, please refere to the official MSAL iOS and macOS documentation.
iOS - MSAL supports iOS 14 and above.
macOS - MSAL supports macOS (OSX) 10.15 and above.
We use Stack Overflow with the community to provide support. We highly recommend you ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before.
If you find a bug or have a feature request, please raise the issue on GitHub Issues.
To provide a recommendation, visit our User Voice page.
We'd like your thoughts on this library. Please complete this short survey.
We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
This library controls how users sign-in and access services. We recommend you always take the latest version of our library in your app when possible. We use semantic versioning, so you can control the risk associated with updating your app. As an example, always downloading the latest minor version number (e.g. x.y.x) ensures you get the latest security and feature enhancements, but our API surface remains the same. You can always see the latest version and release notes under the Releases tab of GitHub.
If you find a security issue with our libraries or services please report it to [email protected] with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.
Copyright © Microsoft Corporation. All rights reserved. Licensed under the MIT License (the “License”).