Authenticating OAuth 2.0 clients with the API

Objective

Create, manage, and authenticate with OAuth 2.0 clients by using the Turbonomic API.

Prerequisites

To use the API to create and manage OAuth 2.0 clients and tokens, you must have the following prerequisites:

Turbonomic version 8.12.4 or later
t8c-operator version 42.57 or later
ADMINISTRATOR or SITE_ADMIN user role privileges. Only users in the ADMINISTRATOR role can create OAuth 2.0 clients that have the ADMINISTRATOR role.

To interact with OAuth 2.0 APIs, you must be authenticated with the Turbonomic instance. For more information, see Authenticating with the API.

Creating and authenticating an OAuth 2.0 client

The following steps describe the process to create an OAuth 2.0 client and exchange the client credentials for an access token that you use to authenticate calls to Turbonomic APIs. You can also easily try these calls by using the Turbonomic swagger UI. For more information, see Turbonomic REST API Swagger Documentation.

Currently, Turbonomic supports only the OAuth 2.0 client credentials flow.

Create an OAuth 2.0 client.

Construct a POST https://[INSTANCE_URL]/api/v3/authorization/oauth2/clients request with the following payload, where [INSTANCE_URL] is the URL for your Turbonomic instance.
```
{
  "clientName": "my-client",
  "grantTypes": [
    "client_credentials"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:SITE_ADMIN"
  ],
  "tokenSettings": {
    "accessToken": {
      "ttlSeconds": 700
    }
  }
}
```
Specify the following values:
- clientName: Choose a name for your client.
- scopes: Specify exactly one value in the format role:<ROLE>, where <ROLE> is a Turbonomic user role, for example, role:SITE_ADMIN. Any access tokens that you generate for this client must have the same role. The following roles are available:
  - role:ADMINISTRATOR (only if the logged-in user is an ADMINISTRATOR)
  - role:SITE_ADMIN
  - role:AUTOMATOR
  - role:DEPLOYER
  - role:ADVISOR
  - role:OBSERVER
  - role:OPERATIONAL_OBSERVER
  - role:SHARED_ADVISOR
  - role:SHARED_OBSERVER
  - role:REPORT_EDITOR
  For more information about the permissions that these roles grant, see step 5 of Managing user accounts.
The following parameters are optional:
- clientAuthenticationMethods: This value determines whether the client credentials must be supplied in a basic auth header or in the request body when you request an access token for the client. Specify one or both of the following values:
  - client_secret_basic: the default, which requires the credentials to be supplied as part of a basic auth header
  - client_secret_post: the credentials must be supplied in the request body
- tokenSettings.accessToken.ttlSeconds: This value determines the lifespan of access tokens that the OAuth 2.0 authorization server issues. The default value is 600 seconds.
The response is similar to the following example.
```
{
  "clientName": "my-client",
  "clientId": "7613c2ca-cee1-4445-aa99-55c9312852c8",
  "grantTypes": [
    "client_secret"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:SITE_ADMIN"
  ],
  "audience": [
    "turbonomic"
  ],
  "createdAt": 1702042743,
  "tokenSettings": {
    "accessToken": {
      "ttlseconds": 700
    }
  },
  "clientSecret": "b6YzO0zaRU6EPYNMZPBIbYhmWL1Jb6PTAKyBUTw7VIG8FQDh2ryCaMspoyh2cKzM"
}
```
Copy the values for clientId and clientSecret. The clientSecret cannot be recovered if lost.
Exchange the client credentials for an access token.

To exchange your credentials for an access token, you must call the https://[INSTANCE_URL]:443/oauth2/token endpoint. This endpoint is a standard 0Auth 2.0 API and you can use any library that supports OAuth 2.0 to facilitate this transaction programmatically. For more information, see the documentation for your chosen library. The following substeps describe how to compose the call manually.
- If your client uses client_secret_basic as the authentication method, you must include the client credentials in a basic auth header, not in the request body. Construct a POST https://[INSTANCE_URL]:443/oauth2/token request with the following payload, where [INSTANCE_URL] is the URL for your Turbonomic instance.
```
grant_type=client_credentials&scope=role:SITE_ADMIN
```
  Specify the following values:
  - grant_type: Specify client_credentials.
  - scope: This value must match the configured scope for your client, for example, role:SITE_ADMIN.
- If your client uses client_secret_post as the authentication method, you must include the client credentials in the request body. Construct a POST https://[INSTANCE_URL]:443/oauth2/token request with the following payload, where [INSTANCE_URL] is the URL for your Turbonomic instance.
```
grant_type=client_credentials&scope=role:SITE_ADMIN&client_id=7613c2ca-cee1-4445-aa99-55c9312852c8&client_secret=b6YzO0zaRU6EPYNMZPBIbYhmWL1Jb6PTAKyBUTw7VIG8FQDh2ryCaMspoyh2cKzM
```
  Specify the following values:
  - client_id: Specify the client ID for your OAuth 2.0 client that you copied from the API response when you created the client.
  - client_secret: Specify the client secret for your OAuth 2.0 client that you copied from the API response when you created the client.
  - grant_type: Specify client_credentials.
  - scope: This value must match the configured scope for your client, for example, role:SITE_ADMIN.
The response is similar to the following example.
```
{
  "access_token": "GiLUVmth6LH6nSocLYtd4DvUxIy4L9zntTbZX7NQVOlq31-kle_ZEDkcJiiZkx0-KtKjJAR78sQ1qR6LJCIqQ_HSO_i0KBfHzzZgc-0x8gBy8FpDnWLdUENuRnlBt2_t",
  "scope": "role:SITE_ADMIN",
  "token_type": "Bearer",
  "expires_in": 599
}
```
Copy the value of the access_token to authenticate calls to Turbonomic APIs.
Use the access token to access Turbonomic APIs.
Include the authorization token in a bearer authorization header of a request to a Turbonomic API that is available to your role, such as the GET licenses API. For example, you can set the token value as a variable in your terminal:
```
token=GiLUVmth6LH6nSocLYtd4DvUxIy4L9zntTbZX7NQVOlq31-kle_ZEDkcJiiZkx0-KtKjJAR78sQ1qR6LJCIqQ_HSO_i0KBfHzzZgc-0x8gBy8FpDnWLdUENuRnlBt2_t
```
When you make a request to a Turbonomic API, include the variable in a bearer authorization header, as shown in the following curl example:
```
curl -H "Authorization: Bearer ${token}" https://$host:443/vmturbo/rest/licenses
```

Listing or deleting OAuth 2.0 clients

After you create OAuth 2.0 clients for your Turbonomic instance, you can list or delete the clients by making API calls.

List the OAuth 2.0 clients in your Turbonomic instance.

Make a GET https://[INSTANCE_URL]/api/v3/authorization/oauth2/clients request, where [INSTANCE_URL] is the URL for your Turbonomic instance. The response is similar to the following example.

{
  "clientName": "my-client",
  "clientId": "7613c2ca-cee1-4445-aa99-55c9312852c8",
  "grantTypes": [
    "client_secret"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:SITE_ADMIN"
  ],
  "audience": [
    "turbonomic"
  ],
  "createdAt": 1702042743,
  "tokenSettings": {
    "accessToken": {
      "ttlSeconds": 700
    }
}

The clientSecret values are not returned.

Delete an OAuth2 client from your Turbonomic instance.

Make a DELETE https://[INSTANCE_URL]/api/v3/authorization/oauth2/clients/[clientId] request, where [clientId] is the clientId value for the client that you want to delete and [INSTANCE_URL] is the URL for your Turbonomic instance.

A successful DELETE request does not return a response body. You can confirm that the request succeeded by running the same request again. The response to that request is 404 NOT_FOUND because the target client was already deleted.

Any tokens that were issued for the deleted client are immediately invalidated and can no longer be used to access Turbonomic APIs.

Troubleshooting OAuth 2.0 clients

If you cannot access the authorization/oauth2/clients/ API, make sure that you satisfy all the prerequisites and that your session is not expired.

If the token you get from the OAuth 2.0 API is not working, check the following values:

Make sure that the token is not expired. The default lifespan of a token is 10 minutes. If the token expires, you must retrieve a new one.
Ensure that you specified a scope in your request to the OAuth2 API. If you don't include a scope in your request, the token is not valid.