JWT ヘッダの操作

ヘッダ値の追加 (承認サーバ)

承認サーバによって JWT トークンが生成される場合、使用される署名アルゴリズムと暗号化アルゴリズムに基づいて、alg、enc、kid、typ、および cty の各ヘッダが自動的に生成されます。これらのヘッダをカスタム・コードで直接操作することはできません。ただし、他のヘッダ値は JWTHeaderClaimsOpens in a new tab 配列を使用して JWT ヘッダに追加できます。例えば、JWTHeaderClaims を使用して、jku および jwk のヘッダ・パラメータをトークンに追加できます。jku の場合、関連する jwk_uri または JWKS がサーバによって自動的に JOSE 配列に追加されます。RFC 7515 で定義されているヘッダ・パラメータの一部はサポートされないことに注意してください。JWTHeaderClaims 配列を使用して、任意のカスタム値を JWT ヘッダに追加することもできます。

例えば、以下のコードを %OAuth2.Server.ValidateOpens in a new tab のサブクラスに追加すると、2 つの標準ヘッダと 1 つのカスタム・ヘッダ値を JWT ヘッダに追加できます。

ClassMethod ValidateUser(username As %String, password As %String, scope As %ArrayOfDataTypes, properties As %OAuth2.Server.Properties, Output sc As %Status) As %Boolean
{
  ...
  Do properties.SetClaimValue("co","intersystems")

  Do properties.JWTHeaderClaims.SetAt("","jku")
  Do properties.JWTHeaderClaims.SetAt("","co")
  Do properties.JWTHeaderClaims.SetAt("","iss")        
  ...
}

ヘッダ値の追加 (JWT の直接生成)

ObjectToJWT()Opens in a new tab メソッドを使用して、カスタム・コードによって OAuth フレームワークの外部で JWT を生成できます。このメソッドは、JOSE ヘッダを表す文字列の配列を最初のパラメータとして受け入れます。JWT ヘッダに値を追加するには、ObjectToJWT メソッドを呼び出す前に JOSE 配列に値を追加するだけです。例えば、jku ヘッダ・パラメータを JOSE ヘッダに追加するには、以下のように指定します。

Set JOSE("jku")=""
Set JOSE("jku_local")=%server.Metadata."jwks_uri"
Set JOSE("jku_remote")=%client.Metadata."jwks_uri"
// set JOSE("sigalg") and/or JOSE("encalg") and JOSE("keyalg")
Set sc=##class(%OAuth2.JWT).ObjectToJWT(.JOSE,json,%server.PrivateJWKS,%client.RemotePublicJWKS,.JWT)

標準のヘッダ・パラメータに対応する JOSE 配列ノードの詳細は、クラス・リファレンスOpens in a new tabを参照してください。

カスタム・ヘッダ・パラメータの追加

ObjectToJWT メソッドに渡される JOSE 配列には、JWT ヘッダに挿入するカスタム・ヘッダ・パラメータを追加できます。カスタム・ヘッダ・パラメータを追加するには、まず、それらのヘッダ・パラメータをキー/値のペアとしてダイナミック・オブジェクト内に定義します。キーはカスタム・パラメータの名前、値はそのパラメータの値です。ダイナミック・オブジェクトを定義したら、custom 添え字を使用してそのダイナミック・オブジェクトを JOSE 配列のノードに追加します。例えば、以下のコードでは、co と prod の 2 つのカスタム・パラメータが JWT ヘッダに挿入されます。

Set newParams={"co":"intersystems","prod":"bazbar"}
Set JOSE("custom")=newParams
// set JOSE("sigalg") and/or JOSE("encalg") and JOSE("keyalg")
Set sc=##class(%OAuth2.JWT).ObjectToJWT(.JOSE,json,%server.PrivateJWKS,%client.RemotePublicJWKS,.JWT)

JOSE 配列の custom ノードを使用して、RFC 7515Opens in a new tab で定義されているヘッダ値をオーバーライドすることはできません。入れ子になった署名または暗号化を行う場合、カスタム・ヘッダは "内部" (署名された) トークンにのみ追加されます。

カスタム・ヘッダ・パラメータの処理

JWTToObjectOpens in a new tab メソッドを使用すると、JWT を処理してヘッダを返すことができます。これらのヘッダにアクセスする方法は 2 つあります。このメソッドでは、JWT に対する署名/暗号化操作に使用するアルゴリズムが含まれる標準の JOSE ヘッダ・パラメータは、文字列の配列で返されます。また、JWT の "未加工" のヘッダはダイナミック・オブジェクトとして 6 番目のパラメータで返されます。このダイナミック・オブジェクトのキー/値ペアを解析することで、JWT ヘッダに存在するカスタムおよび標準のヘッダ・パラメータを処理できます。トークンが、入れ子になった署名および暗号化を使用して作成されている場合、このメソッドで返される未加工のヘッダは、"内部" (署名された) トークンからのものです。