API クライアント

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

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

API クライアントを作成するためのアクセス許可があることを確認します。
API クライアントを作成します。
アクセストークンを生成します。
アクセストークンを使用して REST コールを行います。
アクセストークンを管理します。

API クライアントを作成するためのアクセス許可

API クライアントを作成するには、Account Owner または Administer のロールに割り当てられている必要があります。コントローラの Settings > Administration ページで API クライアントの設定を表示できます。

Create API Clients

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

Log in to the Controller UI as an Account Owner or other roles with the Administer users, groups, roles ... permission.
Click > Administration.
Click the API Clients tab to view the list of existing clients.
Click + Create.
Enter the Client Name and Description.
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.
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.
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.
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 から取得できます。

アクセストークンをコピーして、コマンドのに貼り付けます。この例では、生成されたトークンとエンドポイントを使用して、すべてのアプリケーションを一覧表示します。

curl --location --request GET 'https://<controller address>/controller/rest/applications' \
--header 'Authorization: Bearer eyJraWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImp0aSI6IjlybDVyU0tWZDZwN3hKM3A5NWRfemciLCJzdWIiOiJwb3N0bWFuIiwiaWRUeXBlIjoiQVBJX0NMSUVOVCIsImlkIjoiNjgzZmZmODMtNTY5YS00OGRkLWE4MjMtYWE0ODA4NGYzN2UxIiwiYWNjdElkIjoiYTllMjEzNjQtZWE3Ny00NzllLTk3ZmYtZWJiZDI3NjYzZmJlIiwidG50SWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhY2N0TmFtZSI6ImFwcGR5bmFtaWNzIiwidGVuYW50TmFtZSI6ImFwcGR5bmFtaWNzIiwiZm1tVG50SWQiOm51bGwsImFjY3RQZXJtIjpbXSwicm9sZUlkcyI6W10sImlhdCI6MTY1OTQ4Njk1NiwibmJmIjoxNjU5NDg2ODM2LCJleHAiOjE2NTk1NzMzNTYsInRva2VuVHlwZSI6IkFDQ0VTUyJ9.sKG2hkFofWK9avqr7RlzVEM_APiCUiXRXmA7qm12Wr4'

コールが成功したことを確認します。次のようになり、すべてのアプリケーションが返されます。

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

失敗した場合：HTTP 401 Unauthorized "Failed to authenticate: invalid access token." が返されます。

アクセストークンの管理

アクセストークンは JWT に基づいているため、復号化しても機密情報は表示されません。

ただし、トークンが侵害されたと思われる場合は、[Revoke] をクリックして取り消すか、API クライアントを削除してトークンを無効化することができます。失効したアクセストークンを使用したコールは、401 未認証エラー HTTP ステータスコードにより認証に失敗します。Administration > API Clients の順に移動し、[Regenerate] をクリックしてトークンを更新できます。

注: 再生成されたトークンでは、古いトークンは無効になりません。古いトークンは、期限切れになるまでアクティブのままになります。

トークンを再生成すると、一時的なトークンの有効期限を設定できます。

警告:

過去または現在有効なトークンを取得する方法はありません。そのため、現在のトークンのみを失効させることができます。

また、API 生成トークンには、デフォルトの API 生成トークンの有効期限があるため、UI または REST API を使用して表示または失効することはできません。

Open Authorization（OAuth）メカニズム

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

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

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

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