認証 · Customer Self-Service

認証

このセクションでは、Apex CentralがAPI要求をどのように認証するかについて説明します。

Apex Centralはトークンベースの認証を使用して、信頼されたアプリケーションだけがAPIを使用できるようにします。サービスとリソースにアクセスするには、正しく定義されたJSON Web Token (JWT) を作成し、各API要求に含める必要があります。

JWTは、関係者間で情報をJSONオブジェクトとして安全に送信するためのオープンな業界標準の方法です。情報はデジタル署名されているため確認および信頼できます。

JWTの詳細については、https://jwt.io/introduction/を参照してください。

認証トークンの構造

このトピックでは、Apex Central API要求の認証に使用される認証トークンの構造について説明します。

JSON Web Token (JWT) は、ドットで区切られた3つの部分で構成されます (例: xxxxx.yyyyy.zzzzz)。

ヘッダ: この部分には次の情報が含まれており、Base64URLでエンコードされています。

表 1. JWTヘッダ - 必須情報
内容	説明
`alg`	チェックサムを計算するために使用されるアルゴリズムサポートされるアルゴリズム: HS256 (HMAC SHA256) HS384 HS512
`typ`	トークンの種類重要: Apex CentralではJWTのみ使用できます。

以下に復号化されたJWTヘッダの例を示します。

{
"alg": "HS256",
"typ": "JWT"
}

ペイロード: この部分には、サードパーティのアプリケーションと追加データに関するステートメントが含まれており、Base64URLでエンコードされています。

表 2. JWTペイロード - 必須情報
内容	説明
`appid`	サードパーティアプリケーションのアプリケーションID この値はApex Centralコンソールの [自動APIのアクセス設定] 画面で取得できます。詳細については、アプリケーションを追加するを参照してください。
`iat`	"Issued at"トークンの生成時間この値は、UNIXタイムスタンプ形式 (1970年1月1日 (UTC) からの秒数) で指定する必要があります。
`version`	このJWTのバージョン重要: Apex Centralでは"V1" JWTのみ使用できます。
`checksum`	要求のチェックサム詳細については、チェックサムの計算を参照してください。

重要:

JWTが暗号化されない場合、ペイロードには機密情報を含めないでください。

以下に復号化されたJWTペイロードの例を示します。

{
"appid": "2E28ED1BABA2-4D10BB13-F4FA-D5D4-31F3",
"iat": 1495187266.6215432,
"version": "V1",
"checksum": "J+CMrBKctcXXuQ68GrpFyS1+FXA4gCKs8crdOGJZ24Q="
}

署名: この部分には次の情報が含まれており、署名されています。
- エンコードされたヘッダ
- エンコードされたペイロード
- シークレット: Apex Central APIでは、APIキーがJWTの署名を生成するために使用されるシークレットです。
- ヘッダで指定されたアルゴリズム

チェックサムの計算

このトピックでは、Apex Central API認証トークンの確認に使用されるチェックサムの計算方法について説明します。

第三者がJWTを再利用できないように、トークン内にchecksumフィールドを含めます。チェックサムの計算には次の情報が使用されます。

要求	情報
`HTTP-Method`	要求のHTTPメソッド (大文字) `GET` `POST` `PUT` `DELETE`
`Raw-URL`	要求のパスおよびクエリ文字列 (小文字) 例1: APIのURL: https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents?HostName=TestAgent Raw-URL: `/webapp/API/agentresource/productagents?hostname=testagent` 例2: 自動APIのURL: https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents Raw-URL: `/webapp/API/agentresource/productagents` 重要: クエリ文字列が空の場合は、「?」文字を含めないでください。
`Canonical-Request-Headers`	"API"で始まるすべての要求ヘッダのリスト次の処理を実行する必要があります。ヘッダをアルファベット順にリストし、それぞれを次の形式に変換します。 `LowerCase (ヘッダの名前) + ":" + Trim(ヘッダの値)` "&"セパレータを使用してヘッダを結合します。重要: `API`で始まるヘッダがない場合は、`Canonical-Request-Headers`の値を空の文字列のままにしてください。
`Request-Body`	UTF-8でエンコードされたJSON文字列での要求本文

計算済みのSHA-256チェックサムであるHTTP-Method + "|" + Raw-URL + "|" + Canonical-Request-Headers + "|" + Request-Bodyでは、checksumフィールドは、計算済みのSHA-256チェックサムのバイト配列をBase64文字列で表したものになります。

親トピック

Apex Centralの自動API