API クライアント

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

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

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

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

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

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

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

API クライアントの作成

OAuth トークンを生成するために使用できる新しい API クライアント ID タイプを作成できます。

  1. または 権限を持つ他のロールとしてコントローラ UI にログインします。
  2. [管理(Administration)] をクリックします。
  3. [API Clients] タブをクリックすると、既存のクライアントのリストが表示されます。
  4. [+作成(+ Create)] をクリックします。
  5. クライアント名と説明を入力します。
  6. [] をクリックし、クライアントの秘密を入力します。これにより、API クライアントの秘密として UUID が生成されます。
    注: この API クライアントの秘密はパスワードとして機能します。認証トークンは生成されません。
  7. デフォルトの API 生成トークンの有効期限を設定します。この有効期限は、UI から生成される一時アクセストークンではなく、'/controller/api/oauth/access_token' REST API を介して生成された認証トークンにのみ適用されます。「アクセストークンの使用」を参照してください。
    注: API で生成されたすべてのアクセストークンの有効期限が切れています。デフォルトは 5 分ですが、任意の秒、分、または時間の制限に設定できます。デフォルトの API 生成トークンの有効期限は、管理 UI で生成された認証トークンよりも短くなります。
  8. この API クライアントに関連付けるロールを追加します。ロールはいつでも追加または削除できます。「対象カスタムロールの管理Splunk AppDynamics」を参照してください。
    注: REST API は、アクセストークンが表す ID を使用して RBAC 権限を取得し、基盤となる API レベルでその権限を確認します。
  9. ページの右上にある [保存(Save)] をクリックします。

アクセストークンの生成

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

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

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

[AdministrationAPI 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-Typeapplication/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>'

呼び出しと応答の例

呼び出しの例
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'
応答の例
{
"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." が返されます。

アクセストークンの管理

アクセストークンは 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 方式です。