メインコンテンツへスキップ

APIへの認証済みリクエストの準備

Markdown

サービスアカウントの作成と設定が完了したら、お客様のアプリケーションは次の手順を完了する必要があります。

  1. ヘッダー、ペイロード、署名を含むJSON Web Token(JWT)を作成する。
  2. OAuth2認証プラットフォームからアクセストークン(AccessToken)をリクエストする。
  3. 認証プラットフォームが返すJSONレスポンスを処理する。

レスポンスにアクセストークンが含まれている場合、それを使用してサービスアカウントがアクセス権限を持つUnicoの製品APIにリクエストを送信できます。(レスポンスにアクセストークンが含まれていない場合、JWTおよびトークンリクエストが誤っているか、サービスアカウントがリクエストされたリソースへのアクセスに必要な権限を持っていない可能性があります。)

上記のリクエストで生成されるアクセストークンの有効期間は、デフォルトで3600秒ですが、貴社に設定されたセキュリティ設定によって異なる場合があります。アクセストークンが期限切れになった場合、お客様のアプリケーションは新しいJWTを生成し、署名を行い、認証プラットフォームに新しいアクセストークンをリクエストする必要があります。

1 — JWTの作成​

JWTはヘッダー、ペイロード、署名の3つの部分で構成されます。ヘッダーとペイロードはJSONオブジェクトです。これらのJSONオブジェクトはUTF-8でシリアライズされた後、Base64urlエンコーディング¹を用いてエンコードされます。このエンコーディングは、エンコード処理が繰り返された場合のエンコーディング変更に対する耐性を提供します。ヘッダー、ペイロード、署名はピリオド(.)文字で連結されます。

JWTは次のように構成されます。

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

署名の基となるテキストは次のように構成されます。

{Header in Base64url}.{Payload in Base64url}

1.1 — JWTヘッダーの形成​

ヘッダーは、署名アルゴリズムとトークン形式を指定する2つのフィールドで構成されます。両方のフィールドは必須であり、それぞれ1つの値のみを持ちます。サービスアカウントはRSA SHA-256アルゴリズムとJWTトークン形式に依存しています。そのため、ヘッダーのJSON表現は次のとおりです。

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

Base64url表現は次のとおりです。

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 — JWTペイロードの形成​

JWTペイロードには、リクエストされた権限(スコープ)、アクセスをリクエストしているアカウント、発行者、トークンが発行された時刻、トークンの有効期間など、JWTに関する情報が含まれます。ほとんどのフィールドは必須です。JWTヘッダーと同様に、ペイロードはJSONオブジェクトであり、署名の構成に使用されます。

1.3 — 必須フィールド​

JWTの必須フィールドを以下の表に示します。これらはペイロード内で任意の順序で記載できます。

名前説明
iss会社内でのサービスアカウントの識別子。
scopeアプリケーションがリクエストしている権限をスペース区切りまたはプラス記号(+)区切りで列挙したリスト。アカウントのすべての権限が必要な場合は、アスタリスク(*)記号を使用します。
audアクセストークンを発行する認証プラットフォームのアドレス。この値は常にhttps://identityhomolog.acesso.ioと完全に一致している必要があります。よくあるうまくいかない例:末尾にスラッシュを付ける(https://identityhomolog.acesso.io/)、またはHTTPSの代わりにHTTPを使用する。
expトークンの有効期限を、1970年1月1日00:00:00 UTCからの経過秒数で指定したもの。この値は、JWT発行時刻から最大1時間の期間を持ちます。数値である必要があります — "1524161193"のように引用符で囲まれた値は文字列となり機能しません。1524161193は数値であり機能します。
iatJWTの発行時刻を、1970年1月1日00:00:00 UTCからの経過秒数で指定したもの。この値はexpと同じ規則で数値である必要があります。

iatフィールドは必要な形式で現在時刻を表す必要があり、expフィールドは次の計算に従う必要があります。

exp = iat + 3600

JWTペイロードにおける必須JSONフィールドの表現は次のとおりです。

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

1.4 — 署名の計算​

**JSON Web Signature(JWS)**²仕様は、JWTの署名計算を導くメカニズムです。署名計算の入力コンテンツは、次の内容のバイト配列です。

{Header in Base64url}.{Payload in Base64url}

署名の計算には、JWTヘッダーで指定されたものと同じアルゴリズムを使用する必要があります。OAuth2認証プラットフォームがサポートする唯一の署名アルゴリズムは、JWTヘッダーのalgフィールドでRS256と表される、SHA-256を使用するRSAです。

入力コンテンツのUTF-8表現を、サービスアカウントに関連付けて作成された秘密鍵(メールで受け取ったリクエストから生成された.key.pemファイル)を使用し、SHA256withRSA(SHA-256ハッシュを用いたRSASSA-PKCS1-V1_5-SIGNとも呼ばれます)で署名します。出力コンテンツはバイト配列になります。

次に、署名をBase64urlでエンコードする必要があります。ヘッダー、ペイロード、署名はピリオド文字で連結する必要があります。その結果がJWTとなります。

JWTの作成には、既存のライブラリを利用することも可能です。参考として、jwt.ioのWebサイトでライブラリの一覧を確認できます。

2 — アクセストークンのリクエスト​

署名済みのJWTを生成した後、アプリケーションはそれを使用してアクセストークンをリクエストできます。アクセストークンのリクエストはPOST HTTPSリクエストであり、ボディはURLエンコードされている必要があります。URLは以下のとおりです。

https://identityhomolog.acesso.io/oauth2/token

POST HTTPSリクエストでは、次のパラメーターが必須です。

名前説明
grant_type次のテキストを使用します。必要に応じてURLエンコードしてください:urn:ietf:params:oauth:grant-type:jwt-bearer
assertion署名を含むJWT。
POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>

3 — 認証プラットフォームのレスポンスの処理​

JWTとアクセストークンのリクエストが適切な形式で構成されており、サービスアカウントが必要な権限を持っている場合、認証プラットフォームはアクセストークンを含むJSONオブジェクトを返します。

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

JSONオブジェクトのaccess_tokenフィールドで返されるアクセストークンもJWTトークンであり、Unico製品のAPIで使用する必要があります。リクエストでエラーが発生した場合は、認証エラーでエラーの種類を確認してください。

4 — アクセストークンの有効期間​

アクセストークンの有効期間は可変です。有効期間は、アクセストークンとともに返されるexpires_inフィールドで指定されます。同じアクセストークンは、その有効期間中、製品へのすべてのAPI呼び出しで使用する必要があります。

**現在のトークンの有効期限が近づくまで、新しいアクセストークンをリクエストしないでください。**600秒(10分)のマージンを推奨します。

new Date((token.exp - 600) * 1000)

token.expはトークンの有効期限のタイムスタンプです。

メモ

デフォルトでは、貴社に送信されるトークンの有効期間は1時間ですが、変更することも可能です。推奨事項として、常にexpires_inを基準とし、そこから600秒を差し引いた時点で新しいトークンをリクエストしてください。

例:

標準シナリオ:
expires_in: 3600 (1時間) - トークンが14:42に生成された場合
15:32になって初めて新しいトークンをリクエストします。すなわち14:42 + (3600 - 600)
有効期間が変更されたシナリオ:
expires_in: 7200 (2時間) - トークンが14:42に生成された場合
16:32になって初めて新しいトークンをリクエストします。すなわち14:42 + (7200 - 600)
警告

新しいトークンを取得するために固定の時刻を使用しないでください。受け取ったトークンの有効期間が設定された時間よりも短い場合があり、サービス利用時に障害が発生する可能性があります。

¹ RFC 4648のBaseNエンコーディングの規定によると、Base64url形式はBase64に似ていますが、=文字が省略され、+と/の文字がそれぞれ-と_に置き換えられる点が異なります。 ² JSON Web Signature: https://tools.ietf.org/html/rfc7515。

最終更新 に