Decoding Services Roles/Permissions from a VMware Cloud Services Platform (CSP) Token

To programmatically access the various VMware Cloud Services (CSP) such as VMware Cloud on AWS as an example, a user must first generate a CSP Refresh Token using the CSP Console.

When creating a new CSP Refresh Token, you have the option to scope access to a specific set organization roles and service roles which will enable you to limit the permissions of this token to specific CSP Services. In the example below, I have created a new token which is scoped to the organization owner role along with two VMware Cloud on AWS Service Roles: Administrator (Delete Restricted) and NSX Cloud Admin to be able to grant access to a VMware Cloud on AWS SDDC.

One common issue that I see folks run into when working with some of the CSP Services including VMware Cloud on AWS from a programmatic standpoint is that they did not properly create a token with the correct permissions which usually will lead to some type of invalid request.

For popular services like VMware Cloud on AWS, it is usually pretty easy to track down, especially if the user who is using the CSP Refresh Token is the same person who created it. However, if you are not the person who created the original token or if you have forgotten or you may have access to multiple token, it can be a little bit difficult to troubleshoot.

The good news and probably lesser known detail about how CSP Refresh Tokens work is that you can actually decode these tokens to understand what specific scopes were used to create the initial token. Below are two methods to decode these tokens, both CSP Refresh Tokens (generated from the CSP UI) as well as CSP Access Token, which is returned when you request access providing your CSP Refresh Token.

Decode CSP Refresh Token

Step 1 - Navigate to the Developer Center Portal within the VMware Cloud on AWS Service. Under Cloud Services Platform->Identity and Account Management, search for "api-tokens" and you will find the following CSP API: /am/api/auth/api-tokens/details which will allow you to decode the generated CSP Refresh Token

Step 2 - On the right hand side of the body request, click on GetApiTokenDetailsRequest link which will automatically generate the request payload template. Just paste your CSP Token and click on the Execute button to call the API

If you provided a valid CSP Refresh Token, the API should decode the token and provide a number of details including who created the token, the current expiration and more importantly, the scoped organization and service roles 🙂

Note: You can also do this programmatically using any REST Client, but the API Explorer is a handy way of not having to write a single line of code to be able to use some of the CSP and VMware Cloud APIs.

Decode CSP Access Token

Step 1 - Request a CSP Access Token given your CSP Refresh Token. You can use the following cURL snippet to quickly retrieve it (or if you prefer PowerShell, check out this script)

REFRESH_TOKEN="FILL-ME-IN"
RESULTS=$(curl -s -X POST -H "application/x-www-form-urlencoded" "https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize" -d "refresh_token=$REFRESH_TOKEN")
CSP_ACCESS_TOKEN=$(echo $RESULTS | jq -r .access_token)
echo $CSP_ACCESS_TOKEN

Step 2 - The generated CSP Access Token is a JSON Web Token or JWT (pronounced jot) for short hand. Using any standard JWT tool like https://jwt.io/, you can paste in the token and perform the exact same decoding.

Similar to using the CSP API to decode the CSP Refresh Token, you can see the CSP Access Token contains the exact same information including service scopes.

So the next time you want to quickly check what CSP service roles have been scoped to either your CSP Refresh or Access Token, you now have two easy ways to quickly check and verify.