Help

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

rabbitt
Contributor II
Contributor II

‎07-18-2024 02:03 PM - edited ‎08-01-2024 09:37 AM

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.
 

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

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 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

 
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

 
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
 
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>
<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: 
  • 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.
0 Kudos
2 REPLIES 2

daniel_behan
Contributor III

Posted on ‎07-24-2024 07:14 AM

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

0 Kudos

ganidran
New Contributor III

Friday

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

0 Kudos