API クライアント

このページでは、API クライアントのアイデンティティタイプを作成および使用し、Splunk AppDynamics コントローラの REST API コールを介してコントローラへの安全なアクセスを提供する方法について説明します。これらのコールは、Open Authorization（OAuth）トークンベースの認証を使用します。

次の手順に従って、API クライアントを作成し、Splunk AppDynamics REST API を呼び出します。

  1. API クライアントを作成するためのアクセス許可があることを確認します。
  2. API クライアントを作成します。

  3. アクセストークンを生成します。

  4. アクセストークンを使用して REST コールを行います。

  5. アクセストークンを管理します。

Access Permissions for Creating API Clients

To create API clients, you are required to be assigned to the role of an Account Owner or an Administer. You can view the API Client settings in the Settings > Administration page of the Controller.

Create 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 Roles and Permissions.
    注: 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.

Generate Access Tokens

You can generate an access token for each API access call into your Controller 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 generate tokens frequently.
  • OAuth 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 Administration UI

You can generate the access token by navigating to Administration > API Clients and clicking Generate Temporary Access Token:

Generate the Token Through the OAuth API

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

注: Use the

OAuth 2.0 Client Credentials Grant

to request access tokens with the Splunk AppDynamics OAuth API.

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 must be application/x-www-form-urlencoded.

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=<clientSecret>'

Example Call and Response

Example Call
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -u 'testclient:face10d5-573e-4a75-8396-afa006fd8f19' \
"https://<controller address>/controller/api/oauth/access_token" \
-d 'grant_type=client_credentials&client_id=testclient@<accountName>&client_secret=face10d5-573e-4a75-8396-afa006fd8f19'
Example Response
{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}

アクセストークンを使用して REST コールを行う

Authorization ヘッダー付きのアクセストークンを使用して、AppDynamics REST API を呼び出すことができます。アクセストークンは、管理 UI または OAuth API から取得できます。

  1. アクセストークンをコピーして、 コマンドの に貼り付けます。この例では、生成されたトークンと エンドポイントを使用して、すべてのアプリケーションを一覧表示します。 
    curl --location --request GET 'https://<controller address>/controller/rest/applications' \
--header 'Authorization: Bearer eyJraWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImp0aSI6IjlybDVyU0tWZDZwN3hKM3A5NWRfemciLCJzdWIiOiJwb3N0bWFuIiwiaWRUeXBlIjoiQVBJX0NMSUVOVCIsImlkIjoiNjgzZmZmODMtNTY5YS00OGRkLWE4MjMtYWE0ODA4NGYzN2UxIiwiYWNjdElkIjoiYTllMjEzNjQtZWE3Ny00NzllLTk3ZmYtZWJiZDI3NjYzZmJlIiwidG50SWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhY2N0TmFtZSI6ImFwcGR5bmFtaWNzIiwidGVuYW50TmFtZSI6ImFwcGR5bmFtaWNzIiwiZm1tVG50SWQiOm51bGwsImFjY3RQZXJtIjpbXSwicm9sZUlkcyI6W10sImlhdCI6MTY1OTQ4Njk1NiwibmJmIjoxNjU5NDg2ODM2LCJleHAiOjE2NTk1NzMzNTYsInRva2VuVHlwZSI6IkFDQ0VTUyJ9.sKG2hkFofWK9avqr7RlzVEM_APiCUiXRXmA7qm12Wr4'
  2. コールが成功したことを確認します。次のようになり、すべてのアプリケーションが返されます。 
    <applications>
<application>
<id>25</id>
<name>My Test App</name>
<description></description>
<accountGuid>a9e21364-ea77-479e-97ff-xxxxxxxxxxxxx</accountGuid>
</application>
<application>
<id>54</id>
<name>E-Commerce App</name>
<accountGuid>a9e21364-ea77-479e-97ff-zzzzzzzzzzzzz</accountGuid>
</application>
</applications>
  3. 失敗した場合：HTTP 401 Unauthorized "Failed to authenticate: invalid access token." が返されます。

Manage 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 go to Administration > API Clients and 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.

警告:

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.

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 Splunk 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.