OAuth 2.0アクセストークンを取得する

OAuth 2.0 JWT ベアラーフローを使用して、入出力 API 呼び出し用のアクセストークンを取得します。

Inbound D1 API は OAuth 2.0 JWT ベアラーフロー（RFC 7523）を使用します。あなたのシステムは署名された JSON Web Token（JWT）を次に送信します： /oauth2/token アクセストークンを取得するために。

D1 は要請に応じてアウトバウンド API を OAuth 2.0 で保護することもできます。サポートされるフローについてはアウトバウンドの OpenAPI 仕様を参照してください。

OAuth 2.0 JWT ベアラーフロー

完全な定義についてはインバウンドの OpenAPI 仕様を使用してください： /oauth2/token 定義。

バックエンド間 API のすべてのリソースは保護されています。アクセスを得るためには、事前に生成されたアクセストークンを HTTP リクエストの Authorization ヘッダーに Bearer スキームを用いて添付する必要があります：

Authorization: Bearer <access_token>

生成されるアクセストークンの有効期間は 15 分です。したがって、トークンは 15 分間のみ使用でき、その後クライアントは新しいトークンを取得するために /oauth2/token API を再度呼び出す必要があります。パフォーマンス上の理由から、トークンがまだ有効期間内である場合は、毎回の API 呼び出し前に /oauth2/token API を呼び出すのではなく、そのトークンを再利用することを推奨します。

JSON Web Token（JWT）

/oauth2/token REST API は JSON Web Token（JWT）認証（rfc7519）を要求します。この API のクライアントが有効な JWT トークンを発行できることが想定されています。

JWT トークンは Identity Provider（Keycloak など）から要求して取得するか、手動で作成することができます。いずれの場合も、署名検証に使用される公開鍵は API プロバイダのシステムにプロビジョニングされている必要があります。

Identity Provider が利用できない場合、次のセクションでは JWT トークンと JWT を発行および検証するために使用される暗号鍵の生成方法について説明します。

アルゴリズム

"ES256" で署名された JWT のみがサポートされます。JSON Web Algorithms（JWA）を参照してください（rfc7518).

JWT のセキュリティは共有シークレットをバックエンドサーバに保存することを避けるために非対称暗号アルゴリズムに限定されています。その結果、バックエンドサーバはトークンの署名を検証するために使用される公開鍵のみを保存します。

JWT 形式

JWT はドット（.）で区切られた 3 つの部分で構成されます：

• ヘッダー

• ペイロード

• 署名

したがって、JWT は通常次のようになります： hhhhhhh.pppppppp.ssssssssss

ヘッダー

ヘッダー部分には使用するアルゴリズムと生成するトークンの種類が含まれます。

この kid は必須であり、同一顧客の複数の公開鍵の中から適切な鍵を決定するために使用されます。

ヘッダー例：

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "your_tenant_key_id"
}

ペイロード

ペイロードには次のフィールドを含めることができます：

パラメータ	説明
iss	JWT の発行者。インバウンド API の場合は次の値である必要があります： merchantGatewayId インバウンド API の場合および d1 アウトバウンド API の場合で、オンボードされた公開鍵を照会するために使用されます。
sub	サブジェクトはユーザーの技術的識別子を含む必要があります。ここで、バックエンド間 API の場合、sub は merchantGatewayId.
exp	トークンの有効期限を UTC の 1970 年 1 月 1 日（エポック時）からの秒数で表したもの。最大値は現在の日時 + 15 分です。
aud	aud フィールドは認可サーバを想定されるオーディエンスとして識別します。認可サーバ側はトークンの想定オーディエンスであることを検証する必要があります。オーディエンス値には認可サーバの URL を使用してください：ステージング = stg 、本番 = prd

JWT 有効期限に関する注意事項

この exp 値は最大有効期限と照合されます。もし JWT の exp 値が最大有効期限を超える場合、JWT は自動的に無効と見なされ、リクエストは未認証になります。

ペイロード例

{
  "iss": "d1",
  "sub": "MGW_ID",
  "exp": 1545222654,
  "aud": "stg"
}

JWT 署名

ヘッダーとペイロードの両方の暗号学的ハッシュ。

これらの部分は Base64URL エンコードされ、単一のドット（'.'）で区切って連結されます。

鍵ペアの生成方法

次のコマンドを使用して openssl ツールで鍵ペアを生成できます：

例（ES256）

発行者側で使用され、あなたの環境で厳重に保護されなければならない秘密鍵を生成します。

> openssl ecparam -name prime256v1 -genkey -noout -out customer-jwt-priv-key.pem

D1 に設定する必要がある公開鍵を生成します。

> openssl ec -in customer-jwt-priv-key.pem -pubout > customer-jwt-pub-key.pem

生成された秘密鍵はクライアント側で JWT に署名するために使用され、生成された公開鍵は kid と共にサーバ側にプロビジョニングされ、これらの JWT の署名を検証するために使用されます（オンボーディング時に顧客と Thales 間で交換されます）。

JWT の生成方法

JWT 生成を支援するツールは多数存在します。

ここでは小さな NodeJS ライブラリを使用して生成する例を示します：

/*
プロジェクトに *jose* ライブラリをインストールしてください。
https://www.npmjs.com/package/jose

この例ではバージョン 3.19.0 を使用します
*/
const { SignJWT } = require("jose/jwt/sign");
const { createPrivateKey } = require("crypto");

const alg = "ES256";
const kid = "your_tenant_key_id";
const iss = "your_issuer";
const aud = "your_audience";
const expirationTime = "3mins";
const sub = "our_user_for_audit";

const privateKeyPem = `-----BEGIN EC PRIVATE KEY----- 
MHcCAQEEILlIXMnH1if8EuWykPmWw/LyXZuoNVCzMp3Yhbj9/sEUoAoGCCqGSM49 
AwEHoUQDQgAE6swczLIRn/lPxQPpdUb2pHjCr0YeC02lkG7vMmqCNpalwIQSl+TR 
fZVDwCKJmajRgK3+n5SyAgCp4oH8qNluwQ==
-----END EC PRIVATE KEY-----`;

async function generateJwt() {
  const privateKey = createPrivateKey(privateKeyPem);

  console.log(
    await new SignJWT({})
      .setProtectedHeader({ alg, kid })
      .setIssuedAt()
      .setIssuer(iss)
      .setAudience(aud)
      .setExpirationTime(expirationTime)
      .setSubject(sub)
      .sign(privateKey)
  );
}

(async () => {
  await generateJwt();
})();

JWT 出力例

eyJhbGciOiJFUzI1NiIsImtpZCI6InlvdXJfdGVuYW50X2tleV9pZCJ9.eyJpYXQiOjE2MzYwMzMxODYsImlzcyI6InlvdXJfaXNzdWVyX2lkIiwiYXVkIjoieW91cl9hdWRpZW5jZSIsImV4cCI6MTYzNjAzMzM2Niwic3ViIjoib3VyX3VzZXJfZm9yX2F1ZGl0In0.lgVzN8k9IGcv1s-FZACpEyVxXcS9LAh4ahY3DO5Fg6MRl-Twa_wVAfw_Oe0XiH1Am-RFfafgDrepNi3Jz05Gvg