Authorization requests

Prerequisites

Turbonomic version 8.12.4 or later
t8c-operator version 42.57 or later
ADMINISTRATOR or SITE_ADMIN role

Note: ADMINISTRATOR role is required to create an OAuth 2.0 client with the ADMINISTRATOR role (that is, a client with the same privileges as administrator. The SITE_ADMIN role is not sufficient in this case.

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

Authenticating calls to Turbonomic APIs

To authenticate calls to Turbonomic APIs, create an OAuth 2.0 client and then exchange the client credentials for an access token.

You can also 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.

Creating an OAuth 2.0 client

Construct a POST https://{your_instance_address}/api/v3/authorization/oauth2/clients request with the following payload.

{
  "clientName": "<client_name>",
  "grantTypes": [
    "client_credentials"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:<ROLE_NAME>"
  ],
  "tokenSettings": {
    "accessToken": {
      "ttlSeconds": 700
    }
  }
}

Specify the following values.
- clientName: Choose a name for your client.
- role: Specify a Turbonomic user role. Use uppercase letters only. Any access tokens that you generate for this client must have the same role. The following roles are available:
  - ADMINISTRATOR (only if the logged-in user is an administrator)
    
    Users with this role can use all Turbonomic features and modify settings to configure the Turbonomic installation. For Turbonomic SaaS instances, this role is limited to the Turbonomic representative that manages the instances.
  - SITE_ADMIN
    
    Users with this role can use all Turbonomic features and modify site-specific settings to configure the Turbonomic installation. Users can also administer Groups, Policies, Workflows, Templates, Billing and costs, and Target configuration, but not Email, Licenses, Updates, and Maintenance. Users can create other user accounts, except accounts with the Administrator role.
  - AUTOMATOR
    
    Users with this role can use all Turbonomic features (including Plan, Park, and Place), but cannot configure the Turbonomic installation or create policies. Automator is the minimum role that is required to execute any actions.
  - DEPLOYER
    
    Users with this role can view all Turbonomic charts and data, use Place to reserve workloads, and create placement policies and templates. However, users cannot run plans or execute any actions.
  - PARKER
    
    Users with this role can park workloads manually or automatically (using parking schedules), manage parking schedules, and view all Turbonomic charts and data. However, users cannot create policies and templates, place workloads, run plans, or execute any actions.
  - PARKER_AUTOMATOR
    
    Users with this role can park workloads manually or automatically (using parking schedules) and view all Turbonomic charts and data. However, users cannot manage parking schedules, create policies and templates, place workloads, run plans, or execute any actions.
  - ADVISOR
    
    Users with this role can view all Turbonomic charts and data, and run plans. However, users cannot use Place to reserve workloads, create policies, or execute any actions.
  - OBSERVER
    
    Users with this role can view the environment, including the Home Page and Dashboards. Users can also use Search to set a scope to the session. For scope, only VM groups and Resource Groups are supported. Users cannot execute any actions.
  - OPERATIONAL_OBSERVER
    
    Users with this role can view the environment, including the Home Page, Dashboards, Groups, and Policies. Users can also use Search to set a scope to the session. Users cannot execute any actions.
  - SHARED_ADVISOR
    
    Users with this role are scoped users. They can view the Home Page and Dashboards, but see only VMs and Applications. Users cannot execute any actions.
  - SHARED_OBSERVER
    
    Users with this role are scoped users. They can view the Home Page, custom dashboards, and application maps, but can see only VMs and Applications. They cannot view Executive Dashboards or execute any actions. Shared Observer is the most restricted user role.
  - REPORT_EDITOR
    
    Users with this role can create, edit, and delete reports. Due to limits to the reporting license, only one user per instance is allowed to have this role (by default, the local administrator user). To assign this role to another user, you must first remove it from the current user. Be sure that the new user is not a scoped user.
(Optional) Specify the following parameters:
- 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.

Execute the request.

The response is similar to the following example.

{
  "clientName": "my-client",
  "clientId": "My_ID",
  "grantTypes": [
    "client_secret"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:SITE_ADMIN"
  ],
  "audience": [
    "turbonomic"
  ],
  "createdAt": 1702042743,
  "tokenSettings": {
    "accessToken": {
      "ttlseconds": 700
    }
  },
  "clientSecret": "{secret}"
}

Copy the clientId and clientSecret values.

Important: The clientSecret cannot be recovered if lost.

Exchanging the client credentials for an access token

Construct a request to the /oauth2/token endpoint. This endpoint is a standard OAuth 2.0 API. 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 steps describe how to construct the call manually.
- If your client uses client_secret_basic as the authentication method, include the client credentials in a basic auth header, not in the request body.
  1. Construct a POST https://{your_instance_address}:443/oauth2/token request with the following payload.
```
grant_type=client_credentials&scope=role:<ROLE_NAME>
```
  2. For the role parameter, specify the role that you configured in a previous step.
- If your client uses client_secret_post as the authentication method, include the client credentials in the request body.
  1. Construct a POST https://{your_instance_address}:443/oauth2/token request.
```
grant_type=client_credentials&scope=role:<ROLE_NAME>&client_id=<client_ID>&client_secret=client_secret>
```
  2. Specify the following values:
    - scope: Specify the role that you configured in a previous step.
    - client_id: Specify the client ID that you copied in a previous step.
    - client_secret: Specify the client secret that you copied in a previous step.

Execute the request.

The response is similar to the following example.

{
  "access_token": "{token}",
  "scope": "role:SITE_ADMIN",
  "token_type": "Bearer",
  "expires_in": 599
}

Copy the access_token value.
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={token}
```
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 OAuth 2.0 clients

List the OAuth 2.0 clients in your Turbonomic instance.

Example: GET https://10.10.10.10/api/v3/authorization/oauth2/clients

Response: returns a list of OAuth2ClientApiDTOs for your instance, similar to the following example.

{
  "clientName": "my-client",
  "clientId": "My_ID",
  "grantTypes": [
    "client_secret"
  ],
  "clientAuthenticationMethods": [
    "client_secret_post"
  ],
  "scopes": [
    "role:SITE_ADMIN"
  ],
  "audience": [
    "turbonomic"
  ],
  "createdAt": 1702042743,
  "tokenSettings": {
    "accessToken": {
      "ttlSeconds": 700
    }
}

Deleting an OAuth 2.0 client

Delete an OAuth 2.0 client from your Turbonomic instance.

Example: DELETE https://10.10.10.10/api/v3/authorization/oauth2/clients/[clientId]

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 the prerequisites described in this topic.

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. If you don't include a scope in your request, the token is not valid.