Configure Platform Single Sign-On (PSSOe) for Microsoft Entra ID with Jamf Pro

[rabbitt]

Edited 4SEPT2024: Updated information with the release of Jamf Pro 11.9 for PSSO and Device Compliance.  Also added link to Jamf Pro documentation.

Jamf Learning Hub Instructions:

https://learn.jamf.com/en-US/bundle/technical-articles/page/Platform_SSO_for_Microsoft_Entra_ID.html

Current Public Preview Limitations

What is Public Preview

As of 15 JUL 2024, Microsoft Entra ID support for Platform Single Sign-On extension (PSSOe) is currently in Public Preview. As such, supported features and deployment information is subject to change without notice.  For more information, visit https://learn.microsoft.com/en-us/entra/fundamentals/licensing-preview-info. 

Jamf Pro and Microsoft Entra Conditional Access

Jamf Pro 11.9 and greater now includes logic to detects changes to PSSO registration.  When a new device ID is created in Entra ID as part of the registration, the gatherAADInfo command will report device compliance state to the new object.

For versions prior to Jamf Pro 11.9, visit the Troubleshooting Steps for commands to restore device compliance data being sent to the new device ID created in Entra ID manually.

Administrators are recommended to:

1. Configure Jamf Pro for Device Compliance - https://learn.jamf.com/en-US/bundle/technical-paper-microsoft-intune-current/page/Device_Compliance_...
2. Configure Jamf Pro to deploy a Platform Single Sign-On configuration profile

With this method, when a user registers a device with the Platform Single Sign-On flow, the device compliance will automatically be sent to Entra.

In the event that an organization deploys PSSO first and then later configures and deploys Device Compliance, the user must run the "Register Device with Microsoft" policy from Jamf Self Service or the administrator must deploy a policy to run the gatherAADInfo command at least once before device compliance will be reported.

Prepare a non-production test machine

Any experimentation with the login window has the potential to lock a user out of their machine.  Therefore, use only non-production test equipment when testing and evaluating PSSOe.

Support

PSSOe is a framework built into macOS and the core functionality is designed by Apple.  It is supported by a companion application built by an identity provider.  It is enabled by deploying a configuration profile via an MDM.

• For questions and feedback about the core functionality of PSSOe or any feature using available betas of upcoming versions of macOS, contact AppleCare (https://www.apple.com/support/products/), file an AppleCare Enterprisesupport case, or file a feedback via https://feedbackassistant.apple.com
• For questions about the Microsoft Intune Company Portal application, contact Microsoft Support, subject to the limitations in the link above about preview features.
• For questions about deploying a configuration profile using a Jamf MDM product, contact Jamf Support(https://www.jamf.com/support/)

Deployment

Determine authentication method

Reference: https://learn.microsoft.com/en-us/mem/intune/configuration/platform-sso-macos#step-1---decide-the-au...

Microsoft Entra ID supports three methods of authentication with PSSOe:

1. Secure Enclave (Recommended) - This method creates hardware bound cryptographic keys entangled with the Secure Enclave (link:https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/protectin...) of the Mac hardware.  Keys are not directly accessible by the user, do not store keys in the user’s Keychain, and are non-exportable.  This method is recommended as it is treated by Microsoft Entra ID as a non-phishable authentication method, the strongest authentication factor type for accessing resources.  The local UNIX user name and password are unchanged with this method.
2. Password - This method will synchronize the local macOS UNIX user account password with the Microsoft Entra ID password.  The user FileVault decryption password and Keychain password are updated to match the local UNIX account password.
1. This is not considered a phishing resistant authentication factor.  Setup does not require the use of a strong authentication method like multifactor authentication, and the method does not allow for use of the device as a Passkey for WebAuthN authentication.  
2. Administrators are strongly recommended to check all password complexity requirements in Microsoft Entra ID and password complexity configuration profile payloads passed via MDM.  Conflicting complexity requirements or policies like preventing the use of previously used passwords will result in user lockout of the device.  
3. Legacy per-user multifactor authentication is not supported with this method and will result in the user being unable to register their account for use with PSSOe.  Refer to https://learn.microsoft.com/en-us/entra/identity/authentication/how-to-authentication-methods-manage for deprecation dates and how to migrate to Microsoft Entra Conditional Access policies for MFA enforcement.
3. SmartCard - Associates a user’s SmartCard (also known as PIV or CAC card) and PIN with Microsoft Entra ID authentication methods.  The local UNIX user name and password are unchanged with this method.  Because this method requires additional hardware for both the credential storage and readers for the credentials, administrators are not advised to use this method unless SmartCards are already in use at the organization.

Install the Company Portal app

PSSOe requires the installation of Microsoft Intune Company Portal app (https://go.microsoft.com/fwlink/?linkid=853070) version 5.2404.0 or greater.

Install Company Portal via Policy

Open the Jamf Pro administrator portal.

Navigate to Settings, Computer Management, Packages.

Upload the latest version of Microsoft Intune Company Portal installer package file to your fileshare distribution point.

Navigate to Computers, Policies.

Create a new policy with an Execution Frequency set to Once Per Computer, a Packages payload to install the Microsoft Intune Company Portal package, and a Maintenance payload to Update Inventory.  Execution trigger can be set to Recurring Check-In or installed via Self Service by the user on the device.

Install Company Portal via Jamf App Catalog

Open the Jamf Pro administrator portal.

Navigate to Computers, Mac Apps.

Select the “+ New” option to create a new app installer.

Select App Source as the Jamf App Catalog.

Search for “Microsoft Intune Company Portal” and select the Add button to add the title.

Select a Target Group to deploy the application.

In the Configuration Settings option, select either to install automatically or via Self Service.  Select the Update method to Automatic if you wish to keep the Company Portal app up to date with the latest version automatically.

Once the installation method is configured, install the Company Portal application on your non-production test device.

Create a configuration profile

Open the Jamf Pro administrator portal.

Navigate to Computers, Configuration Profiles.

Select the “+ New” option to create a new Configuration Profile.

Select the payload for “Single Sign-On Extensions” and select the “+ New” option to add payload contents.

• Payload Type: SSO
• Extension Identifier: com.microsoft.CompanyPortalMac.ssoextension
• Team Identifier: UBF8T346G9
• Sign-on Type: Redirect
• URLs:  URLs will be redirected to authenticate with the associated application (Intune Company Portal app).  For a full list of URLs, refer to https://learn.microsoft.com/en-us/entra/identity-platform/apple-sso-plugin and are subject to change.  At time of writing the minimum required URLs were:
  • https://login.partner.microsoftonline.cn
  • https://login.chinacloudapi.cn
  • https://login.microsoftonline.us
  • https://login-us.microsoftonline.com
• https://login.microsoftonline.com
• https://login.microsoft.com
• https://sts.windows.net
• Additional URLs for sovereign cloud domains are optional
• Enable the option for “Use Platform SSO”
• Select the Authentication Method your organization has selected
• Use Shared Device Keys: Enable
• (OPTIONAL) Create New User at Login
• Selecting Enable will allow any user with valid credentials on your Entra ID domain to create a new user account on the Mac.  A local macOS UNIX user account will be created with the user’s Entra ID password.  Users with “passwordless” only authentication in Entra ID cannot use this method.
• (OPTIONAL) Identity Provider Authorization
• Selecting Enable will allow the use of Entra ID credentials for events that require authorization prompts like use of the sudo command, unlocking certain preferences in System Settings, and installation of software.  The user must have administrator rights in addition to complete authorization.
• Display Account Name: Enter a value that will be clear to your end users what user name and password is required upon registration of the device with PSSOe.  These dialog boxes are displayed by macOS to prompt the user as part of the registration process.
• User Mapping - name from the identity provider ID token claim that contains the information to create the user account
• Full name: name 
• Account user name: preferred_username
• A list of all additional claims is available at https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#payload-claims
• Account authorization type: Determines if entry of identity provider credentials during an authorization event will show the user is a member of the Admin or Standard users group.  Select either Standard or Admin.  (Groups is not supported by Microsoft Entra ID at this time).
• New user account type: Determines if a user created at the macOS login window with identity provider credentials will be a local Admin or Standard account.  Select either Standard or Admin.  (Groups is not supported by Microsoft Entra ID at this time).
• Authentication when screen is locked: Set to Do not handle
• (OPTIONAL) Custom Configuration: Microsoft Entra ID supports several additional configuration settings.  Refer to https://learn.microsoft.com/en-us/entra/identity-platform/apple-sso-plugin#manual-configuration-for-... for a full list of settings.  

A standard Custom Configuration payload may look like the following:

<?xml version="1.0" encoding="UTF-8"?>

<plist version="1.0">

<dict>

    <key>AppPrefixAllowList</key>

    <string>com.microsoft.,com.apple.,com.jamf.trust,com.jamf.management.,com.jamf.protect,com.jamfsoftware.</string>

    <key>browser_sso_interaction_enabled</key>

    <integer>1</integer>

    <key>disable_explicit_app_prompt</key>

    <integer>1</integer>

</dict>

</plist>

Scope the Configuration Profile to your non-production test devices.

[Cayde-6]

What do you set for the Registration Token field?

[rabbitt]

You do not.

[nessts]

so if 11.7 is not going to work with PSSO, what version will?

[rabbitt]

Jamf Pro will work with device registration, but you must manually run the gatherAADInfo command.  You also need to make sure a specific order of operations occurs:

A) Device Registration is configured in Jamf Pro.  The computer can be in a registered or unregistered state.
B) Push the PSSOe configuration profile to the device
C) Follow the user enrollment steps to activate PSSOe
D) Manually run either through policy or on the device in terminal the following command:

/Library/Application\ Support/JAMF/Jamf.app/Contents/MacOS/Jamf\ Conditional\ Access.app/Contents/MacOS/Jamf\ Conditional\ Access gatherAADInfo

A future version of Jamf Pro will automatically run this command with a LaunchDaemon after the device and user has registered PSSOe.  I recommend joining the Jamf Pro beta to learn more.

[dthreewitt]

Do you mean you have to go through the Jamf/Intune integration and set up that Device Registration before attempting to set up PlatformSSO?

---

@rabbitt wrote:

Jamf Pro will work with device registration, but you must manually run the gatherAADInfo command.  You also need to make sure a specific order of operations occurs:

A) Device Registration is configured in Jamf Pro.  The computer can be in a registered or unregistered state.

[nessts]

Not sure if I totally understand your question. When you deploy the configurations to a device for PSSOe you have to manually run the alternative jamfAAD command listed above on that computer to get it registered with Entra for the device compliance to start working. Hope that helps. 

[rabbitt]

If you were to deploy PSSO first THEN deploy the device registration settings to machines via Jamf Pro (aka enable it in the Jamf Pro Settings -> Global -> Device Compliance), then the expected behavior would still be that you need to open Self Service and select the "Register device with Microsoft" policy.

When you do that, the device has a registration in Entra ID's directory already, so most of the "hard work" is done.  But that policy will then run the gatherAADInfo command and link the newly deployed compliance policy with the existing Entra ID UUID for the computer.

When Jamf Pro 11.9 drops, there will be a launchdaemon loaded onto the computer when you enable Device Compliance.  The daemon watches for the status of PSSO registration.

But, if you enroll the device in PSSO and THEN deploy Device Compliance, the state of the PSSO registration never changes - it was already registered.  So when deploying Device Compliance starts up that launchdaemon, it never sees a change to PSSO status.  So therefore you need to run the Register policy again to "force" it to register.

[nessts]

doh, its not jamfAAD gatherAADInfo, thanks I did not look closely enough

[nessts]

@rabbitt I thought I sent a question earlier but don't see it here. Do you know if we just need to add all the kerberos keys to the existing custom plist that we add to the PSSOe profile? If we do that will it cause re-registration of all devices that have the profile? https://learn.microsoft.com/en-us/entra/identity/devices/device-join-macos-platform-single-sign-on-k... 

[rabbitt]

The answer is "It depends."  Unfortunately I've seen two different behaviors when a PSSO profile is updated (which really is two separate commands - remove profile, add a new profile with a new identifier).

Authentication type set to "Password" - usually prompts user to re-register
Authentication type set to "Secure Enclave key" - Usually keeps the device registered when profile is removed until reboot.

So if you make any changes to the existing PSSO config profile in any way, it will probably require the user to re-register.

[wlumley]

Has anyone ran into an issue with Microsoft apps constantly asking to be logged into again? It seems like everything is talking correctly, as logging into the Mac uses the Entra ID password credentials, but all the Microsoft applications (Teams, Edge, OneDrive, etc.) keep logging out and ask to be logged into again frequently throughout the day. I feel like I'm missing something, but can't figure it out.

[rabbitt]

Check your Entra Conditional Access policies around session duration.  Also this is one where getting MS support in is 1000% the right answer.  You're paying them for the service, so... :) 

[user-zwVXoRajVX]

We have setup for PSSOe Jamf+MS Entra and running jamf pro 11.9.1 server, After PSSOe enabled in mac, under keychain - login - MS Organization access certificate in removed. After this Specific certificate removed, we cannot able to open any organization sites. Can idea?   

[rabbitt]

It sounds like you may need to reregister the computer. Are you using Jamf Pro 11.9 or greater? As described in https://community.jamf.com/t5/jamf-pro/troubleshooting-platform-single-sign-on-with-microsoft-entra-..., you can either run the command:

/Library/Application\ Support/JAMF/Jamf.app/Contents/MacOS/Jamf\ Conditional\ Access.app/Contents/MacOS/Jamf\ Conditional\ Access gatherAADInfo

Or you can instruct a user to use the “Register with Microsoft” option in Self Service to re-register the device for Microsoft Entra Device Compliance reporting.

[user-zwVXoRajVX]

we are running jamf pro 11.9.1 and we are not facing non compliance issue. yes we know , above command will help to make mac compliance. 

[user-zwVXoRajVX]

only Question, once enabled PSSOe, why certificate removes from keychain, we know this specific certificate will help to access intranet site. we have compared 2 macs, one with PSSOe and another without PSSOe enabled. Once PSSOe registration completed, MS workplace join key (Private key) removes and not blocks the intranet access. 

[rabbitt]

With PSSO in Secure Enclave key authentication mode, the workspace join certificates are removed from the user's keychain and stored instead in the Secure Enclave of the device.  This effectively makes the key non-exportable and hardware bound.  The workspace join key should not be relied on for things like network access.

[user-zwVXoRajVX]

Once PSSOe registration completed, MS workplace join key (Private key) removes and it blocks the intranet access. 

[nessts]

because it moves from keychain to the secure enclave, find a different cert to use. My guess would be to deploy a pkcs device/user cert from your CA would probably be the better thing to do. Or change your intranet policy to ask the device if it is compliant and use MSAL auth stuff.

[andyinindy]

Thanks for this @rabbitt!

Question: with the WPJ cert/key removed, what marker or identifier can we look for on the endpoint to verify a healthy and successful registration? When moving to PSSOe, we see the device record flip from "Microsoft Entra registered" to "Microsoft Entra joined" in Entra, with a new Device ID to boot. However, there is no cert in the keychain that matches the new Device ID (since it's presumably stored in the Secure Enclave). How can we check for this cert/registration on the endpoint?

[user-zwVXoRajVX]

Thanks, I have same question. @rabbitt Can you ?

[rabbitt]

The `/usr/bin/app-sso profile -s` command should give some details on the state of device registration and user registration on the device.  Be forewarned that it produces a LOT of information so you'll need to dig through and pull the information relative to your needs.

You will not be able to directly search for the cert, as you said, as it will be in the Secure Element rather than accessible via the Keychain.

[andyinindy]

I think you meant "/usr/bin/app-sso platform -s". However, the output of this command does not include any data that correlates with the device registration in Entra. The only unique identifiers that we have in Entra are "Device ID" and "Object ID", and neither of these show up when running that command. Perhaps there is a different way to correlate a PSSO Joined Mac with Entra that I am overlooking?  

[rabbitt]

Correct, I typed "profile" but meant "platform".  Don't answer questions without enough coffee in your system.  

I've asked around, and it appears that there is no identifier on device that would correlate the UUID in Entra.  I've been told that Jamf Pro does contain the information, but it's accessible only via the API and with the "conditional-access" endpoint.  The app-sso platform -s simply tells you the device IS registered, but only Jamf Pro knows the device identifier.

That being said, what is the functionality you're trying to get on the client device itself that would need that UUID?

[andyinindy]

This works! Thanks for pointing it out. I will edit my EA to use the API if the device has our SSO profile. Cheers!

[obi-k]

@rabbitt 

Thanks so much for all this. We are testing Microsoft Platform SSO with Entra successfully. In a passwordless environment, we can see some huge benefits and a better overall Mac experience with Smart Cards.

Thanks again for all your help at JNUC with the braindate meet! Your presentation was awesome as well. Appreciate the tips and cheat codes.

[mani2care]

I have an issue where, after authenticating with the company portal, I see the "MS-Organization-Access" certificate in the user's keychain, but it is not trusted. Is it necessary to trust this certificate, and will it cause any issues if it remains untrusted? How can I trust that certificate, and is there a root CA required for it to be trusted?

[rabbitt]

If you're using PSSO with Microsoft in Secure Enclave key authentication mode, there should be no MS-Organization-Access certificate in the user keychain at all, so I'm confused by the question.

[jrippy]

@rabbitt - I'm going to go ahead and get this out of the way - We still AD Bind.   (hangs head in shame).

But, I've been looking to convince management to get away from this for a while.  After JNUC and hearing your session (awesome session BTW), management decided to get some Jamf Connect licenses and start looking at PSSOe.  The problem I'm running into is that we seem dead set on not allowing just anyone the capability to register in Entra.  We have it restricted to a small group of employees.  That means I'll have to touch every single machine.
Do you have any advice on how I can accomplish this easily or how to convince management to open it up?  Their concern is that we've had a bunch of personal devices register in our tenant and this was presented as the way to stop that.

Thanks!

[rabbitt]

I think you less have an issue with registering devices in Entra as much as registering personal devices into Jamf Pro.  The PSSO payload needs to come down from an MDM here to work, so we know the device would be enrolled in Pro.  Perhaps limit registration of devices to only those coming through Apple Business Manager?  Perhaps add in the (in private beta preview, so talk to your Jamf AE) Network Relay with an ACME certificate new to Jamf Connect ZTNA.  That would give you a machine authenticity attestation from Apple with the ACME cert to prevent serial number spoofing.

[jrippy]

I'm not sure I exactly follow.  We have zero Jamf Cloud BYOD, so that's not an issue.  Everything is ASM and PreStage.  However, we have so many personal devices showing up in Entra that management is pulling everything back to try to stop devices from registering with our tenant.

[QS_Logan]

Running into the same limitation as you-- there doesn't seem to be a way to automate registering these devices using Jamf, so to register them, the user has to have permission to join devices to Entra-- which includes personal windows devices, which don't need anything pushed from an MDM to join. If you find a solution to this I'll be curious to know as our org is in the same boat right now. 

[Ehouston3]

@rabbitt , thanks for posting this very helpful information.
We are facing some similar inconsistencies with our test deployment of PSSOe with password sync on Jamf Pro Cloud Version11.10.1-t1728656858, using Company Portal Version: 5.2409.1 (53.2409926.002) and a signed config profile created in iMazing. We were experiencing some issues with the profile created in the Jamf UI, the session duration key value was being manipulated so, we went to a signed profile and didn't set that value, taking the default. We've still been experiencing what I would call a "drift" where, initially, things seem to work fine. After logging in, SSO works and the tokens are read, website and apps seamlessly connect as expected. Then after a few days or so, it may start with Teams displaying a banner that you need to sign in. Other sites that were previously, silently passing the SSO token, were prompting for login credentials and MFA. Our testing with SecureEnclave was must smoother but, due to our environment and culture at the time we have to start with password sync. I've tried to capture some logs using unified logging and some predicates but, I'm not sure what's "normal noise" or what's actually an error. Additionally, a line in the output of the app-sso platform -s command has been getting my attention but, I'm not sure if it's actually an error or if it's just describing what would be output in the event of that type of error. Under the "Login Configuration" section there is a key-value pair with the following:

"invalidCredentialPredicate" : "error = 'invalid_grant' AND suberror != 'device_authentication_failed'",

1. Any thoughts on the "drift" for Microsoft applications and sites that were previously taking SSO tokens prompting for credentials? (I saw your response to "wlumley" and we'll be checking with our Identity & Access folks regarding a conditional access policy if it exists or not.

2. Do you know of any good log predicates that may be of value to stream or look up when troubleshooting PSSOe w/ password sync?

3. Have you heard of or had any experiences with the Jamf UI when creating config profiles changing some values of the keys?

I think this particular one should have the wording changed and that might fix the issue since the key takes seconds but, the interface uses

resulted in:

So, the value entered in the UI was multiplied by 3600. The UI should say to enter the number of hours but, we got an error when entering "1". After this we didn't populate that key but, it still did not affect the issues we've been experiencing.

[Ehouston3]

Forgot to post:
Here's what our current config looks like on the device:

[obi-k]

Also observed the banner for Teams asking to sign in again. Saw earlier this week, but not today. Maybe an update or something came out for Teams.

[Ehouston3]

¯\_(ツ)_/¯ I had been trying to find a log from Teams that even displayed the banner's text with a timestamp, to attempt to correlate it with some other events but, I was unsuccessful.

[Ehouston3]

Also, replace "session duration key" with "login frequency" woops.

[Ehouston3]

We've decided to switch to SecureEnclave. During my journey down the rabbit hole of Platform SSO logs I came up with a few variations on a predicate that gave some insight into the problem.

Silent token refresh attempt results
log show --style compact --predicate '(subsystem contains [c] "AppSSO Extensi" or subsystem contains [c] "com.microsoft.ssoextension" or subsystem = "com.apple.AppSSO") and (eventMessage contains "_finishAuthorization:withCompletion:" or eventMessage contains "authorization:didCompleteWithError:")' --debug --info

You can play with variations on this predicate to see some interesting things. The subsystems listed were the ones I found mostly related to SSO. I also looked at keychain and device unlock logs with variations on this predicate. I was able to compare my experience on an Intune managed device running password sync vs our Jamf managed devices. The Jamf implementation at this time seems to have some bugs around the silent refresh. Not surprisingly, the Intune implementation for both password sync and SecureEnclave were both smooth.

The above predicate only showed successful results on my Intune managed device.