This library, ADAL for iOS and macOS, will no longer receive new feature improvements. Instead, use the new library MSAL for iOS and macOS.

• If you are starting a new project, you can get started with the MSAL for iOS and macOS docs for details about the scenarios, usage, and relevant concepts.
• If your application is using the previous ADAL for iOS and macOS library, you can follow this migration guide to update to MSAL for iOS and macOS.
• Existing applications relying on ADAL for iOS and macOS will continue to work.

Microsoft Azure Active Directory Authentication Library (ADAL) for iOS and macOS

=====================================

Release Versions

We recommend remaining up-to-date with the latest version of ADAL. The best place to check what the most recent version is is the releases page on GitHub, you can also subscribe the the Atom Feed from GitHub, or use a 3rd party tool like Sibbell to receive emails when a new version is released.

The only approved way to get the latest version is through a tagged release on GitHub, or a tool that relies on that data. Tools like CocoaPods can make it easier to set up your project dependencies and update to the latest release. ADAL follows the GitFlow branching model. You should never pull an ADAL version for release from any branch other then master, any other branch is for versions of ADAL still in development or testing, and are subject to change.

NOTE:

• To work with iOS 15, you must have at least version 5.0.0. However, we recommend switching to version 6.0.0 since 5.0.0 won't be maintained.

• To work with iOS 10-11.3 you must have at least version 2.2.5.

• To work with iOS 11.3-12.4 you must have at least version 2.6.3.

• To work with iOS 13+ (when built with Xcode 11) you must have at least version 2.7.14 or 4.0.2

• ADAL supports iOS 10+ and macOS 10.11+. iOS 9 and macOS 10.10 support was dropped in ADAL 4.0.0 release.

• WKWebView drops network connection if device got locked on iOS 12. It is by design and not configurable.

The ADAL SDK for iOS and macOS gives you the ability to add support for Work Accounts to your application with just a few lines of additional code. This SDK gives your application the full functionality of Microsoft Azure AD, including industry standard protocol support for OAuth2, Web API integration with user level consent, and two factor authentication support. Best of all, it’s FOSS (Free and Open Source Software) so that you can participate in the development process as we build these libraries.

Contribution History

Samples and Documentation

We provide a full suite of sample applications and documentation on GitHub to help you get started with learning the Azure Identity system. This includes tutorials for native clients such as Windows, Windows Phone, iOS, macOS, Android, and Linux. We also provide full walkthroughs for authentication flows such as OAuth2, OpenID Connect, Graph API, and other awesome features.

Azure Identity samples for iOS is here: https://github.com/AzureADSamples/NativeClient-iOS

Community Help and Support

We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browser existing issues to see if someone has had your question before.

We recommend you use the "adal" tag so we can see it! Here is the latest Q&A on Stack Overflow for ADAL: http://stackoverflow.com/questions/tagged/adal

SSO and Conditional Access Support

This library allows your application to support our Enterprise Mobility Suite, including Conditional Access, so businesses can use your application in their secure environment.

To configure your application to support these scenarios, please read this document: How to enable cross-app SSO on iOS using ADAL

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.

Contributing

All code is licensed under the MIT license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now.

Quick Start

1. Clone the repository to your machine
2. Build the library or framework
3. Add the ADAL library or framework your project

Download

We've made it easy for you to have multiple options to use this library in your iOS project:

Option 1: Git Submodule

If your project is managed in a git repository you can include ADAL 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/azure-activedirectory-library-for-objc adal
cd adal
git checkout tags/<latest_release_tag>
cd ..
git add adal
git commit -m "Use ADAL git submodule at <latest_release_tag>"
git push

We recommend only syncing to specific release tags to make sure you're at a known good point. We will not support versions of ADAL between release tags.

Option 2: Cocoapods

You can use CocoaPods to remain up to date with ADAL within a specific major version. Include the following line in your podfile:

pod 'ADAL', '~> 6.0'

You then you can run either pod install (if it's a new PodFile) or pod update (if it's an existing PodFile) to get the latest version of ADAL. Subsequent calls to pod update will update to the latest released version of ADAL as well.

ADAL is using submodules, so if you're using a specific branch of ADAL in your Podfile, you need to enable submodules, e.g.

pod 'ADAL', :git => 'https://github.com/AzureAD/azure-activedirectory-library-for-objc', :branch => 'branch-name', :submodules => true

See CocoaPods for more information on setting up a PodFile

Option 3: Source Zip

To download a copy of the source code, first make sure you're on the "master" branch and click "Clone or download" then "Download ZIP" in the upper right hand corner, or you can download it here

This is not recommended, as it leaves no infrastructure in place for being able to easily update to the latest version.

Usage

Caching

iOS

Keychain Setup

Click on your project in the Navigator pane in Xcode. Click on your application target and then the "Capabilities" tab. Scroll down to "Keychain Sharing" and flip the switch on. Add "com.microsoft.adalcache" to that list.

Alternatively you can disable keychain sharing by setting the keychain sharing group to nil or your application's bundle id.

    [[ADALAuthenticationSettings sharedInstance] setDefaultKeychainGroup:nil];

Inspecting the Cache

If you need to inspect the cache in your app, you can do it through the ADKeychainTokenCache interface.

macOS

Keychain is not directly supported by ADAL on macOS. The default caching implementation will keep around tokens for the life time of the process, but they will not be persisted. If you wish to persist tokens you must implement the ADALTokenCacheDelegate and provide it on AuthenticationContext creation

@protocol ADALTokenCacheDelegate <NSObject>

- (void)willAccessCache:(nonnull ADALTokenCache *)cache;
- (void)didAccessCache:(nonnull ADALTokenCache *)cache;
- (void)willWriteCache:(nonnull ADALTokenCache *)cache;
- (void)didWriteCache:(nonnull ADALTokenCache *)cache;

@end

In this delegate you can call -serialize and -deserialize on the cache object to save or update the cache in the form of an NSData binary blob.

Quick Start

The starting point for the API is in ADALAuthenticationContext.h header. ADALAuthenticationContext is the main class used for obtaining, caching and supplying access tokens.

How to quickly get a token from the SDK:

+ (void)getToken:(void (^)(NSString*))completionBlock;
{
    ADALAuthenticationError *error = nil;
    authContext = [ADALAuthenticationContext authenticationContextWithAuthority:@"https://login.microsoftonline.com/common"
                                                                        error:&error];
        
    [authContext acquireTokenWithResource:@"https://graph.windows.net"                 
                                 clientId:@"<Your Client ID>"                          // Comes from App Portal
                              redirectUri:[NSURL URLWithString:@"<Your Redirect URI>"] // Comes from App Portal
                          completionBlock:^(ADALAuthenticationResult *result)
    {
        if (AD_SUCCEEDED != result.status){
            // display error on the screen
            [self showError:result.error.errorDetails];
        }
        else{
            completionBlock(result.accessToken);
        }
    }];
}

Adding the Token to the authHeader to access APIs:

    NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:yourAppURL];
    NSString *authHeader = [NSString stringWithFormat:@"Bearer %@", accessToken];
    [request addValue:authHeader forHTTPHeaderField:@"Authorization"];
            
    NSOperationQueue *queue = [[NSOperationQueue alloc] init];
            
    [NSURLConnection sendAsynchronousRequest:request
                                       queue:queue
                           completionHandler:^(NSURLResponse *response, NSData *data, NSError *error)
    {
    	// Process Response Here
    }];

Brokered Authentication

If your app requires conditional access or certificate authentication (currently in preview) support, you must set up your AuthenticationContext and redirectURI to be able to talk to the Azure Authenticator app.

Enable Broker Mode on Your Context

Broker is enabled on a per-authentication-context basis. You must set your credentials type if you wish ADAL to call to broker:

/*! See the ADCredentialsType enumeration definition for details */
@property ADALCredentialsType credentialsType;

The AD_CREDENTIALS_AUTO setting will allow ADAL to try to call out to the broker, AD_CREDENTIALS_EMBEDDED will prevent ADAL from calling to the broker.

Registering a URL Scheme

ADAL uses URLs to invoke the broker and then return back to your app. To finish that round trip you need a URL scheme registered for your app. We recommend making the URL scheme fairly unique to minimize the chances of another app using the same URL scheme.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.MSOpenTech.MyTestiOSApp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>x-msauth-mytestiosapp</string>
        </array>
    </dict>
</array>

LSApplicationQueriesSchemes

ADAL uses –canOpenURL: to check if the broker is installed on the device. in iOS 9 Apple locked down what schemes an application can query for. You will need to add “msauth” and "msauthv3" to the LSApplicationQueriesSchemes section of your info.plist file. Note that "msauthv3" scheme is needed when compiling with Xcode 11+.

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
     <string>msauthv3</string>
</array>

Redirect URI

This adds extra requirements on your redirect URI. Your redirect URI must be in the proper form.

<app-scheme>://<your.bundle.id>
ex: x-msauth-mytestiosapp://com.microsoft.mytestiosapp

This Redirect URI needs to be registered on the app portal as a valid redirect URI. Additionally a second "msauth" form needs to be registered to handle certificate authentication in Azure Authenticator.

msauth://code/<broker-redirect-uri-in-url-encoded-form>
ex: msauth://code/x-msauth-mytestiosapp%3A%2F%2Fcom.microsoft.mytestiosapp

iOS 13 support

If you adopted UISceneDelegate, you must also add an ADAL callback into the scene:openURLContexts: method.

This is needed so that ADAL can get a response from the Microsoft Authenticator application.

For example:

 - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
 {
     UIOpenURLContext *context = URLContexts.anyObject;
     NSURL *url = context.URL;
     NSString *sourceApplication = context.options.sourceApplication;
     
     [ADALAuthenticationContext handleADALResponse:url sourceApplication:sourceApplication];
 }

If you're not using UISceneDelegate functionality yet, you can ignore this step.

Diagnostics

Logs

ADAL relies heavily on logging to diagnose issues. It is highly recommended that you set an ADAL logging callback and provide a way for users to submit logs when they are having authentication issues.

Logging Callback

You can set a callback to capture ADAL logging and incorporate it in your own application's logging:

/*!
    The LogCallback block for the ADAL logger
 
    @param  logLevel        The level of the log message
    @param  message         A short log message describing the event that occurred, this string will not contain PII.
    @param  additionalInfo  A longer message that may contain PII and other details relevant to the event.
    @param  errorCode       An integer error code if the log message is an error.
    @param  userInfo        A dictionary with other information relevant to the log message. The information varies,
                            for most error messages the error object will be in the "error" key.
 */
typedef void (^LogCallback)(ADAL_LOG_LEVEL logLevel,
                            NSString *message,
                            NSString *additionalInfo,
                            NSInteger errorCode,
                            NSDictionary *userInfo);

Otherwise ADAL outputs to NSLog by default, which will print messages on the console.

Example Log Message

The message portion of ADAL iOS are in the format of ADALiOS [timestamp - correlation_id] message

ADAL [2015-06-22 19:42:53 - 1030CB25-798F-4A6F-97DF-04A3A3E9DFF2] ADAL API call [Version - 2.1.0]

Providing correlation IDs and timestamps are tremendously in tracking down issues. The only reliable place to retrieve them is from ADAL logging.

Logging Levels

• ADAL_LOG_LEVEL_NO_LOG (Disable all logging)
• ADAL_LOG_LEVEL_ERROR (Default level, prints out information only when errors occur)
• ADAL_LOG_LEVEL_WARNING (Warning)
• ADAL_LOG_LEVEL_INFO (Library entry points, with parameters and various keychain operations)
• ADAL_LOG_LEVEL_Verbose (API tracing )

To set the logging level in your application call +[ADALLogger setLevel:]

[ADALLogger setLevel:ADAL_LOG_LEVEL_INFO]

Network Traces

You can use various tools to capture the HTTP traffic that ADAL generates. This is most useful if you are familiar with the OAuth protocol or if you need to provide diagnostic information to Microsoft or other support channels.

Charles is the easiest HTTP tracing tool in OSX. Use the following links to setup it up to correctly record ADAL network traffic. In order to be useful it is necessary to configure Charles, to record unencrypted SSL traffic. NOTE: Traces generated in this way may contain highly privileged information such as access tokens, usernames and passwords.
If you are using production accounts, do not share these traces with 3rd parties. If you need to supply a trace to someone in order to get support, reproduce the issue with a temporary account with usernames and passwords that you don't mind sharing.

• Setting Up SSL For iOS Simulator or Devices

ADALAuthenticationError

ADALAuthenticationErrors are provided in all callbacks in the ADALAuthenticationResult's error property when an error occurs. They can be used to have the application display more more informative errors to the user, however ADAL Error messages are not localized. All ADAuthenticationErrors are logged with the ADAL logger as well.

##Common problems

Application, using the ADAL library crashes with the following exception:
*** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: '+[NSString isStringNilOrBlank:]: unrecognized selector sent to class 0x13dc800'

Solution: Make sure that you add the -ObjC flag to "Other Linker Flags" build setting of the application. For more information, see Apple documentation for using static libraries:
https://developer.apple.com/library/ios/technotes/iOSStaticLibraries/Articles/configuration.html#//apple_ref/doc/uid/TP40012554-CH3-SW1.

Log ins are not persisting, Cache always returns empty

Solution: Either add the "com.microsoft.adalcache" keychain sharing entitlement to your application, or disable keychain sharing by passing in your application's bundle id in ADAuthenticationSettings:

    [[ADALAuthenticationSettings sharedInstance] setDefaultKeychainGroup:nil];

ADAL keeps returning SSL errors in iOS 9 and later

iOS 9 added App Transport Security (ATS). ATS restricts apps from accessing the internet unless they meet several security requirements including TLS 1.2 and SHA-256. It also prevents network traces that rely on self signed certs to crack SSL from working. Disabling ATS must be done in the Application's info.plist file, see documentation on the NSAppTransport info.plist key for more information.

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License");

We Value and Adhere to the Microsoft Open Source Code of Conduct

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.