Acquire an Authentication Token

VMware Aria Operations requires API requests to be authenticated. The first step in this workflow is to obtain an authentication token.

To obtain an authentication token, the login request supplies the user credentials in a form that Basic HTTP authentication requires. In this example, the user is logging in to a VMware Aria Operations instance with URL https://vrealize.example.com/.

Note: This example uses token-based authentication. For more information regarding authentication mechanisms, see Security.

Using authSource, you can import and authenticate users and user group information that reside on another machine. For example, you can authenticate users from LDAP, Active Directory, VMware Identity Manager, Single Sign-On and so on. When you import user account information that resides on another machine, you must define the criteria used to import the user accounts from the source machine.

After creating an auth source you can use it for acquiring a token by specifying the name. The default auth source type is LOCAL.

Prerequisites

• Secure a channel between the web browser and the VMware Aria Operations server. Open a browser and enter the URL of a VMware Aria Operations instance such as:

  https://vrealize.example.com

  The system warns that your connection is not private. Click through to confirm the security exception and establish an SSL handshake.

• Verify that you can access the APIs. Enter the URL of your VMware Aria Operations instance with suite-api/docs/rest/index.html added to the end, such as:

  https://vrealize.example.com/suite-api/docs/rest/index.html

• Verify that you have the login credentials for a user of your VMware Aria Operations instance.

Procedure

1. POST a request to the login URL to acquire a token.
   See Login Request and Response.

   1. You obtain valid user credentials for your VMware Aria Operations instance.
   2. POST a request to the REST endpoint for authentication (non-SSO).

      https://RESTendpoint.example.com/suite-api/api/auth/token/acquire

      The request body includes the user name, password, and authentication source.

   3. In the response body, the endpoint returns the token, expiry date, and time.
   4. For further communication, you include the token object in the Authorization header with the format :

      Authorization: OpsToken <vROps_token>

      Note: The old format,

      Authorization: vRealizeOpsToken <vROps_token>

      continues to be supported in VMware Aria Operations.
      If you acquired the token externally from an SSO source (without using /suite-api/api/auth/token/acquire API), the Authorization header is of the format:

      Authorization: SSO2Token <SSO_SAML_TOKEN>

2. Examine the response.
   A successful request returns an ops authorization token, which you must included in subsequent API requests.

Example: Login Request and Response

This example shows a request and response for a user with the login username: vRealize-user and password: vRealize-dummy-password.

Request header:

POST https://vrealize.example.com/suite-api/api/auth/token/acquire
Content-Type: application/json
Accept: application/json

Request body in JSON format:

{
  "username" : "vRealize-user",
  "password" : "vRealize-dummy-password"
}

Response in JSON:

200 OK

{  
  "token": "8f868cca-27cc-43d6-a838-c5467e73ec45::77cea9b2-1e87-490e-b626-e878beeaa23b",  
  "validity": 1470421325035,  
  "expiresAt": "Friday, August 5, 2016 6:22:05 PM UTC",  
  "roles": []
}

The response code indicates whether the request succeeded, or how it failed.

• If the request is successful, the server return HTTP response code 200 (OK) and re-usable ops authorization token that expires after six hours. This token must be included in each subsequent API request.
• If the authorization header is missing for the request, the server returns HTTP response code 403.
• If the credentials supplied in the Authorization header are invalid, the server returns HTTP response code 401.