Microsoft Authentication Library for iOS and macOS

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.

Native authentication support in MSAL

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.

Get started

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

Migrate from ADAL Objective-C

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.

Quick sample

Swift

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.")
}

Objective-C

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
    }
}];

Master branch deprecation

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'.

Installation

Using CocoaPods

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.

Using Carthage

You can use Carthage to install MSAL by adding it to your Cartfile:

github "AzureAD/microsoft-authentication-library-for-objc" "main"

Using Swift Packages

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.

1. For your project in Xcode, click File → Swift Packages → Add Package Dependency...
2. Choose project to add dependency in
3. Enter : https://github.com/AzureAD/microsoft-authentication-library-for-objc as the package repository URL
4. Choose package options with :
   1. Rules → Branch : main (For latest MSAL release)
   2. 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

Manually

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.

Using Git Submodule

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 msal
• cd msal
• git checkout tags/<latest_release_tag>
• git submodule update --init --recursive
• cd ..
• git add msal
• git commit -m "Use MSAL git submodule at <latest_release_tag>"
• git push

Next steps

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.

Supported Versions

iOS - MSAL supports iOS 14 and above.

macOS - MSAL supports macOS (OSX) 10.15 and above.

Community help and support

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.

Submit feedback

We'd like your thoughts on this library. Please complete this short survey.

Contribute

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.

Security library

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.

Security reporting

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.

License

Copyright © Microsoft Corporation. All rights reserved. Licensed under the MIT License (the “License”).