VMware Cloud Foundation

Getting Started with Token-Based Authentication for VMware Cloud Foundation APIs

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.

Important Note: To illustrate, administrator@vsphere.local user will be used in this post to generate a authentication token and use it for invoking the SDDC Manager APIs. By default, administrator@vsphere.local user who is part of vCenter Single Sign-On (SSO) domain is added to VMware Cloud Foundation (VCF) with ADMIN role.

Note that any other user can be used but ensure the user is mapped with an ADMIN or OPERATOR role and added to VCF. Refer to Add a User or Group to Cloud Foundation section in VMware Cloud Foundation documentation for more information on how to add a user or group to VCF.

How to generate a token

Use the following API endpoint to generate a token. Make sure to use the valid credentials while executing the below API.

cURL Request Syntax:

Replace the following in the above command:

<USERNAME>: The username created in SSO (For Example: administrator@vsphere.local).
<PASSWORD>: The user password.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.


Example request:

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:

 

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:

Replace the following in the above command:

<ACCESS_TOKEN>: The accessToken.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.


Example request:


Example response:

 

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:

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:


Example response:

 

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:

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:


Example response:

 

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:

Replace the following in the above command:

<ACCESS_TOKEN>: The accessToken.
<SDDC_MANAGER_IP>: The IP address of the SDDC Manager.


Example request:


Example response:


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:

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)


Example response:


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:

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:


Example response:

 

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:

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:


Example response:

 

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

Related Articles

Comments

2 comments have been added so far

  1. Dear Amarnath Reddy,
    Thank you for sharing a nice article.Excellent for understanding SDDC Manager APIs in VMware Cloud Foundation 4.0.
    It will beneficial for IT professionals. Thanks for sharing one of these wonderful posts. Keep It Up.
    Faisal Bashir

Leave a Reply

Your email address will not be published. Required fields are marked *