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

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

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

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

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

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

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

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

API クライアントの作成

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

  1. Account Owner または Administer users, groups, roles ...  権限を持つ他のロールとしてコントローラ UI にログインします。
  2. [gearicon.png]> [Administration] をクリックします。
  3. [API Clients] タブをクリックすると、既存のクライアントのリストが表示されます。
  4. [+ Create] をクリックします。
  5. クライアント名と説明を入力します。

  6. [Generate Secret] をクリックし、クライアントの秘密を入力します。
    これにより、API クライアントの秘密として UUID が生成されます。 

    この API クライアントの秘密はパスワードとして機能します。認証トークンは生成されません。

  7. デフォルトの API 生成トークンの有効期限を設定します。この有効期限は、UI から生成される一時アクセストークンではなく、/controller/api/oauth/access_token REST API を介して生成された認証トークンにのみ適用されます。「アクセストークンの使用」を参照してください。

    API で生成されたすべてのアクセストークンの有効期限が切れています。デフォルトは 5 分ですが、任意の秒、分、または時間の制限に設定できます。デフォルトの API 生成トークンの有効期限は、管理 UI で生成された認証トークンよりも短くなります。

  8. この API クライアントに関連付ける Roles を追加します。ロールはいつでも追加または削除できます。「カスタムロールの管理」を参照してください。

    REST API は、アクセストークンが表す ID を使用して RBAC 権限を取得し、基盤となる API レベルでその権限を確認します。

  9. 右上の [Save] をクリックします。

アクセストークンの生成

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

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

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

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


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

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

OAuth 2.0 Client Credentials Grant を使用して、Cisco 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. になることにも注意してください。

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

呼び出しと応答の例

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'
BASH 
{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}
CODE

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

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

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

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

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

    <applications>
  <application>
    <id>25</id>
    <name>My Test App</name>
    <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>
    XML


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

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

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