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）メカニズム

OAuth は、web、モバイル、およびデスクトップ アプリケーションによるシンプルで標準的な方法でのセキュアな許可を可能にするオープンプロトコルです。https://oauth.net/ を参照してください。

OAuth は、特定のアカウント情報の共有を許可するアクセストークンを使用してサードパーティ製のアプリケーションを提供し、ユーザの代わりに仲介として機能します。コントローラ情報Splunk AppDynamicsへのアクセス権を安全に付与する最善の方法は、 コントローラ REST API を使用した OAuth プロトコルの使用です。

OAuth 認証プロセスによって要求トークンを認証し、それを使用してコントローラから暗号化されたアクセストークンを取得します。アクセストークンが使用可能になると、トークンが期限切れになるか、または失効するまで、そのトークンを使用してコントローラに要求を行うことができます。

トークンは、JSON Web Tokens（JWT）認証形式に基づいています。これは、2 者間でクレームを安全に示すための業界標準 RFC 7519 方式です。