In this blog post we will learn how to generate an authentication token and use it to invoke the SDDC Manager APIs in VMware Cloud Foundation 4.0.
With the release of VMware Cloud Foundation 4.0, all the SDDC Manager APIs are secured and use a token-based authentication model for API invocation (except restore and Cloud Builder APIs).
To demonstrate, all the examples described in the article use cURL to invoke the SDDC Manager APIs. Before you continue, make sure cURL is installed on your machine.
cURL Request Syntax:
|
1 |
curl -X POST -H "Content-Type: application/json" -d '{"username": "<USERNAME>","password": "<PASSWORD>"}' https://<SDDC_MANAGER_IP>/v1/tokens |
Replace the following in the above command:
<USERNAME>: The username created in SSO (For Example: [email protected]).
<PASSWORD>: The user password.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -X POST -H "Content-Type: application/json" -d '{"username": "[email protected]","password": "SomePassword123!"}' https://10.0.0.4/v1/tokens | json_pp |
Note: In case if you get this error “Peer’s certificate issuer has been marked as not trusted by the user” while executing the above curl command, turn off the certificate verification by using -k (or –insecure) option. This applies to other examples also which are listed in the blog.
Example response:
|
1 2 3 4 5 6 |
{ "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZmI2MjNkZS1kZjIwLTQ1NWEtOWQ3NC1mYzgwZmFjNzM5ZGUiLCJpYXQiOjE1ODIxOTcxODcsInN1YiI6InZjZi1zZWN1cmUtdXNlckB2c3BoZXJlLmxvY2FsIiwiaXNzIjoidmNmLWF1dGgiLCJhdWQiOiJzZGRjLXNlcnZpY2VzIiwibmJmIjoxNTgyMTk3MTg3LCJleHAiOjE1ODIyMDA3ODcsInVzZXIiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsIm5hbWUiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ._92IFJCQsbRbAWd4PQmBDczWXtuVCWPOsL1ZyCdKEMU", "refreshToken": { "id": "3c6b3c30-3bf2-480b-9539-8483699ab928" } } |
How to use a token to invoke API
Firstly, generate a token pair as described in the earlier section and then use that access token here as a Bearer token in the Authorization header and invoke the SDDC Manager API.
As an example, use the following API endpoint (using token) to get all the VCF domains.
cURL Request Syntax:
|
1 |
curl -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://<SDDC_MANAGER_IP>/v1/domains |
Replace the following in the above command:
<ACCESS_TOKEN>: The accessToken.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZmI2MjNkZS1kZjIwLTQ1NWEtOWQ3NC1mYzgwZmFjNzM5ZGUiLCJpYXQiOjE1ODIxOTcxODcsInN1YiI6InZjZi1zZWN1cmUtdXNlckB2c3BoZXJlLmxvY2FsIiwiaXNzIjoidmNmLWF1dGgiLCJhdWQiOiJzZGRjLXNlcnZpY2VzIiwibmJmIjoxNTgyMTk3MTg3LCJleHAiOjE1ODIyMDA3ODcsInVzZXIiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsIm5hbWUiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ._92IFJCQsbRbAWd4PQmBDczWXtuVCWPOsL1ZyCdKEMU" https://10.0.0.4/v1/domains | json_pp |
Example response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "elements" : [ { "vcenters" : [ { "id" : "d6c29e6a-cd20-4d26-bcec-615c5e4be5d9" } ], "name" : "sddcId-1001", "clusters" : [ { "id" : "1041a2ab-1420-43c2-8344-8d13f9a76e2e" } ], "type" : "MANAGEMENT", "id" : "3bee94a0-3cd2-4046-a87a-5f0b87288fc4" } ] } |
How to generate a new token using the refresh token
The refresh token is a special type of token used to renew an access token either when the access token expires or preemptively. A refresh token can be used any number of times to obtain an access token until it expires or invalidated.
Use the following API endpoint to get a new access token using the refresh token.
cURL Request Syntax:
|
1 |
curl -X PATCH -H "Content-Type: application/json" -d '<REFRESH_TOKEN_ID>' https://<SDDC_MANAGER_IP>/v1/tokens/access-token/refresh |
Replace the following in the above command:
<REFRESH_TOKEN_ID>: The refreshToken id (Note: Use refreshToken id obtained in “How to generate a token” section or generate a new token and use that refresh token here).
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -X PATCH -H "Content-Type: application/json" -d '3c6b3c30-3bf2-480b-9539-8483699ab928' https://10.0.0.4/v1/tokens/access-token/refresh |
Example response:
|
1 |
"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI5MDZiYjkzMS1hZjdiLTQzYTAtYjEyMC1kMzk3YmMwYjE1NzEiLCJpYXQiOjE1ODcwNDc0MzAsInN1YiI6InZjZi10ZXN0LXVzZXJAdnNwaGVyZS5sb2NhbCIsImlzcyI6InZjZi1hdXRoIiwiYXVkIjoic2RkYy1zZXJ2aWNlcyIsIm5iZiI6MTU4NzA0NzQzMCwiZXhwIjoxNTg3MDUxMDMwLCJ1c2VyIjoidmNmLXRlc3QtdXNlckB2c3BoZXJlLmxvY2FsIiwibmFtZSI6InZjZi10ZXN0LXVzZXJAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ.fW_GUy41Od_MNqIRqPjCD5qwk92KBpRaASeDL9Oq4YQ" |
How to revoke a refresh token
To demonstrate, let’s first generate a token as described in section “How to generate a token” and then use that refresh token here to invalidate it.
Note that refresh token cannot be used again to renew an access token after it is revoked.
Use the following API endpoint to revoke a refresh token.
cURL Request Syntax:
|
1 |
curl -i -X DELETE -H "Content-Type: application/json" --data '<REFRESH_TOKEN_ID>' https://<SDDC_MANAGER_IP>/v1/tokens/refresh-token |
Replace the following in the above command:
<REFRESH_TOKEN_ID>: The refreshToken id.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -i -X DELETE -H "Content-Type: application/json" --data '3c6b3c30-3bf2-480b-9539-8483699ab928' https://10.0.0.4/v1/tokens/refresh-token |
Example response:
|
1 2 3 4 5 6 7 8 9 10 11 |
HTTP/1.1 204 Server: nginx Date: Wed, 15 Apr 2020 11:26:21 GMT Connection: keep-alive X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Frame-Options: DENY Strict-Transport-Security: max-age=15768000 |
How to use a token generated by service account user to invoke an API
The following are the step-by-step instructions to invoke the SDDC Manager API using the token obtained by the service account user.
Step 1: Get the role id to assign a role for the service account user.
Use the following API endpoint to get all the role id’s.
cURL Request Syntax:
|
1 |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://<SDDC_MANAGER_IP>/v1/roles |
Replace the following in the above command:
<ACCESS_TOKEN>: The accessToken.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZmI2MjNkZS1kZjIwLTQ1NWEtOWQ3NC1mYzgwZmFjNzM5ZGUiLCJpYXQiOjE1ODIxOTcxODcsInN1YiI6InZjZi1zZWN1cmUtdXNlckB2c3BoZXJlLmxvY2FsIiwiaXNzIjoidmNmLWF1dGgiLCJhdWQiOiJzZGRjLXNlcnZpY2VzIiwibmJmIjoxNTgyMTk3MTg3LCJleHAiOjE1ODIyMDA3ODcsInVzZXIiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsIm5hbWUiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ._92IFJCQsbRbAWd4PQmBDczWXtuVCWPOsL1ZyCdKEMU" https://10.0.0.4/v1/roles | json_pp |
Example response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "elements" : [ { "name" : "ADMIN", "id" : "d40632bd-3e5d-b209-bca0-c73bb97733c5", "description" : "Administrator" }, { "name" : "OPERATOR", "id" : "246f28d4-414b-d096-070a-042e63812b1c", "description" : "Operator" } ] } |
Step 2: Add Service Account User with ADMIN or OPERATOR role.
As an example, use the following API endpoint to add the service account user with role mapped to Admin or Operator.
cURL Request Syntax:
|
1 |
curl -i -H "Content-Type: application/json" --data @<FILE_NAME> -H "Authorization: Bearer <ACCESS_TOKEN>" https://<SDDC_MANAGER_IP>/v1/users |
Replace the following in the above command:
<FILE_NAME>: The name of the file containing the service account user details. Refer to the sample data file (user.json) mentioned below as an example.
<ACCESS_TOKEN>: The accessToken.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
user.json (Note: Update the below JSON spec with correct role id as obtained in Step 2)
|
1 2 3 4 5 6 7 8 9 10 |
[ { "name": "automation_test_account", "type": "SERVICE", "role": { "id": "d40632bd-3e5d-b209-bca0-c73bb97733c5" } } ] |
|
1 |
curl -H "Content-Type: application/json" --data @user.json -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZmI2MjNkZS1kZjIwLTQ1NWEtOWQ3NC1mYzgwZmFjNzM5ZGUiLCJpYXQiOjE1ODIxOTcxODcsInN1YiI6InZjZi1zZWN1cmUtdXNlckB2c3BoZXJlLmxvY2FsIiwiaXNzIjoidmNmLWF1dGgiLCJhdWQiOiJzZGRjLXNlcnZpY2VzIiwibmJmIjoxNTgyMTk3MTg3LCJleHAiOjE1ODIyMDA3ODcsInVzZXIiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsIm5hbWUiOiJ2Y2Ytc2VjdXJlLXVzZXJAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ._92IFJCQsbRbAWd4PQmBDczWXtuVCWPOsL1ZyCdKEMU" https://10.0.0.4/v1/users | json_pp |
Example response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ “elements”:[ { “id”:“763d2a1b-0591-4008-b0cf-fd9365a5942b”, “name”:“new_automation_test_account_8”, “domain”:“Nil”, “type”:“SERVICE”, “apiKey”:“mTCfynCKBjFts4iFvu9RIiTb5sE6Ntuu”, “role”:{ “id”:“97ab1f02-0e59-ce22-e9cd-a53f85ad8515" }, “creationTimestamp”:“2020-02-27T09:45:56.940Z” } ] } |
Step 3: Generate token using the API key of Service Account User.
Use the following API endpoint to generate a token using the apiKey of Service Account User.
cURL Request Syntax:
|
1 |
curl -X POST -H "Content-Type: application/json" -d '{"apiKey": "<API_KEY>"}' https://<SDDC_MANAGER_IP>/v1/tokens |
Replace the following in the above command:
<API_KEY>: The apiKey (Note: Use apiKey obtained in the previous step).
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -X POST -H "Content-Type: application/json" -d '{"apiKey": "mTCfynCKBjFts4iFvu9RIiTb5sE6Ntuu"}' https://10.0.0.4/v1/tokens | json_pp |
Example response:
|
1 2 3 4 5 6 |
{ "accessToken" : "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI3NmY3OWYwYS1iNTEzLTQ5ZGUtYWQ2MC1hNDllZDc1MThkYjEiLCJpYXQiOjE1ODIyMTU2NTAsInN1YiI6ImF1dG9tYXRpb25fYnJpbmd1cF9yYW5nYSIsImlzcyI6InZjZi1hdXRoIiwiYXVkIjoic2RkYy1zZXJ2aWNlcyIsIm5iZiI6MTU4MjIxNTY1MCwiZXhwIjoxNTgyMjE5MjUwLCJ1c2VyIjoiYXV0b21hdGlvbl9icmluZ3VwX3JhbmdhIiwibmFtZSI6ImF1dG9tYXRpb25fYnJpbmd1cF9yYW5nYSIsInNjb3BlIjpbIkNSRURFTlRJQUxfUkVBRCIsIkNSRURFTlRJQUxfV1JJVEUiLCJVU0VSX1JFQUQiLCJVU0VSX1dSSVRFIiwiQkFDS1VQX0NPTkZJR19SRUFEIiwiQkFDS1VQX0NPTkZJR19XUklURSIsIk9USEVSX1JFQUQiLCJPVEhFUl9XUklURSJdfQ.igC4x7hLEB1PaN6PQgLhFdNAhcQfu9jGtz0ki4D05KE", "refreshToken" : { "id" : "73af92dc-a24d-4fab-9a80-311d1ef68b57" } } |
Step 4: Invoke SDDC Manager API using the token obtained by the Service Account User.
As an example, use the following API endpoint to get network pools using the token obtained by the service account user.
cURL Request Syntax:
|
1 |
curl -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://<SDDC_MANAGER_IP>/v1/network-pools |
Replace the following in the above command:
<ACCESS_TOKEN>: The accessToken (Note: Use accessToken obtained in the previous step).
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.
Example request:
|
1 |
curl -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI3NmY3OWYwYS1iNTEzLTQ5ZGUtYWQ2MC1hNDllZDc1MThkYjEiLCJpYXQiOjE1ODIyMTU2NTAsInN1YiI6ImF1dG9tYXRpb25fYnJpbmd1cF9yYW5nYSIsImlzcyI6InZjZi1hdXRoIiwiYXVkIjoic2RkYy1zZXJ2aWNlcyIsIm5iZiI6MTU4MjIxNTY1MCwiZXhwIjoxNTgyMjE5MjUwLCJ1c2VyIjoiYXV0b21hdGlvbl9icmluZ3VwX3JhbmdhIiwibmFtZSI6ImF1dG9tYXRpb25fYnJpbmd1cF9yYW5nYSIsInNjb3BlIjpbIkNSRURFTlRJQUxfUkVBRCIsIkNSRURFTlRJQUxfV1JJVEUiLCJVU0VSX1JFQUQiLCJVU0VSX1dSSVRFIiwiQkFDS1VQX0NPTkZJR19SRUFEIiwiQkFDS1VQX0NPTkZJR19XUklURSIsIk9USEVSX1JFQUQiLCJPVEhFUl9XUklURSJdfQ.igC4x7hLEB1PaN6PQgLhFdNAhcQfu9jGtz0ki4D05KE" https://10.0.0.4/v1/network-pools | json_pp |
Example response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{ "elements" : [ { "name" : "bringup-networkpool", "id" : "fbe5bea1-08d0-43a6-a55d-7abf3c71ee73", "networks" : [ { "id" : "e30bed88-3896-48a5-8c67-e4e0513bbfb9" }, { "id" : "9a6a9768-934a-4c2b-bd63-383937fbd46a" } ] } ] } |
References:
For any additional information refer to VMware Cloud Foundation documentation. Here are a few links for quick reference:
VMware Cloud Foundation 4.0 API Reference
VMware Cloud Foundation 4.0 Operations and Administration Guide
