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",
        "userStatus": "1",
        "domain": "1dsavm.com",
        "userStoreUuid": "987dca12-22e3-4ec6-8958-110cca481c3d",
        "externalUserDisabled": false,
        "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"