Skip navigation
2019

There are times during troubleshooting where you like to see a particular attribute in Workspace ONE Identity (VMware Identity Manager) and its not displayed in the web portal or times when you would like to update a particular attribute or delete a JIT user.

 

DISCLAIMER:  Please use the API with caution as this can potentially cause issues if not used appropriately. Please do NOT use in Production. Please use at your own risk.

 

In this blog we'll walk through a few useful API calls to help in your troubleshooting. For a complete list of API calls and documentation:

 

VMware Identity Manager API - VMware API Explorer - VMware {code}

 

Please download and install the latest version of Postman.

 

In this blog we'll go use the following API's:

  • Get Specific User Details
  • Update SCIM User
  • Delete SCIM User
  • Create SCIM User

 

Step 1: Getting your OAuth Token

 

In order do use the SCIM based API you need an OAuth token. I'm going to walk through two different ways of getting a token to use in your environment.

 

If you are going to access a particular environment quite often using postman I would suggest you go with Option 1. If its unlikely you will access a particular environment that often then you should go with Option 2.

 

Option 1: Creating an OAuth Application

  1. Log into Workspace ONE Identity Admin Console
  2. Click on the Catalog (down arrow) and select Settings
    Screen Shot 05-08-19 at 01.16 PM.PNG
  3. Click "Remote App Access"
  4. Click Create Client
    Screen Shot 05-08-19 at 01.18 PM.PNG
  5. Select "Service Access Token" from the Drop down menu
  6. Provide a Client ID ie. Postman
  7. Expand Advanced
  8. Click Generate Shared Secret (or provide one)
  9. Click Add
    Screen Shot 05-08-19 at 02.30 PM.PNG
  10. We will configure Postman in the next section.

 

Option 2: Using your browser cookies

 

  1. Make sure you have a way of accessing your browser cookies. I use a Chrome plugin called "Edit this cookie"
    Screen Shot 05-08-19 at 02.40 PM.PNG
  2. Log into your Workspace ONE Identity Admin Console
  3. Click the Cookie Icon in the chrome address bar
  4. Search for the "HZN" cookie
    Screen Shot 05-08-19 at 02.43 PM.PNG
  5. Copy the value for HZN.
  6. We will configure Postman in the next section.

 

Step 2: Configure Postman to use your OAuth Token

Depending which option you chose in the previous step, follow the instructions below to add your OAuth Token

 

Option 1: Creating an OAuth Application

  1. Open a new Tab in Postman
  2. In the authorization section, select "OAuth 2.0" as the type:
    Screen Shot 05-08-19 at 02.50 PM.PNG
  3. Click Get New Access Token
    Screen Shot 05-08-19 at 02.52 PM.PNG
  4. Provide a Token Name (ie. Workspace ONE)
  5. Under "Auth URL", enter https:[Tenant URL]/SAAS/auth/oauth2/authorize
    ie. https://dsas.vmwareidentity.com/SAAS/auth/oauth2/authorize
  6. "Under Access Token URL", enter https:[Tenant URL]/SAAS/auth/oauthtoken
    ie. https://dsas.vmwareidentity.com/SAAS/auth/oauthtoken
  7. Under Client ID, enter your Client ID from step 1.
  8. Under Secret, enter your secret from step 1.
  9. Under Scope, leave blank.
  10. Under Grant Type, select "Client Credentials"
    Screen Shot 05-08-19 at 02.58 PM.PNG
  11. Click Request Token
  12. Click on WorkspaceONE under Existing Tokens
  13. Select Use Token
    Screen Shot 05-08-19 at 03.00 PM.PNG
  14. If you click on the headers tab you will see the "Authorization" header has been added with the correct token.

 

Option 2: Using your browser cookies

 

  1. Open a new Tab in Postman
  2. Click on the Headers Section
  3. Add the Header Key "Authorization"
  4. In the Value, type "Bearer" then paste the value of the HZN cookie.
    Screen Shot 05-08-19 at 03.10 PM.PNG

 

Getting User Details

Now that you have your OAuth token, we can use this token to query Workspace ONE Identity.

 

  1. For the HTTP Method, select "GET"
  2. Enter the following for the URL: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users?filter=username%20eq%20%22MyUserID%22
  3. Replace MyUserID with a username in your environment
    ie. https://dsas.vmwareidentity.com/SAAS/jersey/manager/api/scim/Users?filter=username%20eq%20%22sdsa%22
  4. This will return a complete result set of attributes for the particular user.
    Screen Shot 05-08-19 at 03.23 PM.PNG

Updating User Details

In order to update user details via the API, you will need to collect some information from the Get User Details.

 

In my example, I'm going to update the "userPrincipalName" in Workspace ONE Access for one of my users.

  1. Perform a "Get" on the particular user and retrieve the schema information. Please note, this will be different for each tenant as the tenant name is part of the schema.
    Screen Shot 05-08-19 at 03.34 PM.PNG
  2. Copy this section to notepad.
  3. Retrieve the section which contains the attribute(s) you want to update
    Screen Shot 05-08-19 at 03.35 PM.PNG
  4. Copy the ID of the User
    Screen Shot 05-08-19 at 03.38 PM.PNG
  5. Open a new Tab in Postman
  6. Add the Authorization Header as per the previous section.
  7. For the HTTP Method, select "PATCH"
  8. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users/[ID]
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com//SAAS/jersey/manager/api/scim/Users/884b7e7d-6a7b-4985-b113-56235826e8a6
  9. Select Body
  10. Enter the JSON in raw text that we'll post to Workspace ONE
  11. Select "JSON (application/json)" as the Content-Type
    Screen Shot 05-08-19 at 04.02 PM.PNG
  12. Click Send
  13. You should receive a "204 No Content" response
    Screen Shot 05-08-19 at 04.03 PM.PNG
  14. If you perform a GET User again you should see the value has changed.

 

Delete Users

If you are using JIT to onboard users into Workspace ONE Identity you've probably noticed there is no way to delete users in the web portal. They only way to delete is with the API.

  1. Perform a "Get" on the particular user and retrieve the ID
    Screen Shot 05-09-19 at 10.47 AM.PNG
  2. Open a new Tab in Postman
  3. Add the Authorization Header as per the previous section.
  4. For the HTTP Method, select "DELETE"
  5. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users/[ID]
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com//SAAS/jersey/manager/api/scim/Users/f6f89782-0a2a-4cc8-84a8-057f1da6ecde
  6. Click Send
    Screen Shot 05-09-19 at 10.50 AM 001.PNG
  7. You should receive a "204 No Content" response
    Screen Shot 05-08-19 at 04.03 PM.PNG
  8. If you perform a GET User again you should see no results found.
    Screen Shot 05-09-19 at 10.53 AM.PNG

 

Create Users

Creating Users in Workspace ONE Identity require a lot more steps. I reluctantly decided to document the steps as this should really be done by the out of the box connectors. The process is slightly different between System Directory, Local Directory, and Other.  The "Other" directory is created automatically when setting up the UEM/WS1 Integration.

 

Creating Users in the System Directory

  1. Open a new Tab in Postman
  2. Add the Authorization Header as per the previous section.
  3. For the HTTP Method, select "POST"
  4. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com//SAAS/jersey/manager/api/scim/Users
  5. Set the Content-Type to "application/json"
  6. Use the following as a sample:
{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:workspace:tenant:sva:1.0",
    "urn:scim:schemas:extension:workspace:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "userName": "testing4@mydomain.com",
  "name": {
    "givenName": "first4",
    "familyName": "last4"
  },
  "emails": [
    {
      "value": "testing4@mydomain.com"
    }
  ],
  "password": "Password$!"
}

 

Creating Users in a Local Directory

 

  1. Open a new Tab in Postman
  2. Add the Authorization Header as per the previous section.
  3. For the HTTP Method, select "POST"
  4. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com//SAAS/jersey/manager/api/scim/Users
  5. Set the Content-Type to "application/json"
  6. Use the following as a sample:
{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:workspace:tenant:sva:1.0",
    "urn:scim:schemas:extension:workspace:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "userName": "testing5@mydomain.com",
  "name": {
    "givenName": "first5",
    "familyName": "last5"
  },
  "emails": [
    {
      "value": "testing5@mydomain.com"
    }
  ],
  "password": "Password$!",
   "urn:scim:schemas:extension:workspace:1.0": {
        "internalUserType": "LOCAL",
        "userStatus": "1",
        "domain": "mydomain.com"
      }


}

 

Creating Users in an Other Directory

 

The steps to create a user in an other directory is almost identity to the local directory except that we need to know the "userStoreUuid" of the directory and we need an ExternalID. The External ID should be a valid ObjectGUID. If you don't have a valid ObjectGUID you will have problems when enrolling devices from the Workspace ONE Intelligent Hub application. Ensure that you generate a proper guid. See Online UUID Generator Tool as a example of a proper guid.

 

  1. Open a new Tab in Postman
  2. Add the Authorization Header as per the previous section.
  3. For the HTTP Method, select "GET"
  4. For the URL, enter: https://[TENANT URL]/SAAS/jersey/manager/api/connectormanagement/directoryconfigs?includeJitDirectories=true
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com/SAAS/jersey/manager/api/connectormanagement/directoryconfigs?includeJitDirectories=true
  5. Click Send
  6. In the response, search for your "Other Directory" and copy the userStoreID
  7. Screen Shot 05-09-19 at 05.25 PM.PNG
  8. Open a new Tab in Postman
  9. Add the Authorization Header as per the previous section.
  10. For the HTTP Method, select "POST"
  11. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/scim/Users
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com//SAAS/jersey/manager/api/scim/Users
  12. Set the Content-Type to "application/json"
  13. Use the following as a sample and don't forget to create a Unique External ID.
{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:workspace:tenant:sva:1.0",
    "urn:scim:schemas:extension:workspace:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "externalId": "c58085e6-c97a-4df3-8e4a-e376913fab17",
  "userName": "testing6@mydomain.com",
  "name": {
    "givenName": "test6",
    "familyName": "last6"
  },
  "emails": [
    {
      "value": "testing6@mydomain.com"
    }
  ],
  "password": "Password$!",
   "urn:scim:schemas:extension:workspace:1.0": {
        "internalUserType": "PROVISIONED",
        "domain": "1dsavm.com",
        "userPrincipalName": "testing6@mydomain.com"
      }
}

 

Creating an Other Directory

When you configure UEM to integrate with Identity Manager an "Other" Directory should be automatically created. If in the case it is not created, you can create one via the API as well.

  1. Open a new Tab in Postman
  2. Add the Authorization Header as per the previous section.
  3. For the HTTP Method, select "POST"
  4. For the URL, enter: https://[TENANTURL]/SAAS/jersey/manager/api/connectormanagement/directoryconfigs
    Replace the Tenant URL with your URL
    Replace the ID with the ID from the step 4 in this section.
    ie. https://dsas.vmwareidentity.com/SAAS/jersey/manager/api/connectormanagement/directoryconfigs
  5. Set the Content-Type to "application/vnd.vmware.horizon.manager.connector.management.directory.other+json"
  6. Use the following as a sample
{
"type":"OTHER_DIRECTORY",
"domains":["SteveTestDomain2"],
"name":"SteveTest2"
}

 

Troubleshooting

It would be impossible to discuss every combination of errors that can be returned using the API. Here are a few common ones:

 

  1. If you receive the error "User is not authorized to perform the task.".
    This error typically means that your Oauth Token has expired. Regenerate your OAuth Token.  If you have used the browser cookies method to get your token, ensure that your HZN cookie is from the administrative interface.
  2. When doing an update user, you receive the error ""???UNSUPPORTED_MEDIA_TYPE???""
    This error means that you are sending a blank or incorrect Content-Type. Check to make sure the content-type is set to "application/json"

The release of Workspace ONE 19.03 brought in a very seamless integration of Okta Applications.

 

If you have integrated the two solutions previously you will recall the number of steps required to create and entitle new applications in Workspace from Okta. This integrations you to create and entitle applications in Okta and have them seamless appear in Workspace ONE along with your Native and Virtual Applications.

 

Lets walk through the steps to integrate the two solutions.

 

In this blog we are going to assume that you have existing connectors for Workspace ONE UEM and Workspace ONE Identity. We are also assuming you have your Workspace ONE Identity access policies already configured for Mobile SSO, Certificate or Password (Cloud Deployment).

 

Part 2: Unified Digital Workspace

The objective of this section to automatically sync all SAML enabled applications from Okta to Workspace ONE. This configuration will eliminate the manual steps required to both create and entitle Okta applications in Workspace ONE.

 

Step 1: Create an Okta API Key

  1. Log into the Okta Admin Console
  2. Go to Security -> API
  3. Click on Tokens
    Screen Shot 05-08-19 at 10.32 AM.PNG
  4. Click Create Token
  5. Provide a name for the token
    Screen Shot 05-08-19 at 10.34 AM.PNG
  6. Click Create Token
  7. Click the Copy Token button
    Screen Shot 05-08-19 at 10.35 AM.PNG
    Note:  Its very important you copy and save this token somewhere. Once you close this window you will not be able to retrieve this value again. You will have to delete the token and create a new one.

 

Step 2: Configure Workspace ONE with Okta API Information

  1. Log into the Workspace ONE Admin Console
  2. Click on Identity & Access Management -> Setup -> Okta
    Screen Shot 05-08-19 at 10.41 AM.PNG
    Note: If you are using Chrome, please be aware of Chrome auto filling any fields.

  3. Enter your Okta Cloud URL.
    Note: Do NOT use the Admin URL!!
    Screen Shot 05-08-19 at 12.19 PM.PNG

  4. Paste your Okta API Token
  5. Select the username search parameter that will match in Okta.
  6. Click Save

 

NOTE: Okta Applications will NOT appear in the Workspace ONE Admin Console

 

Step 3: Testing

  1. Log into Workspace ONE with a directory account.
  2. You should now see all your Okta Applications along with any other applications configured in Workspace ONE.

Screen Shot 05-08-19 at 12.38 PM.PNG

                                                                    down_arrow_clip_art_7569.jpg

Screen Shot 05-08-19 at 12.38 PM 001.PNG

The release of Workspace ONE 19.03 brought in a very seamless integration of Okta Applications.

 

If you have integrated the two solutions previously you will recall the number of steps required to create and entitle new applications in Workspace from Okta. This integrations you to create and entitle applications in Okta and have them seamless appear in Workspace ONE along with your Native and Virtual Applications.

 

Lets walk through the steps to integrate the two solutions.

 

In this blog we are going to assume that you have existing connectors for Workspace ONE UEM and Workspace ONE Identity. We are also assuming you have your Workspace ONE Identity access policies already configured for Mobile SSO, Certificate or Password (Cloud Deployment).

 

 

Part 1: Core Setup and Configuration

The objective of this section to configure Okta to delegate authentication to Workspace ONE Identity where Mobile SSO and Device Compliance are configured.

 

Step 1:  Exporting the Workspace ONE IdP Metadata

  1. Log into Workspace ONE Identity Console -> Catalog -> Settings
  2. Click on "Identity Provider (IdP) metadata" and save the file locally.
    Screen Shot 04-26-19 at 03.16 PM.PNG
  3. Scroll down to the Signing Certificate Section and Download.
    Screen Shot 04-26-19 at 03.30 PM.PNG

Step 2: Add Identity Provider to Okta

  1. Log into your Okta Admin Console
  2. Click on Security -> Identity Providers -> SAML 2.0 Identity Provider
  3. Click on Add Identity Provider
  4. Provider a name: ie. Workspace ONE
  5. For IdP Username, select "idpuser.subjectNameId"
  6. For "If no match is found", select "Redirect to Okta sign-in page"
  7. For your "IdP Issuer URI", retrieve and paste this value from your SAML Metadata you downloaded in step one.
  8. For your "IdP Single Sign-On URL",retrieve and paste this value from your SAML Metadata you downloaded in step one.
  9. For the "IdP Signature Certificate, upload the signing certificate you downloaded in Step 1.
  10. Expand the newly created Identity Provider and download the metadata
    Screen Shot 04-26-19 at 03.34 PM.PNG

Step 3: Create Okta Application Source in Workspace ONE Identity

  1. In Workspace ONE Identity Console, click on Catalog -> Settings
  2. Click on Application Sources
  3. Click on Okta
    Screen Shot 04-26-19 at 03.37 PM.PNG
  4. On the Okta Application Source page, click next
    Screen Shot 04-26-19 at 03.38 PM.PNG
  5. Select "URL/XML" and paste the contents of the Okta metdata we downloaded in the previous step.
    Screen Shot 04-26-19 at 03.40 PM.PNG
    If you chose manual, the mappings should be follow as below:
    Screen Shot 05-09-19 at 12.36 PM.PNG

  6. On the Access Policies page, click next (see note below):
    Screen Shot 04-26-19 at 03.41 PM.PNG

    Note: For the purpose of this blog we are using the "default_access_policy_set". However, it is recommended that you create an access policy specific for the Okta Application Source.  The reason for this recommendation is that you'll likely not want any fallback mechanisms when performing Mobile SSO (so we can present a error message to enroll your device). However, when you enroll your device into Workspace ONE UEM you probably want a fallback mechanism.

  7. Click Save on the summary page.

 

Step 4: Create Okta Routing Rules

  1. Log into the Okta console.
  2. Go to Security -> Identity Providers
  3. Click on Routing Rules
    Screen Shot 05-02-19 at 11.18 AM.PNG
  4. Click Add Routing Rule
  5. Provide a Rule Name
  6. Select the platforms that you want to using Workspace ONE Identity (ie. IOS/Android)
  7. Select the applications that you want to use Workspace ONE Identity
  8. Select the Identity Provider we created previously
    Screen Shot 05-02-19 at 11.21 AM.PNG
  9. Click Create Rule

 

Step 5: Testing

  1. Access your Salesforce development tenant
  2. Select to Authenticate with Okta
  3. Based on your Okta Rules, you should be redirected to Workspace ONE Identity.
  4. Authenticate within WS1
  5. You should return back to Okta and be redirected and successfully authenticated into SalesForce

Troubleshooting Tips

 

  1. Ensure your user is entitled to Salesforce within Okta.
  2. Verify the IdP Issuer in Okta is correct:

    https://aw-sdsatest.vidmpreview.com/SAAS/API/1.0/GET/metadata/idp.xml
  3. Verify the username values we are sending from Workspace ONE to Okta will match:
    Screen Shot 05-03-19 at 10.07 AM.PNG  TO Screen Shot 05-03-19 at 10.09 AM.PNG