This page describes how to create and use the API Clients identity type to provide secure access to the Controller through AppDynamics Controller REST API calls. These calls use Open Authorization (OAuth) token-based authentication.

Open Authorization (OAuth) Mechanisms

OAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications. See https://oauth.net/

It acts as the intermediary on your behalf by providing third-party applications with an access token that authorizes sharing specific account information. Using the OAuth protocol with AppDynamics Controller REST APIs is the best way to securely grant access to your Controller information.

The OAuth authentication process authenticates a request token and uses it to obtain an encrypted access token from your Controller. Once the access token is available, you can use it to make requests to your Controller until the token expires or is revoked.

The tokens are based on JSON Web Tokens (JWT) authentication format, which is the industry standard RFC 7519 method for representing claims securely between two parties. 

Accessing Authentication Provider Settings

Users with the Account Owner role or the Administer users, groups, roles ... permission can view API Clients settings in the Settings > Administration page.

Creating API Clients

You can create new API Client identity types that can be used to generate OAuth tokens.

  1. Log in to the Controller UI as an Account Owner or other roles with the Administer users, groups, roles ... permission.
  2. Click  > Administration.
  3. Click the API Clients tab to view the list of existing clients.
  4. Click + Create.
  5. Enter the Client Name and Description.

  6. Click Generate Secret to populate the Client Secret. 
    This will generate a UUID as the secret of the API Client. 

    This API Client secret acts as a password. It does not generate the authentication token.

  7. Set the Default API-generated Token Expiration. This expiration only applies to authentication tokens generated through the /controller/api/oauth/access_token REST API, not to Temporary Access Tokens generated from the UI. See Using the Access Token.

    Every API-generated access token has an expiration. Although the default is five minutes, you can set it to any second, minute, or hour limit. The Default API-generated Token has a shorter expiration than the authentication token generated through the Administration UI.

  8. Add the Roles you would like to associate with this API Client. You can add or remove roles at any time. See Create and Manage Custom Roles.

    The REST APIs will use the identity which the access token represents to pull up RBAC permissions and check those permissions at the underlying API level.

  9. Click Save at the top right.

Using the Access Token

You can generate and use the access token for each API access call into your Controller by generating the token through one of the following means:

  • Administration UI: These tokens usually have a longer expiration. The account administrator can generate and distribute to parties/teams who need Controller access, but do not want to refresh such tokens frequently. 
  • API: These tokens usually have a relatively short expiration. The program generates and refreshes regularly before expiration. These tokens are visible from the UI and are not individually tracked and managed.

Generate the Token Through the UI

When you are ready to use the access token, you will generate it through the Administration UI:

  1. Click Generate Temporary Access Token when you are ready to use the access token.

    Remember that temporary token expirations are usually longer than the Default API-generated Token Expiration.

  2. Copy and paste the access token from the Temporary Access Token field into the TOKEN portion of your curl command. For example:

    curl -H "Authorization:Bearer <AUTH_TOKEN>" "http://master-onprem-controller.e2e.appd-test.com:8090/controller/rest/applications"
  3. Check that your call is successful. It should look like this:
     

Generate the Token Through an API

You can use REST APIs to generate a short-lived access token. This default, on-demand token is not tracked on the UI. 

For example, use POST with the OAuth API endpoint /controller/api/oauth/access_token. You will need the API Client name, the Client Secret, and to specify grant_type=client_credentials to generate the token. The Content-Type header is not restricted to application/x-www-form-urlencoded, but is correct in the given example because of the data being passed in the request body. Note also that the default Content-Type being returned from this example call will be application/vnd.appd.cntrl+json;v=1.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "https://<controller address>/controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=<apiClientName>@<accountName>&client_secret=10d5-573e-4a75-8396-afa006fd8f19'

Be aware that:

  • For Controllers < 4.5.9, an authentication header is required in the request as shown below:
curl -X POST -H "Content-Type: application/vnd.appd.cntrl+protobuf;v=1" -u 'TestApiClient@customer:face10d5-573e-4a75-8396-afa006fd8f19' "https://<controller address>/controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=TestApiClient@customer&client_secret=face10d5-573e-4a75-8396-afa006fd8f19'

{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}
CODE
  • The token generation API requires an authentication header with username and password and the oAuth request body to successfully request a token.

Use the generated token to list all applications. For example:

curl -H "Authorization:Bearer <AUTH_TOKEN>" https://master-controller.e2e.appd.com/controller/rest/applications
  • In the case of success: all applications are returned.
  • In the case of failure: HTTP 401 Unauthorized "Failed to authenticate: invalid access token." is returned.

Managing Access Tokens 

Access tokens are based on JWT, therefore decoding them will not show sensitive information. 

However, if you believe that your token has become compromised, you can revoke it by clicking Revoke or by deleting the API Client to invalidate the token. Calls using revoked access tokens fail to authenticate with a 401 Unauthorized error HTTP status code. You can click Regenerate to refresh a token.

Regenerated tokens do not disable older tokens. The older tokens will remain active until they expire.

When you regenerate a token, you can set the Temporary Token Expiration.

The default value is 1 day and the maximum limit is 30 days.

There is no way to retrieve previous or currently valid tokens. Therefore, only the current token can be revoked.

Also, API-generated tokens that have Default API-generated Token Expiration, cannot be viewed nor revoked through the UI or REST API.