Using Postman to Manage Workspace ONE Identities

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
   
3. Click "Remote App Access"
4. Click Create Client
   
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
   
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"
   
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
   
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:
   
3. Click Get New Access Token
   
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"
    
11. Click Request Token
12. Click on WorkspaceONE under Existing Tokens
13. Select Use Token
    
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.
   

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://[TENANT URL]/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.
   

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.
   
2. Copy this section to notepad.
3. Retrieve the section which contains the attribute(s) you want to update
   
4. Copy the ID of the User
   
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://[TENANT URL]/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
    
12. Click Send
13. You should receive a "204 No Content" response
    
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
   
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://[TENANT URL]/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
   
7. You should receive a "204 No Content" response
   
8. If you perform a GET User again you should see no results found.
   

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://[TENANT URL]/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://[TENANT URL]/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 Toolas 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
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://[TENANT URL]/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 the 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@oktatest.com",  "name": {    "givenName": "test6",    "familyName": "last6"  },  "emails": [    {      "value": "testing2@oktatest.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"      }
}

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"