JWT 認証の構成

始める前に

第三者認証の情報に精通している必要があります。

JWT に存在するクレームを知っておく必要があります。

以下が必要です。

• JWT 署名検証用の公開鍵を含む X.509 証明書。 適切な X.509 証明書を取得する方法については、JWT 発行者のセキュリティー管理者に問い合わせてください。
• server.xml 構成ファイルへの書き込み権限。

このタスクについて

このタスクでは、JWT 認証を実行するように Liberty JVM サーバーを構成してから、JWT 内の ID を使用して CICS タスクを実行します。

このタスクは、以下のことを前提

• JWTは、 HTTP Authorization リクエスト・ヘッダ・フィールドで CICSに送信される。
• RS256 公開/秘密アルゴリズムを使用して JWT に署名します。
• JWT subject クレーム内の ID は分散 ID です。
• RACF は、ユーザー・レジストリー、証明書の保管、および CICS トランザクションへのアクセスの許可に使用されます。
• アプリケーションは CICS バンドルとしてデプロイされるため、すべての認証済みユーザーは、Liberty でのアプリケーションの実行を自動的に許可されます。 詳しくは、 CICS バンドル内の Enterprise Java アプリケーションの Liberty JVM サーバーへのデプロイを参照してください。

図 1 は、認証に使用される JWT の例を示しています。

header には、使用されるアルゴリズム (HMAC SHA256 や RSA SHA256など) が含まれており、JWT の最初の部分を形成するために Base64Url でエンコードされています。

ペイロード にはクレームが含まれます。 ペイロードには、 iss (発行者)、 exp (有効期限)、 sub (サブジェクト)、および aud (オーディエンス) などの一連の事前定義クレームが含まれています。 これらのクレームは必須ではありませんが、一連の有用な相互運用可能なクレームを提供することをお勧めします。 ペイロードはまた、従業員の役割のようなカスタムクレームを定義する追加属性を含むことができる。 通常、sub クレームは、 OpenID Connect ユーザー・サブジェクトを作成するために使用されます。

上記の例では、

• iss (発行者) クレーム idg は、JWT を発行したプリンシパルを識別します。
• sub (サブジェクト) クレームは、ID cn=JeanLeclerc,ou=employees,o=ibm,c=frです。

• exp (有効期限) クレームは、JWT が処理のために受け入れられなければならない有効期限を識別します。
• iat (発行時刻) クレームは、JWT が発行された時刻を識別します。

ペイロードは、JWT の 2 番目の部分を形成するためにエンコードされた Base64Url です。

手順

1. JWT 署名の検証に使用されるトラストストアとして RACF 鍵リングを構成します。 この例では、秘密鍵を使用して JWT に署名するため、公開鍵を含む X.509 証明書を Liberty JVM サーバーのトラストストアに保管する必要があります。

   JWT 署名を検証するために必要な公開鍵を含む X.509 証明書を、信頼できる証明書として RACF 鍵リングに追加します。 CERTAUTH の用途で X.509 証明書を接続します。

   次のコマンドを入力します。

   RACDCERT ID(CICS1) CONNECT(RING(myKeyRing) LABEL('jwtValidate') CERTAUTH)

   このコマンドでは、以下の値を使用します。

   • CICS1 は、 CICS 領域のユーザー ID です。
   • myKeyRing は鍵リングの名前です。
   • jwtValidate は、鍵リングに接続される証明書のラベルまたは別名です。
     • トラストストアの server.xml 構成ファイルに keyStore エレメントを追加します。

   trustStore エレメントの id 属性値は、 openidConnectClient エレメントの trustStoreRef 属性で指定された値と一致する必要があります。以下に例を示します。

   <keyStore id="JWTTrustStore" fileBased="false"    location="safkeyring://CICS1/myKeyRing"
           password="myPassword"     readOnly="true"
           type="JCERACFKS" />

   Java 11を実行している場合は、 location="safkeyringjce://CICS1/myKeyring"。 キーストアの詳細については、 IBM WebSphere Application Server for z/OS Liberty ドキュメントの「 Keystores 」を参照。

2. openidConnectClient-1.0 Liberty フィーチャーを server.xml ファイルに追加します。
3. JWT 認証を使用するように server.xml 内の <openidConnectClient> エレメントを構成します。以下に例を示します。

   <openidConnectClient id="RS"
           clientId="RS-JWT-CICS" inboundPropagation="required"
             signatureAlgorithm="RS256" trustStoreRef="JWTTrustStore"
             trustAliasName="JWTTrustCert" userIdentifier="sub"
             mapIdentityToRegistryUser="false" issuerIdentifier="idg"
             audiences=”urn:myEntity”/>

   この例では、次のようになっています。

   • id と clientId はエレメント ID です。
   • inboundPropagation は required に設定され、Liberty JVM サーバーが受信した JWT を認証トークンとして使用できるようにします。
   • signatureAlgorithm は、JWT 署名の検査に使用されるアルゴリズムを指定します。

   CICS Liberty は、 RS256 (非対称アルゴリズム) および HS256 (対称アルゴリズム) をサポートします。

   • trustStoreRef検証証明書の場所を定義するキーストア要素の名前 (id 属性内) を指定します。
   • trustAliasName署名の検証に使用する証明書の別名またはラベルを指定します。
   • userIdentifier は、ユーザー対象の作成に使用されるクレームを示します。 ユーザー対象に使用されるデフォルト・クレームは sub クレームです。
   • mapIdentityToRegistryUser取得した ID をレジストリ ユーザーにマップするかどうかを示します。 あなたが設定したmapIdentityToRegistryUserとしてfalseサブクレームのアイデンティティはRACFユーザーID。
   • issuerIdentifier は、予期される発行者を定義します。
   • audiences は、ターゲット・オーディエンスのコンマ区切りリストを定義します (JWT 内のオーディエンスは、定義されているオーディエンスの 1 つと一致する必要があります)。
   その他の openidConnectClient 属性の詳細については、 WebSphere Application Server for z/OS Liberty IBM Documentationトピック OpenID Connect Client ( openidConnectClient ) を参照のこと。

   重要： JWT認証がLiberty JVMサーバーへのリクエストのサブセットだけに必要な場合、 openidConnectClient 要素は、 HTTP リクエストに対してマッチする条件を表す authFilter 属性を含めることができます。

   認証フィルタの詳細については、 認証フィルタ( authFilter )を参照のこと。

4. server.xml 構成ファイル内の safCredentials エレメントに属性 mapDistributedIdentities="true" を設定します。

   例:

   <safCredentials mapDistributedIdentities="true" suppressAuthFailureMessages="false"/>

5. RACF IDIDMAP クラスをアクティブにします。 以下の RACF コマンドを入力します。

   SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)

6. RACF で分散 ID フィルターを定義して、JWT サブジェクト・クレームから RACF ユーザー ID に分散ユーザー ID をマップします。

   例えば、次のコマンドを入力します。

   RACMAP ID(EMPLOY1) MAP USERDIDFILTER(NAME('cn=JeanLeclerc,ou=employees,o=ibm,c=fr')) REGISTRY(NAME('*')) WITHLABEL('Mapping Jean Leclerc')

   この例では、次の値が使用されています。

   • cn=JeanLeclerc,ou=employees,o=ibm,c=fr は、JWT サブジェクト・クレームからの分散ユーザー ID です。
   • EMPLOY1 は、分散ユーザー ID のマップ先となる RACF ユーザー ID です。
   • REGISTRY(NAME('*')) は、任意のレジストリー・レルム名と一致します。 あるいは、特定のレルムに一致させるには、*をrealmNameの属性openidConnectClient要素。
   重要: この例は、1 対 1 のマッピングを示しています。 z/OS ID 伝搬は、多対 1 のマッピングもサポートします。 例えば、多対 1 のマッピングを使用して、すべての従業員を同じ RACF ユーザー ID にマップすることができます。

   RACMAP コマンドの詳細については、『 z/OS Security Server RACF Command Language Reference』の「 RACMAP (Create, delete, list, or query a distributed identity filter) 」を参照してください。

7. RACF IDIDMAP クラスをリフレッシュします。

   変更を有効にするには、以下の RACF コマンドを入力します。

   SETROPTS RACLIST(IDIDMAP) REFRESH

Liberty z/OS を使用した OpenID Connect Client 機能の構成の詳細については、 OpenID Connect の JSON Web Token 認証の構成を参照してください。

結果

JWT は、Liberty JVM サーバーに対する要求を認証するために使用されます。 JWT 内の分散 ID は RACF ユーザー ID にマップされ、 RACF ユーザー ID は CICS タスクの実行に使用されます。

この例を検証するために、 CICS Explorer® から、 CICS® セキュリティリクエスト記録（SRR）機能を使用することができます。 「領域」ビュー がフォーカスされている状態で、 「セキュリティー要求の記録の追加」 ポップアップ・メニュー・オプションを選択します。 そのウィンドウで、 「JVM サーバー」 タブを選択し、 「トランザクション ID」 フィールドを、要求 (またはデフォルトでは CJSA) に一致する URIMAP によって定義されたトランザクション ID に設定します。 詳しくは、 SRR を使用した CICS セキュリティー構成の例が機能しているかどうかの確認を参照してください。

JWK または HS256 アルゴリズムを使用する場合の代替構成

JWT が、JWK (JSON Web 鍵) をサポートする JWT プロバイダーによって発行されるか、 HMAC-SHA256 秘密鍵アルゴリズムを使用して署名される場合、トラストストアは必要ありません。 ただし、openidConnectClient エレメントで別の属性を指定する必要があります。

代替プロセス

1. 公開鍵が JWK エンドポイントから取得される場合は、jwkEndpointUrl 属性で JWK エンドポイント URL を指定します。
2. JWT が、HMAC-SHA256 アルゴリズムで共有秘密鍵を使用することで署名されている場合は、sharedKey 属性または clientSecret 属性でその共有秘密鍵を定義します。

これらの代替 openidConnectClient 属性については、 WebSphere Application Server for z/OS Liberty IBM Documentationトピック OpenID Connect Client ( openidConnectClient ) を参照のこと。