OAuth Clients

An OAuth client is an application with secure, delegated access to your resources. It makes protected-resource requests on your behalf and with your authorization. For example, you can register an OAuth client that performs Continuous Integration and Continuous Deployment. Additionally, TIBCO Cloud domains register their own OAuth client and ask your consent when redirecting to a URL not controlled by TIBCO Cloud.

Note: An OAuth client that is not used for a year, is automatically deleted.

Client-Credential Flow
Refresh Tokens
Registering an OAuth Client
Token Endpoints in Different Regions
Error Response

Client-Credential Flow

A Introduction to Service Accounts user can use a client's credentials to obtain an access token. To see the list of available token endpoints, refer to the Token Endpoints in Different Regions section in this topic.

For example, to request an access token for TCI in the US region by using a client configured to use the header authentication method:

  curl -v https://account.cloud.tibco.com/idm/v1/oauth2/token \

  --header "application/x-www-form-urlencoded" \

  --data "grant_type=client_credentials&scope=TCI" \

  --user "${client_id}:${client_secret}"

Refresh Tokens

The client-credential flow is limited to service account users who can use a client's credentials through API calls to get an access token. Other users can get a new access token if they have a refresh token. Currently, you can generate the initial refresh token only through the web UI.

An OAuth client uses a refresh token to obtain an access token and a new refresh token. To see the list of available token endpoints, refer to the OAuth Clients section in this topic.

For example, in the US region:

  curl -v https://account.cloud.tibco.com/idm/v1/oauth2/token \

  --header "application/x-www-form-urlencoded" \

  --data "refresh_token=${refresh_token}&grant_type=refresh_token" \

  --user "${client_id}:${client_secret}"

Sample response:

{
  "access_token" : "CIC~qzNjDIKRsopj_SAMPLE_SAMPLE",

  "expires_in" : 28800,

  "refresh_token" : "rt.K7KAL_QxtYnY_SAMPLE_SAMPLE",

  "refresh_token_expires_in": 7776000,

  "token_type" : "Bearer"
}

Here, the client is authenticated by using basic authentication and passed a refresh token. The response contains a new access token and a new refresh token. It also shows that the access token has a validity of 28,800 seconds, that is, 8 hours.

The client can use the refresh token to obtain a new access token before or after the old access token expires. After such a renewal, both the refresh token and access token are no longer valid.

Note: An access token can be used multiple times and expires after a few hours; while a refresh token is valid for a much longer period (ninety days or as indicated by the refresh_token_expires_in member in the response) but can be used only once.

New refresh tokens might not reach the client (you) due to network glitches. Before securing new refresh tokens against reuse, TIBCO Cloud needs to know that you have obtained new tokens. When you use an access token for the first time, it serves as a confirmation receipt.

After you use the access token, if you use the same refresh token again, it is considered as a security breach. This results in revoking the refresh token; and the access token that was previously valid and issued by this refresh token is also revoked. In such a scenario, you have to generate a new refresh token and a new access token.

Note: A refresh token is valid for up to ninety days. It expires unless it is used to generate a new refresh token and an access token in ninety days.

The two authentication methods for the client are Header or Body, depending on whether the client's credentials are sent as an Authorization Basic header or sent in the body by using POST. They are described in section 2.3.1 of RFC 6749. For more information, see Section 2.3.1 of RFC 6749.

Registering an OAuth Client

To register an OAuth client, perform the following steps:

Procedure

Go to the Settings tab, and select OAuth access > OAuth clients from the navigation pane.
Click the Register OAuth client link.
Enter the OAuth client name, the authentication method to token endpoint, and the applicable domains and then click Register. To know which token endpoint to use, see OAuth Clients.

The header authentication sends the client's credentials in the authorization header. The body authentication sends them as payload data in the body instead.

After you register the OAuth client, the client ID, client secret, and the scope is displayed. Clicking the Copy to clipboard button copies all client details, including the secret, as a JSON. The client secret is displayed only this one time. So, copy it and store it securely because the client acts on your behalf. Use them when renewing tokens.

Token Endpoints in Different Regions

Depending on where your subscription has been provisioned, you can use the following token endpoints:

Region	Token Endpoint
AWS US	https://account.cloud.tibco.com/idm/v1/oauth2/token
AWS US East	https://us-east.account.cloud.tibco.com/idm/v1/oauth2/token
AWS Europe	https://eu.account.cloud.tibco.com/idm/v1/oauth2/token
AWS Australia	https://au.account.cloud.tibco.com/idm/v1/oauth2/token
Azure	https://account.us.azure.cloud.tibco.com/idm/v1/oauth2/token

Error Response

OAuth endpoints always respond in a JSON format (as per https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1). If the response is in any other format, it indicates that you are calling the wrong path.

The error response consists of error and error description and depends on which endpoint you have called. It conforms to OAuth RFCs.

Here is an example of the format of the error response in JSON:

{
  "error" : "invalid_grant",
  "error_description" : "invalid or unknown client id"
}

Introduction to Service Accounts

Did you find this helpful?