API クライアント

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

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

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

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

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

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

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

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

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

アクセストークンの生成

次のいずれかを使用してトークンを生成することによって、コントローラへの各 API アクセスコールのアクセストークンを生成できます。

  • 管理 UI：通常、これらのトークンは有効期間が長くなります。管理 UI はアカウント管理者によって生成され、コントローラにアクセスする必要があるが、トークンを頻繁に生成しない関係者/チームに配布することができます。
  • OAuth API：通常、これらのトークンは有効期限が比較的短くなっています。通常は、期限切れになる前にプログラムによって定期的に生成および更新されます。これらのトークンは UI から表示され、個別に追跡および管理されるわけではありません。

管理 UI を介したトークンの生成

[Administration > API Clients] に移動し、[Generate Temporary Access Token] をクリックして、アクセストークンを生成できます。

OAuth API を介したトークンの生成

REST API を使用して、存続期間の短いアクセストークンを生成できます。このデフォルトのオンデマンドトークンは UI で追跡されません。

注:  

「OAuth 2.0 クライアントログイン情報の付与」

を使用して、Splunk AppDynamics OAuth API でアクセストークンを要求します。

たとえば、OAuth API エンドポイント /controller/api/oauth/access_token で POST を使用します。トークンを生成するには、API クライアント名、クライアントシークレット、および grant_type=client_credentials の指定が必要です。Content-Type ヘッダーが application/x-www-form-urlencoded である必要があります。

このコール例から返されるデフォルトの Content-Type は、application/vnd.appd.cntrl+json;v=1 になります。

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

呼び出しと応答の例

呼び出しの例
CODE 
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'
応答の例
JSON 
{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}

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

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

  1. アクセストークンをコピーして、 コマンドの に貼り付けます。この例では、生成されたトークンと エンドポイントを使用して、すべてのアプリケーションを一覧表示します。
    CODE 
    curl --location --request GET 'https://<controller address>/controller/rest/applications' \
--header 'Authorization: Bearer eyJraWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImp0aSI6IjlybDVyU0tWZDZwN3hKM3A5NWRfemciLCJzdWIiOiJwb3N0bWFuIiwiaWRUeXBlIjoiQVBJX0NMSUVOVCIsImlkIjoiNjgzZmZmODMtNTY5YS00OGRkLWE4MjMtYWE0ODA4NGYzN2UxIiwiYWNjdElkIjoiYTllMjEzNjQtZWE3Ny00NzllLTk3ZmYtZWJiZDI3NjYzZmJlIiwidG50SWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhY2N0TmFtZSI6ImFwcGR5bmFtaWNzIiwidGVuYW50TmFtZSI6ImFwcGR5bmFtaWNzIiwiZm1tVG50SWQiOm51bGwsImFjY3RQZXJtIjpbXSwicm9sZUlkcyI6W10sImlhdCI6MTY1OTQ4Njk1NiwibmJmIjoxNjU5NDg2ODM2LCJleHAiOjE2NTk1NzMzNTYsInRva2VuVHlwZSI6IkFDQ0VTUyJ9.sKG2hkFofWK9avqr7RlzVEM_APiCUiXRXmA7qm12Wr4'
  2. コールが成功したことを確認します。次のようになり、すべてのアプリケーションが返されます。
    CODE 
    <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." が返されます。

アクセストークンの管理

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

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

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

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

警告:

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

また、API 生成トークンには、デフォルトの API 生成トークンの有効期限があるため、UI または 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.