JWT 認証の構成

以下の情報を使用して、ビジネス要件に応じて JWT 認証を構成します。さまざまなエンドポイントに対して JWT 認証をセットアップできます。例えば、REST API などです。

始める前に

JWT 認証の構成を開始する前に、以下のことを知っておく必要があります。

秘密鍵を使用して JWT を生成し、署名する発行者の名前。一部の構成では、発行者名が必要になる場合があります。
JWT に署名するために使用される秘密鍵に対応する公開鍵。この公開鍵は、JWT の署名を検証するために使用されます。
JWT 内に存在するデータ、および OMS ユーザーにマップするために使用できるフィールド。

手順

適切なエンドポイントに対して JWT 認証を有効にします。
エンドポイントが REST API の場合は、 customer_overrides.properties ファイル内の servlet.jwt.auth.enabled プロパティーの値を true に設定して、JWT 認証を有効にします。例えば、 xapirest.servlet.jwt.auth.enabled=trueなどです。

特定のタイプの鍵ローダーを使用する決定に基づいて、適切な構成を設定する必要があります。鍵ローダーは、着信 JWT を検証するための公開鍵を取得するために使用されます。 Sterling™ Order Managementシステムは、デフォルトで以下のタイプのキーローダーを提供する。

重要: IBM Sterling® Order Management System on IBM CloudSaaS を使用している場合は、デフォルトのプロパティを変更しないでください。発行者固有のプロパティーを使用します。例えば、 yfs.yfs.jwt.verify.keyloader 鍵ローダーは変更しないでください。代わりに、新しい発行者固有の鍵ローダー yfs.yfs.jwt.< issuer_name>.verify.keyloaderを追加します。

表 1. アプリケーション提供の鍵ローダー
鍵ローダー・タイプ	説明	構成
プロパティー・キー・ローダー	yfs プロパティーから特定のプロパティーを読み取って、キーを取得します。このプロパティーには、JWT ヘッダーから取得された「kid」(鍵 ID) が含まれます。 ID に基づいて、プロパティーからキーの値を読み取ろうとします。鍵の値は、 Base64 エンコード PEM 形式であることが予期されます。	プロパティー・キー・ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。 `yfs.yfs.jwt.verify.keyloader=properties` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader=properties` として構成できます。 `yfs.yfs.jwt.verify.propkeyloader.kid=base64 encoded public key`
Https URI 公開鍵ローダー	これは、JWT 検証時に https URI から公開鍵または証明書をダウンロードする方法を提供します。 https URI を使用する場合は、アプリケーションが正常に URI に接続できるように、この https URI の証明書を JVM またはアプリケーション・サーバーのトラストストアに追加する必要があります。	https URI 公開鍵ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。デフォルトでは、 Sterling Order Management System は、以下の https URI キー・ローダーを提供します。これらの URI キー・ローダー・オプションのいずれかを使用できます。 httpsjwks-httpsjwks キー・ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。 `yfs.yfs.jwt.verify.keyloader=httpsjwks` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader=httpsjwks` として構成できます。 `yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in JWKS format` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in JWKS format` として構成できます。 httpsjwk-httpsjwk 鍵ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。 `yfs.yfs.jwt.verify.keyloader=httpsjwk` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader=httpsjwk` として構成できます。 `yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in JWK format` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in JWK format` として構成できます。 httpsbase64 - httpsbase64 キー・ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。 `yfs.yfs.jwt.verify.keyloader=httpsbase64` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader=httpsbase64` として構成できます。 `yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in Base64 encoded format` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in Base64 encoded format` として構成できます。
カスタム・キー・ローダー	これは、ボールトまたはカスタム・ストレージから検証鍵をロードする方法を提供します。カスタム実装は、IPLTJWTVerificationKeyLoaderインターフェースを実装しなければならない。このインターフェースは、鍵を戻す方法を提供します。この鍵は、JWS の署名を検証するために使用されます。必要に応じて、発行者ごとに別個のカスタム鍵ローダーを構成できます。	カスタム・キー・ローダーを使用するには、 customer_overrides.properties ファイルで以下のプロパティーを構成する必要があります。 `yfs.yfs.jwt.verify.keyloader=class name implementing IPLTJWTVerificationKeyLoader interface` 発行者固有の鍵ローダーは、 `yfs.yfs.jwt.<issuer name>.verify.keyloader=class name implementing IPLTJWTVerificationKeyLoader interface` として構成できます。

注: JWT にサード・パーティー・プロバイダーを使用している場合は、JWT 認証に httpsjwks keyloader 構成を使用できます。プロバイダーが JSON Web Key Set (JWKS) エンドポイントをサポートしていない場合は、表 1 にリストされている他のオプションを使用できます。

着信 JWT ペイロード・クレームから OMS ユーザーを識別します。 OMS ユーザーの詳細は、 customer_overrides.properties ファイル内の以下のいずれかのプロパティーを構成することによって提供できます。
- OMS ユーザー・パス - yfs.yfs.jwt.defclaimparser.user.path=<path relative to the JWT body JSON to read the user>
  発行者固有の OMS ユーザー・パスは、 yfs.yfs.jwt.issuer name.defclaimparser.user.path=path relative to the JWT body JSON to read the user として構成できます。
- OMS ユーザー E メール・パス (OMS User Email Path) - yfs.yfs.jwt.defclaimparser.user.email.path=path relative to the JWT body JSON to read the user email
  発行者固有の OMS ユーザー E メール・パスは、 yfs.yfs.jwt.issuer name.defclaimparser.user.email.path=path relative to the JWT body json to read the user email として構成できます。
例
JWT ペイロードに以下の JSON 構造があるとします。
```
{
  "iat": 1516239022,
  "exp": 1531762065,
  "userid" : "testuser",
  "otherinfo" : { "email": "test@foo.com", "usergroup":"testGroup"}
}
```
次に、ユーザー・パスを指定するために、プロパティーを以下のように設定します。
```
yfs.yfs.jwt.defclaimparser.user.path=userid
```
ユーザーの E メール・パスを指定するには、このプロパティーを以下のように設定します。
```
yfs.yfs.jwt.defclaimparser.user.email.path=otherinfo.email
```
つまり、パス内のドット (.) は、オブジェクト email がオブジェクト otherinfoの子であることを示すために、JSON 構造内の子オブジェクトへのトラバースに使用されます。
注: <path relative to the JWT body JSON to read the user> または <path relative to the JWT body JSON to read the user email> の値にドット (.) 文字が含まれている場合は、ドット (.) 以外の別の区切り文字を使用するように yfs.yfs.jwt.defclaimparser.path.delim プロパティーを設定する必要があります。これは、ドットがデフォルトで区切り文字として使用される特殊文字であるためです。
```
yfs.yfs.jwt.defclaimparser.path.delim=<value>
```
ここで、 value は、 path relative to the JWT body JSON to read the user または path relative to the JWT body JSON to read the user emailに存在しない文字です。

パスにドット (.) が含まれている場合は、 yfs.yfs.jwt.defclaimparser.path.delim プロパティーを使用して、パスを指定するための別の区切り文字を設定できます。
例えば、JWT ペイロードに以下の JSON 構造があり、ユーザー・パスとユーザー E メール・パスにドット文字が含まれているとします。
```
{
  "iat": 1516239022,
  "exp": 1531762065,
  "www.foo.com/userid" : "testuser",
  "www.foo.com/otherinfo" : { "email": "test@foo.com", "usergroup":"testGroup"}
}
```
次に、区切り文字を変更するために、以下のプロパティーを設定します。
```
yfs.yfs.jwt.defclaimparser.path.delim=$
```
$ はパスに存在しないため、代替区切り文字として使用できます。
これで、ユーザー・パスとユーザー E メール・パスを以下のように指定できます。
```
yfs.yfs.jwt.defclaimparser.user.path=www.foo.com/userid
yfs.yfs.jwt.defclaimparser.user.email.path=www.foo.com/otherinfo$email
```
ここで、パス内の $ は、オブジェクト email がオブジェクト www.foo.com/otherinfoの子であることを示します。