OAuth 2.0 承認サーバとしての Caché の使用法
この章では、OAuth 2.0 承認サーバとして Caché インスタンスを使用する方法について説明します。以下の項目について説明します。
この章は、このドキュメントの他の章と編成が異なります。クライアント定義を作成するユーザとサーバを設定するユーザは異なる可能性が高いためです。また、クライアント定義の継続的な作成が必要になる場合があるためです。そのため、クライアント定義の作成タスクは、独立したセクションとしてこの章の最後に収録されています。
Caché 承認サーバの構成要件
OAuth 2.0 承認サーバとして Caché インスタンスを使用するには、次の構成タスクを実行します。
-
Caché にサービスを提供している Web サーバでは、その Web サーバが SSL を使用するように構成します。Caché に付属している専用の Web サーバは、SSL をサポートしていません。SSL を使用するように Web サーバを構成する方法は、このドキュメントの対象外であるため、ここでは取り上げません。
-
サーバが使用する Caché の SSL 構成を作成します。
これはクライアント SSL 構成です。証明書は不要です。この構成は Web サーバへの接続に使用されます。この接続を通じて、承認サーバは、request_uri パラメータが指定する要求オブジェクトにアクセスします。この接続を通じて、承認サーバは、クライアントの JWKS を更新するときに jwks_uri にもアクセスします。クライアントが request_uri パラメータを使用して要求を送信せず、承認サーバが jwks_uri パラメータでクライアントの JWKS を更新しない場合、承認サーバは SSL 構成を必要としません。
SSL 構成の作成の詳細は、"Caché セキュリティ管理ガイド" の “Caché での SSL/TLS の使用法” の章を参照してください。
それぞれの SSL 構成には一意の名前が付いています。参照用に、このドキュメントではこの SSL 構成を sslconfig と呼びますが、一意の名前を任意に付けることができます。
-
以下のサブセクションの説明に従ってサーバ構成を作成します。
-
その後、必要に応じてクライアント定義を作成します。この章の前のセクションを参照してください。
承認サーバの構成
このタスクを実行するには、%Admin_Secure リソースの USE 権限を持つユーザとしてログインする必要があります。
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[サーバ構成] を選択します。
-
[一般] タブで、以下の詳細を指定します。
-
[説明] — 必要に応じて説明を入力します。
-
[発行者エンドポイント] — 承認サーバのエンドポイント URL を指定します。この URL を指定するには、次のオプションの値を入力します。
-
[ホスト名] — 承認サーバのホスト名または IP アドレスを指定します。
-
[ポート] — CSP ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。
-
[接頭語] — CSP ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。
指定した発行者エンドポイントは以下の形式になります。
https://hostname:port/prefix/oauth2
[ポート] の指定を省略すると、コロンが省略されます。同様に、[接頭語] の指定を省略すると、hostname:port と oauth2 の間のスラッシュが 1 つだけになります。
-
-
[対象者は必須] — 承認サーバが承認コードおよび暗黙の要求で aud パラメータを必要とするかどうかを指定します。このチェック・ボックスのチェックを外すと、aud は必須でなくなります。
-
[ユーザ・セッションのサポート] — 承認サーバがユーザ・セッションをサポートするかどうかを指定します。Caché 承認サーバは (CSP セッションではない) ユーザ・セッションをサポートすることができます。その場合、Caché はセッション維持クラス ([セッション維持クラス]) を使用します (既定値が提供されます)。この章で後述する “コードのカスタマイズ・オプション” を参照してください。このチェック・ボックスのチェックを外すと、セッションはサポートされません。
-
[リフレッシュ・トークンの返却] — アクセス・トークンと共にリフレッシュ・トークンが返される条件を指定します。それぞれのビジネス・ケースに適したオプションを選択します。
-
[サポートされている付与タイプ] — この承認サーバがアクセス・トークンを作成するために使用を許可する付与タイプを指定します。少なくとも 1 つ選択します。
-
[OpenID プロバイダ・ドキュメント] — OpenID プロバイダによって提供される URL を以下のように指定します。
-
[サービス・ドキュメント URL] — OpenID プロバイダの使用時に開発者が理解しておく必要があると思われる、人が読める情報を提供する Web ページの URL です。
-
[ポリシー URL] — Relying Party がプロバイダによって提供されるデータを使用する方法について、OpenID プロバイダのポリシーを記述する Web ページの URL です。
-
[サービス条件 URL] — OpenID プロバイダのサービス条件を記述する Web ページの URL です。
-
-
[SSL 構成] — 承認サーバ用に作成した SSL 構成を選択します (例:sslconfig)。
-
-
[スコープ] タブで、以下の詳細を指定します。
-
[スコープ] と [説明] の列を持つテーブル — この承認サーバがサポートしているスコープをすべて指定します。
-
[サポートされていないスコープを許可] — サポートしていないスコープ値を承認サーバが無視するかどうかを指定します。このチェック・ボックスのチェックを外すと、サポートされていないスコープ値が要求に含まれる場合、承認サーバはエラーを返します。この場合、要求は処理されません。このチェック・ボックスにチェックを付けると、承認サーバはスコープを無視して要求を処理します。
-
[既定のスコープ] — アクセス・トークンの要求やクライアント構成でスコープが指定されていない場合に使用する、アクセス・トークンの既定のスコープを指定します。
-
-
[間隔] タブで、以下の詳細を指定します。
-
[アクセス・トークン間隔] — このサーバが発行したアクセス・トークンの有効期限が切れる秒数を指定します。既定値は 3,600 秒です。
-
[承認コード間隔] — このサーバが発行した承認コードの有効期限が切れる秒数を指定します。既定値は 60 秒です。
-
[リフレッシュ・トークン間隔] — このサーバが発行したリフレッシュ・トークンの有効期限が切れる秒数を指定します。既定値は 24 時間 (86,400 秒) です。
-
[セッション終了間隔] — ユーザ・セッションが自動的に終了する秒数を指定します。値 0 はセッションが自動的に終了しないことを意味します。既定値は 24 時間 (86,400 秒) です。
-
[クライアント秘密鍵の有効期間] — このサーバが発行したクライアント秘密鍵の有効期限が切れる秒数を指定します。既定値 (0) は、クライアント秘密鍵が期限切れにならないことを示します。
-
-
[JWT 設定] タブで、以下の詳細を指定します。
-
[X509 資格情報から JWT 設定を作成] — 署名と暗号化で証明書に関連付けられた秘密鍵を使用する場合は、このオプションを選択します。この場合は、付録 “証明書と JWT (JSON Web Token)” の “OAuth 2.0 承認サーバの証明書の使用” も参照してください。
Note:InterSystems では、[X509 資格情報から JWT 設定を作成] オプションが使用されることはまれで、次に説明する既定の動作が代わりに使用されると考えています。
このオプションのチェックを外したままにすると、システムは JWKS (JSON Web Key Set) のペアを生成します。一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。また、Caché は、公開の JWKS をクライアントにコピーして、クライアントが承認サーバから JWT の暗号化およびシグニチャの検証を実行できるようにします。
-
[署名アルゴリズム] — JWT を署名するときに使用するアルゴリズムを選択します。JWT を署名しない場合は空白のままにします。
-
[キー管理アルゴリズム] — JWT を暗号化するときにキー管理で使用するアルゴリズムを選択します。
この選択は、コンテンツの暗号化アルゴリズムを選択する場合にのみ行います。
-
[コンテンツ暗号化アルゴリズム] — JWT を暗号化するときに使用するアルゴリズムを選択します。JWT を暗号化しない場合は空白のままにします。アルゴリズムを選択する場合は、キー管理のアルゴリズムも選択する必要があります。
-
-
[カスタマイズ] タブで、この章で後述する “コードのカスタマイズ・オプション” に従って詳細を指定します
-
[保存] を選択します。
この構成を保存すると、システムは承認サーバが使用する Web アプリケーション (/oauth2) を作成します。この Web アプリケーションは変更しないでください。
コードのカスタマイズ・オプションと全体的な手順
このセクションでは、承認サーバの構成オプションの[カスタマイズ・オプション] セクションにある項目について説明します。サブセクションでは、全体的な手順と既定のクラスについて説明します。
-
[認証クラス] — %OAuth2.Server.AuthenticateOpens in a new tab (既定値) またはそのクラスのカスタム・サブクラスを使用します。
カスタム・サブクラスを定義する場合は、必要に応じて以下のメソッドの一部またはすべてを実装します。
-
BeforeAuthenticate() — 必要に応じてこのメソッドを実装し、認証の前にカスタム処理を実行します。
-
DisplayLogin() — 必要に応じてこのメソッドを実装し、ユーザを識別するログイン・ページを表示します。(一般的でない代替メソッドについては、付録の “DirectLogin() の実装” を参照してください。)
-
DisplayPermissions() — 必要に応じてこのメソッドを実装し、要求された許可をユーザに表示します。
-
AfterAuthenticate() — 必要に応じてこのメソッドを実装し、認証の後にカスタム処理を実行します。
-
-
[ユーザ検証クラス] — %OAuth2.Server.ValidateOpens in a new tab (既定値) を使用するか、次のメソッドを定義するカスタム・クラスを使用します。
-
ValidateUser() (クライアント資格情報を除くすべての付与タイプで使用)
-
ValidateClient() (クライアント資格情報付与タイプで使用)
カスタム・クラスを定義して使用することを強くお勧めします。%OAuth2.Server.ValidateOpens in a new tab クラスは実例で説明するためのものであり、実稼働環境での使用に適していない可能性があります。
-
-
[セッション維持クラス] — OAuth2.Server.SessionOpens in a new tab (既定値) またはそのクラスのカスタム・サブクラスを使用します。既定のセッション・クラスは、HTTP 専用 Cookie を介してユーザ・セッションを維持します。
-
[トークン生成クラス] — %OAuth2.Server.GenerateOpens in a new tab (既定値)、%OAuth2.Server.JWTOpens in a new tab、またはメソッド GenerateAccessToken() を定義するカスタム・クラスを使用します。カスタム・クラスを作成する場合は、ここに記載したクラスの 1 つをサブクラス化すると、使用するメソッドが得られるため便利です。
-
[カスタマイズ・ネームスペース] — カスタマイズ・コードを実行するネームスペースを指定します。
-
[カスタマイズ・ロール] — カスタマイズ・コードを実行するときに使用するロールを 1 つ以上指定します。
カスタム・サブクラスを使用する場合は、“カスタム・メソッドの実装” を参照してください。
Caché 承認サーバが要求を処理する方法
このセクションでは、トークンの承認コード要求または暗黙要求を受け取った Caché 承認サーバが実行する処理について説明します。
-
[認証クラス] オプションで指定されたクラスの BeforeAuthenticate() メソッドを呼び出します。このメソッドの目的は、ユーザの識別を開始する前に要求に変更を加えることです。
既定のクラスでは、このメソッドはスタブです。
-
次に、付与タイプが承認コードまたは暗黙付与である場合、Caché は以下の手順を実行します。
-
[認証クラス] オプションで指定されたクラスの DisplayLogin() を呼び出します。(付録の “DirectLogin() の実装” も参照してください。)
既定のクラスで、DisplayLogin() は単純な HTML ログイン・ページを表示します。
-
ユーザ名が Null でない場合は、[ユーザ検証クラス] オプションで指定されたクラスの ValidateUser() メソッドを呼び出します。このメソッドの目的は、ユーザを検証して、(properties 配列の変更によって) トークン・エンドポイント、Userinfo エンドポイント、トークン・イントロスペクション・エンドポイントによって返されるクレームを準備することです。
既定のクラスでは、このメソッドは例にすぎず、実稼働環境での使用には適していない可能性があります。
-
ユーザが検証されると、[認証クラス] オプションで指定されたクラスの DisplayPermissions() メソッドを呼び出します。このメソッドの目的は、要求された許可の一覧を示すページをユーザに表示することです。
既定のクラスで、このメソッドは許可の一覧を示す単純な HTML ページを表示します。
または、付与タイプがパスワード資格情報である場合、Caché は [ユーザ検証クラス] オプションで指定されたクラスの ValidateUser() メソッドを呼び出します。
または、付与タイプがクライアント資格情報である場合、Caché は [ユーザ検証クラス] オプションで指定されたクラスの ValidateClient() メソッドを呼び出します。
-
-
ユーザが許可を受け入れると、[認証クラス] オプションで指定されたクラスの AfterAuthenticate() メソッドを呼び出します。 このメソッドの目的は、アクセス・トークンを生成する前にカスタム処理を実行することです。
既定のクラスでは、このメソッドはスタブです。
-
[トークン生成クラス] オプションで指定されたクラスの GenerateAccessToken() メソッドを呼び出します。このメソッドの目的は、ユーザに返すアクセス・トークンを生成することです。
既定のクラス (%OAuth2.Server.GenerateOpens in a new tab) で、このメソッドは opaque 文字列のアクセス・トークンを生成します。さらに Caché は代替クラス (%OAuth2.Server.JWTOpens in a new tab) を提供し、このクラスで GenerateAccessToken() は JWT のアクセス・トークンを生成します。
既定のクラス
このセクションでは、Caché 承認サーバの既定のクラスについて説明します。さらに、[トークン生成クラス] の別のオプションとして提供される %OAuth2.Server.JWTOpens in a new tab クラスについても説明します。
%OAuth2.Server.Authenticate (認証クラスの既定値)
%OAuth2.Server.AuthenticateOpens in a new tab クラスは、以下のメソッドを定義します (呼び出し順に記載)。
-
BeforeAuthenticate() はスタブです。OK ステータスを表示して終了します。
-
DisplayLogin() は、[ログイン] ボタンと [キャンセル] ボタンからなる単純なログイン・ページを作成する HTML を記述します。
-
DisplayPermissions() は、要求された許可を表示する単純なページを作成する HTML を記述します。このページには、[許可] ボタンと [キャンセル] が表示されます。
-
AfterAuthenticate() はスタブです。OK ステータスを表示して終了します。
%OAuth2.Server.Validate (ユーザ検証クラスの既定値)
%OAuth2.Server.ValidateOpens in a new tab クラスは、[ユーザ検証クラス] オプションの既定のクラスです。
このクラスは実例で説明するためのものであり、実稼働環境での使用には適していない可能性があります。各自のニーズに応じてこのクラスを置き換えるか、サブクラス化することをお勧めします。
このクラスは、以下のサンプル・メソッドを定義します。
-
ValidateUser() は以下を実行します。
-
指定されたユーザを CACHESYS データベースで検索します。
-
そのユーザのパスワードを検証します。
-
そのユーザに関する情報を含む多次元配列を取得します。
-
この配列を使用して追加のクレームを properties オブジェクトに加えます。
-
-
SupportedClaims() は、この承認サーバがサポートしているクレームの $LIST を返します。既定では、このメソッドは OpenID Connect CoreOpens in a new tab で定義されているクレームのリストを特に返します。
-
ValidateClient() (クライアント資格情報付与タイプで使用) はすべてのクライアントを受け入れて、プロパティは追加しません。
サブクラス内のこれらのメソッドはすべてオーバーライドすることができます。
OAuth2.Server.Session (セッション・クラスの既定値)
%OAuth2.Server.Session クラスは、[セッション維持クラス] オプションの既定のクラスです。このクラスは、HTTP 専用 Cookie を介してセッションを維持します。
このクラスで、GetUser() メソッドは現在のセッションにアクセスしようとします。セッションが存在する場合、このメソッドはそのセッションからユーザ名を取得して返します。セッションが存在しない場合、このメソッドはユーザ名を空の文字列で返し、出力としてエラー・ステータスも返します。
このクラスの追加情報は、クラスリファレンスを参照してください。
%OAuth2.Server.Generate (トークン生成クラスの既定値)
%OAuth2.Server.GenerateOpens in a new tab クラスは、[トークン生成クラス] オプションの既定のクラスです。このクラスは、以下のメソッドを定義します。
-
GenerateAccessToken() は、opaque アクセス・トークンとしてランダムな文字列を生成します。
-
IsJWT() は 0 を返します。
%OAuth2.Server.JWT (アクセス・トークン生成クラスの別のオプション)
%OAuth2.Server.JWTOpens in a new tab クラスは、[トークン生成クラス] オプションで使用できる (またはサブクラス化できる) 別のクラスです。このクラスは、以下のメソッドを定義します。
-
GenerateAccessToken() は JWT を返します。承認サーバの構成 の [JSON Web Token (JWT) の設定] に従って、Caché は JWT を返す前に JWT の署名か暗号化またはその両方を行います。
-
IsJWT() は 1 を返します。
-
CreateJWT() はクレームを含む JSON オブジェクトに基づいて JWT を作成し、承認サーバの構成で規定されているように JWT の署名と暗号化を行います。このメソッドは、OAuth 2.0 および OpenID Connect 使用法の仕様に準拠しており、サブクラス内でオーバーライドするべきではありません。
-
AddClaims() — 要求されたクレームを JWT に追加します。このメソッドは、以下のとおりです。
ClassMethod AddClaims(claims As %ArrayOfObjects, properties As %OAuth2.Server.Properties, json As %DynamicObject)
引数は以下のとおりです。
-
claims は %OAuth2.Server.ClaimOpens in a new tab インスタンスの配列です。
-
properties は、承認サーバが使用するプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。
-
json は JWT を表すダイナミック・オブジェクトです。このオブジェクトはこのメソッドによって変更されます。
-
Caché 承認サーバのカスタム・メソッドの実装
承認サーバの動作をカスタマイズするには、“コードのカスタマイズ・オプション” の説明に従ってクラスを定義します。次に、このセクションの情報に基づいて、カスタマイズする処理手順に応じて、これらのクラスのメソッドを定義します。
これらのサブセクションに続く最後のサブセクションでは、このサーバがクライアント資格情報付与タイプをサポートする必要がある場合にクライアントを検証する方法について説明します。クライアント資格情報付与タイプでは、前述のリストの手順 2 ~ 4 は使用しません。
認証前のオプションのカスタム処理
ここに記載されている情報は、すべての付与タイプに当てはまります。
ユーザを認証する前にカスタム処理を実行するには、認証クラスの BeforeAuthenticate() メソッドを実装します。このメソッドには、以下のシグニチャがあります。
ClassMethod BeforeAuthenticate(scope As %ArrayOfDataTypes,
properties As %OAuth2.Server.Properties) As %Status
以下はその説明です。
-
scope は、元のクライアント要求に含まれるスコープを含む %ArrayOfDataTypesOpens in a new tab のインスタンスです。配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認サーバが使用するプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
必要に応じて、メソッドのこれらの引数のいずれかまたは両方を変更します。どちらの引数もユーザの識別に使用されるメソッドに後で渡されます。このメソッドは %StatusOpens in a new tab を返す必要があります。
通常、このメソッドを実装する必要はありません。ただし、このメソッドの使用事例の1つとして、FHIR® で使用される launch と launch/patient のスコープを実装するのに利用するというようなものがあります。この事例では、特定の患者を含めるようにスコープを調整する必要があります。
ユーザの識別
ここに記載されている情報は、承認コード付与タイプと暗黙付与タイプにのみ当てはまります。
ユーザを識別するには、認証クラスの DisplayLogin() メソッドを実装します。DisplayLogin() メソッドには、以下のシグニチャがあります。
ClassMethod DisplayLogin(authorizationCode As %String,
scope As %ArrayOfDataTypes,
properties As %OAuth2.Server.Properties,
loginCount As %Integer = 1) As %Status
以下はその説明です。
-
authorizationCode
-
scope は、元のクライアント要求に含まれるスコープを含む %ArrayOfDataTypesOpens in a new tab のインスタンスです。このスコープは、BeforeAuthenticate() メソッドによって変更されている可能性があります。配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認サーバが受信し、処理の早い段階にメソッドが変更したプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
-
loginCount は、ログイン試行の回数を示す整数値です。
このメソッドは、ユーザのログイン・フォームを表示する HTML を記述します。ログイン・フォームには、[ユーザ名] フィールド、[パスワード] フィールド、[承認コード] フィールド (非表示) を含める必要があります。既定の DisplayLogin() メソッドは、%CSP.PageOpens in a new tab の InsertHiddenField() メソッドを使用して、承認コードの非表示フィールドを追加します。
通常、このフォームには Login ボタンと Cancel のボタンがあります。これらのボタンによってフォームが送信されます。ユーザが Login ボタンでフォームを送信すると、このメソッドはユーザ名とパスワードを受け入れます。ユーザが Cancel ボタンでフォームを送信すると、承認プロセスは access_denied のエラーを返して終了します。
実装時に、同じページに許可を表示することも選択できます。その場合、メソッドはスコープを表示し、Accept という名前のボタンを使用してページを送信します。
このメソッドは %StatusOpens in a new tab を返す必要があります。
properties.CustomProperties の更新
フォームに名前が p_ で始まる要素が含まれている場合は、その要素に特別な処理を施します。Caché は DisplayLogin() メソッドが返した要素の値を properties.CustomProperties 配列に追加するとき、最初に p_ 接頭語を名前から削除します。例えば、フォームに p_addme という名前の要素が含まれている場合、Caché は addme (および p_addme 要素の値) を properties.CustomProperties 配列に追加します。
必要に応じて properties の他のプロパティをメソッドで直接設定することもできます。
ユーザの検証とクレームの指定
ここに記載されている情報は、クライアント資格情報付与タイプを除くすべての付与タイプに当てはまります。(この付与タイプについては、“クライアントの検証” を参照してください。)
ユーザを検証し、トークン・エンドポイント、Userinfo エンドポイント、トークン・イントロスペクション・エンドポイントによって返されるクレームを指定するには、ユーザ検証クラスの ValidateUser() メソッドを定義します。このメソッドには、以下のシグニチャがあります。
ClassMethod ValidateUser(username As %String,
password As %String,
scope As %ArrayOfDataTypes,
properties As %OAuth2.Server.Properties,
Output sc As %Status) As %Boolean
以下はその説明です。
-
username はユーザが提供したユーザ名です。
-
password はユーザが提供したパスワードです。ユーザが既にログインしている場合、Caché は空の文字列の password でこのメソッドを呼び出します。この場合、メソッドは password が空の文字列であることを検知し、パスワードの確認を試みません。
-
scope は、元のクライアント要求に含まれるスコープを含む %ArrayOfDataTypesOpens in a new tab のインスタンスです。このスコープは、BeforeAuthenticate() メソッドによって変更されている可能性があります。配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認サーバが受信し、処理の早い段階にメソッドが変更したプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
-
sc はこのメソッドが設定したステータス・コードです。このコードを使用してエラーの詳細を伝えます。
このメソッドは、以下を実行します。
-
パスワードが指定されたユーザ名に対応していることを確認します。
-
業務のニーズに応じて scope および properties 引数を適宜使用します。
-
必要に応じて properties オブジェクトを変更してクレーム値を指定するか、新しいクレームを追加します。以下に例を示します。
// Setup claims for profile and email OpenID Connect scopes. Do properties.SetClaimValue("sub",username) Do properties.SetClaimValue("preferred_username",username) Do properties.SetClaimValue("email",email) Do properties.SetClaimValue("email_verified",0,"boolean") Do properties.SetClaimValue("name",fullname)
-
エラーの場合には sc 変数を設定します。
-
ユーザを有効と見なす場合は 1 を返し、それ以外の場合は 0 を返します。
ValidateUser() が値を返すと、承認サーバは properties オブジェクトの以下の値を自動的に設定します (これらの値が欠落している場合)。
-
properties.ClaimValues:
-
iss — 承認サーバの URL
-
sub — client_id
-
exp — 1840 年 12 月 31 日からの秒単位による有効期限
-
-
properties.CustomProperties:
-
client_id — 要求しているクライアントの client_id
-
許可の表示
ここに記載されている情報は、承認コード付与タイプと暗黙付与タイプにのみ当てはまります。
ユーザの検証後に許可を表示するには、認証クラスの DisplayPermissions() メソッドを実装します。このメソッドには、以下のシグニチャがあります。
ClassMethod DisplayPermissions(authorizationCode As %String,
scopeArray As %ArrayOfDataTypes,
currentScopeArray As %ArrayOfDataTypes,
properties As %OAuth2.Server.Properties) As %Status
以下はその説明です。
-
authorizationCode は承認コードです。
-
scopeArray は、ユーザがまだ許可を与えられていない、新たに要求されたスコープです。この引数は、%ArrayOfDataTypesOpens in a new tab のインスタンスです。
配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
currentScopeArray は、ユーザが以前に許可を与えられているスコープです。この引数は、%ArrayOfDataTypesOpens in a new tab のインスタンスです。
配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認サーバが受信し、処理の早い段階にメソッドが変更したプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
このフォームには Accept ボタンと Cancel のボタンが必要です。これらのボタンによってフォームが送信されます。ユーザが Accept ボタンでフォームを送信すると、このメソッドは承認を続行します。ユーザが Cancel ボタンでフォームを送信すると、承認プロセスは終了します。
認証後のオプションのカスタム処理
ここに記載されている情報は、すべての付与タイプに当てはまります。
認証後にカスタム処理を実行するには、認証クラスの AfterAuthenticate() メソッドを実装します。このメソッドには、以下のシグニチャがあります。
ClassMethod AfterAuthenticate(scope As %ArrayOfDataTypes, properties As %OAuth2.Server.Properties) As %Status
以下はその説明です。
-
scope は、承認要求が設定したスコープとこのメソッドが呼び出される前のすべての処理を含む %ArrayOfDataTypesOpens in a new tab のインスタンスです。配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認要求が設定したプロパティおよびクレームとこのメソッドが呼び出される前のすべての処理を含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
必要に応じて、メソッドのこれらの引数のいずれかまたは両方を変更します。具体的には、プロパティを認証 HTTP 応答に追加することもできます。その場合は、プロパティを properties.ResponseProperties に追加します。
通常、このメソッドを実装する必要はありません。ただし、このメソッドの使用事例の1つとして、FHIR® で使用される launch と launch/patient のスコープを実装するのに利用するというようなものがあります。この事例では、特定の患者を含めるようにスコープを調整する必要があります。
アクセス・トークンの生成
ここに記載されている情報は、すべての付与タイプに当てはまります。
アクセス・トークンを生成するには、トークン生成クラスの GenerateAccessToken() メソッドを実装します。このメソッドには、以下のシグニチャがあります。
ClassMethod GenerateAccessToken(properties As %OAuth2.Server.Properties, Output sc As %Status) As %String
以下はその説明です。
-
properties は、承認サーバが受信し、処理の早い段階にメソッドが変更したプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
-
出力として返される sc は、このメソッドが設定したステータス・コードです。この変数を設定してエラーの詳細を伝えます。
このメソッドはアクセス・トークンを返します。このアクセス・トークンは properties 引数に基づきます。このメソッドで、クレームを JSON 応答オブジェクトに追加することもできます。そのためには、properties オブジェクトの ResponseProperties 配列プロパティを設定します。
クライアントの検証
ここに記載されている情報は、クライアント資格情報付与タイプにのみ当てはまります。
クライアント資格情報を検証し、トークン・エンドポイント、Userinfo エンドポイント、トークン・イントロスペクション・エンドポイントによって返されるクレームを指定するには、ユーザ検証クラスの ValidateClient() メソッドを定義します。このメソッドには、以下のシグニチャがあります。
ClassMethod ValidateClient(clientId As %String,
clientSecret As %String,
scope As %ArrayOfDataTypes,
Output properties As %OAuth2.Server.Properties,
Output sc As %Status) As %Boolean
以下はその説明です。
-
clientId はクライアント ID です。
-
clientSecret はクライアント秘密鍵です。
-
scope は、元のクライアント要求に含まれるスコープを含む %ArrayOfDataTypesOpens in a new tab のインスタンスです。このスコープは、BeforeAuthenticate() メソッドによって変更されている可能性があります。配列キーはスコープ値であり、配列値はスコープ値の対応する表示形式です。
-
properties は、承認サーバが受信し、処理の早い段階にメソッドが変更したプロパティとクレームを含む %OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。“%OAuth2.Server.Properties オブジェクトの詳細” を参照してください。
-
sc はこのメソッドが設定したステータス・コードです。このコードを使用してエラーの詳細を伝えます。
このメソッドは、以下を実行します。
-
クライアント秘密鍵が指定されたクライアント ID に対応していることを確認します。
-
業務のニーズに応じて scope および properties 引数を適宜使用します。
-
必要に応じて、properties オブジェクトを変更してクレーム値を指定します。以下に例を示します。
// Setup claims for profile and email OpenID Connect scopes. Do properties.SetClaimValue("sub",username) Do properties.SetClaimValue("preferred_username",username) Do properties.SetClaimValue("email",email) Do properties.SetClaimValue("email_verified",0,"boolean") Do properties.SetClaimValue("name",fullname)
-
エラーの場合には sc 変数を設定します。
-
ユーザを有効と見なす場合は 1 を返し、それ以外の場合は 0 を返します。
ValidateClient() が値を返すと、承認サーバは properties オブジェクトの以下の値を自動的に設定します (これらの値が欠落している場合)。
-
properties.ClaimValues:
-
iss — 承認サーバの URL
-
sub — client_id
-
exp — 1840 年 12 月 31 日からの秒単位による有効期限
-
-
properties.CustomProperties:
-
client_id — 要求しているクライアントの client_id
-
%OAuth2.Server.Properties オブジェクトの詳細
前のセクションで説明したメソッドでは、properties 引数を使用していますが、この引数は%OAuth2.Server.PropertiesOpens in a new tab のインスタンスです。%OAuth2.Server.PropertiesOpens in a new tab クラスの目的は、承認サーバ・コード内のメソッド間で受け渡す必要がある情報を保持することです。このセクションでは、このクラスの基本プロパティとクレーム関連のプロパティについて説明します。このクラスには、クレームを操作するメソッドもあります。これらのメソッドについては、最後のサブセクションで説明します。
基本プロパティ
%OAuth2.Server.PropertiesOpens in a new tab クラスには以下の基本プロパティがあります。これらのプロパティは、カスタム・コードの内部処理の情報の伝達に使用されます。
Property RequestProperties as array of %String (MAXLEN=16384);
承認要求のクエリ・パラメータが含まれています。
このプロパティは配列であるため、通常の配列インタフェースを使用して操作します。(これは、このクラスの他のプロパティでも同様です。)例えば、クエリ・パラメータの値を取得するには、RequestProperties.GetAt(parmname) を使用します。ここで、parmname はクエリ・パラメータの名前です。
Property ResponseProperties as array of %String (MAXLEN=1024);
トークン要求への JSON 応答オブジェクトに追加されるプロパティがすべて含まれます。このプロパティは必要に応じて設定します。
Property CustomProperties as array of %String (MAXLEN=1024);
さまざまなカスタマイズ・コード間の通信に使用されるカスタム・プロパティが含まれます。“properties.CustomProperties の更新” セクションを参照してください。
Property ServerProperties as array of %String (MAXLEN=1024);
承認サーバがカスタマイズ・コードと共有するプロパティが含まれます。認証クラスで使用するために、クライアント・プロパティの logo_uri、client_uri、policy_uri、tos_uri がこの方法で共有されます。
クレーム関連のプロパティ
%OAuth2.Server.PropertiesOpens in a new tab クラスには、IntrospectionClaims、IDTokenClaims、UserinfoClaims、JWTClaims プロパティがあります。これらのプロパティは、必須のクレーム、特にカスタム・クレームに関する情報を伝達します。
このクラスには、実際のクレーム値を伝達する ClaimValues プロパティもあります。カスタマイズ・コードでクレームの値を設定する必要があります (通常は ValidateUser クラス内で)。
以下のリストで、これらのプロパティについて説明します。
Property IntrospectionClaims as array of %OAuth2.Server.Claim;
イントロスペクション・エンドポイントが返すクレームを指定します (必須クレームの基本セットの範囲を超えて指定)。承認サーバは scope、client_id、username、token_type、exp、iat、nbf、sub、aud、iss、jti クレームを (このプロパティに含まれていない場合でも) 返します。
ほとんどの場合、このプロパティの値には空の文字列を使用できます。このプロパティは、claims 要求パラメータをサポートするために指定されます (詳細は、OpenID Connect CoreOpens in a new tab のセクション 5.5 を参照してください)。
形式的にはこのプロパティは配列であり、その配列キーは (ClaimValues プロパティの名前と一致する) クレーム名であり、その配列値は %OAuth2.Server.ClaimOpens in a new tab のインスタンスです。%OAuth2.Server.ClaimOpens in a new tab クラスには以下のプロパティがあります。
-
Essential
property Essential as %Boolean [ InitialExpression = 0 ];
クレームが必須、任意選択のいずれであるかを指定します。値 1 は必須を意味し、値 0 は任意選択を意味します。
-
Values
property Values as list of %String(MAXLEN=2048);
このクレームの許容値のリストを指定します。
通常、クレームの値は ValidateUser クラスで設定されます。
Property IDTokenClaims as array of %OAuth2.Server.Claim;
承認サーバが IDToken で必要とするクレームを指定します (必須クレームの基本セットの範囲を超えて指定)。承認サーバは、iss、sub、exp、aud、azp クレームを (このプロパティに含まれていない場合でも) 必要とします。
このプロパティはオブジェクトの配列です。詳細は、IntrospectionClaims プロパティの項目を参照してください。
ほとんどの場合、このプロパティの値には空の文字列を使用できます。このプロパティは、claims 要求パラメータをサポートするために指定されます (詳細は、OpenID Connect CoreOpens in a new tab のセクション 5.5 を参照してください)。
Property UserinfoClaims as array of %OAuth2.Server.Claim;
Userinfo エンドポイントが返すクレームを指定します (必須クレームの基本セットの範囲を超えて指定)。承認サーバは sub クレームを (このプロパティに含まれていない場合でも) 返します。
ほとんどの場合、このプロパティの値には空の文字列を使用できます。このプロパティは、OpenID Connect Core のセクション 5.5 をサポートするために提供されます。
このプロパティはオブジェクトの配列です。詳細は、IntrospectionClaims プロパティの項目を参照してください。
クレームは、スコープと要求のクレーム・パラメータに基づいて定義されます。クレームの戻り値は、ClaimValues プロパティの同じキーを持ちます。通常、クレームの値は ValidateUser クラスで設定されます。
Property JWTClaims as array of %OAuth2.Server.Claim;
JWT ベースの既定のアクセス・トークン・クラス (%OAuth2.Server.JWTOpens in a new tab) が返す JWT アクセス・トークンで必要とされるクレームを必須クレームの基本セットの範囲を超えて指定します。承認サーバは、iss、sub、exp、aud、jti クレームを (このプロパティに含まれていない場合でも) 返します。
このプロパティはオブジェクトの配列です。詳細は、IntrospectionClaims プロパティの項目を参照してください。
このクレームはカスタマイズ・コードによって定義されます。通常、クレームの値は ValidateUser クラスで設定されます。
property ClaimValues as array of %String(MAXLEN=1024);
実際のクレーム値とその型を指定します。このプロパティを操作するには、次のセクションのメソッドを使用します。
このプロパティを直接操作する必要がある場合は、このプロパティが以下の特徴を持つ配列であることに注意してください。
-
配列キーはクレーム名です。
-
配列値は $LISTBUILD(type,value) の形式をとります。ここで、type は値のタイプを保持し、value は実際の値を保持します。type には "string"、"boolean"、"number"、または "object" を指定できます。 type が "object" の場合、value は文字列としてシリアル化された JSON オブジェクトとなります。
value は $LIST 構造となります。この場合、クレーム値はシリアル化されるときに JSON 配列としてシリアル化され、それぞれの配列項目は指定された type となります。
クレームを操作するメソッド
%OAuth2.Server.PropertiesOpens in a new tab クラスは、ClaimValues プロパティの操作を簡素化するために使用できるインスタンス・メソッドも提供します。
Method SetClaimValue(name As %String, value As %String, type As %String = "string")
name 引数で指定したクレームの値を設定することで、ClaimValues プロパティを更新します。type 引数はクレームの型を示します。型には "string" (既定値)、"boolean"、"number"、"object" があります。 type が "object" の場合、value は文字列としてシリアル化された JSON オブジェクトでなければなりません。
value は $LIST 構造にすることもできます。この場合、クレーム値はシリアル化されるときに JSON 配列としてシリアル化され、それぞれの配列項目は指定された type となります。
Method RemoveClaimValue(name As %String)
name 引数で指定したクレームを削除することで、ClaimValues プロパティを更新します。
Method GetClaimValue(name As %String, output type) As %String
ClaimValues プロパティを調べて、name 引数で指定されたクレームの値を返します。出力として返される type 引数はクレームの型を示します。SetClaimValue() を参照してください。
Method NextClaimValue(name As %String) As %String
指定されたクレームの後にある (ClaimValues プロパティの) 次のクレームの名前を返します。
承認サーバ・エンドポイントの場所
OAuth 2.0 承認サーバとして Caché インスタンスを使用する場合、承認エンドポイントの URL は次のようになります。
エンドポイント | URL |
---|---|
発行者エンドポイント | https://serveraddress/oauth2 |
承認エンドポイント | https://serveraddress/oauth2/authorize |
トークン・エンドポイント | https://serveraddress/oauth2/token |
Userinfo エンドポイント | https://serveraddress/oauth2/userinfo |
トークン・イントロスペクション・エンドポイント | https://serveraddress/oauth2/introspection |
トークン取り消しエンドポイント | https://serveraddress/oauth2/revocation |
いずれの場合も、serveraddress は Caché インスタンスを実行しているサーバの IP アドレスまたはホスト名になります。
Caché OAuth 2.0 承認サーバでのクライアント定義の作成
このセクションでは、クライアントを動的に登録していない場合に、Caché OAuth 2.0 承認サーバでクライアント定義を作成する方法について説明します。まず、この章の前述の説明に従って Caché OAuth 2.0 承認サーバを設定します。管理ポータルで以下の手順を実行します。
-
[システム管理]→[セキュリティ]→[OAuth2.0]→[サーバ構成] を選択します。
-
[クライアント構成] ボタンをクリックしてクライアント記述を表示します。このテーブルは最初は空です。
-
[一般] タブで、以下の詳細を指定します。
-
[名前] — このクライアントの一意の名前を指定します。
-
[説明] — 必要に応じて説明を入力します。
-
[クライアント・タイプ] — このクライアントのタイプを指定します。選択項目には [パブリック] (パブリック・クライアント、RFC 6749Opens in a new tab に準拠)、[機密] (機密クライアント、RFC 6749 に準拠)、[リソース] (専用のリソース・サーバ) があります。
-
[リダイレクト URL] — このクライアントで予期される 1 つ以上のリダイレクト URL。
-
[サポートされている付与タイプ] — このクライアントがアクセス・トークンを作成するために使用できる付与タイプを指定します。少なくとも 1 つ選択します。
-
[サポートされるレスポンス・タイプ] — クライアントが限定使用するOAuth 2.0 response_type値を選択します。
-
[認証タイプ] — 承認サーバへの HTTP 要求で使用する認証タイプを選択します (RFC 6749Opens in a new tab または OpenID Connect CoreOpens in a new tab のセクション 9 で規定)。以下のいずれかを選択します。
-
なし
-
基本
-
フォームエンコードされた本文
-
クライアント秘密鍵 JWT
-
秘密鍵 JWT
-
-
[認証署名アルゴリズム] — トークン・エンドポイントでこのクライアントを認証するために使用される JWT の署名に必要なアルゴリズムを選択します ([認証タイプ] が [クライアント秘密鍵 JWT] または [秘密鍵 JWT] である場合)。オプションを選択しない場合、OpenID プロバイダおよび Relying Party でサポートされる任意のアルゴリズムが使用されます。
-
-
必要な場合は、[クライアント資格情報] タブを選択し、次の詳細を表示します。
-
[クライアント ID] — RFC 6749 で規定されているクライアント ID。Caché がこの文字列を生成します。
-
[クライアント秘密鍵] — RFC 6749 で規定されているクライアント秘密鍵。Caché がこの文字列を生成します。
-
-
[クライアント情報] タブで、以下の詳細を指定します。
-
[起動 URL] — このクライアントの起動に使用する URL を指定します。状況によっては、この値をクライアントの識別に使用することも、aud クレームの値として使用することもできます。
-
[承認の表示] セクション:
-
[クライアント名] — エンド・ユーザに表示するクライアントの名前を指定します。
-
[ロゴ URL] — クライアント・アプリケーションのロゴを参照する URL を指定します。このオプションを指定すると、承認サーバは承認中にこのイメージをエンド・ユーザに表示します。このフィールドの値は、有効なイメージ・ファイルを指している必要があります。
-
[クライアント・ホーム・ページ] — クライアントのホーム・ページの URL を指定します。このフィールドの値は、有効な Web ページを指している必要があります。このオプションを指定すると、承認サーバは、この URL を分かりやすい形でエンド・ユーザに示します。
-
[ポリシー URL] — プロファイル・データの取り扱い方法を確認できるよう Relying Party Client エンド・ユーザに提供する URL を指定します。このフィールドの値は、有効な Web ページを指している必要があります。
-
[サービス条件の URL] — Relying Party のサービス条件を確認できるように Relying Party Client がエンド・ユーザに提供する URL を指定します。このフィールドの値は、有効な Web ページを指している必要があります。
-
-
[連絡先電子メール] — クライアント・アプリケーションの責任者への連絡に使用する適切な電子メール・アドレスをコンマで区切ったリストです。
-
[既定の最長経過時間] — 既定の最長認証経過時間 (秒単位) を指定します。このオプションを指定した場合、最長認証経過時間に達したとき、エンド・ユーザをアクティブに再認証する必要があります。max_age 要求パラメータは、この既定値をオーバーライドします。このオプションを省略した場合に、既定で最長認証経過時間は設定されません。
-
[既定のスコープ] — アクセス・トークン要求の既定のスコープを空白で区切ったリストで指定します。
-
-
[JWT 設定] タブで、以下の詳細を指定します。
-
[JSON Web Token (JWT) の設定] — 承認サーバから JWT のシグニチャを検証し、承認サーバに送信される JWT を暗号化するためにクライアントが使用する公開鍵のソースを指定します。
既定では、ダイナミック登録プロセスは JWKS (JSON Web Key Set) のペアを生成します。一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。ダイナミック登録プロセスは、公開の JWKS のクライアントへのコピーも実行します。
その他のオプションは以下のとおりです。
-
[URL から JWKS] — 公開の JWKS を指す URL を指定した後、Caché に JWKS をロードします。
-
[ファイルから JWKS] — 公開の JWKS を含むファイルを選択し、そのファイルを Caché にロードします。
-
[X509 証明書] — 詳細については、付録 “証明書と JWT (JSON Web Token)” の “OAuth 2.0 承認サーバの証明書の使用” を参照してください。
これらのオプションのいずれかにアクセスするには、まず [ダイナミック登録以外のソース] を選択します。
-
-
-
[保存] を選択します。
JWT で使用するキーの回転
ほとんどの場合、新しい公開/秘密鍵ペアを承認サーバに生成させることができます。これは、非対称の RS256、RS384、および RS512 の各アルゴリズムに使用する RSA 鍵にのみ適用されます。(例外は、[X509 証明書] として、[ダイナミック登録以外のソース] を指定する場合です。この場合、新しいキーは生成できません。)
新しい公開/秘密鍵ペアの生成は、キーの回転と呼ばれています。このプロセスは、新しい秘密 RSA 鍵および関連する公開 RSA 鍵を秘密と公開の JWKS に追加します。
承認サーバでキーの回転を実行すると、承認サーバは新しい秘密 RSA 鍵を使用して、クライアントに送信する JWT に署名します。同様に、承認サーバは新しい公開 RSA 鍵を使用して、クライアントに送信する JWT を暗号化します。承認サーバは、クライアントから受信した JWT を解読するために新しい RSA 鍵を使用しますが、これが失敗したら古い RSA 鍵を使用するため、古い公開 RSA 鍵を使用して作成された JWT を解読できます。
最後に、クライアントから受信した署名済み JWT を承認サーバが検証できない場合、承認サーバにクライアントの公開の JWKS の URL があると、承認サーバは新しい公開の JWKS を取得し、署名の検証を再試行します。(ダイナミック Discovery を使用した場合や、構成で [URL から JWKS] オプションが指定された場合、承認サーバはクライアントの公開の JWKS の URL を持っています。それ以外の場合には承認サーバはこの URL を持っていません。)
承認サーバのキーを回転するには、以下の手順を実行します。
-
[システム管理]→[セキュリティ]→[OAuth 2.0]→[サーバ構成] を選択します。
承認サーバの構成が表示されます。
-
[キーの回転] ボタンを選択します。
対称の HS256、HS384、および HS512 の各アルゴリズムは、常に対称鍵としてクライアントの秘密鍵を使用します。
承認サーバのキーの回転の API
承認サーバでキーをプログラムによって回転させるには、OAuth2.Server.ConfigurationOpens in a new tab の RotateKeys() メソッドを呼び出します。
新しいクライアントの JWKS を取得するには、OAuth2.Server.ClientOpens in a new tab の UpdateJWKS() メソッドを呼び出します。
これらのメソッドの詳細は、クラス・リファレンスを参照してください。
クライアントからの新しい公開の JWKS の取得
ほとんどの場合、クライアントは JWKS の公開/秘密鍵ペアを生成します。公開の JWKS を承認サーバが受信する方法はさまざまです。1 つの方法は、クライアントが URL で公開の JWKS を提供する方法です。“Caché OAuth 2.0 承認サーバでのクライアント定義の作成” の [URL から JWKS] オプションを参照してください。
クライアントが [URL から JWKS] で定義されていて、クライアントが JWKS の新しいペアを生成する場合、同じ URL から新しい公開の JWKS を承認サーバに取得させることができます。そのためには、以下の操作を実行します。
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[サーバ構成] を選択します。
承認サーバの構成が表示されます。
-
[JWKS の更新] ボタンを選択します。
クライアントが [URL から JWKS] で定義されておらず、クライアントが JWKS の新しいペアを生成する場合、公開の JWKS を取得し、これを承認サーバに送信し、ファイルからロードする必要があります。