Microsoft Identity Mac

• Microsoft Identity Management
• Microsoft Identity Mac Full
• Microsoft Office Identity Folder Mac

Jan 24, 2020 For a comprehensive list of Microsoft products and their lifecycle policy timelines, including migration options, please search the Microsoft Lifecycle Product Database. If you have any questions regarding support for a product, please contact your Microsoft Account Representative. If you need technical support, visit the Microsoft Support website. Microsoft Edge for Mac is now built from a Chromium base, which means we don’t need a separate extension - though we may indeed have one in the official MS Edge for Mac extensions store at some point. For the present, this isn’t exactly pretty, but it can be done if you want to use the companion 1Password extension instead of 1Password X. 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.

This quickstart contains a code sample that demonstrates how a native iOS or macOS application can use the Microsoft identity platform to sign in personal, work and school accounts, get an access token, and call the Microsoft Graph API.

This quickstart applies to both iOS and macOS apps. Some steps are needed only for iOS apps. Those steps call out that they are only for iOS.

Register and download your quickstart app

This package contains the binaries of the Microsoft Authentication Library for.NET (MSAL.NET). MSAL.NET makes it easy to obtain tokens from the Microsoft identity platform for developers (formally Azure AD v2.0) signing-in users with work & school accounts, Microsoft personal accounts and social identities Azure AD B2C. These tokens again access to Microsoft Cloud API and any other API. Install Office for Mac now Office 365 customers get the new Office for Mac first. You’ll have Office applications on your Mac or PC, apps on tablets and smartphones for when you're on the go, and Office Online on the web for everywhere in between.

You have two options to start your quickstart application:

• [Express] Option 1: Register and auto configure your app and then download your code sample
• [Manual] Option 2: Register and manually configure your application and code sample

Option 1: Register and auto configure your app and then download the code sample

Outlook 2011for Mac has a special folder within the Mac OS X Finder called Office 2011 Identities. Just like it sounds, this special folder contains everything about your Outlook activities. Inside the Office 2011 Identities folder, Outlook stores one folder for each individual Identity. The name of the folder is the name of the Identity. Warning: Outlook data will be removed when you move the three folders listed in this step to Trash. You should back up these folders before you delete them. Click the back arrow to go back to the Library folder and open Group Containers.

Step 1: Register your application

To register your app,

1. Go to the new Azure portal - App registrations pane.
2. Enter a name for your application and select Register.
3. Follow the instructions to download and automatically configure your new application with just one click.

Option 2: Register and manually configure your application and code sample

Step 1: Register your application

To register your application and add the app's registration information to your solution manually, follow these steps:

1. Navigate to the Microsoft identity platform for developers App registrations page.
2. Select New registration.
3. When the Register an application page appears, enter your application's registration information:
   • In the Name section, enter a meaningful application name that will be displayed to users of the app when they sign in or consent to your app.
   • Skip other configurations on this page.
   • Select Register.
4. In the Manage section, select Authentication > Add Platform > iOS.
   • Enter the Bundle Identifier for your application. The bundle identifier is just a unique string that uniquely identifies your application, for example com.<yourname>.identitysample.MSALMacOS. Make a note of the value you use.
   • Note that the iOS configuration is also applicable to macOS applications.
5. Select Configure and save the MSAL Configuration details for later in this quickstart.

Step 1: Configure your application

For the code sample for this quickstart to work, you need to add a redirect URI compatible with the Auth broker.

Your application is configured with these attributes

Step 2: Download the sample project

Step 3: Install dependencies

In a terminal window, navigate to the folder with the downloaded code sample and run pod install to install the latest MSAL library.

Step 4: Configure your project

If you selected Option 1 above, you can skip these steps.

1. Extract the zip file and open the project in XCode.

2. Edit ViewController.swift and replace the line starting with 'let kClientID' with the following code snippet. Remember to update the value for kClientID with the client ID that you saved when you registered your app in the portal earlier in the quickstart:

3. Edit ViewController.swift and replace the line starting with 'let kAuthority' with the following code snippet:

4. Edit ViewController.swift and replace the line starting with 'let kGraphEndpoint' with the following code snippet:

5. Open the project settings. In the Identity section, enter the Bundle Identifier that you entered into the portal.

6. For iOS only, right-click Info.plist and select Open As > Source Code.

7. For iOS only, under the dict root node, replace CFBundleURLSchemes with the Bundle Id that you entered in the portal.

8. Build & run the app!

1. Extract the zip file and open the project in XCode.

2. Edit ViewController.swift and replace the line starting with 'let kClientID' with the following code snippet. Remember to update the value for kClientID with the clientID that you saved when you registered your app in the portal earlier in this quickstart:

3. If you're building an app for Azure AD national clouds, replace the line starting with 'let kGraphEndpoint' and 'let kAuthority' with correct endpoints. For global access, use default values:

4. Other endpoints are documented here. For example, to run the quickstart with Azure AD Germany, use following:

5. Open the project settings. In the Identity section, enter the Bundle Identifier that you entered into the portal.

6. For iOS only, right-click Info.plist and select Open As > Source Code.

7. For iOS only, under the dict root node, replace Enter_the_bundle_Id_Here with the Bundle Id that you used in the portal.

8. Build & run the app!

More Information

Read these sections to learn more about this quickstart.

Get MSAL

MSAL (MSAL.framework) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. You can add MSAL to your application using the following process:

Add the following to this podfile (with your project's target):

Run CocoaPods installation command:

pod install

Initialize MSAL

You can add the reference for MSAL by adding the following code:

Then, initialize MSAL using the following code:

For iOS only, additional app requirements

Your app must also have the following in your AppDelegate. This lets MSAL SDK handle token response from the Auth broker app when you do authentication.

Note

On iOS 13+, if you adopt UISceneDelegate instead of UIApplicationDelegate, place this code into the scene:openURLContexts: callback instead (See Apple's documentation).If you support both UISceneDelegate and UIApplicationDelegate for compatibility with older iOS, MSAL callback needs to be placed into both places.

Finally, your app must have an LSApplicationQueriesSchemes entry in your Info.plist alongside the CFBundleURLTypes. The sample comes with this included.

Sign in users & request tokens

MSAL has two methods used to acquire tokens: acquireToken and acquireTokenSilent.

acquireToken: Get a token interactively

Some situations require users to interact with Microsoft identity platform. In these cases, the end user may be required to select their account, enter their credentials, or consent to your app's permissions. For example,

• The first time users sign in to the application
• If a user resets their password, they'll need to enter their credentials
• When your application is requesting access to a resource for the first time
• When MFA or other Conditional Access policies are required

Microsoft Identity Management

acquireTokenSilent: Get an access token silently

Apps shouldn't require their users to sign in every time they request a token. If the user has already signed in, this method allows apps to request tokens silently.

Next steps

Try out the tutorial for iOS and macOS for a complete step-by-step guide on building applications, including a complete explanation of this quickstart.

Learn how to create the application used in this quickstart

Help and support

If you need help, want to report an issue, or want to learn more about your support options, see the following article:

In this tutorial, you'll learn how to integrate an iOS or macOS app with the Microsoft identity platform. The app will sign in a user, get an access token to call the Microsoft Graph API, and make a request to the Microsoft Graph API.

Microsoft Identity Mac Full

When you've completed the guide, your application will accept sign-ins of personal Microsoft accounts (including outlook.com, live.com, and others) and work or school accounts from any company or organization that uses Azure Active Directory.

Note

If you are new to the Microsoft identity platform, we recommend you start with the Sign in users and call the Microsoft Graph API from an iOS or macOS app.

How this tutorial works

The app in this tutorial will sign in users and get data on their behalf. This data will be accessed via a protected API (Microsoft Graph API in this case) that requires authorization and is protected by the Microsoft identity platform.

More specifically:

• Your app will sign in the user either through a browser or the Microsoft Authenticator.
• The end user will accept the permissions your application has requested.
• Your app will be issued an access token for the Microsoft Graph API.
• The access token will be included in the HTTP request to the web API.
• Process the Microsoft Graph response.

This sample uses the Microsoft Authentication library (MSAL) to implement Authentication. MSAL will automatically renew tokens, deliver single sign-on (SSO) between other apps on the device, and manage the Account(s).

This tutorial is applicable to both iOS and macOS apps. Note that some steps are different between those two platforms.

Prerequisites

• XCode version 11.x or greater is required to build the app in this guide. You can download XCode from the iTunes website.
• Microsoft Authentication Library (MSAL.framework). You can use a dependency manager or add the library manually. The instructions below show you how.

This tutorial will create a new project. If you want to download the completed tutorial instead, download the code:

Create a new project

1. Open Xcode and select Create a new Xcode project.
2. For iOS apps, select iOS > Single view App and select Next.
3. For macOS apps, select macOS > Cocoa App and select Next.
4. Provide a product name.
5. Set the Language to Swift and select Next.
6. Select a folder to create your app and click Create.

Register your application

1. Go to the Azure portal

2. Open the App registrations blade and click +New registration.

3. Enter a Name for your app and then, without setting a Redirect URI.

4. Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) under Supported account types

5. Click Register

6. In the Manage section of the pane that appears, select Authentication.

7. Click Try out the new experience near the top of the screen to open the new app registration experience, and then click +New registration > + Add a platform > iOS/macOS.

   • Enter your project's Bundle ID. If you downloaded the code, this is com.microsoft.identitysample.MSALiOS. If you're creating your own project, select your project in Xcode and open the General tab. The bundle identifier appears in the Identity section.

8. Click Configure and save the MSAL Configuration that appears in the MSAL configuration page so you can enter it when you configure your app later. Click Done.

Add MSAL

Choose one of the following ways to install the MSAL library in your app:

CocoaPods

1. If you're using CocoaPods, install MSAL by first creating an empty file called podfile in the same folder as your project's .xcodeproj file. Add the following to podfile:

2. Replace <your-target-here> with the name of your project.

3. In a terminal window, navigate to the folder that contains the podfile you created and run pod install to install the MSAL library.

4. Close Xcode and open <your project name>.xcworkspace to reload the project in Xcode.

Carthage

If you're using Carthage, install MSAL by adding it to your Cartfile:

From a terminal window, in the same directory as the updated Cartfile, run the following command to have Carthage update the dependencies in your project.

iOS:

macOS:

Manually

You can also use Git Submodule, or check out the latest release to use as a framework in your application.

Add your app registration

Next, we'll add your app registration to your code.

First, add the following import statement to the top of the ViewController.swift, as well as AppDelegate.swift or SceneDelegate.swift files:

Microsoft Office Identity Folder Mac

Then Add the following code to ViewController.swift prior to viewDidLoad():

The only value you need to modify above is the value assigned to kClientIDto be your Application ID. This value is part of the MSAL Configuration data that you saved during the step at the beginning of this tutorial to register the application in the Azure portal.

For iOS only, configure URL schemes

In this step, you will register CFBundleURLSchemes so that the user can be redirected back to the app after sign in. By the way, LSApplicationQueriesSchemes also allows your app to make use of Microsoft Authenticator.

In Xcode, open Info.plist as a source code file, and add the following inside of the <dict> section. Replace [BUNDLE_ID] with the value you used in the Azure portal which, if you downloaded the code, is com.microsoft.identitysample.MSALiOS. If you're creating your own project, select your project in Xcode and open the General tab. The bundle identifier appears in the Identity section.

For macOS only, configure App Sandbox

1. Go to your Xcode Project Settings > Capabilities tab > App Sandbox
2. Select Outgoing Connections (Client) checkbox.

Create your app’s UI

Now create a UI that includes a button to call the Microsoft Graph API, another to sign out, and a text view to see some output by adding the following code to the ViewControllerclass:

iOS UI

macOS UI

Next, also inside the ViewController class, replace the viewDidLoad() method with:

Use MSAL

Initialize MSAL

Add the following initMSAL method to the ViewController class:

Add the following after initMSAL method to the ViewController class.

iOS code:

macOS code:

For iOS only, handle the sign-in callback

Open the AppDelegate.swift file. To handle the callback after sign-in, add MSALPublicClientApplication.handleMSALResponse to the appDelegate class like this:

If you are using Xcode 11, you should place MSAL callback into the SceneDelegate.swift instead.If you support both UISceneDelegate and UIApplicationDelegate for compatibility with older iOS, MSAL callback would need to be placed into both files.

Acquire Tokens

Now, we can implement the application's UI processing logic and get tokens interactively through MSAL.

MSAL exposes two primary methods for getting tokens: acquireTokenSilently() and acquireTokenInteractively():

• acquireTokenSilently() attempts to sign in a user and get tokens without any user interaction as long as an account is present. acquireTokenSilently() requires providing a valid MSALAccount which can be retrieved by using one of MSAL account enumeration APIs. This sample uses applicationContext.getCurrentAccount(with: msalParameters, completionBlock: {}) to retrieve current account.

• acquireTokenInteractively() always shows UI when attempting to sign in the user. It may use session cookies in the browser or an account in the Microsoft authenticator to provide an interactive-SSO experience.

Add the following code to the ViewController class:

Get a token interactively

The code below gets a token for the first time by creating an MSALInteractiveTokenParameters object and calling acquireToken. Next you will add code that:

1. Creates MSALInteractiveTokenParameters with scopes.
2. Calls acquireToken() with the created parameters.
3. Handles errors. For more detail, refer to the MSAL for iOS and macOS error handling guide.
4. Handles the successful case.

Add the following code to the ViewController class.

Get a token silently

To acquire an updated token silently, add the following code to the ViewController class. It creates an MSALSilentTokenParameters object and calls acquireTokenSilent():

Call the Microsoft Graph API

Once you have a token, your app can use it in the HTTP header to make an authorized request to the Microsoft Graph:

Add the following code to the ViewController class:

See Microsoft Graph API to learn more about the Microsoft Graph API.

Use MSAL for Sign-out

Next, add support for sign-out.

Important

Signing out with MSAL removes all known information about a user from the application, as well as removing an active session on their device when allowed by device configuration. You can also optionally sign user out from the browser.

To add sign-out capability, add the following code inside the ViewController class.

Enable token caching

By default, MSAL caches your app's tokens in the iOS or macOS keychain.

To enable token caching:

1. Ensure your application is properly signed
2. Go to your Xcode Project Settings > Capabilities tab > Enable Keychain Sharing
3. Click + and enter a following Keychain Groups entry:3.a For iOS, enter com.microsoft.adalcache3.b For macOS enter com.microsoft.identity.universalstorage

Add helper methods

Add the following helper methods to the ViewController class to complete the sample.

iOS UI:

macOS UI:

For iOS only, get additional device information

Use following code to read current device configuration, including whether device is configured as shared:

Multi-account applications

This app is built for a single account scenario. MSAL also supports multi-account scenarios, but it requires some additional work from apps. You will need to create UI to help users select which account they want to use for each action that requires tokens. Alternatively, your app can implement a heuristic to select which account to use by querying all accounts from MSAL. For example, see accountsFromDeviceForParameters:completionBlock:API

Test your app

Run locally

Build and deploy the app to a test device or simulator. You should be able to sign in and get tokens for Azure AD or personal Microsoft accounts.

The first time a user signs into your app, they will be prompted by Microsoft identity to consent to the permissions requested. While most users are capable of consenting, some Azure AD tenants have disabled user consent, which requires admins to consent on behalf of all users. To support this scenario, register your app's scopes in the Azure portal.

After you sign in, the app will display the data returned from the Microsoft Graph /me endpoint.

Get help

Visit Help and support if you have trouble with this tutorial or with the Microsoft identity platform.