Okta Integrations
An important acknowledgement here: there is a new product from VMware, called VMware Identity Services, that can setup SCIM provisioning much faster for a net-new Workspace ONE environment. This method that I am detailing on this page has been around a bit longer than the aforementioned offering. But worth noting that details on this new offering can be found here. Please note the "Key Considerations" and "Unsupported Workspace ONE features" sections on the document, and then follow the "Generic SCIM 2.0 Identity Provider" steps (that have been validated to work for Okta).
Overview
Between Workspace ONE and Okta exists a few integrations. The goal of this document is to go through what each integration does, and the configuration required for each. Below is a basic breakdown of each integration:
SAML for SSO
This refers to the ability to use Okta as an identity provider (IdP) for Workspace ONE. Generally the easiest integration to complete. SSO here sometimes involves JIT provisioning (just-in-time provisioning of users into WS1 from Okta) using select attributes passed as part of the SAML assertion. It's recommended to setup SCIM provisioning if you are looking to leverage SAML SSO, as there are numerous benefits to SCIM provisioning over JIT provisioning.
SCIM Provisioning
This refers to the ability to replicate the directory from Okta (entitled users, that is) to Workspace ONE without using JIT provisioning. This is useful because it will replicate the entire user identity, including group entitlements. If a user has their WS1 entitlement removed from Okta, the user is disabled downstream (WS1 UEM and Access) and any associated devices are wiped... though this functionality can be disabled.
Okta Application Source in Workspace ONE Access
This allows a user's application entitlements to appear in their Workspace ONE Access catalog. Authentication is still handled through Okta, but this will just create links to those apps in Workspace ONE Access. This is useful so that users can open Intelligent Hub on their enrolled devices to have a single place to go for their applications, whether it be okta-based, Horizon virtual apps, or links pushed through Workspace ONE.
Note: this does not actually facilitate any authentication between Workspace ONE and Okta. It merely replicates a user's app entitlements to Workspace ONE Access and the Intelligent Hub.
Desktop SSO
This isn't strictly an "okta" integration as it can be done with any IdP. What this means is that Workspace ONE UEM will issue a user identity certificate to a device, and we can use this for certificate-based authentication in Workspace ONE Access, forgoing a user entering a password. This is much more secure than entering a password. Why this exists on the "Okta Integrations" page of this site is that it can facilitate device factor trust with Okta - checking a device's enrollment and compliance status prior to permitting access to a SaaS application.
Mobile SSO
Similar to the above for desktop, but for mobile. Workspace ONE UEM will push a user identity certificate to a mobile device and we can leverage this for certificate-based authenticataion and device trust with Okta. While conceptually similar, this is implemented differently from the desktop platform (and even differently comparing iOS to Android!). But this will be leveraged for device trust from Okta.
Device Trust / Device Factor Trust
This is a fairly sought after integration between Okta and Workspace ONE. This will check a device for enrollment into Workspace ONE, and for compliance with any policies in UEM, prior to allowing access to a SaaS application through Okta. Device trust is the older implementation, and device factor trust the newer implementation. I'll dive into detail in its section of this document, but just know the two essentially accomplish the same end purpose - just work differently under the hood.
SAML for SSO
As mentioned above, you can setup SSO between Workspace ONE and Okta to leverage JIT provisioning of users. The idea with this is that Workspace ONE does not know about any users in the Okta directory until the user launches the app. Through the SAML assertion, Workspace ONE will, as the name implies, just in time create the user in its own directory with the attributes passed in the SAML assertion. This can work in a pinch, has implications with the downstream directory not always being a complete picture / up to date with what Okta shows.
Because of the above, I recommend doing SCIM provisioning as part of SSO. Because of this, I will cover both setting up the SCIM directory and the SAML SSO metadata exchange in the next section. I just wanted to call out here that SCIM provisioning isn't a requirement, though a strong recommendation, when setting up SAML SSO between Okta and Workspace ONE.
SCIM Provisioning
Create SCIM directory in Workspace ONE Access
Download and install the Postman Application here. We'll need to use Postman to form API calls to create the directory in Workspace ONE Access
Open your Workspace ONE Access console. If you see a blank catalog, click on your user icon in the top right corner and select "Workspace ONE Access Console" to go to the administrative console. Go to Settings - OAuth 2.0 Management. Here we are going to create an API key to authorize Postman to connect to Workspace ONE.
Click "Add Client"
Fill in the form to create the OAuth 2.0 Token
Access Type: Service Client Token
Client ID: OktaSCIM (or something to call the token)
Scope: Admin (check the box)
Access Token TTL: 3 years (set to something longer than default)
Idle Token TTL: 1 year (set to something longer than default)
Click save.On the next screen, notate the Client ID that you created earlier, and the shared secret. If you navigate away from the screen, you will not be able to see the shared secret again.
6. Open Postman. Open a new tab, and set the request type to HTTP POST.
7. For the URL, specify https://tenanturl/SAAS/jersey/manager/api/connectormanagement/directoryconfigs
8. In the authorization tab, select "OAuth 2.0" for authorization type. Scroll down on the inner window, find "configure new token" and specify the following for a new access token in Postman:
Token Name: (what postman will call this access token), ex. Workspace ONE
Grant Type: Client Credentials
Access Token URL: https://tenantURL/SAAS/auth/oauthtoken
Client ID: Generated from Access in a previous step
Client Secret: Generated from Access in a previous step
Scope: admin
Client Authentication: Send as Basic Auth Header
9. Click "Get New Access Token"
10. Copy down the Token Name and the value of the Access Token, we'll need the latter for Okta later on. Then click "Use Token"
11. Go to the Headers Tab in postman. Click the button to expand all hidden headers.
12. Change the header for "Content-Type" (no quotes) to be "application/vnd.vmware.horizon.manager.connector.management.directory.other+json" (no quotes)
13. Click into the Body tab. Select the format to be "raw" and then specify the following as the body of the API call:
{
"type":"OTHER_DIRECTORY",
"domains":["OKTA.COM"],
"name":"Okta Universal Directory"
}
14. If successful, you should see a message like the following, and a new directory in Workspace ONE Access:
Configure the Workspace ONE Application in Okta
Login to your Okta tenant (or Okta dev/preview tenant if this is done as part of a trial/proof of concept)
In the admin console, go to applications - applications - Browse App Catalog
Search for "VMware Workspace ONE" application, and click "Browse App Catalog"
4. Specify a name for the application (default is fine) and the base URL for your Workspace ONE Access tenant
Note: if you put a forward slash at the end of the URL, it will fail validation. The URL without the slash at the very end should work.
5. Within the VMware Workspace ONE application, go to the provisioning tab, and click "configure API integration". Check the box to enable the API integration, enter the bearer token (access token) from postman earlier, and click "Test API credentials". Then click Save.
6. Okta should now direct you to the provisioning tab in the section "to app". Click Edit, and enable provisioning for create, update, and deactivating of users (if desired). Then click save.
7. Next, go to the sign on tab within the application, and a little bit down the page, on the right, find "View SAML Setup Instructions" link. Click this, and it should open in a new tab.
8. In the below screenshot is what Okta will show you when you click "View SAML setup Instructions". On the document, look for a section "SAML Metadata" followed by a bunch of text in a grey box. Copy all of the text in this box.
9. Next, return to Workspace ONE Access. Go to Integrations - Identity Providers. Click Add - SAML IdP.
10. Give the IdP a name, and paste the text into the box for "Identity Provider Metadata". Then click "Process IdP metadata".
11. Scroll down, and do not enable JIT provisioning. Under the "users" section, check the box for the Okta Universal Directory (or what the name of the directory created via postman is).
12. Under the network section, check the box for "all ranges".
13. Under the authentication methods section, provide a name for the Okta authentication method (ex. "Okta Auth"), and then for the SAML context specify urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
14. Scroll back up to the top and click save.
15. Next, still in Workspace ONE Access, go to Resources - Policies - Edit Default Policy
Note: it isn't a best practice in a production environment to edit the default policy, but is okay in a pinch / for trial or POC purposes
16. On the left side, click "configuration" and click "add policy rule". On the window that pops up, for "then the user may authenticate using" select the Okta authentication method you created earlier, and for "If the preceding method fails or is not applicable, then" select "Password (local directory)"
Note: using a "any" method, meaning a policy that applies to any type of device, isn't an ideal security practice for production environments, though can be used in a pinch or as part of a trial/POC.
17. Click save, and drag the policy to the top of the list (policies are executed in order as they appear). Then click next, and save.
18. Back into Okta, we need to assign the Workspace ONE Application to a user or two for testing. In the Workspace ONE application in Okta, under Assignments, click Assign and assign to a person or a testing group.
Note: After they are assigned, you should see them as a user in the accounts tab in Workspace ONE Access, if all is successful thus far.
To further test, login to the okta app catalog as the test user, and verify they can sign into Workspace ONE Access by clicking on the application in their catalog.
AirWatch Provisioning Adapter (VMware Documentation for Reference)
The AirWatch Provisioning Adapter will replicate users into Workspace ONE UEM from Access
In the Workspace ONE Access console, go to Resources - Web Apps - New
In the search field in the window that comes up, search for AirWatch Provisioning.
3. Click next. Continue clicking next, and click save.
4. Once the application appears in the list, check the box next to it and click Edit
5. Under Provisioning, ensure that "Enable Certificate Auth" is selected. Enter the Group ID from your Workspace ONE UEM console, and click Test Connection.
6. Once you see the green message, click next twice, and then "Save and Assign"
7. Assign this application to your users from Okta. Be sure that you have set Deployment Type to be Automatic, and Entitlement Type to be Include. Then click Save.
You may want to create a group for all users in your okta directory. You can do this in Access by going to Accounts - User Groups - Add User Group, and specify criteria for users from the Okta Universal Directory. Then assign the AirWatch Provisioning Application (and all subsequent applications in Access) to that group. Details on this process can be found here in VMware documentation.
8. Next, click on Settings in the Web Apps section, go to SAML Metadata, and Save the IdP metadata (XML) document. We'll need it in a minute.
9. Next, go into your Workspace ONE UEM console. Go to Groups and Settings - All Settings - System - Enterprise Integration - Directory Services. Select "Skip Wizard and Configure Manually"
10. Change directory type to be "none" and change "Use SAML for Authentication" to be enabled. Check the boxes for Enrollment and Self Service Portal. Change "Use New SAML Authentication Endpoint" to be enabled. Upload the downloaded IdP metadata XML document to "Import Identity Provider Settings" section. Then scroll down and click save to import the XML document metadata.
12. For request and response binding type, change both to be set to POST. Scroll down and click Save once again.
13. On the same page, go to the user tab, and expand the advanced section. Notate the user attributes here, particularly username.
14. Lastly, still in the UEM console settings, go to Devices & Users - General - Enrollment. Select the "override" radio button. Check the box for "directory" for the "authentication mode(s)" setting, and select "Workspace ONE Access" for "Source of Authentication for Intelligent Hub". Finally, scroll down and click save.
15. Now back in Workspace ONE Access, go to Resources - Web Apps - New. Search for "AirWatch". Click Next.
16. Scroll down and look for "Application Parameters". For AWServerName, specify your server URL, for ac specify your group ID, and "AirWatch" (without quotes) for the last blank.
For your Server URL, replace "cn" with "ds". So that the server, instead of cn1784.awmdm.com or cn1688.awmdm.com, will be ds1784.awmdm.com and ds1688.awmdm.com, respectively.
If you do not know what your Group ID is, you can locate it in the Workspace ONE UEM console using these instructions.
17. Expand advanced properties. Scroll down and ensure that the attribute being matched for username is exactly what is specified in UEM. That is, if UEM's name for the username attribute is sAMAccountName, it should also be listed as the attribute name here. Click next, next, and Save and Assign.
18. Assign this application to the same test user (or group) as the AirWatch Provisioning Adapter earlier. Make sure deployment type is Automatic, and click Save.
19. Check the box next to AirWatch Provisioning Adapter, and click Assign. Be sure it shows as provisioned for the user, and if not, click the retry button (we fixed the error for directory authentication in a previous step - it may just need to retry the provisioning action to work here).
20. To test this out, to into Workspace ONE UEM and go to Accounts. Verify that the okta-based account is present here. Next, go to the self-service portal in an incognito window and sign in with the Okta account credentials (ds####.awmdm.com/MyDevice... ex. ds1688.awmdm.com/MyDevice). Click "Account" in the top right corner. You should see all attributes from the user being provisioned from Access into UEM (ex. first name, last name, email address, username, despite username only being specified as part of the SAML assertion from Access).
You should now have completed the SCIM and SAML SSO integration is now completed. If your intent is just to SCIM provision users, you can stop here. There are other integrations available as notated below (ex. device trust, certificate-based SSO through the AirWatch CA and Workspace ONE Access). See the appropriate sections for next steps.
Desktop SSO
As mentioned above, the section for "Desktop SSO" will refer to using a certificate for authentication in Workspace ONE. Generally this is the most useful when using Access as the source of truth IdP (as it magically signs you into SaaS apps in lieu of a password every time). But in this case, we need to set this up to leverage the device trust/device factor trust integration. Details on that forthcoming in the following sections. For now, let's focus on setting up certificate based authentication using the Workspace ONE UEM built-in CA. Note: You don't need to use the built in CA (also known as AirWatch CA) for certificate based auth. Workspace ONE supports many third party CA's, and we can leverage those instead. For purpose of this guide and keeping configuration simple to a CA that all customers have, I will focus on the AirWatch CA. You can find details on integrating with third party CA's in Workspace ONE here.
First, let's open up the Workspace ONE UEM console. Go to Groups and Settings - All Settings - System - Enterprise Integration - Workspace ONE Access - Configuration. You should already have your Workspace ONE Access environment details specified here. If not, take a moment to input your Access tenant URL and admin credentials. Scroll down on this page, and under the "certificate" section, click "enable".
2. Still on this page, the enable button should turn into an export button. Click "export" to export the AirWatch root certificate.
3. Next, jump to the Workspace ONE Access console. Go to Integrations - Authentication Methods. Select the radio button next to "certificate (cloud deployment)" and click Configure.
4. Enable the certificate adapter, and upload the root certificate you downloaded earlier. The defaults here should be fine.
5. Still in the Access console, go to Integrations - Identity Providers. Click on the "Built-In" identity provider.
6. In the Built-In identity provider, check the box for the Okta Universal Directory. Under the Authentication Methods section, make sure that "Certificate (Cloud Deployment)" is selected. Under Network Ranges, select ALL RANGES. Then click Save on this page to save all changes.
7. While we are in Access, we will need to change the access policy for sign in. This essentially tells WS1 Access how to authenticate different types of devices/types of users/network ranges/etc. We'll need to basically create an authentication method for Windows (as this is the platform we are targeting with certificate based authentication) to use cert-based auth and then use Okta as a fallback.
In Access, go to Resources - Policies - Edit Default Policy (note: in a production environment, it is a good idea to utilize multiple access policies here)
8. Under configuration, click "Add Policy Rule"
9. Create the policy rule for Windows 10+ that authenticates using the certificate authentication method we created earlier with Okta authentication as a fallback method
10. Next click save. Move the Windows 10+ rule to the top of the list (so it is executed first), and then click next and Save to close out of the authentication policies window.
11. Next, we'll need to jump back into the Workspace ONE UEM console to actually push certificates to the devices. Go to resources - profiles & baselines - profiles - add - add profile
12. We'll need to select Windows for the platform, and select a user profile.
13. Give the profile a name and assign it to a smart group. Then select the SCEP payload.
14. Select the AirWatch CA for the certificate source and certificate authority. Set Certificate (cloud deployment) for the certificate template. Set the key location to TPM if present (relevant if testing on a Win10 VM with no TPM). Then select Save and Publish.
15. Create another Windows profile, this time a device profile. Give it a name and assign it to a smart group. This profile will be pushing the root CA to the device to establish trust on the device. We will then be pushing a credentials payload.
16. Upload the AirWatch root certificate from Workspace ONE UEM (what was downloaded in step 2). Set the certificate store to be "trusted root". Save and publish the profile. (This will make sure the computer sees the user identity certificate as coming from a trusted CA)
Note: If you are using an environment that is not a trial (ex. testdrive sandbox) that doesn't have Hub Services enabled out of the box, you may need to do so to get sign in to work properly for enrollment. In the UEM console, go to Configurations - Intelligent Hub. Make sure Hub Services is enabled here (or enable it if not done so, should all configuration should be preset).
If Hub Services is configured, it will look something like this:
17. Now you should have certificate based SSO working on Windows. You can verify this by going to your Workspace ONE Access tenant URL on an enrolled Windows machine and be able to use the certificate to authenticate. You can also view the personal certificate store on the Windows machine and see a certificate with the enrollment username:
Mobile SSO
For Mobile SSO, I will refer to this blog post by Steve, "The Identity Guy". He walks through the steps to get Mobile SSO working for iOS and Android (which require different steps between the two platforms).
Okta as an Application Source
Through this integration, we can pull in any app entitlements for a user from Okta into Workspace ONE. What's important to note here is that this is not changing the authentication flow for these applications - that is still handled by Okta. We are just using API to pull a user's app entitlements into the Workspace ONE Access catalog. This way, the user has one portal to go to - either the Intelligent Hub application on their device, or by visiting the Workspace ONE Access portal URL.
First, we will need to configure Workspace ONE Access as an IdP in Okta. We'll start in the Workspace ONE Access console. Go to Resources - Web Apps - Settings.
2. Go to the SAML Metadata section, and download the IdP metadata file and the Signing Certificate. We'll need this in a minute to configure WS1 as an IdP in Okta.
3. Next, in the Okta admin console, go to Security - Identity Providers - Add Identity Provider. Select "SAML 2.0 IdP" as the type, and then fill in the form as follows:
Name: (Your choice), ex. Workspace ONE
IdP Usage: SSO Only
IdP Username: idpuser.subjectNameID
Match against: Okta Username
If no match is found: Redirect to Okta sign-in page
IdP Issuer URI: entityID value in the SAML metadata. Ex. https://tenant.vmwareidentity.com/SAAS/API/1.0/GET/metadata/idp.xml
IdP Single Sign On URL: Found in the SAML Metadata. Ex. https://tenant.vmwareidentity.com/SAAS/auth/federation/sso
IdP Signature Certificate: Downloaded from previous step
Click finish.
On the next page that displays the SAML information for Okta, click the link for "download metadata"
4. While in Okta, let's obtain the API key needed for the application source integration. Go to Security - API - Tokens. Click Create Token. Name the token and copy this value (don't lose it!)
5. Next, in the Access console, go to Integrations - Okta Catalog. Specify your okta tenant URL (be sure to remove the admin suffix from any URL's or else nothing will populate), the API key, and set the user search parameter to be ${user.userName}. Click Save.
6. In the Access console, go back to resources - web apps - settings (the button on the main page). Then go to Application Sources - OKTA.
7. After clicking Okta, click Next. Paste the contents of the metadata document you downloaded from Okta into the appropriate box. Note: Open the metadata in textedit or notepad to ensure that no data is lost to formatting.
8. Click next, next, and save.
The integration should now be complete. You can test this by going to your Workspace ONE Access tenant URL, login as the Okta user, and you should see all app entitlements once you click on "Apps" in Hub. (It may take a minute before they will populate after sign in)
Device Factor Trust
In this section, I will go through setting up device factor trust. This differs from simple device trust between WS1 and Okta in the sense that we are leveraging WS1 Access as a factor instead of having it send a trusted/untrusted "flag" as part of the SAML assertion. Device trust will only work with the Okta Classic Engine, device factor trust will work regardless of using that or Okta Identity Engine. Finally, it will also work with all platforms (Windows, Mac, iOS, Android) since it leverages certificate-based authentication within WS1 Access. Prior to completing this integration, you'll need to make sure that (1) you've completed all other steps on this page (as it pertains to the appropriate platform) and (2) contact Okta Support and ask them to enable the features CLAIMS_AS_FACTOR and MFA_ENROLL_POLICY_APP_CONDITION. These will allow us to leverage Workspace ONE IdP as a MFA factor.
If you have not done so already, download the Workspace ONE Access IdP metadata from Workspace ONE Access (Resources - Settings button on main page - SAML Metadata - right click and download Identity Provicer (IdP) Metadata)
2. In Okta, go to Security - Identity Providers. Click Add new identity provider, select SAML 2.0 IdP as the type, and click next.
3. Give it a distinct name (ex. Workspace ONE SSO Factor). Change "IdP usage" to be "Factor Only"
4. Fill the remaining fields in as they were when configuring WS1 as an IdP in Okta for the "Okta as an Application Source" section:
IdP Issuer URI: entityID value in the SAML metadata. Ex. https://tenant.vmwareidentity.com/SAAS/API/1.0/GET/metadata/idp.xml
IdP Single Sign On URL: Found in the SAML Metadata. Ex. https://tenant.vmwareidentity.com/SAAS/auth/federation/sso
IdP Signature Certificate: Downloaded from previous step
Click Save. Export the metadata from this SSO Factor IdP, we will need it later.
5. In Okta, go to Security - Multifactor. Under Factor Types, find IdP factor. Enable it and select the type to be Workspace ONE.
6. Next, we will need to create a group to assign the MFA policy to (and ideally any applications that are going to be "protected" - or require WS1 to do the device enrollment/compliance check. In Okta, go to Directory - Groups. Create a group, for instance WS1 or ProtectedApp, and assign it to some users and aforementioned apps to be "protected"
7. Next, go to Security - Multifactor - Multifactor enrollment. Add a multifactor policy for the group you created. Disable all factors except for the IdP Factor. Within the multifactor policy, you may need to create a rule that looks something like the second screenshot -
8. Still in Okta, go to Applications - Applications, find the application you wish to protect. In that app settings, go to Sign on, and scroll down to the bottom of the page. Create a sign on policy rule to enforce MFA for each sign on attempt. In my example, I am doing this just for Windows, but check all applicable platforms.
After clicking add sign on rule:
Rinse and repeat this for every "protected" application. This will ensure that every sign on attempt will redirect to Workspace ONE to authenticate as a factor.
8. In okta, go to Security - Identity Providers, and click on the Routing Rules tab. Add a routing rule for the applicable platform(s) and application(s). Set it such that if it matches, to redirect to the SSO Factor IdP we created earlier.
9. On the home stretch. Jump back into Workspace ONE Access. Under Resources - Web Apps, create a new web app. Give it a name (this will allow okta to connect to Workspace ONE Access to authenticate as a SSO factor). Click next.
10. Copy and paste the contents of the XML metadata document into the URL/XML box in Workspace ONE Access (we downloaded this when creating the SSO Factor IdP in Okta in step 4 of this section). Scroll down and then deselect "Show in User Portal". Click next, next, and save and assign.
11. Assign this application to all Okta users (ideally the group created in Access to house all users provisioned via SCIM from Okta). Set the deployment type to be automatic, and entitlement type to be include. Then click save.
12. Still in Access, go to resources - policies - add a policy.
13. Name it something like Okta Factor Trust, and assign it to the application that we just created (in my case, named the same). Click next.
14. Under configuration, create a policy rule for Windows (or applicable platform) set to certificate (cloud deployment) - or mobile sso for applicable mobile platform. You can also setup device compliance checks with Workspace ONE and add it here as a additional authentication method. The key here is not setting a fallback authentication method. If the device doesn't have the certificate on it (that is, is not enrolled or the certificate is revoked as a result of a compliance policy), it will fail authentication into the SaaS application as a result of this policy.
15. When done, click save, next, and save.
The device trust integration should now be complete. You can test this out by enrolling a device into Workspace ONE and attempting to either access the protected application via Workspace ONE or via Okta. Okta will redirect to Workspace ONE for authentication via certificate as a MFA factor. This authentication policy that requires a certificate is applied only to the IdP that is used as a SSO factor. Regular SSO will not be impacted.
Appendix
For additional information on the integrations above, I wanted to supply the below links. Note that the documentation from VMware can differ from what I walk through above (ex. VMware Doc may mention enabling JIT provisioning for Okta as a third party IdP because of the fact that documentation is separate from the SCIM provisioning documentation). Though these are still a good resource to have on hand.
If you've spotted an error in this and would like to let me know, please email me: help@seinanrv.com, and I'll do my best to correct any errors.