ben_whitis
New Contributor II
New Contributor II

A Little Background

In 2017, Jamf released an integration with Microsoft Endpoint Manager’s (formerly Intune) Partner Device Management (PDM) API. This API allows Jamf Pro to send inventory data for managed computers to Microsoft Endpoint Manager, where compliance is then calculated using Microsoft Endpoint Manager’s Compliance Policies.

In order for Jamf Pro to send data to Microsoft Endpoint Manager, computers must be registered to Azure AD using Company Portal, and a jamf agent (JamfAAD) must collect and maintain an active user session token. Organizations seeking to use the PDM integration must guide end users through this registration flow.

The following document addresses best practices for registration, including configuration of the JamfAAD agent, Azure AD SSO Extension, using policies to guide the user, and tracking registrations via Extension Attributes.

Configuring the JamfAAD agent

UseWKWebView

JamfAAD must prompt the user to sign in with their Azure AD credentials in order to obtain a user session token. To do this, JamfAAD leverages MSAL, and defaults to MSAL’s ASWebAuthenticationSessionRequest. ASWebAuthenticationSessionRequest calls on the user’s default browser (if that browser supports ASWebAuth) to handle a sign in to login.microsoft.com

However, due to the variability introduced by supporting multiple browsers (ASWebAuth is supported by Chrome, Edge, and Safari), the default browser can often be a point of failure for conditional access registrations.

In Jamf Pro 10.38 and higher, an optional configuration was added to use MSAL’s WKWebView instead. This leverages macOS’s built in WebView to present the Azure AD login. This setting is recommended to all environments that are compatible with WKWebView (note some forms of MFA, like hardware tokens, are not supported by WKWebView at time of writing).

To use UseWKWebView, push this PLIST out to the com.jamf.management.jamfAAD preference domain.

Screenshot 2022-09-23 at 1.57.23 PM.png

ben_whitis_1-1663170319632.png

 

Retry Logic

The JamfAAD agent attempts to refresh the user’s session token when the LaunchAgent loads, and additionally once every two hours. This refresh is performed using an MSAL silent authentication flow. If this silent authentication fails to obtain a user session token for any reason, JamfAAD will fall back to an interactive MSAL flow, resulting in the user being prompted to sign in with their Azure AD credentials again.

In many scenarios, this is JamfAAD helpfully doing its job. For example, if the user’s Azure AD credentials have been changed, JamfAAD will need to prompt the user for their new Azure AD credentials. JamfAAD might also prompt for the user to sign in if a conditional access policy requires interactive sign-ins (this may be a pain point for end users, and conditional access policies should be configured to not force re-authentication if possible).

However, JamfAAD may also fail to retrieve a user’s session token in a scenario where the LaunchAgent loads but a stable network connection has not yet been established. This momentary lack of connectivity may result in JamfAAD falling back to the interactive flow, prompting the user to sign in again. This may manifest as the user having a JamfAAD prompt waiting for them every morning.

In Jamf Pro 10.27 and higher, JamfAAD can be configured to wait and retry a silent authentication a configurable number of times before falling back to an interactive flow. Configuring this retry logic to try again just a couple of times over a few minutes is enough to ensure users are not prompted due to network related timing issues. This setting is recommended for all environments. The retry wait and count settings can be adjusted if desired, but these default settings should cover the most common scenarios.

To configure retry wait and count, push this PLIST to the com.jamf.management.jamfAAD preference domain.

ben_whitis_2-1663170319634.png

 

Azure AD SSO Extensions

In macOS 10.15, Apple rolled out their first iteration of SSO extensions. Microsoft has published their SSO extension, which uses Self Service on macOS, and Microsoft Authenticator on iOS. The SSO extension can handle authentication for any app that uses MSAL, or that supports redirect SSO extensions. Since JamfAAD uses MSAL, this means that the SSO extension can handle the JamfAAD sign-in prompts automatically. This reduces the registration flow to a single authentication in Company Portal.

Note: The SSO extension does not bypass MFA, if the JamfAAD sign in falls into a Conditional Access policy requiring MFA, the user will be prompted to sign in and complete MFA

Microsoft has published documentation on how to configure the Azure AD SSO extension in Jamf Pro here: Microsoft Enterprise SSO plug-in in Jamf Pro

In order to grant JamfAAD access to the SSO extension, com.jamf.management. must be added to the AppPrefixAllowList (step 5 in the Microsoft document). Here's an example plist.

ben_whitis_3-1663170319635.png

 

Prompting Users to Register

To initiate the registration, the user must run the registration policy from Self Service. A policy that leverages osascript, JamfHelper, or other user notification tools can guide the user to execute the policy and provide some explanation of what is happening and why.

Here's a link to a script that leverages osascript to prompt the user to register from Self Service.

ben_whitis_4-1663170319636.png

 

Tracking Registration

After users register, there are two things to look for on the computer itself to gauge whether or not the registration was successful:

  • Is there a Workplace Join key in the user’s Login Keychain
  • Was JamfAAD able to obtain the Azure AD ID of the user

Here's a link to an extension attribute that checks both.

The script can return one of four results:

     1. Registered

This signifies that the user has a WPJ certificate in their keychain, and JamfAAD has successfully obtained their Azure AD ID.

     2. WPJ Key present, JamfAAD PLIST missing

This signifies that the user has a WPJ certificate in their keychain, but JamfAAD has never run. This may indicate that the user was manually registered via Company Portal without jamfAAD calling the registration.

Machines in this state should run the registration policy in Self Service.

     3. WPJ Key present, AAD ID not acquired

This signifies that the user has a WPJ certificate in their keychain, but JamfAAD has not successfully obtained the Azure AD ID of the user. JamfAAD may try again to grab the AAD ID of the user within the next two hours.

This scenario may also be remediated by running /usr/local/jamf/bin/jamfaad gatherAADInfo on that machine as the logged in user.

Note: If this command is run as root, it will do more harm than good. If running from Jamf Pro, make sure to run it as the logged in user!

     4. Not Registered

This indicates that no WPJ certificate is present in the user’s login keychain. This indicates that either the machine has never been registered via Company Portal, or something has happened to the user’s login keychain. If the machine was previously registered, this may indicate a password reset was performed (password resets will most often result in the loss the existing login keychain).

Machines in this state should run the registration policy from Self Service.

ben_whitis_5-1663170319638.png

 

This was originally posted to my personal GitHub, available here.

 

3 Comments
About the Author
Started working at Jamf in 2018. Focus on Conditional Access, Jamf Connect, and Jamf Protect.