Configure Platform Single Sign-On for Okta Identity Engine with Jamf Pro

[rabbitt]

Updated 9 OCT 2024:

NOTE: Okta Verify appears to have rolled back to 9.23.0 as the official release which is working in macOS 18.1 beta 6.  iOS SSOe support appears to be working in 9.24.1 with iOS 18.1 beta 6.

Limitations and Requirements

Apple has made two revisions to the PSSOe framework.  V1 allowed for Password authentication and can be used with macOS Ventura and greater.  V2 added functionality for authentication with PSSOe to include SmartCard and Secure Enclave credentials.

At this time, Okta supports the V1 framework with limited support for V2 with Shared Device Keys.  The “Password”authentication method is available with Okta.  PSSOe support is limited to local account password sync only.  The PSSOe credentials are not used for authentication to Okta gated resources. 

To complete the setup for the full expected behavior of PSSOe, an administrator must set up both the Extensible Single Sign-On extension (SSOe) configuration and the PSSOe configuration on the same device.  Okta uses a hybrid of the Credential sign-on type for accessing Okta gated resources and a Redirect sign-on type for local macOS UNIX user account password sync.

Administrators are advised that two separate configuration profiles are required in organizations with mixed fleets with macOS Ventura and macOS Sonoma and greater.  “Shared Device Key” is only available in Sonoma and greater.  Deploying unsupported keys to macOS Ventura may reveal unexpected results.

Passwordless accounts are NOT SUPPORTED

PSSOe does NOT support “passwordless” users in Okta.  PSSOe compares the password of the local macOS user account with the password stored in Okta.  PSSOe is not a passwordless solution for macOS.

Non-Production Test Device Recommended

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.

Okta Tenant Requirements

PSSOe support with Okta is in general release.  The Okta product name is “Desktop Password Sync for macOS”. Contact your Okta account representative for pricing and access to this feature.

SSOe support with Okta requires activation of the passwordless feature called “Okta FastPass.”  Contact your Okta account representative for pricing and access to this feature.

Okta tenants must be of the Okta Identity Engine type.  Okta Classic tenants must be upgraded to work with SSOe or PSSOe.

Okta Verify must be the non-App Store version deployed via a .pkg installer.  As of the writing of this article (17 JUL 2024), the latest version of Okta Verify is 9.19.2 and should be considered the minimum version required for PSSOe deployment.

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 Okta Desktop Password Sync for MacOS, Okta Verify, or any security settings and authentication policies, contact Okta Support (https://support.okta.com)
• For questions about deploying a configuration profile using a Jamf MDM product, contact Jamf Support(https://www.jamf.com/support/)

Okta Tenant Configuration and Deployment

The following instructions assume the organization has deployed macOS Sonoma or greater.  Notes will be shown for changes to configuration profiles that are intended for macOS Ventura.  Deploying unsupported keys to an OS may result in them being ignored or unexpected behavior.  Buy the ticket, take the ride.

-----

Expand

Instructions between this spoiler tag and the next spoiler tag are all you need to deploy Single Sign-On aka Okta Fast Pass.  If you just stop at the next tag, you've got the SSOe instructions too.

Enable Okta FastPass

Reference: https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/fp/fp-main.htm

Okta FastPass is the branded name for Extensible Single Sign-On extension (SSOe) support for macOS and the various mobile Apple operating systems.  Instructions on how to enable Okta FastPass are extensive and will not be covered here.  Instructions to enable SSOe for macOS are included below.  Refer to the following links.

• Create a Global Session Policy for Okta FastPass - https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/fp/fp-osop.htm
• Enable Okta FastPass - https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/fp/fp-enable.htm
• Create an authentication policy for Okta FastPass - https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/fp/fp-asop.htm

Create a SCEP certificate for managed device attestion

Configure Okta as a Dynamic SCEP provider

Open the Okta administrative portal for your tenant.

Navigate to Security, Device Integrations.

Select the “Endpoint Mangement” tab at the top of the window.

Select “Add Platform”.

In the new configuration, select Platform of “Desktop (Windows and macOS only)”.  Select Next.

Select the options for “Use Okta as certificate authority”, “Dynamic SCEP URL”, and “Generic.”  Select “Generate” to create a new configuration.

Save the following for future use:

• SCEP URL
• Challenge URL
• Username
• Password (this will be the only time you can copy this value)

Select the “Save” button to continue.

Create a configuration profile in Jamf Pro for SCEP certificate deployment

Open the Jamf Pro admin console.

Navigate to Computers, Configuration Profiles.  Select the “+ New” button to create a new configuration profile.

In General settings, name and optionally select a category for your configuration profile.  Your name should reflect that this certificate is used for Okta Device Management Attestation to differentiate it from another SCEP certificate to be made later in these instructions.  Set the “Level” to Computer Level.”

Select the SCEP payload from the left hand navigation bar.  Select “Configure”.

Configure the following:

• URL - Use the SCEP URL from Okta
• Name - Create a name for this certificate.  This may be shown to end users in Keychain or looking at deployed profiles in System Settings.
• Redistribute Profile - Select any value other than “Never.”  Recommended value is 5 days.
• Subject - Enter the value CN=$COMPUTERNAME managementAttestation $UDID
• Challenge Type: “Dynamic-MicrosoftCA”
• URL To SCEP Admin - Use the Challenge URL from Okta
• Username - Use the Username provided by Okta
• Password - Enter the password provided by Okta 
• Verify Password - Enter the password provided by Okta
• Retries - Recommended value is 5
• Retry Delay - Recommended value is 300
• Certificate Expiration Notification Threshold - Recommended value is 14
• Key Size - Select “2048”
• Select the option for “Use as digital signature”
• Deselect the option for “Allow export from keychain”
• Select the option for “Allow all apps access”

Use the Scope tab to select a group of computers to receive the configuration profile.

Deploy Okta Verify to macOS devices

Reference: https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/ov-install-options-macos.htm

NOTE: PSSOe does not support the Apple App Store deployed version of Okta Verify.  Installing a new version of Okta Verify via policy or Mac Apps will overwrite the App Store version of Okta Verify.  Okta Verify secrets are stored in the user’s Keychain and will not be overwritten.

Deploy via Policy

Download the latest version of Okta Verify.  Open the Okta administrative portal for your Okta tenant.  Navigate to Settings, Downloads.  Locate Okta Verify and select Download Latest.

Open the Jamf Pro admin console.

Navigate to Settings, Computer Management, Packages.

Upload the Okta Verify package to your fileshare distribution point.

Navigate to Computers, Policies.

Create a policy to install the Okta Verify package.  Add a Maintenance payload to Update inventory.   Under General settings, select a trigger as desired (enrollment complete and recurring check-in recommended) with Execution Frequency of Once per computer.  Alternatively, allow the policy to be run via Self Service for manual installation by a user.

Deploy via Jamf App Catalog

Open the Jamf Pro admin console.

Navigate to Computers, Mac Apps.

Select the “+ New” button to create a new Mac App for deployment.

Select Jamf App Catalog as the App Source.

Search for “Okta Verify”.  Use the “Add” button to add the title.

Set Initial distribution method to either Install automatically or Make available in Self Service as desired.

Set Update method to Automatic.

Set a Target Group as a group of computers who will be used for PSSOe.

Create a configuration profile in Jamf Pro to enable Extensible Single Sign-On (SSOe)

Open the Jamf Pro admin console.

Navigate to Computers, Configuration Profiles.  Select “+ New” to create a new configuration profile.

In General settings, name and optionally select a category for your configuration profile.

Select the Single Sign-On Extensions payload from the left navigation bar.  Select “+ Add” to create a configuration.

Add the following settings:

• Payload Type: SSO
• Extension Identifier: com.okta.mobile.auth-service-extension
• Team Identifier: B7F62B65BN
• Sign-on Type: Credential
• Realm: Okta Device (note: case must match exactly)
• Hosts: Enter your Okta domain in the format of example.okta.com.  If you have a custom domain, use the “+ Add” button below the hosts to add an additional host name with the custom domain.  Example format would be id.example.com.  Do not use any URI notation like “https://” in your host name.

Use the Scope tab to select a group of computers to receive the configuration profile.

Expand

HERE is where you stop if you just want SSOe aka Okta Fast Pass.

-----

Create Desktop Password Sync application in Okta

Reference: https://help.okta.com/oie/en-us/content/topics/oda/macos-pw-sync/configure-macos-password-sync.htm

Open the Okta administrative portal for your tenant.

Navigate to Applications, Applications.  (This is not a typo.)

Select “Browse App Catalog”.

Search for “Desktop Password Sync” and select the application.

Select “Add integration.”  If you receive an error message saying “This feature isn’t enabled, contact your account representative”, your tenant is not configured for this feature.  Contact your Okta sales representative for more information.

Open the Desktop Password Sync application from the applications list to configure the app.

Select the “Sign on” tab.  Copy the “Client ID” value for use later in configuration.

Select the “Assignments” tab.  Assign individual or groups of users to the application.

Create a configuration profile for Okta Verify

Reference: https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/managed-app-configs-macos.htm

Follow the instructions in the linked article above to create a .plist file with the settings your organization wishes to deploy.  A sample configuration profile follows:

<plist version="1.0">

<dict>

<key>OktaVerify.OrgUrl</key>

<string>https://replace-with-your-org-URL</string>

<key>OktaVerify.UserPrincipalName</key>

<string>$USERNAME</string>

<key>OktaVerify.PasswordSyncClientID</key>

<string>replace-with-your-client-ID-from-Desktop-Password-Sync</string>

<key>PlatformSSO.ProtocolVersion</key>

<string>2.0</string>

</dict>

</plist>

Note: PlatformSSO.ProtocolVersion is intended for use on macOS Sonoma or greater.  If using macOS Ventura, administrators must create a separate configuration profile scoped specifically to those machines that set the PlatformSSO.ProtocolVersion to 1.0.

Note: OktaVerify.OrgURL should be the organization’s tenant name in the format of https://example.okta.com or if using a custom domain, something similar to https://exampleoktatenant.example.com.

Open the Jamf Pro admin console.

Navigate to Computers, Configuration Profiles.  Select the “+ New” button to create a new configuration profile.

In General settings, name and optionally select a category for your configuration profile.

Select the “Applications & Custom Settings” payload type from the left navigation bar.  Select the “Upload” sub-option.  Select the “+ Add” button to add a new domain.  (You will do this twice.)

In the Preference Domain section, enter com.okta.mobile

In the Property List, either cut and paste your .plist file created with your settings or use the “Upload” button to upload your .plist file.

Select the “+ Add” button at the top of the page to add a second domain.

In the Preference Domain section, enter com.okta.mobile.auth-service-extension

In the Property List, either cut and paste your .plist file created with your settings or use the “Upload” button to upload your .plist file.

Use the Scope tab to select a group of computers to receive the configuration profile.

Create Device Access SCEP certificates in Okta

Configure Okta as a Dynamic SCEP provider

Open the Okta administrative portal for your tenant.

Navigate to Security, Device Integrations.

Select the “Device Access” tab at the top of the window.

Select the “Add SCEP Configuration” option.

In the new configuration, select “Dynamic SCEP URL” and “Generic”.  Select the “Generate” option.

Save the following for future use:

• SCEP URL
• Challenge URL
• Username
• Password (this will be the only time you can copy this value)

Select the “Save” button to continue.

Create a configuration profile in Jamf Pro for SCEP certificate deployment

Open the Jamf Pro admin console.

Navigate to Computers, Configuration Profiles.  Select the “+ New” button to create a new configuration profile.

In General settings, name and optionally select a category for your configuration profile.  Your name should denote that this certificate is used for Okta Device Access and is different from the previously created SCEP payload.  Set the “Level”to Computer Level.”

Select the SCEP payload from the left hand navigation bar.  Select “Configure”.

Configure the following:

• URL - Use the SCEP URL from Okta
• Name - Create a name for this certificate.  This may be shown to end users in Keychain or looking at deployed profiles in System Settings.
• Redistribute Profile - Select any value other than “Never.”  Recommended value is 5 days.
• Subject - Enter the value CN=$COMPUTERNAME managementDeviceAccess $UDID
• Challenge Type: “Dynamic-MicrosoftCA”
• URL To SCEP Admin - Use the Challenge URL from Okta
• Username - Use the Username provided by Okta
• Password - Enter the password provided by Okta 
• Verify Password - Enter the password provided by Okta
• Retries - Recommended value is 5
• Retry Delay - Recommended value is 300
• Certificate Expiration Notification Threshold - Recommended value is 14
• Key Size - Select “2048”
• Select the option for “Use as digital signature”
• Deselect the option for “Allow export from keychain”
• Select the option for “Allow all apps access”

Use the Scope tab to select a group of computers to receive the configuration profile.

Note: SCEP certificate is required only on macOS Sonoma and greater that can use the Platform SSO 2.0 specification.  Certificate will be ignored on devices running macOS Ventura.

Create a configuration profile in Jamf Pro to enable PSSOe

Open the Jamf Pro admin console.

Navigate to Computers, Configuration Profiles.  Select “+ New” to create a new configuration profile.

In General settings, name and optionally select a category for your configuration profile.

Select the Associated Domains payload from the left navigation bar.  Select “Configure”.

Select “+ Add”.  Enter the following values:

• App identifier: B7F62B65BN.com.okta.mobile.auth-service-extension
• Associated Domain: Your Okta domain with the preface of the characters “authsrv:”  Example: authsrv:example.okta.com

Select the Single Sign-On Extensions payload from the left navigation bar.  Select “+ Add” to create a configuration.

Add the following settings:

• Payload Type: SSO
• Extension Identifier: com.okta.mobile.auth-service-extension
• Team Identifier: B7F62B65BN
• Sign-on Type: Redirect
• URLs: Add your Okta org URL with the path /device-access/api/v1/nonce and /oauth2/v1/token. Contact Okta support if you have a custom domain.  Example: 
• https://example.okta.com/device-access/api/v1/nonce
• https://customer.okta.com/oauth2/v1/token
• Use Platform SSO: Enable
• Authentication Method: Password
• Use Shared Device Keys: Enable
• If the organization has devices running macOS Ventura, create a separate configuration profile where the“Use Shared Device Keys” payload is not included.
• Create New User at Login: Optional.  If you wish any user of your Okta tenant to make user accounts on deployed Macs, enable this feature.  It is not possible to limit new account creation when this feature is enabled.
• Identity Provider Authorization: Optional.  Allows users to enter their Okta credentials for authorization requests when administrator credentials are required.
• Account Display Name: Shown to users while enrolling a device in PSSOe.  Use a descriptive message that explains to users they are using their Okta credentials from your tenant.  Example: AnyCo Okta tenant
• Account Authorization Type: Optional.  Determines if a user is considered a standard or an administrative user when performing authorization events like installing software, unlocking settings in System Settings, or sudo events.  Group membership is not available at this time.
• New User Account Type: Optional.  Determines if users created with Okta credentials at the macOS login window will become standard or administrator users.  Group membership is not available at this time.
• Authentication when screen is locked: Do not handle

Use the Scope tab to select a group of computers to receive the configuration profile.

[daniel_behan]

This is great Sean.  The only thing I'd like to add is that if you already have a valid PKI, you can integrate it with Okta instead of have Okta manage a SCEP.  See the section stating Use your own Certificate Authority for Device Access at  https://help.okta.com/oie/en-us/content/topics/oda/oda-as-scep.htm#byo-DA-CA

[ganidran]

@rabbitt would it be advised against placing all these into one config profile (having 2 SSO extension entries), etc.?

[rabbitt]

Should be no issues putting multiple SSO configs in one payload. Just remember that if you make changes to an existing installed profile, users may be required to re-register the device and user account with PSSO.