場所：このメソッドはクラス %SYS.OAuth2.ValidationOpens in a new tab にあります。
ClassMethod ValidateJWT(applicationName As %String,
accessToken As %String,
scope As %String,
aud As %String,
Output jsonObject As %RegisteredObject,
Output securityParameters As %String,
Output sc As %Status) As %Boolean
アクセス・トークンが (opaque トークンではなく) JWT である場合にのみこのメソッドを使用します。
このメソッドは JWT の復号化 (必要な場合) と検証を行い、オブジェクト (jsonObject) を作成して JWT プロパティを格納します。JWT を検証するために、このメソッドは、対象者 (aud が指定されている場合)、発行者エンドポイント (サーバ記述で指定されているものとの一致が必要)、スコープ (scope が指定されている場合) を確認します。このメソッドは、アクセス・トークンの有効期限が切れていないことも確認します。署名された JWT と署名されていない JWT の両方が許可されます。JWT が署名されている場合は、そのシグニチャを確認します。
このメソッドは JWT が有効な場合は 1 を返し、それ以外の場合は 0 を返します。さらに、複数の引数を出力として返します。
引数は以下のとおりです。
-
applicationName はクライアント・アプリケーションの名前です。
-
accessToken は検証される JWT です。
-
scope は、スペースで区切られたスコープのリストです。例えば、"scope1 scope2 scope3" のような形式をとります。
scope が指定されている場合は、このスコープを含むスコープ・クレームが JWT に含まれている必要があります。
-
aud は、このトークンを使用する対象者を指定します。トークンに関連付けられた aud プロパティがある場合 (通常、対象者はトークンの要求時に指定されているため)、aud はトークンの対象者と一致します。aud が指定されていない場合、対象者のチェックは行われません。
-
出力として返される jsonObject は、JWT のクレームを含むダイナミック・オブジェクトです。このダイナミック・オブジェクトには aud、exp、iss などのプロパティが含まれます。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。
-
出力として返される securityParameters は、ヘッダから取得されたセキュリティ情報を含む多次元配列です。このセキュリティ情報は、シグニチャや復号化の検証で必要に応じて追加使用されます。
この配列には以下のノードがあります。
| ノード |
値 |
| securityParameters("sigalg") |
シグニチャまたは MAC アルゴリズム。JWT が署名されている場合にのみ設定します。 |
| securityParameters("keyalg") |
キー管理アルゴリズム |
| securityParameters("encalg") |
コンテンツ暗号化アルゴリズム |
keyalg と encalg のノードは、両方が指定されるか、両方が Null になります。
-
出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。
このメソッドが成功 (1) を返す場合は、jsonObject を検証し、必要に応じて含まれているクレームを使用して、要求されたリソースへのアクセスを許可するかどうかを決定します。 必要に応じて securityParameters を使用します。
Oauth 仕様では、アプリケーションは署名された JWT と署名されていない JWT の両方を受け入れることができるため、ValidateJWT メソッドは署名されていない JWT を拒否しません。ただし、多くの場合、署名されていない JWT を拒否して、アプリケーションにより厳しいセキュリティを実装することを強くお勧めします。メソッドから返された securityParameters 配列を調べることで、ValidateJWT に渡されたトークンが署名されていないかどうかを確認できます。securityParameters("sigalg") が設定されていない場合、トークンは署名されていません。例えば、以下のコードは、トークンが署名されていないかどうかを判断し、署名されていない場合は拒否します。
Set tInitialValidationPassed = ##class(%SYS.OAuth2.Validation).ValidateJWT(tClientName, tAccessToken, "", "", .tJsonObj,.tSecurityParams, .tValidateStatus)
// the “sigalg” subscript is set only if the JWT was signed
Set tIsTokenSigned = $Data(tSecurityParams("sigalg"))#2
If 'tIsTokenSigned {
$$$ThrowStatus($System.Status.Error($$$AccessDenied))
}
