Troubleshooting the Microsoft Enterprise SSO Extension plugin on Apple devices
This article provides troubleshooting guidance used by administrators to resolve issues with deploying and using the Enterprise SSO plugin. The Apple SSO extension can be deployed to iOS/iPadOS and macOS.
Organizations can opt to deploy SSO to their corporate devices to provide a better experience for their end users. On Apple platforms, this process involves implementing Single Sign On (SSO) via Primary Refresh Tokens. SSO relieves end users of the burden of excessive authentication prompts.
Microsoft has implemented a plugin built on top of Apple's SSO framework, which provides brokered authentication for applications integrated with Microsoft Entra ID. For more information, see the article Microsoft Enterprise SSO plug-in for Apple devices.
Extension types
Apple supports two types of SSO Extensions that are part of its framework: Redirect and Credential. The Microsoft Enterprise SSO plugin has been implemented as a Redirect type and is best suited for brokering authentication to Microsoft Entra ID. The following table compares the two types of extensions.
| Extension type | Best suited for | How it works | Key differences |
|---|---|---|---|
| Redirect | Modern authentication methods such as OpenID Connect, OAUTH2, and SAML (Microsoft Entra ID) | Operating System intercepts the authentication request from the application to the Identity provider URLs defined in the extension MDM configuration profile. Redirect extensions receive: URLs, headers, and body. | Request credentials before requesting data. Uses URLs in MDM configuration profile. |
| Credential | Challenge and response authentication types like Kerberos (on-premises Active Directory Domain Services) | Request is sent from the application to the authentication server (AD domain controller). Credential extensions are configured with HOSTS in the MDM configuration profile. If the authentication server returns a challenge that matches a host listed in the profile, the operating system routes the challenge to the extension. The extension has the choice of handling or rejecting the challenge. If handled, the extension returns the authorization headers to complete the request, and the authentication server returns a response to the caller. | Request data then get challenged for authentication. Use HOSTs in MDM configuration profile. |
Microsoft has implementations for brokered authentication for the following client operating systems:
| OS | Authentication broker |
|---|---|
| Windows | Web Account Manager (WAM) |
| iOS/iPadOS | Microsoft Authenticator |
| Android | Microsoft Authenticator or Microsoft Intune Company Portal |
| macOS | Microsoft Intune Company Portal (via SSO Extension) |
All Microsoft broker applications use a key artifact known as a Primary Refresh Token (PRT), which is a JSON Web Token (JWT) used to acquire access tokens for applications and web resources secured with Microsoft Entra ID. When deployed through an MDM, the Enterprise SSO extension for macOS or iOS obtains a PRT that is similar to the PRTs used on Windows devices by the Web Account Manager (WAM). For more information, see the article What is a Primary Refresh Token.
Troubleshooting model
The following flowchart outlines a logical flow for approaching troubleshooting the SSO Extension. The rest of this article goes into detail on the steps depicted in this flowchart. The troubleshooting can be broken down into two separate focus areas: Deployment and Application Auth Flow.
Steps to Opt out of Platform SSO on macOS
To opt out of PSSO that was enabled by mistake, admins should remove the SSO extension profile with PSSO enabled from the devices and deploy a new SSO extension profile with PSSO flags disabled/removed.
- Remove the targeting for the SSO profile with PSSO enabled
- Initiate device sync to get the SSO profile with PSSO enabled removed from the device
- Target the device with a new SSO profile with PSSO disabled
- Initiate device sync to get the new profile installed on the device
Important
Note: Updating the existing SSO profile on the device WON'T help to disable PSSO after PSSO registration is completed. Only a complete removal of the SSO profile from the device will remove the PSSO state from the device.
Context :
Users will start seeing PSSO registration notification on macOS 13+ devices in two scenarios :
- If device already has Intune Company Portal version supporting PSSO and admin deploys new SSO extension policy with PSSO enabled
- If user is already targeted with SSO extension policy having PSSO enabled and later an Intune Company Portal version supporting PSSO is installed on the device.
Caution
Admins should NOT target users with SSO extension policy having PSSO enabled unless they are tested and ready to be deployed, as this can potentially break existing users and their compliance conditions.
Important
Note : For users who complete PSSO registration, the legacy WPJ registration will be removed from the keychain. If PSSO registration was done by mistake , once admin removes the SSO profile with PSSO and installs new profile without PSSO, the legacy WPJ registration should be done again for device compliance to work.
Deployment troubleshooting
Most issues that customers encounter stem from either improper Mobile Device Management (MDM) configuration(s) of the SSO extension profile, or an inability for the Apple device to receive the configuration profile from the MDM. This section covers the steps you can take to ensure that the MDM profile has been deployed to a Mac and that it has the correct configuration.
Deployment requirements
- macOS operating system: version 10.15 (Catalina) or greater.
- iOS operating system: version 13 or greater.
- Device managed by any MDM vendor that supports Apple macOS and/or iOS (MDM Enrollment).
- Authentication Broker Software installed: Microsoft Intune Company Portal or Microsoft Authenticator for iOS.
Check macOS operating system version
Use the following steps to check the operating system (OS) version on the macOS device. Apple SSO Extension profiles are only deployed to devices running macOS 10.15 (Catalina) or greater. You can check the macOS version from either the User Interface or from the Terminal.
User interface
From the macOS device, select on the Apple icon in the top left corner and select About This Mac.
The Operating system version is listed beside macOS.
Terminal
From the macOS device, double-click on the Applications folder, then double-click on the Utilities folder.
Double-click on the Terminal application.
When the Terminal opens type sw_vers at the prompt, look for a result like the following:
% sw_vers ProductName: macOS ProductVersion: 13.0.1 BuildVersion: 22A400
Check iOS operating system version
Use the following steps to check the operating system (OS) version on the iOS device. Apple SSO Extension profiles are only deployed to devices running iOS 13 or greater. You can check the iOS version from the Settings app. Open the Settings app:
Navigate to General and then About. This screen lists information about the device, including the iOS version number:
MDM deployment of SSO extension configuration profile
Work with your MDM administrator (or Device Management team) to ensure that the extension configuration profile is deployed to the Apple devices. The extension profile can be deployed from any MDM that supports macOS or iOS devices.
Important
Apple requires devices are enrolled into an MDM for the SSO extension to be deployed.
The following table provides specific MDM installation guidance depending on which OS you're deploying the extension to:
- iOS/iPadOS: Deploy the Microsoft Enterprise SSO plug-in
- macOS: Deploy the Microsoft Enterprise SSO plug-in
Important
Although, any MDM is supported for deploying the SSO Extension, many organizations implement device-based Conditional Access polices by way of evaluating MDM compliance policies. If a third-party MDM is being used, ensure that the MDM vendor supports Intune Partner Compliance if you would like to use device-based Conditional Access policies. When the SSO Extension is deployed via Intune or an MDM provider that supports Intune Partner Compliance, the extension can pass the device certificate to Microsoft Entra ID so that device authentication can be completed.
Validate Networking Configuration on macOS device
The SSO extension framework from Apple and the Microsoft Enterprise SSO Extension built on it require that certain domains are exempted from TLS interception/inspection (also known as break and inspect proxying). The following domains must not be subject to TLS inspection:
- app-site-association.cdn-apple.com
- app-site-association.networking.apple
Check if the SSO configuration is broken due to TLS Inspection
You can validate if TLS inspection is impacting your SSO configuration by running a sysdiagnose from the Terminal application on an impacted device:
sudo sysdiagnose -f ~/Desktop/
The sysdiagnose will be saved to your desktop as a .tar.gz archive. Extract the archive and open the system_logs.logarchive file. This will open in the Console application. Search for com.apple.appsso and change the filter to SUBSYSTEM:
Look for events stating that there are Associated Domain failures, especially related to Microsoft domains, such as login.microsoftonline.com. These events might indicate TLS inspection issues, which will prevent the SSO Extension from working properly. Apple domains will not appear in the sysdiagnose log, even if they are impacted by an unsupported TLS inspection configuration.
Validate TLS Inspection Configuration
Apple provides a macOS tool for checking a number of common configuration issues called the Mac Evaluation Utility. This tool can be downloaded from AppleSeed for IT. If you have access to AppleSeed for IT then download the Mac Evaluation Utility from the Resources area. After installing the application, run an evaluation. Once the evaluation is complete, navigate to HTTPS Interception --> Additional Content --> and check the two items below:
If these checks have a warning or error then there might be TLS inspection occurring on the device. Work with your network team to exempt *.cdn-apple.com and *.networking.apple from TLS inspection.
Output detailed swcd logs
Apple provides a command line utility called swcutil that allows for monitoring the progress of the associated domain validation. You can monitor for any associated domain errors using the following command:
sudo swcutil watch --verbose
Locate the following entry in the logs and check if it is marked approved, or if there're any errors:
```
Entry s = authsrv, a = UBF8T346G9.com.microsoft.CompanyPortalMac, d = login.microsoftonline.com
```
Clear macOS TLS Inspection Cache
If you have issues with associated domains and have allow-listed domains in your on-device TLS inspection tool, then it may take some time for Apple's associated domain validation cache to be invalidated. Unfortunately, there're no deterministic steps that re-trigger associated domain re-validation on all machines, but there're a few things that can be attempted.
You can run following commands to reset the device's cache:
pkill -9 swcd
sudo swcutil reset
pkill -9 AppSSOAgent
Re-test the SSO extension configuration after resetting the cache.
Sometimes, this command is insufficient and doesn't fully reset the cache. In these cases, you can attempt the following:
- Remove or move the Intune Company Portal app to the Trash, then restart your device. After the restart is complete, you can try re-install the Company Portal app.
- Re-enroll your device.
If none of above methods resolve your issue, there may be something else in your environment that could be blocking the associated domain validation. If this happens, please reach out to Apple support for further troubleshooting.
Validate SSO configuration profile on macOS device
Assuming the MDM administrator has followed the steps in the previous section MDM Deployment of SSO Extension Profile, the next step is to verify if the profile has been deployed successfully to the device.
Locate SSO extension MDM configuration profile
From the macOS device, select on the System Settings.
When the System Settings appears type Profiles and hit return.
This action should bring up the Profiles panel.
Screenshot callout Description 1 Indicates that the device is under MDM Management. 2 There might be multiple profiles to choose from. In this example, the Microsoft Enterprise SSO Extension Profile is called Extensible Single Sign On Profile-32f37be3-302e-4549-a3e3-854d300e117a. Note
Depending on the type of MDM being used, there could be several profiles listed and their naming scheme is arbitrary depending on the MDM configuration. Select each one and inspect that the Settings row indicates that it is a Single Sign On Extension.
Double-click on the configuration profile that matches a Settings value of Single Sign On Extension.
Screenshot callout Configuration profile setting Description 1 Signed Signing authority of the MDM provider. 2 Installed Date/Timestamp showing when the extension was installed (or updated). 3 Settings: Single Sign On Extension Indicates that this configuration profile is an Apple SSO Extension type. 4 Extension Identifier that maps to the bundle ID of the application that is running the Microsoft Enterprise Extension Plugin. The identifier must always be set to com.microsoft.CompanyPortalMac.ssoextensionand the Team Identifier must appear as (UBF8T346G9) if the profile is installed on a macOS device. If any values differ, then the MDM doesn't invoke the extension correctly.5 Type The Microsoft Enterprise SSO Extension must always be set to a Redirect extension type. For more information, see Redirect vs Credential Extension Types. 6 URLs The login URLs belonging to the Identity Provider (Microsoft Entra ID). See list of supported URLs. All Apple SSO Redirect Extensions must have the following MDM Payload components in the configuration profile:
MDM payload component Description Extension Identifier Includes both the Bundle Identifier and Team Identifier of the application on the macOS device, running the Extension. Note: The Microsoft Enterprise SSO Extension should always be set to: com.microsoft.CompanyPortalMac.ssoextension (UBF8T346G9) to inform the macOS operating system that the extension client code is part of the Intune Company Portal application. Type Must be set to Redirect to indicate a Redirect Extension type. URLs Endpoint URLs of the identity provider (Microsoft Entra ID), where the operating system routes authentication requests to the extension. Optional Extension Specific Configuration Dictionary values that can act as configuration parameters. In the context of Microsoft Enterprise SSO Extension, these configuration parameters are called feature flags. See feature flag definitions. Note
The MDM definitions for Apple's SSO Extension profile can be referenced in the article Extensible Single Sign-on MDM payload settings for Apple devices Microsoft has implemented our extension based on this schema. See Microsoft Enterprise SSO plug-in for Apple devices
To verify that the correct profile for the Microsoft Enterprise SSO Extension is installed, the Extension field should match: com.microsoft.CompanyPortalMac.ssoextension (UBF8T346G9).
Take note of the Installed field in the configuration profile as it can be a useful troubleshooting indicator, when changes are made to its configuration.
If the correct configuration profile has been verified, proceed to the Application Auth Flow Troubleshooting section.
MDM configuration profile is missing
If the SSO extension configuration profile doesn't appear in the Profiles list after following the previous section, it could be that the MDM configuration has User/Device targeting enabled, which is effectively filtering out the user or device from receiving the configuration profile. Check with your MDM administrator and collect the Console logs found in the next section.
Collect MDM specific console logs
From the macOS device, double-click on the Applications folder, then double-click on the Utilities folder.
Double-click on the Console application.
Click the Start button to enable the Console trace logging.
Have the MDM administrator try to redeploy the config profile to this macOS device/user and force a sync cycle.
Type subsystem:com.apple.ManagedClient into the search bar and hit return.
Where the cursor is flashing in the search bar type message:Extensible.
You should now see the MDM Console logs filtered on Extensible SSO configuration profile activities. The following screenshot shows a log entry Installed configuration profile, showing that the configuration profile was installed.
Application auth flow troubleshooting
The guidance in this section assumes that the macOS device has a correctly deployed configuration profile. See Validate SSO Configuration Profile on macOS Device for the steps.
Once deployed the Microsoft Enterprise SSO Extension for Apple devices supports two types of application authentication flows for each application type. When troubleshooting, it's important to understand the type of application being used.
Application types
| Application type | Interactive auth | Silent auth | Description | Examples |
|---|---|---|---|---|
| Native MSAL App | X | X | MSAL (Microsoft Authentication Library) is an application developer framework tailored for building applications with the Microsoft identity platform (Microsoft Entra ID). Apps built on MSAL version 1.1 or greater are able to integrate with the Microsoft Enterprise SSO Extension. If the application is SSO extension (broker) aware it utilizes the extension without any further configuration for more information, see our MSAL developer sample documentation. |
Microsoft To Do |
| Non-MSAL Native/Browser SSO | X | Applications that use Apple networking technologies or webviews can be configured to obtain a shared credential from the SSO Extension Feature flags must be configured to ensure that the bundle ID for each app is allowed to obtain the shared credential (PRT). |
Microsoft Word Safari Microsoft Edge Visual Studio |
Important
Not all Microsoft first-party native applications use the MSAL framework. At the time of this article's publication, most of the Microsoft Office macOS applications still rely on the older ADAL library framework, and thus rely on the Browser SSO flow.
How to find the bundle ID for an application on macOS
From the macOS device, double-click on the Applications folder, then double-click on the Utilities folder.
Double-click on the Terminal application.
When the Terminal opens type
osascript -e 'id of app "<appname>"'at the prompt. See some examples follow:% osascript -e 'id of app "Safari"' com.apple.Safari % osascript -e 'id of app "OneDrive"' com.microsoft.OneDrive % osascript -e 'id of app "Microsoft Edge"' com.microsoft.edgemacNow that the bundle ID(s) have been gathered, follow our guidance to configure the feature flags to ensure that Non-MSAL Native/Browser SSO apps can utilize the SSO Extension. Note: All bundle ids are case sensitive for the Feature flag configuration.
Caution
Applications that do not use Apple Networking technologies (like WKWebview and NSURLSession) will not be able to use the shared credential (PRT) from the SSO Extension. Both Google Chrome and Mozilla Firefox fall into this category. Even if they are configured in the MDM configuration profile, the result will be a regular authentication prompt in the browser.
Bootstrapping
By default, only MSAL apps invoke the SSO Extension, and then in turn the Extension acquires a shared credential (PRT) from Microsoft Entra ID. However, the Safari browser application or other Non-MSAL applications can be configured to acquire the PRT. See Allow users to sign in from applications that don't use MSAL and the Safari browser. After the SSO extension acquires a PRT, it will store the credential in the user login Keychain. Next, check to ensure that the PRT is present in the user's keychain:
Checking keychain access for PRT
From the macOS device, double-click on the Applications folder, then double-click on the Utilities folder.
Double-click on the Keychain Access application.
Under Default Keychains select Local Items (or iCloud).
- Ensure that the All Items is selected.
- In the search bar, on the right-hand side, type
primaryrefresh(To filter).
Screenshot callout Keychain credential component Description 1 All Items Shows all types of credentials across Keychain Access 2 Keychain Search Bar Allows filtering by credential. To filter for the Microsoft Entra PRT type primaryrefresh3 Kind Refers to the type of credential. The Microsoft Entra PRT credential is an Application Password credential type 4 Account Displays the Microsoft Entra user account, which owns the PRT in the format: UserObjectId.TenantId-login.windows.net5 Where Displays the full name of the credential. The Microsoft Entra PRT credential begins with the following format: primaryrefreshtoken-29d9ed98-a469-4536-ade2-f981bc1d605The 29d9ed98-a469-4536-ade2-f981bc1d605 is the Application ID for the Microsoft Authentication Broker service, responsible for handling PRT acquisition requests6 Modified Shows when the credential was last updated. For the Microsoft Entra PRT credential, anytime the credential is bootstrapped or updated by an interactive sign-on event it updates the date/timestamp 7 Keychain Indicates which Keychain the selected credential resides. The Microsoft Entra PRT credential resides in the Local Items or iCloud Keychain. When iCloud is enabled on the macOS device, the Local Items Keychain will become the iCloud keychain If the PRT isn't found in Keychain Access, do the following based on the application type:
- Native MSAL: Check that the application developer, if the app was built with MSAL version 1.1 or greater, has enabled the application to be broker aware. Also, check Deployment Troubleshooting steps to rule out any deployment issues.
- Non MSAL (Safari): Check to ensure that the feature flag
browser_sso_interaction_enabledis set to 1 and not 0 in the MDM configuration profile
Authentication flow after bootstrapping a PRT
Now that the PRT (shared credential) has been verified, before doing any deeper troubleshooting, it's helpful to understand the high-level steps for each application type and how it interacts with the Microsoft Enterprise SSO Extension plugin (broker app). The following animations and descriptions should help macOS administrators understand the scenario before looking at any logging data.
Native MSAL application
Scenario: An application developed to use MSAL (Example: Microsoft To Do client) that is running on an Apple device needs to sign the user in with their Microsoft Entra account in order to access a Microsoft Entra protected service (Example: Microsoft To Do Service).
- MSAL-developed applications invoke the SSO extension directly, and send the PRT to the Microsoft Entra token endpoint along with the application's request for a token for a Microsoft Entra protected resource
- Microsoft Entra ID validates the PRT credential, and returns an application-specific token back to the SSO extension broker
- The SSO extension broker then passes the token to the MSAL client application, which then sends it to the Microsoft Entra protected resource
- The user is now signed into the app and the authentication process is complete
Non-MSAL/Browser SSO
Scenario: A user on an Apple device opens up the Safari web browser (or any Non-MSAL native app that supports the Apple Networking Stack) to sign into a Microsoft Entra protected resource (Example: https://office.com).
- Using a Non-MSAL application (Example: Safari), the user attempts to sign into a Microsoft Entra integrated application (Example: office.com) and is redirected to obtain a token from Microsoft Entra ID
- As long as the Non-MSAL application is allow-listed in the MDM payload configuration, the Apple network stack intercepts the authentication request and redirects the request to the SSO Extension broker
- Once the SSO extension receives the intercepted request, the PRT is sent to the Microsoft Entra token endpoint
- Microsoft Entra ID validates the PRT, and returns an application-specific token back to the SSO Extension
- The application-specific token is given to the Non-MSAL client application, and the client application sends the token to access the Microsoft Entra protected service
- The user now has completed the sign-in and the authentication process is complete
Obtaining the SSO extension logs
One of the most useful tools to troubleshoot various issues with the SSO extension are the client logs from the Apple device.
Save SSO extension logs from Company Portal app
From the macOS device, double-click on the Applications folder.
Double-click on the Company Portal application.
When the Company Portal loads, navigate to the top menu bar: Help->Save diagnostic report. There's no need to Sign into the app.
Save the Company Portal Log archive to place of your choice (for example: Desktop).
Open the CompanyPortal.zip archive and Open the SSOExtension.log file with any text editor.
Tip
A handy way to view the logs is using Visual Studio Code and installing the Log Viewer extension.
Tailing SSO extension logs on macOS with terminal
During troubleshooting it might be useful to reproduce a problem while tailing the SSOExtension logs in real time:
From the macOS device, double-click on the Applications folder, then double-click on the Utilities folder.
Double-click on the Terminal application.
When the Terminal opens type:
tail -F ~/Library/Containers/com.microsoft.CompanyPortalMac.ssoextension/Data/Library/Caches/Logs/Microsoft/SSOExtension/*Note
The trailing /* indicates that multiple logs will be tailed should any exist
% tail -F ~/Library/Containers/com.microsoft.CompanyPortalMac.ssoextension/Data/Library/Caches/Logs/Microsoft/SSOExtension/* ==> /Users/<username>/Library/Containers/com.microsoft.CompanyPortalMac.ssoextension/Data/Library/Caches/Logs/Microsoft/SSOExtension/SSOExtension 2022-12-25--13-11-52-855.log <== 2022-12-29 14:49:59:281 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Handling SSO request, requested operation: 2022-12-29 14:49:59:281 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Ignoring this SSO request... 2022-12-29 14:49:59:282 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Finished SSO request. 2022-12-29 14:49:59:599 | I | Beginning authorization request 2022-12-29 14:49:59:599 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Checking for feature flag browser_sso_interaction_enabled, value in config 1, value type __NSCFNumber 2022-12-29 14:49:59:599 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Feature flag browser_sso_interaction_enabled is enabled 2022-12-29 14:49:59:599 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Checking for feature flag browser_sso_disable_mfa, value in config (null), value type (null) 2022-12-29 14:49:59:599 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Checking for feature flag disable_browser_sso_intercept_all, value in config (null), value type (null) 2022-12-29 14:49:59:600 | I | Request does not need UI 2022-12-29 14:49:59:600 | I | TID=783491 MSAL 1.2.4 Mac 13.0.1 [2022-12-29 19:49:59] Checking for feature flag admin_debug_mode_enabled, value in config (null), value type (null)As you reproduce the issue, keep the Terminal window open to observe the output from the tailed SSOExtension logs.
Exporting SSO extension logs on iOS
It isn't possible to view iOS SSO Extension logs in real time, as it is on macOS. The iOS SSO extension logs can be exported from the Microsoft Authenticator app, and then reviewed from another device:
Open the Microsoft Authenticator app:
Press the menu button in the upper left:
Choose the "Send feedback" option:
Choose the "Having trouble" option:
Press the View diagnostic data option:
Tip
If you are working with Microsoft Support, at this stage you can press the Send button to send the logs to support. This will provide you with an Incident ID, which you can provide to your Microsoft Support contact.
Press the "Copy all" button to copy the logs to your iOS device's clipboard. You can then save the log files elsewhere for review or send them via email or other file sharing methods:
Understanding the SSO extension logs
Analyzing the SSO extension logs is an excellent way to troubleshoot the authentication flow from applications sending authentication requests to Microsoft Entra ID. Any time the SSO extension Broker is invoked, a series of logging activities results, and these activities are known as Authorization Requests. The logs contain the following useful information for troubleshooting:
- Feature Flag configuration
- Authorization Request Types
- Native MSAL
- Non MSAL/Browser SSO
- Interaction with the macOS Keychain for credential retrival/storage operations
- Correlation IDs for Microsoft Entra sign-in events
- PRT acquisition
- Device Registration
Caution
The SSO extension logs are extremely verbose, especially when looking at Keychain credential operations. For this reason, it's always best to understand the scenario before looking at the logs during troubleshooting.
Log structure
The SSO extension logs are broken down into columns. The following screenshot shows the column breakdown of the logs:
| Column | Column name | Description |
|---|---|---|
| 1 | Local Date/Time | The Local Date and Time displayed |
| 2 | I-Information W-Warning E-Error |
Displays Information, Warning, or Errors |
| 3 | Thread ID (TID) | Displays the thread ID of the SSO extension Broker App's execution |
| 4 | MSAL Version Number | The Microsoft Enterprise SSO extension Broker Plugin is build as an MSAL app. This column denotes the version of MSAL that the broker app is running |
| 5 | macOS version | Show the version of the macOS operating system |
| 6 | UTC Date/Time | The UTC Date and Time displayed |
| 7 | Correlation ID | Lines in the logs that have to do with Microsoft Entra ID or Keychain operations extend the UTC Date/Time column with a Correlation ID |
| 8 | Message | Shows the detailed messaging of the logs. Most of the troubleshooting information can be found by examining this column |
Feature flag configuration
During the MDM configuration of the Microsoft Enterprise SSO Extension, an optional extension specific data can be sent as instructions to change how the SSO extension behaves. These configuration specific instructions are known as Feature Flags. The Feature Flag configuration is especially important for Non-MSAL/Browser SSO authorization requests types, as the Bundle ID can determine if the Extension is invoked or not. See Feature Flag documentation. Every authorization request begins with a Feature Flag configuration report. The following screenshot walks through an example feature flag configuration:
| Callout | Feature flag | Description |
|---|---|---|
| 1 | browser_sso_interaction_enabled | Non-MSAL or Safari browser can bootstrap a PRT |
| 2 | browser_sso_disable_mfa | (Now deprecated) During bootstrapping of the PRT credential, by default MFA is required. Notice this configuration is set to null which means that the default configuration is enforced |
| 3 | disable_explicit_app_prompt | Replaces prompt=login authentication requests from applications to reduce prompting |
| 4 | AppPrefixAllowList | Any Non-MSAL application that has a Bundle ID that starts with com.micorosoft. can be intercepted and handled by the SSO extension broker |
Important
Feature flags set to null means that their default configuration is in place. Check Feature Flag documentation for more details
MSAL native application sign-in flow
The following section walks through how to examine the SSO extension logs for the Native MSAL Application auth flow. For this example, we're using the MSAL macOS/iOS sample application as the client application, and the application is making a call to the Microsoft Graph API to display the sign-in user's information.
MSAL native: Interactive flow walkthrough
The following actions should take place for a successful interactive sign-on:
- The user signs in to the MSAL macOS sample app.
- The Microsoft SSO Extension Broker is invoked and handles the request.
- Microsoft SSO Extension Broker undergoes the bootstrapping process to acquire a PRT for the signed in user.
- Store the PRT in the Keychain.
- Check for the presence of a Device Registration object in Microsoft Entra ID (WPJ).
- Return an access token to the client application to access the Microsoft Graph with a scope of User.Read.
Important
The sample log snippets that follows, have been annotated with comment headers // that are not seen in the logs. They are used to help illustrate a specific action being undertaken. We have documented the log snippets this way to assist with copy and paste operations. In addition, the log examples have been trimmed to only show lines of significance for troubleshooting.
The user clicks on the Call Microsoft Graph API button to invoke the sign-in process.
//////////////////////////
//get_accounts_operation//
//////////////////////////
Handling SSO request, requested operation: get_accounts_operation
(Default accessor) Get accounts.
(MSIDAccountCredentialCache) retrieving cached credentials using credential query
(Default accessor) Looking for token with aliases (null), tenant (null), clientId 08dc26ab-e050-465e-beb4-d3f2d66647a5, scopes (null)
(Default accessor) No accounts found in default accessor.
(Default accessor) No accounts found in other accessors.
Completed get accounts SSO request with a personal device mode.
Request complete
Request needs UI
ADB 3.1.40 -[ADBrokerAccountManager allBrokerAccounts:]
ADB 3.1.40 -[ADBrokerAccountManager allMSIDBrokerAccounts:]
(Default accessor) Get accounts.
No existing accounts found, showing webview
/////////
//login//
/////////
Handling SSO request, requested operation: login
Handling interactive SSO request...
Starting SSO broker request with payload: {
authority = "https://login.microsoftonline.com/common";
"client_app_name" = MSALMacOS;
"client_app_version" = "1.0";
"client_id" = "08dc26ab-e050-465e-beb4-d3f2d66647a5";
"client_version" = "1.1.7";
"correlation_id" = "3506307A-E90F-4916-9ED5-25CF81AE97FC";
"extra_oidc_scopes" = "openid profile offline_access";
"instance_aware" = 0;
"msg_protocol_ver" = 4;
prompt = "select_account";
"provider_type" = "provider_aad_v2";
"redirect_uri" = "msauth.com.microsoft.idnaace.MSALMacOS://auth";
scope = "user.read";
}
////////////////////////////////////////////////////////////
//Request PRT from Microsoft Authentication Broker Service//
////////////////////////////////////////////////////////////
Using request handler <ADInteractiveDevicelessPRTBrokerRequestHandler: 0x117ea50b0>
(Default accessor) Looking for token with aliases (null), tenant (null), clientId 29d9ed98-a469-4536-ade2-f981bc1d605e, scopes (null)
Attempting to get Deviceless Primary Refresh Token interactively.
Caching AAD Environements
networkHost: login.microsoftonline.com, cacheHost: login.windows.net, aliases: login.microsoftonline.com, login.windows.net, login.microsoft.com, sts.windows.net
networkHost: login.partner.microsoftonline.cn, cacheHost: login.partner.microsoftonline.cn, aliases: login.partner.microsoftonline.cn, login.chinacloudapi.cn
networkHost: login.microsoftonline.de, cacheHost: login.microsoftonline.de, aliases: login.microsoftonline.de
networkHost: login.microsoftonline.us, cacheHost: login.microsoftonline.us, aliases: login.microsoftonline.us, login.usgovcloudapi.net
networkHost: login-us.microsoftonline.com, cacheHost: login-us.microsoftonline.com, aliases: login-us.microsoftonline.com
Resolved authority, validated: YES, error: 0
[MSAL] Resolving authority: Masked(not-null), upn: Masked(null)
[MSAL] Resolved authority, validated: YES, error: 0
[MSAL] Start webview authorization session with webview controller class MSIDAADOAuthEmbeddedWebviewController:
[MSAL] Presenting web view controller.
The logging sample can be broken down into three segments:
| Segment | Description |
|---|---|
get_accounts_operation |
Checks to see if there are any existing accounts in the cache - ClientID: The application ID registered in Microsoft Entra ID for this MSAL app ADB 3.1.40 indicates that version of the Microsoft Enterprise SSO Extension Broker plugin |
login |
Broker handles the request for Microsoft Entra ID: - Handling interactive SSO request...: Denotes an interactive request - correlation_id: Useful for cross referencing with the Microsoft Entra server-side sign-in logs - scope: User.Read API permission scope being requested from the Microsoft Graph - client_version: version of MSAL that the application is running - redirect_uri: MSAL apps use the format msauth.com.<Bundle ID>://auth |
| PRT Request | Bootstrapping process to acquire a PRT interactively has been initiated and renders the Webview SSO Session Microsoft Authentication Broker Service - clientId: 29d9ed98-a469-4536-ade2-f981bc1d605e - All PRT requests are made to Microsoft Authentication Broker Service |
The SSO Webview Controller appears and user is prompted to enter their Microsoft Entra login (UPN/email)
Note
Clicking on the i in the bottom left corner of the webview controller displays more information about the SSO extension and the specifics about the app that has invoked it.
After the user successfully enters their Microsoft Entra credentials, the following log entries are written to the SSO extension logs
SSOExtensionLogs
///////////////
//Acquire PRT//
///////////////
[MSAL] -completeWebAuthWithURL: msauth://microsoft.aad.brokerplugin/?code=(not-null)&client_info=(not-null)&state=(not-null)&session_state=(not-null)
[MSAL] Dismissed web view controller.
[MSAL] Result from authorization session callbackURL host: microsoft.aad.brokerplugin , has error: NO
[MSAL] (Default accessor) Looking for token with aliases (
"login.windows.net",
"login.microsoftonline.com",
"login.windows.net",
"login.microsoft.com",
"sts.windows.net"
), tenant (null), clientId 29d9ed98-a469-4536-ade2-f981bc1d605e, scopes (null)
Saving PRT response in cache since no other PRT was found
[MSAL] Saving keychain item, item info Masked(not-null)
[MSAL] Keychain find status: 0
Acquired PRT.
///////////////////////////////////////////////////////////////////////
//Discover if there is an Azure AD Device Registration (WPJ) present //
//and if so re-acquire a PRT and associate with Device ID //
///////////////////////////////////////////////////////////////////////
WPJ Discovery: do discovery in environment 0
Attempt WPJ discovery using tenantId.
WPJ discovery succeeded.
Using cloud authority from WPJ discovery: https://login.microsoftonline.com/common
ADBrokerDiscoveryAction completed. Continuing Broker Flow.
PRT needs upgrade as device registration state has changed. Device is joined 1, prt is joined 0
Beginning ADBrokerAcquirePRTInteractivelyAction
Attempting to get Primary Refresh Token interactively.
Acquiring broker tokens for broker client id.
Resolving authority: Masked(not-null), upn: auth.placeholder-61945244__domainname.com
Resolved authority, validated: YES, error: 0
Enrollment id read from intune cache : (null).
Handle silent PRT response Masked(not-null), error Masked(null)
Acquired broker tokens.
Acquiring PRT.
Acquiring PRT using broker refresh token.
Requesting PRT from authority https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
[MSAL] (Default accessor) Looking for token with aliases (
"login.windows.net",
"login.microsoftonline.com",
"login.windows.net",
"login.microsoft.com",
"sts.windows.net"
), tenant (null), clientId (null), scopes (null)
[MSAL] Acquired PRT successfully!
Acquired PRT.
ADBrokerAcquirePRTInteractivelyAction completed. Continuing Broker Flow.
Beginning ADBrokerAcquireTokenWithPRTAction
Resolving authority: Masked(not-null), upn: auth.placeholder-61945244__domainname.com
Resolved authority, validated: YES, error: 0
Handle silent PRT response Masked(not-null), error Masked(null)
//////////////////////////////////////////////////////////////////////////
//Provide Access Token received from Azure AD back to Client Application//
//and complete authorization request //
//////////////////////////////////////////////////////////////////////////
[MSAL] (Default cache) Removing credentials with type AccessToken, environment login.windows.net, realm TenantID, clientID 08dc26ab-e050-465e-beb4-d3f2d66647a5, unique user ID dbb22b2f, target User.Read profile openid email
ADBrokerAcquireTokenWithPRTAction succeeded.
Composing broker response.
Sending broker response.
Returning to app (msauth.com.microsoft.idnaace.MSALMacOS://auth) - protocol version: 3
hash: 4A07DFC2796FD75A27005238287F2505A86BA7BB9E6A00E16A8F077D47D6D879
payload: Masked(not-null)
Completed interactive SSO request.
Completed interactive SSO request.
Request complete
Completing SSO request...
Finished SSO request.
At this point in the authentication/authorization flow, the PRT has been bootstrapped and it should be visible in the macOS keychain access. See Checking Keychain Access for PRT. The MSAL macOS sample application uses the access token received from the Microsoft SSO Extension Broker to display the user's information.
Next, examine server-side Microsoft Entra sign-in logs based on the correlation ID collected from the client-side SSO extension logs. For more information, see Sign-in logs in Microsoft Entra ID.
View Microsoft Entra sign-in logs by correlation ID filter
- Open the Microsoft Entra Sign-ins for the tenant where the application is registered.
- Select User sign-ins (interactive).
- Select the Add Filters and select the Correlation Id radio button.
- Copy and paste the Correlation ID obtained from the SSO extension logs and select Apply.
For the MSAL Interactive Login Flow, we expect to see an interactive sign-in for the resource Microsoft Authentication Broker service. This event is where the user entered their password to bootstrap the PRT.
There are also non-interactive sign-in events, due to the fact the PRT is used to acquire the access token for the client application's request. Follow the View Microsoft Entra sign-in logs by Correlation ID Filter but in step 2, select User sign-ins (non-interactive).
| Sign-in log attribute | Description |
|---|---|
| Application | Display Name of the Application registration in the Microsoft Entra tenant where the client application authenticates. |
| Application Id | Also referred to the ClientID of the application registration in the Microsoft Entra tenant. |
| Resource | The API resource that the client application is trying to obtain access to. In this example, the resource is the Microsoft Graph API. |
| Incoming Token Type | An Incoming token type of Primary Refresh Token (PRT) shows the input token being used to obtain an access token for the resource. |
| User Agent | The user agent string in this example is showing that the Microsoft SSO Extension is the application processing this request. A useful indicator that the SSO extension is being used, and broker auth request is taking place. |
| Microsoft Entra app authentication library | When an MSAL application is being used the details of the library and the platform are written here. |
| Oauth Scope Information | The Oauth2 scope information requested for the access token. (User.Read,profile,openid,email). |
MSAL Native: Silent flow walkthrough
After a period of time, the access token will no longer be valid. So, if the user reclicks on the Call Microsoft Graph API button. The SSO extension attempts to refresh the access token with the already acquired PRT.
SSOExtensionLogs
/////////////////////////////////////////////////////////////////////////
//refresh operation: Assemble Request based on User information in PRT /
/////////////////////////////////////////////////////////////////////////
Beginning authorization request
Request does not need UI
Handling SSO request, requested operation: refresh
Handling silent SSO request...
Looking account up by home account ID dbb22b2f, displayable ID auth.placeholder-61945244__domainname.com
Account identifier used for request: Masked(not-null), auth.placeholder-61945244__domainname.com
Starting SSO broker request with payload: {
authority = "https://login.microsoftonline.com/<TenantID>";
"client_app_name" = MSALMacOS;
"client_app_version" = "1.0";
"client_id" = "08dc26ab-e050-465e-beb4-d3f2d66647a5";
"client_version" = "1.1.7";
"correlation_id" = "45418AF5-0901-4D2F-8C7D-E7C5838A977E";
"extra_oidc_scopes" = "openid profile offline_access";
"home_account_id" = "<UserObjectId>.<TenantID>";
"instance_aware" = 0;
"msg_protocol_ver" = 4;
"provider_type" = "provider_aad_v2";
"redirect_uri" = "msauth.com.microsoft.idnaace.MSALMacOS://auth";
scope = "user.read";
username = "auth.placeholder-61945244__domainname.com";
}
//////////////////////////////////////////
//Acquire Access Token with PRT silently//
//////////////////////////////////////////
Using request handler <ADSSOSilentBrokerRequestHandler: 0x127226a10>
Executing new request
Beginning ADBrokerAcquireTokenSilentAction
Beginning silent flow.
[MSAL] Resolving authority: Masked(not-null), upn: auth.placeholder-61945244__domainname.com
[MSAL] (Default cache) Removing credentials with type AccessToken, environment login.windows.net, realm <TenantID>, clientID 08dc26ab-e050-465e-beb4-d3f2d66647a5, unique user ID dbb22b2f, target User.Read profile openid email
[MSAL] (MSIDAccountCredentialCache) retrieving cached credentials using credential query
[MSAL] Silent controller with PRT finished with error Masked(null)
ADBrokerAcquireTokenWithPRTAction succeeded.
Composing broker response.
Sending broker response.
Returning to app (msauth.com.microsoft.idnaace.MSALMacOS://auth) - protocol version: 3
hash: 292FBF0D32D7EEDEB520098E44C0236BA94DDD481FAF847F7FF6D5CD141B943C
payload: Masked(not-null)
Completed silent SSO request.
Request complete
Completing SSO request...
Finished SSO request.
The logging sample can be broken down into two segments:
| Segment | Description |
|---|---|
refresh |
Broker handles the request for Microsoft Entra ID: - Handling silent SSO request...: Denotes a silent request - correlation_id: Useful for cross referencing with the Microsoft Entra server-side sign-in logs - scope: User.Read API permission scope being requested from the Microsoft Graph - client_version: version of MSAL that the application is running - redirect_uri: MSAL apps use the format msauth.com.<Bundle ID>://authRefresh has notable differences to the request payload: - authority: Contains the Microsoft Entra tenant URL endpoint as opposed to the common endpoint - home_account_id: Show the User account in the format <UserObjectId>.<TenantID> - username: hashed UPN format auth.placeholder-XXXXXXXX__domainname.com |
| PRT Refresh and Acquire Access Token | This operation revalidates the PRT and refreshes it if necessary, before returning the access token back to the calling client application. |
We can again take the correlation Id obtained from the client-side SSO Extension logs and cross reference with the server-side Microsoft Entra sign-in logs.
The Microsoft Entra Sign-in shows identical information to the Microsoft Graph resource from the login operation in the previous interactive login section.
Non-MSAL/Browser SSO application login flow
The following section walks through how to examine the SSO extension logs for the Non-MSAL/Browser Application auth flow. For this example, we're using the Apple Safari browser as the client application, and the application is making a call to the Office.com (OfficeHome) web application.
Non-MSAL/Browser SSO flow walkthrough
The following actions should take place for a successful sign-on:
- Assume that User who already has undergone the bootstrapping process has an existing PRT.
- On a device, with the Microsoft SSO Extension Broker deployed, the configured feature flags are checked to ensure that the application can be handled by the SSO Extension.
- Since the Safari browser adheres to the Apple Networking Stack, the SSO extension tries to intercept the Microsoft Entra auth request.
- The PRT is used to acquire a token for the resource being requested.
- If the device is Microsoft Entra registered, it passes the Device ID along with the request.
- The SSO extension populates the header of the Browser request to sign-in to the resource.
The following client-side SSO Extension logs show the request being handled transparently by the SSO extension broker to fulfill the request.
SSOExtensionLogs
Created Browser SSO request for bundle identifier com.apple.Safari, cookie SSO include-list (
), use cookie sso for this app 0, initiating origin https://www.office.com
Init MSIDKeychainTokenCache with keychainGroup: Masked(not-null)
[Browser SSO] Starting Browser SSO request for authority https://login.microsoftonline.com/common
[MSAL] (Default accessor) Found 1 tokens
[Browser SSO] Checking PRTs for deviceId 73796663
[MSAL] [Browser SSO] Executing without UI for authority https://login.microsoftonline.com/common, number of PRTs 1, device registered 1
[MSAL] [Browser SSO] Processing request with PRTs and correlation ID in headers (null), query 67b6a62f-6c5d-40f1-8440-a8edac7a1f87
[MSAL] Resolving authority: Masked(not-null), upn: Masked(null)
[MSAL] No cached preferred_network for authority
[MSAL] Caching AAD Environements
[MSAL] networkHost: login.microsoftonline.com, cacheHost: login.windows.net, aliases: login.microsoftonline.com, login.windows.net, login.microsoft.com, sts.windows.net
[MSAL] networkHost: login.partner.microsoftonline.cn, cacheHost: login.partner.microsoftonline.cn, aliases: login.partner.microsoftonline.cn, login.chinacloudapi.cn
[MSAL] networkHost: login.microsoftonline.de, cacheHost: login.microsoftonline.de, aliases: login.microsoftonline.de
[MSAL] networkHost: login.microsoftonline.us, cacheHost: login.microsoftonline.us, aliases: login.microsoftonline.us, login.usgovcloudapi.net
[MSAL] networkHost: login-us.microsoftonline.com, cacheHost: login-us.microsoftonline.com, aliases: login-us.microsoftonline.com
[MSAL] Resolved authority, validated: YES, error: 0
[MSAL] Found registration registered in login.microsoftonline.com, isSameAsRequestEnvironment: Yes
[MSAL] Passing device header in browser SSO for device id 43cfaf69-0f94-4d2e-a815-c103226c4c04
[MSAL] Adding SSO-cookie header with PRT Masked(not-null)
SSO extension cleared cookies before handling request 1
[Browser SSO] SSO response is successful 0
[MSAL] Keychain find status: 0
[MSAL] (Default accessor) Found 1 tokens
Request does not need UI
[MSAL] [Browser SSO] Checking PRTs for deviceId 73796663
Request complete
| SSO extension log component | Description |
|---|---|
| Created Browser SSO request | All Non-MSAL/Browser SSO requests begin with this line: - bundle identifier: Bundle ID: com.apple.Safari- initiating origin: Web URL the browser is accessing before hitting one of the login URLs for Microsoft Entra ID (https://office.com) |
| Starting Browser SSO request for authority | Resolves the number of PRTs and if the Device is Registered: https://login.microsoftonline.com/common, number of PRTs 1, device registered 1 |
| Correlation ID | [Browser SSO] Processing request with PRTs and correlation ID in headers (null), query <CorrelationID>. This ID is important for cross-referencing with the Microsoft Entra server-side sign-in logs |
| Device Registration | Optionally if the device is Microsoft Entra registered, the SSO extension can pass the device header in Browser SSO requests: - Found registration registered in - login.microsoftonline.com, isSameAsRequestEnvironment: Yes Passing device header in browser SSO for device id 43cfaf69-0f94-4d2e-a815-c103226c4c04 |
Next, use the correlation ID obtained from the Browser SSO extension logs to cross-reference the Microsoft Entra sign-in logs.
| Sign-in log attribute | Description |
|---|---|
| Application | Display Name of the Application registration in the Microsoft Entra tenant where the client application authenticates. In this example, the display name is OfficeHome. |
| Application Id | Also referred to the ClientID of the application registration in the Microsoft Entra tenant. |
| Resource | The API resource that the client application is trying to obtain access to. In this example, the resource is the OfficeHome web application. |
| Incoming Token Type | An Incoming token type of Primary Refresh Token (PRT) shows the input token being used to obtain an access token for the resource. |
| Authentication method detected | Under the Authentication Details tab, the value of Microsoft Entra SSO plug-in is useful indicator that the SSO extension is being used to facilitate the Browser SSO request |
| Microsoft Entra SSO extension version | Under the Additional Details tab, this value shows the version of the Microsoft Enterprise SSO extension Broker app. |
| Device ID | If the device is registered, the SSO extension can pass the Device ID to handle device authentication requests. |
| Operating System | Shows the type of operating system. |
| Compliant | SSO extension can facilitate Compliance policies by passing the device header. The requirements are: - Microsoft Entra Device Registration - MDM Management - Intune or Intune Partner Compliance |
| Managed | Indicates that device is under management. |
| Join Type | macOS and iOS, if registered, can only be of type: Microsoft Entra registered. |
Tip
If you use Jamf Connect, it is recommended that you follow the latest Jamf guidance on integrating Jamf Connect with Microsoft Entra ID. The recommended integration pattern ensures that Jamf Connect works properly with your Conditional Access policies and Microsoft Entra ID Protection.
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for