API クライアント

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

Open Authorization（OAuth）メカニズム

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

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

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

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

認証プロバイダ設定へのアクセス

Account Owner ロールまたは Administer users, groups, roles ... 権限を持つユーザは、[Settings] > [Administration] ページで API クライアント設定を表示できます。

API クライアントの作成

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

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

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

API で生成されたすべてのアクセストークンの有効期限が切れています。デフォルトは 5 分ですが、任意の秒、分、または時間の制限に設定できます。デフォルトの API 生成トークンの有効期限は、管理 UI で生成された認証トークンよりも短くなります。
この API クライアントに関連付ける Roles を追加します。ロールはいつでも追加または削除できます。「カスタムロールの作成と管理」を参照してください。

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

アクセストークンの使用

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

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

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

アクセストークンを使用する準備が整ったら、管理 UI を介して生成します。

アクセストークンの使用の準備が完了したら、[Generate Temporary Access Token] クリックします。

通常、一時的なトークンの期限切れは、API で生成されたデフォルトのトークンの有効期限よりも長くなることに注意してください。
[Temporary Access Token] フィールドから、curl コマンドの TOKEN の部分にアクセストークンをコピーして貼り付けます。例：
```
curl -H "Authorization:Bearer <AUTH_TOKEN>" "http://master-onprem-controller.e2e.appd-test.com:8090/controller/rest/applications"
```
コールが成功したことを確認します。そして次のようになります。

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

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

たとえば、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=10d5-573e-4a75-8396-afa006fd8f19'

次の点に注意してください。

4.5.9 より前のコントローラの場合、要求には次に示すような認証ヘッダーが必要です。

curl -X POST -H "Content-Type: application/vnd.appd.cntrl+protobuf;v=1" -u 'TestApiClient@customer:face10d5-573e-4a75-8396-afa006fd8f19' "https://<controller address>/controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=TestApiClient@customer&client_secret=face10d5-573e-4a75-8396-afa006fd8f19'

{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}

CODE

トークン生成 API には、トークンを正常に要求するために、ユーザ名とパスワードが含まれた認証ヘッダーに加えて、oAuth 要求本文が必要です。

生成されたトークンを使用して、すべてのアプリケーションを一覧表示します。例：

curl -H "Authorization:Bearer <AUTH_TOKEN>" https://master-controller.e2e.appd.com/controller/rest/applications

成功の場合：すべてのアプリケーションが返されます。
失敗した場合：HTTP 401 Unauthorized "Failed to authenticate: invalid access token." が返されます。

アクセストークンの管理

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

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

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

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

デフォルト値は 1 日で、上限は 30 日です。

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

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