OAuth 2.0 および OpenID Connect

アクセス・トークンの形態

InterSystems IRIS は、次の 2 種類のアクセス・トークンをサポートしています。

• JSON Web Token (JWT)。JWT は JSON オブジェクトです。JWT はデジタル署名か暗号化またはその両方を行うことができます。

  JWT の 1 種が ID トークンであり、OpenID Connect に固有のトークンです。

  JWT は署名か暗号化またはその両方を行うことができます。

• opaque アクセス・トークン (別名：参照トークン)。この形態のアクセス・トークンは、他の場所、具体的には承認サーバに格納されているトークンの識別子です。この識別子は長いランダムな文字列であり、これには推測を困難にするという意図が込められています。

クレーム

アクセス・トークンには、ユーザまたはクライアントの ID の伝達や、トークンの有効期限、予期される発行者名、予期される対象者、スコープなどのメタデータの伝達を行う一連のクレームが含まれています。OpenID Connect Core の仕様ではクレームの標準セットが定義されていますが、その他のクレームも使用できます。

JWT および JWKS

上記のように、JWT は署名か暗号化またはその両方を行うことができます。ほとんど場合、OAuth 2.0 フレームワークの参加者は、この目的で JWKS (JSON Web Key Set) のペアを使用します。JWKS の任意のペアにおいて、一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。

それぞれの参加者は、秘密の JWKS を持っていて、対応する公開の JWKS を他の参加者に提供します。秘密の JWKS の所有者は、その JWKS を使用して、送信 JWT に署名し、受信 JWT を解読します。他の参加者は、以下の図に示すように、対応する公開の JWKS を使用して送信 JWT を暗号化し、受信 JWT の署名を確認します。

サーバ記述の作成 (Discovery の使用)

1. 管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。

   このインスタンスで利用可能なサーバ記述を示すページが表示されます。どの行でも、[発行者エンドポイント] 列はサーバ記述の発行者エンドポイントを示します。[クライアント数] 列は、指定されたサーバ記述に関連付けられたクライアント構成の数を示します。最後の列では [クライアント構成] リンクにより、関連付けられているクライアント構成の作成、表示、編集、削除を行うことができます。

2. [サーバ構成の作成] を選択します。

   管理ポータルに、サーバ記述の詳細を入力できる新たなページが表示されます。

3. 以下の詳細情報を指定します。

   • [発行者エンドポイント] (必須) — 承認サーバの識別に使用するエンドポイントの URL を入力します。

   • [SSL/TLS 構成] (必須) — ダイナミック・クライアント登録要求時に使用する SSL/TLS 構成を選択します。

   • [登録アクセス・トークン] — オプションで、ダイナミック・クライアント登録要求を承認するためのベアラー・トークンとして使用する初期登録アクセス・トークンを入力します。

4. [検出と保存] を選択します。

   次に InterSystems IRIS は、指定された承認サーバと通信し、サーバ記述に必要な情報を取得して、情報を保存します。

   管理ポータルにサーバ記述の一覧が再度表示されます。

サーバ記述の手動による作成 (Discovery なし)

(Discovery を使用せずに) 手動でサーバ記述を作成するには、まずサーバ記述ページを表示して (上記の手順 1 および 2)、次に [手動] を選択します。これによって、以下のようにページに多数のオプション・セットが表示されます。

• [発行者エンドポイント] (必須) — 承認サーバの識別に使用するエンドポイントの URL を入力します。

• [承認エンドポイント] (必須) — 承認サーバに承認コードを要求するときに使用するエンドポイント URL を入力します。

• [トークン・エンドポイント] (必須) — 承認サーバにアクセス・トークンを要求するときに使用するエンドポイント URL を入力します。

• [Userinfo エンドポイント] (必須) — 承認サーバのアクセス・トークンを使用して承認の Userinfo 要求を行うときに使用するエンドポイント URL を入力します。

• [トークン・イントロスペクション・エンドポイント] — client_id と client_secret を使用して承認のトークン・イントロスペクション要求を行うときに使用するエンドポイント URL を入力します。RFC 7662Opens in a new tab を参照してください。

• [トークン取り消しエンドポイント] — client_id と client_secret を使用して承認のトークン取り消し要求を行うときに使用するエンドポイント URL を入力します。RFC 7009Opens in a new tab を参照してください。

• [JSON Web Token (JWT) の設定] — JWT のシグニチャの検証および解読を承認サーバからクライアントが行うために使用する公開鍵のソースを指定します。

  既定では、承認サーバは JWKS (JSON Web Key Set) のペアを生成します。一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。また、サーバ記述を作成するプロセスでも、JWT のシグニチャの検証と暗号化に使用するために、承認サーバからクライアントに公開の JWKS がコピーされます。

  • [URL から JWKS] — 公開の JWKS を指す URL を指定した後、InterSystems IRIS に JWKS をロードします。

  • [ファイルから JWKS] — 公開の JWKS を含むファイルを選択し、そのファイルを InterSystems IRIS にロードします。

  • [X509 証明書] — 詳細は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 承認サーバの証明書の使用" を参照してください。

  これらのオプションのいずれかにアクセスするには、まず [ダイナミック登録以外のソース] を選択します。

これらの値を指定し、[保存] を選択します。

クライアントの構成および動的な登録

ここでは、クライアントの構成を作成し、クライアントを動的に登録する方法について説明します。

1. 管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。

   管理ポータルにサーバ記述の一覧が表示されます。

2. このクライアント構成を関連付けるサーバ記述の行で [クライアント構成] リンクをクリックします。

   管理ポータルに、サーバ記述に関連付けられているクライアント構成の一覧が表示されます。これは、最初は空のリストです。

3. [クライアント構成の作成] をクリックします。

   管理ポータルに、詳細を入力できる新たなページが表示されます。

4. [一般] タブで、以下の詳細を指定します。

   • [アプリケーション名] — アプリケーションの短い名前を指定します。

   • [クライアント名] — エンド・ユーザに表示するクライアント名を指定します。

   • [説明] — アプリケーションの説明を入力します (オプション)。

   • [有効] — このアプリケーションが使用されないようにする場合は、このチェック・ボックスのチェックを外すこともできます。

   • [クライアント・タイプ] — 以下のいずれかを選択します。

     • [機密] — RFC 6749Opens in a new tab に従って、クライアントを機密クライアントに指定します。

       このページでは、クライアントが承認コード付与タイプを使用するシナリオについて主に説明します。このシナリオでは、[クライアント・タイプ] に [機密] を指定します。その他の付与タイプは、"バリエーション" を参照してください。

     • [パブリック] — RFC 6749Opens in a new tab に従って、クライアントをパブリック・クライアントに指定します。

     • [リソース・サーバ] — クライアントを専用のリソース・サーバに指定します。

   • [SSL/TLS 構成] — クライアントで使用するために作成した SSL 構成を選択します (例：sslconfig)。

   • [応答を受信するために承認サーバに対して指定されるクライアント URL] — InterSystems IRIS OAuth 2.0 クライアントで必要とされる内部宛先の URL を指定します。この宛先でアクセス・トークンが保存され、ブラウザは元のクライアント・アプリケーションへリダイレクトされます。

     この URL を指定するには、次のオプションの値を入力します。

     • [ホスト名] — 承認サーバのホスト名または IP アドレスを指定します。

     • [ポート] — Web ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。

     • [接頭語] — Web ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。

     指定した URL は以下の形式をとります。

     https://hostname:port/prefix/csp/sys/oauth2/OAuth2.Response.cls
     

     

     [ポート] の指定を省略すると、コロンが省略されます。同様に、[接頭語] の指定を省略すると、hostname:port と csp の間のスラッシュが 1 つだけになります。(さらに、[TLS/SSL を使用する] オプションのチェックを外すと、URL は https ではなく http で始まります。)

   • [TLS/SSL を使用する] — リダイレクト・ページを開くときに TLS/SSL を使用しない正当な理由がある場合を除き、このオプションを選択します。

   • [フロントチャネルログアウト URL] — 必要に応じて HTTP ベースのフロントチャネル・ログアウト URL を指定します。サーバはこの URL を登録し、それを使用してクライアント上のユーザをログアウトします。フロントチャネル・ログアウトをサポートしないクライアントを作成するには、この URL を空白のままにします。このフィールドの上のボックスには指定した URL が表示され、それに 'IRISLogout=end' が追記されます。

     Note:

     InterSystems IRIS クライアントでフロントチャネル・ログアウトがサポートされるようにするには、クライアント・アプリケーションの [セッション Cookie のスコープ] を [なし] に設定します。アプリケーションの設定の構成の詳細は、"アプリケーションの作成および編集" を参照してください。

   • [必要な付与タイプ] — クライアントで限定使用する OAuth 2.0 付与タイプを指定します。

   • [認証タイプ] — 承認サーバへの HTTP 要求で使用する認証タイプを選択します (RFC 6749Opens in a new tab または OpenID Connect CoreOpens in a new tab のセクション 9 で規定)。[なし]、[基本]、[フォームエンコードされた本文]、[クライアント秘密鍵 JWT]、または [秘密鍵 JWT] のいずれかを選択します。

   • [認証サーバがログアウトURLを呼び出す際に iss および sid クエリパラメータが必要] — 承認サーバからフロントチャネル・ログアウト URL が呼び出されるときにクエリ・パラメータとして iss (発行者) と sid (セッション ID) を必要とするには、このオプションを選択します。

   • [認証署名アルゴリズム] — トークン・エンドポイントでこのクライアントを認証するために使用される JWT の署名に必要なアルゴリズムを選択します ([認証タイプ] が [クライアント秘密鍵 JWT] または [秘密鍵 JWT] である場合)。オプションを選択しない場合、OpenID プロバイダおよび Relying Party でサポートされる任意のアルゴリズムが使用されます。

5. [クライアント情報] タブで、以下の詳細を指定します。

   • [ロゴ URL] — クライアント・アプリケーションのロゴの URL です。

   • [クライアント・ホームページ URL] — クライアント・アプリケーションのホーム・ページの URL です。

   • [ポリシー URL] — クライアント・アプリケーションのポリシー・ドキュメントの URL です。

   • [サービス条件の URL] — クライアント・アプリケーションのサービス条件ドキュメントの URL です。

   • [デフォルトのスコープ] — アクセス・トークン要求の既定のスコープを空白で区切ったリストで指定します。この既定値は、承認サーバで許可されているスコープと一致している必要があります。

   • [連絡先電子メール] — クライアント・アプリケーションの責任者への連絡に使用する適切な電子メール・アドレスをコンマで区切ったリストです。

   • [既定の最長経過時間] — 既定の最長認証経過時間 (秒単位) を指定します。このオプションを指定した場合、最長認証経過時間に達したとき、エンド・ユーザをアクティブに再認証する必要があります。max_age 要求パラメータは、この既定値をオーバーライドします。このオプションを省略した場合に、既定で最長認証経過時間は設定されません。

6. [JWT 設定] タブで、以下の詳細を指定します。

   • [X509 資格情報から JWT 設定を作成] — 証明書に関連付けた秘密鍵を署名と暗号化で使用する場合は、このオプションを選択します。この場合は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 クライアントの証明書の使用" も参照してください。

     Note:

     インターシステムズでは、[X509 資格情報から JWT 設定を作成] オプションが使用されることはまれで、次に説明する既定の動作が代わりに使用されると考えています。

     このオプションのチェックを外したままにすると、システムは JWKS (JSON Web Key Set) のペアを生成します。一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。ダイナミック登録プロセスでは、公開の JWKS を承認サーバにもコピーし、承認サーバがこのクライアントから JWT の暗号化およびシグニチャの検証を実行できるようにします。

   • [署名アルゴリズム] — 署名済み JWT の作成に使用する署名アルゴリズムを選択します。JWT を署名しない場合は空白のままにします。

   • [暗号化アルゴリズム] — 暗号化された JWT の作成に使用する暗号化アルゴリズムを選択します。JWT を暗号化しない場合は空白のままにします。値を選択する場合は、[キー・アルゴリズム] も指定する必要があります。

   • [キー・アルゴリズム] — 暗号化された JWT の作成に使用するキー管理アルゴリズムを選択します。JWT を暗号化しない場合は空白のままにします。

7. 承認サーバがダイナミック登録をサポートする場合は、入力したすべてのデータを再確認した後、[ダイナミック登録と保存] をクリックします。次に、InterSystems IRIS は承認サーバを接続し、クライアントを登録して、クライアント ID とクライアント秘密鍵を取得します。

   承認サーバがダイナミック登録をサポートしない場合については、この後のサブセクションを参照してください。

クライアントの構成 (ダイナミック登録なし)

承認サーバがダイナミック登録をサポートしない場合は、上記の最後の手順に代わって以下の手順を実行します。

1. [クライアント資格情報] タブを選択し、次の詳細を指定します。

   • [クライアント ID] — 承認サーバが提供したクライアント ID を入力します。

   • [クライアント秘密鍵] — 承認サーバが提供したクライアント秘密鍵を入力します。[クライアント・タイプ] が [機密] の場合は、この値が必須となります。

     このページでは、クライアントが承認コード付与タイプを使用するシナリオについて主に説明します。このシナリオでは、[クライアント秘密鍵] の値を指定します。その他の付与タイプは、"バリエーション" を参照してください。

   [クライアント ID 発行日時]、[クライアント秘密鍵有効期限]、および [登録クライアント URI] の値を入力しないでください。

2. [保存] を選択します。

メソッドの詳細

このサブセクションでは、前のサブセクションで使用したメソッドについて詳しく説明します。

IsAuthorized()

場所：このメソッドはクラス %SYS.OAuth2.AccessTokenOpens in a new tab にあります。

ClassMethod IsAuthorized(applicationName As %String, 
                         sessionId As %String, 
                         scope As %String = "", 
                         Output accessToken As %String, 
                         Output IDToken As %String, 
                         Output responseProperties, 
                         Output error As %OAuth2.Error) As %Boolean

このクライアントおよびセッションのアクセス・トークンがローカルに保存され、さらにそのアクセス・トークンが scope 引数で提供されるすべてのスコープを承認する場合、このメソッドは 1 を返します。(このメソッドは IRISSYS データベースでアクセス・トークンを探します。これらのトークンは、有効期限が切れると自動的に削除されます。)

それ以外の場合、このメソッドは 0 を返します。

引数は以下のとおりです。

• applicationName はクライアント・アプリケーションの名前です。

• sessionId はセッション ID を指定します。既定のセッション (%session.SessionId) をオーバーライドする場合のみこれを指定します。

• scope は、スペースで区切られたスコープのリストです。例えば、"openid profile scope1 scope2" のような形式をとります。

  openid および profile は、OpenID Connect CoreOpens in a new tab で定義されている特別なスコープです。

• 出力として返される accessToken はアクセス・トークンです (存在する場合)。

• 出力として返される IDToken は ID トークンです (存在する場合)。(これは、OpenId ConnectOpens in a new tab を使用している場合にのみ適用されます。具体的には、要求でスコープ openid が使用された場合です。)ID トークンは JWT です。

• 出力として返される responseProperties は、応答のパラメータを含む多次元配列です。この配列の構造は以下のとおりです。

  配列ノード	配列値
  responseProperties(parametername)、ここで parametername はパラメータの名前です (token_type、expires_in など)。	指定されたパラメータの値。

• 出力として返される error は、空の文字列であるか (エラーがない場合)、エラー情報を含む %OAuth2.ErrorOpens in a new tab のインスタンスです (エラーがある場合)。

  %OAuth2.ErrorOpens in a new tab は、Error、ErrorDescription、ErrorUri という 3 つの文字列プロパティを持ちます。

GetAuthorizationCodeEndpoint()

場所：このメソッドはクラス %SYS.OAuth2.AuthorizationOpens in a new tab にあります。

ClassMethod GetAuthorizationCodeEndpoint(applicationName As %String, 
                                         scope As %String, 
                                         redirectURL As %String, 
                                         ByRef properties As %String, 
                                         Output isAuthorized As %Boolean, 
                                         Output sc As %Status, 
                                         responseMode As %String
                                         sessionId As %String = "") As %String

このメソッドは、InterSystems IRIS が承認コードを要求するときに使用するローカルな内部ページの URL を、必要なすべてのクエリ・パラメータと共に返します。(このページはユーザには表示されません。)

引数は以下のとおりです。

• applicationName はクライアント・アプリケーションの名前です。

• scope は、スペースで区切られた、アクセスが要求されているスコープのリストです。例えば、"scope1 scope2 scope3" のような形式をとります。

  既定値は、指定された applicationName のクライアント構成によって決まります。

• redirectURL は、クライアントのリダイレクト・ページの完全な URL です。クライアントにアクセス・トークンを返した承認サーバは、このページにブラウザをリダイレクトします。

• 参照によって渡される properties は、要求に追加されるパラメータを含む多次元配列です。この配列は以下の構造を持つ必要があります。

  配列ノード

  配列値

  properties (parametername)、ここで parametername はパラメータの名前です。

  指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。 JSON オブジェクトの値を持つパラメータを要求に含める場合は、ダイナミック・オブジェクトを使用します。その 1 つのシナリオが OpenID Connect で定義されている claims パラメータです。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。 request または request_uri パラメータを使用する場合は、"JWT としての要求オブジェクトの受け渡し" セクションを参照してください。 code_verifier パラメータを使用して、承認サーバに送信するシークレット PKCE 値を変更できます。既定では、PKCE シークレット は、SHA-256 ハッシュを使用したランダムな 43 文字の文字列から生成されます。カスタム文字列からシークレットを生成するには (例えば、128 文字を使用する場合)、code_verifier パラメータにカスタム値を設定します。

• このクライアントおよびセッションのアクセス・トークンがローカルに保存されている場合、出力として返される isAuthorized の値は 1 になります (スコープはチェックされていません)。それ以外の場合、このパラメータの値は 0 になります。さきほど IsAuthorized() メソッドを呼び出したので、この出力引数を確認する必要はありません。

• 出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。

• responseMode は、承認サーバの応答モードを指定します。このモードは "query" (既定値)、"fragment"、または "form_post" にできます。ほとんどの場合、既定値が適切な値となります。

• sessionId はセッション ID を指定します。既定のセッション (%session.SessionId) をオーバーライドする場合のみこれを指定します。

Note:

Active Directory フェデレーション・サービス (ADFS) サーバは、承認エンドポイント URL にキーと値のペア resource=urn:microsoft:userinfo が含まれることを期待しています。GetAuthorizationCodeEndpoint の properties 引数を使用して、このキーと値のペアをサーバ記述で定義された URL の末尾に追加できます。管理ポータルで承認エンドポイントを変更してこの情報を含めることは避けてください。以下のコードを使用して、GetAuthorizationCodeEndpoint メソッドを呼び出す前に、properties 引数を変更してください。

set properties("resource") = "urn:microsoft:userinfo"
set url = ##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint(appName, scopes, clientRedirectURI, .properties, .isAuthorized,.sc) 

"バリエーション ：OnPreHTTP 内でのリダイレクトの実行" も参照してください。

OAuth 2.0 クライアント用の ZAUTHENTICATE ルーチンの作成および使用

OAuth 2.0 クライアントとして使用する InterSystems IRIS Web クライアント用に ZAUTHENTICATE ルーチンを作成して使用するには、以下の手順をすべて実行します。

• クライアント・コードで、%SYS.OAuth2.AccessTokenOpens in a new tab クラスの IsAuthorized() メソッドを呼び出してアクセス・トークンの取得に成功した後、%session 変数の Login() メソッドを呼び出します。ユーザ名として OAuth 2.0 のアプリケーション名を指定し、パスワードとして Web セッション ID を指定します。

• ZAUTHENTICATE ルーチンを作成します。このルーチンは、ロールや他のユーザ・プロパティの指定など、ユーザ・アカウントの基本的な設定を実行する必要があります。

  インターシステムズが提供するサンプル・ルーチン OAUTH2.ZAUTHENTICATE.mac をコピーして変更することができます。このルーチンは GitHub の Samples-Security サンプルに含まれています (https://github.com/intersystems/Samples-SecurityOpens in a new tab)。"InterSystems IRIS で使用するサンプルのダウンロード" で説明されているようにサンプル全体をダウンロードすることもできますが、単に GitHub でルーチンを開いて、その内容をコピーするほうが簡単です。

  ZAUTHENTICATE ルーチンを定義する場合、このルーチンは %SYS ネームスペース内にあり、ZAUTHENTICATE という名前である必要があります。"OAUTH2.ZAUTHENTICATE.mac サンプルの注意事項" を参照してください。代行認証に関する一般的な情報は、"代行 (ユーザ定義) 認証コードの作成" と "代行認証" を参照してください。

• [認証オプション] ページで、InterSystems IRIS インスタンスに対して代行認証を有効にします。

  この手順と次の手順の詳細は、"代行認証" を参照してください。

• 関連する Web アプリケーションに対して代行認証を有効にします。

OAuth 2.0 クライアント用のカスタム・ログイン・ページの作成および使用

OAuth 2.0 クライアントとして使用する InterSystems IRIS Web クライアント用にカスタム・ログイン・ページを作成して使用するには、以下の手順をすべて実行します。

• %OAuth2.LoginOpens in a new tab のサブクラスを作成します。サブクラスで以下を実行します。

  • アプリケーション名、スコープ・リスト、およびレスポンス・モード (オプション) を指定します。以下のいずれかまたは両方を実行してこれらの項目を指定できます。

    • %OAuth2.LoginOpens in a new tab のサブクラスのパラメータを指定。

    • DefineParameters() クラス・メソッドのオーバーライド。パラメータの指定と対照的に、このテクニックでは実行中にこれらの値を設定できます。

    これらのパラメータは、以下のとおりです。

    • APPLICATION — これは、ログインするアプリケーションのアプリケーション名である必要があります。

    • SCOPE — これは、アクセス・トークン要求に使用するスコープ・リストを指定します。これは、空白で区切られた文字列リストである必要があります。

    • RESPONSEMODE — これは、レスポンスのモードを指定します。可能な値は "query" (既定値)、"fragment"、または "form_post" です。

    DefineParameters() クラス・メソッドには以下のシグニチャがあります。

    ClassMethod DefineParameters(Output application As %String, Output scope As %String, Output responseMode As %String)
    

    

    このメソッドは、アプリケーション名、スコープ・リスト、およびレスポンス・モードを出力引数として返します。このメソッドの既定の実装では、APPLICATION、SCOPE、および RESPONSEMODE の各クラス・パラメータの値が返されます。

  • %OAuth2.LoginOpens in a new tab のサブクラスで、GetAccessTokenAuthorizationCode() 呼び出しのプロパティ・リストも指定します。そのためには、DefineProperties() クラス・メソッドをオーバーライドします。このメソッドには、以下のシグニチャがあります。

    ClassMethod DefineProperties(Output properties As %String)
    

    

    このメソッドは、properties 配列を出力として返します。これは、トークン要求に含める追加プロパティを指定するローカル配列です。properties 配列は以下の形式をとります。

    ノード	値
    properties(name)、ここで name はパラメータの名前です。	指定されたパラメータの値。

    JSON オブジェクトである要求パラメータを追加するには、%DynamicObjectOpens in a new tab のインスタンスであるプロパティ要素を作成します。または、UTF-8 でエンコードされたシリアル化オブジェクトである文字列を作成します。

    request または request_uri 要求パラメータを追加するには、%SYS.OAuth2.RequestOpens in a new tab クラスを使用して JWT を作成します。次に必要に応じて、properties("request") を JWT と等しい値に設定するかまたは properties("request_uri") を JWT の URL と同じ値に設定します。

• 関連 Web アプリケーションを構成して、カスタム・ログイン・ページを使用します。

• 前のセクションの説明に従って、ZAUTHENTICATE ルーチンを作成して使用します。ただし、中黒で示された最初の項目を除きます。(このシナリオでは、クライアント・コードで %session.Login() を呼び出す必要はありません。)

OAUTH2.ZAUTHENTICATE.mac サンプルの注意事項

OAUTH2.ZAUTHENTICATE.mac サンプル (https://github.com/intersystems/Samples-SecurityOpens in a new tab から取得) は、前のサブセクションで説明した両方のシナリオをサポートします。このサンプルでは、GetCredentials() サブルーチンは以下のようになります。

GetCredentials(ServiceName,Namespace,Username,Password,Credentials) Public {
    If ServiceName="%Service_WebGateway" {
        // Supply user name and password for authentication via a subclass of %OAuth2.Login
        Set Username="OAuth2"
        Set Password=$c(1,2,3)
    }
    Quit $$$OK
}

このサブルーチンは、ユーザ名とパスワードが指定されていないと呼び出されます (これはカスタム・ログイン・ページが使用された場合です)。サービス %Service_WebGateway では、このサンプルは、ユーザ名とパスワードを (後の処理で呼び出す) ZAUTHENTICATE() サブルーチンでも使用する特定の値に設定します。

ZAUTHENTICATE() サブルーチンには以下が含まれています。

If Username="OAuth2",Password=$c(1,2,3) {
    // Authentication is via a subclass of %OAuth2.Login that sets the query parameter CSPOAUTH2
    // with a hash value that allows GetCurrentApplication to determine the application -- 
    // username/password is supplied by GetCredentials.
    Set sc=##class(OAuth2.Response).GetCurrentApplication(.applicationName)
    Set sessionId=%session.SessionId
} Else {
    // If authentication is based on %session.Login, then application and session id are passed in.
    Set applicationName=Username
    Set sessionId=Password
}

後の手順では、次のように isAuthorized() メソッドを呼び出します。

Set isAuthorized=##class(%SYS.OAuth2.AccessToken).IsAuthorized(applicationName,sessionId,,.accessToken,,,.error)

isAuthorized() が 1 を返す場合、後述のコードは、イントロスペクション・エンドポイントを呼び出し、そこから取得した情報を使用してユーザを定義します。

Set sc=##class(%SYS.OAuth2.AccessToken).GetIntrospection(applicationName,accessToken,.jsonObject)
...
Set Username="OAuth2"_jsonObject.sub
Set Properties("FullName")="OAuth account "_Username
Set Properties("Username")=Username
Set Properties("Password")=""    // we don't really care about oauth2 account password
// Set the roles and other Properties as appropriate.
Set Properties("Roles")=roles

コードで異なるロジックを使用して、ユーザの定義に必要な情報を取得できます。代わりに以下の方法でこの情報を取得することもできます。

• OpenID Connect を使用している場合には IDToken から取得。この場合、%SYS.OAuth2.Validate の ValidateIDToken() を呼び出します。

• OpenID Connect の場合には Userinfo エンドポイントから取得。この場合、%SYS.OAuth2.AccessTokenOpens in a new tab の GetUserinfo() を呼び出します。

どの場合でも、ユーザ名が通常の InterSystems IRIS ユーザ名と一致しないユーザを定義する必要があります。

また、アプリケーションの要件に応じて、ルーチンでロールおよび Properties 配列のその他の部分を設定する必要もあります。"代行 (ユーザ定義) 認証コードの作成" と "代行認証" を参照してください。

ユーザのアクセス・トークンの取り消し

指定されたユーザのアクセス・トークンをすべて取り消すには、次の手順を実行します。

1. [システム管理]→[セキュリティ]→[OAuth 2.0]→[管理] を選択します。

2. ユーザ ID を [ユーザのトークンの取り消し] フィールドに入力します。

3. [取り消す] を選択します。

このタスクを実行するには、%Admin_OAuth2_Registration リソースの USE 権限を持つユーザとしてログインする必要があります。

プログラムによるアクセス・トークンの取り消し

クライアントがアクセス・トークンを取り消す必要がある場合は、%SYS.OAuth2.AccessTokenOpens in a new tab の RevokeToken() メソッドを使用します。指定されたトークンを保持しているセッションが削除されると、システムはこのメソッドを自動的に呼び出します (取り消しエンドポイントが指定されている場合)。

ClassMethod RevokeToken(applicationName As %String, accessToken As %String) As %Status

引数は以下のとおりです。

• applicationName はクライアント・アプリケーションの名前です。

• accessToken はアクセス・トークンです。

要求は、client_id と client_secret が applicationName に関連付けられている、基本的な承認 HTTP ヘッダによって承認されます。

以下に例を示します。

set sc=##class(%SYS.OAuth2.AccessToken).RevokeToken("myclient",accessToken)
if $$$ISERR(sc) {
    //error handling here
}

サーバで取り消しエンドポイントが指定されていない場合や、[クライアントの秘密鍵] が指定されていない場合は、このメソッドを使用できません。

%SYS.OAuth2.AccessTokenOpens in a new tab はメソッド RemoveAccessToken() も提供します。このメソッドはクライアントからアクセス・トークンを削除しますが、サーバからはアクセス・トークンを削除しません。

クライアント用のキーの回転の API

クライアントでキーをプログラムによって回転させるには、OAuth2.ClientOpens in a new tab の RotateKeys() メソッドを呼び出します。

新しい承認サーバの公開の JWKS を取得するには、OAuth2.ServerDefinitionOpens in a new tab の UpdateJWKS() メソッドを呼び出します。

これらのメソッドの詳細は、クラス・リファレンスを参照してください。

値による要求オブジェクトの受け渡し

request パラメータを使用して JWT として要求オブジェクトを渡すには、以下の手順を実行します。

1. %SYS.OAuth2.RequestOpens in a new tab クラスの MakeRequestJWT() メソッドを呼び出します。

   ClassMethod MakeRequestJWT(applicationName As %String, 
                              ByRef properties As %String, 
                              Output sc As %Status) As %String
   

   

   以下はその説明です。

   • applicationName はクライアント・アプリケーションの名前です。

   • 参照によって渡される properties は、要求に追加されるパラメータを含む多次元配列です。この配列は以下の構造を持つ必要があります。

     配列ノード	配列値
     properties (parametername)、ここで parametername はパラメータの名前です。	指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。

   • 出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。

   このメソッドは JWT の文字列を返します。以下に例を示します。

    // create jwt 
    set jwt=##class(%SYS.OAuth2.Request).MakeRequestJWT("myapp",.properties,.sc)
   

   

2. GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() の引数として使用する properties 配列を変更します。前の手順で作成した JWT と等しくなるようにノード properties("request") を設定します。以下に例を示します。

    set properties("request")=jwt

   

3. GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() を呼び出すときに properties 配列を指定します。以下に例を示します。

    set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp",
          scope,redirect,.properties,.isAuthorized,.sc, responseMode)
   

   

参照による要求オブジェクトの受け渡し

request_uri パラメータを使用して JWT として要求オブジェクトを渡すには、以下の手順を実行します。

1. %SYS.OAuth2.RequestOpens in a new tab クラスの UpdateRequestObject() メソッドを呼び出します。

   ClassMethod UpdateRequestObject(applicationName As %String, 
                                   requestName As %String, 
                                   ByRef properties As %String, 
                                   Output sc As %Status) As %SYS.OAuth2.Request
   

   

   以下はその説明です。

   • applicationName はクライアント・アプリケーションの名前です。

   • requestName は要求の名前です。

   • 参照によって渡される properties は、要求に追加されるパラメータを含む多次元配列です。この配列は以下の構造を持つ必要があります。

     配列ノード	配列値
     properties (parametername)、ここで parametername はパラメータの名前です。	指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。

   • 出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。

   このメソッドは %SYS.OAuth2.RequestOpens in a new tab のインスタンスの作成、保存、返却を行います。

    // create requestobject 
    set requestobject=##class(%SYS.OAuth2.Request).UpdateRequestObject("myapp","myrequest",.properties,.sc)
   

   

2. 保存されている要求オブジェクトの URL を取得します。そのためには、このインスタンスの GetURL() メソッドを呼び出します。GetURL() は、最初の引数の出力としてステータス・コードを返すので、コードでこれを確認します。

    Set requesturl=requestobject.GetURL()

   

3. GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() の引数として使用する properties 配列を変更します。前の手順で取得した URL と等しくなるようにノード properties("request_uri") を設定します。以下に例を示します。

   set properties("request_uri")=requesturl
   

   

4. GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() を呼び出すときに properties 配列を指定します。以下に例を示します。

    set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp",
          scope,redirect,.properties,.isAuthorized,.sc, responseMode)
   
   

   

バリエーション：リソース・サーバによる Userinfo エンドポイントの呼び出し

リソース・サーバは Userinfo エンドポイントを呼び出すこともできます。そのためには、OAuth クライアントの場合と同様に、リソース・サーバのコードで GetUserinfo() メソッドを使用する必要があります。

バリエーション：リソース・サーバでエンドポイントを呼び出さない

InterSystems IRIS リソース・サーバが承認サーバのエンドポイントを使用しない場合は、このマシンで OAuth 2.0 構成を作成する必要はありません。

さらに、リソース・サーバが GetAccessTokenFromRequest() を使用する必要はありません。代わりに、リソース・サーバは HTTP 承認ヘッダからアクセス・トークンを直接取得し、必要に応じて使用することができます。

承認サーバの構成

このタスクを実行するには、%Admin_OAuth2_Server リソースの USE 権限を持つユーザとしてログインする必要があります。

1. 管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[サーバ構成] を選択します。

2. [一般] タブで、以下の詳細を指定します。

   • [説明] — 必要に応じて説明を入力します。

   • [発行者エンドポイント] — 承認サーバのエンドポイント URL を指定します。この URL を指定するには、次のオプションの値を入力します。

     • [ホスト名] — 承認サーバのホスト名または IP アドレスを指定します。

     • [ポート] — Web ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。

     • [接頭語] — Web ゲートウェイ構成の変更に対応するために必要な場合は、この値を指定します。

     指定した発行者エンドポイントは以下の形式になります。

     https://hostname:port/prefix/oauth2
     

     

     [ポート] の指定を省略すると、コロンが省略されます。同様に、[接頭語] の指定を省略すると、hostname:port と oauth2 の間のスラッシュが 1 つだけになります。

   • [対象者は必須] — 承認サーバが承認コードおよび暗黙の要求で aud パラメータを必要とするかどうかを指定します。このチェック・ボックスのチェックを外すと、aud は必須でなくなります。

   • [ユーザセッションをサポート] — 承認サーバがユーザ・セッション (Web セッションではない) をサポートするかどうかを指定します。選択すると、InterSystems IRIS はセッション維持クラス (既定のセッション維持クラスは OAuth2.Server.SessionOpens in a new tab ですが、カスタマイズできます。詳細は、"コードのカスタマイズ・オプション" を参照してください) を使用します。このチェック・ボックスのチェックを外すと、ユーザ･セッションはサポートされません。

   • [パブリッククライアント更新を許可] — サーバでクライアントのリフレッシュ・トークンを処理できるようにするかどうかを指定します。このチェック・ボックスにチェックを付けると、サーバはリフレッシュ・トークンを処理するためにクライアントの秘密鍵を必要としなくなります。

   • [Enforce Proof Key for Code Exchange (PKCE) for public clients] — 承認サーバで承認コード付与タイプがサポートされる場合、このチェック・ボックスにチェックを付けると、パブリック・クライアントは承認コードを要求してコードをアクセス・トークンに交換する際に、PCKE シークレット値を提供する必要があります。

   • [Enforce Proof Key for Code Exchange (PKCE) for confidential clients] — 承認サーバで承認コード付与タイプがサポートされる場合、このチェック・ボックスにチェックを付けると、機密クライアントは承認コードを要求してコードをアクセス・トークンに交換する際に、PCKE シークレット値を提供する必要があります。

   • [HTTPベースのフロントチャネルログアウトをサポート] — フロント・チャネル・ログアウトを有効にするか無効にするかを指定します。既定では、フロント・チャネル・ログアウトが有効になっています。このチェック・ボックスのチェックを外すと、ユーザがサーバからログアウトしたときに、そのユーザはサーバに登録されているクライアントからもログアウトされます。

     Note:

     InterSystems IRIS 承認サーバでフロント・チャネル・ログアウトがサポートされるようにするには、/oauth2 Web アプリケーションの [ユーザ Cookie スコープ] を [Lax] に設定する必要があります。アプリケーションの設定の構成の詳細は、"アプリケーションの作成および編集" を参照してください。

   • [フロントチャネルログアウトURLとともに sid (セッションID) クレームの送信をサポート] — フロント・チャネル・ログアウト URL と共にセッション ID クレームを送信できるようにするかどうかを指定します。既定では、セッション ID が送信されるようになっています。このチェック・ボックスのチェックを外すと、サーバがフロント・チャネル・ログアウト URL を呼び出した場合、その URL には iss (発行者) と sid (セッション ID) の各クエリ・パラメータが付加されません。

   • [リフレッシュ・トークンの返却] — アクセス・トークンと共にリフレッシュ・トークンが返される条件を指定します。それぞれのビジネス・ケースに適したオプションを選択します。

   • [サポートされている付与タイプ] — この承認サーバがアクセス・トークンを作成するために使用を許可する付与タイプを指定します。少なくとも 1 つ選択します。

   • [OpenID プロバイダ・ドキュメント] — OpenID プロバイダによって提供される URL を以下のように指定します。

     • [サービス・ドキュメント URL] — OpenID プロバイダの使用時に開発者が理解しておく必要があると思われる、人が読める情報を提供する Web ページの URL です。

     • [ポリシー URL] — Relying Party がプロバイダによって提供されるデータを使用する方法について、OpenID プロバイダのポリシーを記述する Web ページの URL です。

     • [サービス条件 URL] — OpenID プロバイダのサービス条件を記述する Web ページの URL です。

   • [SSL/TLS 構成] — 承認サーバ用に作成した SSL/TLS 構成を選択します (例：sslconfig)。

3. [スコープ] タブで、以下の詳細を指定します。

   • [スコープ] と [説明] の列を持つテーブル — この承認サーバがサポートしているスコープをすべて指定します。

   • [サポートされていないスコープを許可] — サポートしていないスコープ値を承認サーバが無視するかどうかを指定します。このチェック・ボックスのチェックを外すと、サポートされていないスコープ値が要求に含まれる場合、承認サーバはエラーを返します。この場合、要求は処理されません。このチェック・ボックスにチェックを付けると、承認サーバはスコープを無視して要求を処理します。

   • [既定のスコープ] — アクセス・トークンの要求やクライアント構成でスコープが指定されていない場合に使用する、アクセス・トークンの既定のスコープを指定します。

4. [間隔] タブで、以下の詳細を指定します。

   • [アクセス・トークン間隔] — このサーバが発行したアクセス・トークンの有効期限が切れる秒数を指定します。デフォルトは 3600 秒です。

   • [認証コードの間隔] — このサーバが発行した認証コードの有効期限が切れる秒数を指定します。デフォルトは 60 秒です。

   • [トークン間隔を更新] — このサーバが発行したリフレッシュ・トークンの有効期限が切れる秒数を指定します。既定値は 24 時間 (86,400 秒) です。

   • [セッション終了間隔] — ユーザ・セッションが自動的に終了する秒数を指定します。値 0 はセッションが自動的に終了しないことを意味します。既定値は 24 時間 (86,400 秒) です。

   • [クライアント秘密鍵の有効期間] — このサーバが発行したクライアント秘密鍵の有効期限が切れる秒数を指定します。既定値 (0) は、クライアント秘密鍵が期限切れにならないことを示します。

5. [JWT 設定] タブで、以下の詳細を指定します。

   • [X509 資格情報から JWT 設定を作成] — 証明書に関連付けた秘密鍵を署名と暗号化で使用する場合は、このオプションを選択します。この場合は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 承認サーバの証明書の使用" も参照してください。

     Note:

     インターシステムズでは、[X509 資格情報から JWT 設定を作成] オプションが使用されることはまれで、次に説明する既定の動作が代わりに使用されると考えています。

     このオプションのチェックを外したままにすると、システムは JWKS (JSON Web Key Set) のペアを生成します。一方の JWKS は秘密鍵で、(アルゴリズムあたり) 必要なすべての秘密鍵だけでなく、対称鍵として使用するクライアント秘密鍵も含んでいます。この JWKS は共有されません。他方の JWKS には、対応する公開鍵が含まれていて、公開されて利用できます。また、InterSystems IRIS は、公開の JWKS をクライアントにコピーして、クライアントが承認サーバから JWT の暗号化およびシグニチャの検証を実行できるようにします。

   • [署名アルゴリズム] — JWT を署名するときに使用するアルゴリズムを選択します。JWT を署名しない場合は空白のままにします。

   • [キー管理アルゴリズム] — JWT を暗号化するときにキー管理で使用するアルゴリズムを選択します。

     この選択は、コンテンツの暗号化アルゴリズムを選択する場合にのみ行います。

   • [コンテンツ暗号化アルゴリズム] — JWT を暗号化するときに使用するアルゴリズムを選択します。JWT を暗号化しない場合は空白のままにします。アルゴリズムを選択する場合は、キー管理のアルゴリズムも選択する必要があります。

6. [カスタマイズ] タブで、"コードのカスタマイズ・オプション" に従って詳細を指定します。

7. [保存] を選択します。

この構成を保存すると、システムは承認サーバが使用する Web アプリケーション (/oauth2) を作成します。この Web アプリケーションは変更しないでください。

InterSystems IRIS 承認サーバが要求を処理する方法

このセクションでは、トークンの承認コード要求または暗黙要求を受け取った InterSystems IRIS 承認サーバが実行する処理について説明します。

1. [認証クラス] オプションで指定されたクラスの BeforeAuthenticate() メソッドを呼び出します。このメソッドの目的は、ユーザの識別を開始する前に要求に変更を加えることです。

   既定のクラスでは、このメソッドはスタブです。

2. 次に、付与タイプが承認コードまたは暗黙付与である場合、InterSystems IRIS は以下の手順を実行します。

   1. [認証クラス] オプションで指定されたクラスの DisplayLogin() を呼び出します。("DirectLogin() の実装" も参照してください。)

      既定のクラスで、DisplayLogin() は単純な HTML ログイン・ページを表示します。

   2. ユーザ名が Null でない場合は、[ユーザ検証クラス] オプションで指定されたクラスの ValidateUser() メソッドを呼び出します。このメソッドの目的は、ユーザを検証して、(properties 配列の変更によって) トークン・エンドポイント、Userinfo エンドポイント、トークン・イントロスペクション・エンドポイントによって返されるクレームを準備することです。

      既定のクラスでは、このメソッドは例にすぎず、実稼働環境での使用には適していない可能性があります。

   3. ユーザが検証されると、[認証クラス] オプションで指定されたクラスの DisplayPermissions() メソッドを呼び出します。このメソッドの目的は、要求された許可の一覧を示すページをユーザに表示することです。

      既定のクラスで、このメソッドは許可の一覧を示す単純な HTML ページを表示します。

   または、付与タイプがパスワード資格情報である場合、InterSystems IRIS は [ユーザ検証クラス] オプションで指定されたクラスの ValidateUser() メソッドを呼び出します。

   または、付与タイプがクライアント資格情報である場合、InterSystems IRIS は [ユーザ検証クラス] オプションで指定されたクラスの ValidateClient() メソッドを呼び出します。

3. ユーザが許可を受け入れると、[認証クラス] オプションで指定されたクラスの AfterAuthenticate() メソッドを呼び出します。 このメソッドの目的は、アクセス・トークンを生成する前にカスタム処理を実行することです。

   既定のクラスでは、このメソッドはスタブです。

4. [トークン生成クラス] オプションで指定されたクラスの GenerateAccessToken() メソッドを呼び出します。このメソッドの目的は、ユーザに返すアクセス・トークンを生成することです。

   既定のクラス (%OAuth2.Server.GenerateOpens in a new tab) で、このメソッドは opaque 文字列のアクセス・トークンを生成します。さらに InterSystems IRIS は代替クラス (%OAuth2.Server.JWTOpens in a new tab) を提供し、このクラスで GenerateAccessToken() は JWT のアクセス・トークンを生成します。

既定のクラス

このセクションでは、InterSystems IRIS 承認サーバの既定のクラスについて説明します。さらに、[トークン生成クラス] の別のオプションとして提供される %OAuth2.Server.JWTOpens in a new tab クラスについても説明します。

認証前のオプションのカスタム処理

ここに記載されている情報は、すべての付与タイプに当てはまります。

ユーザを認証する前にカスタム処理を実行するには、認証クラスの 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_ で始まる要素が含まれている場合は、その要素に特別な処理を施します。InterSystems IRIS は DisplayLogin() メソッドが返した要素の値を properties.CustomProperties 配列に追加するとき、最初に p_ 接頭語を名前から削除します。例えば、フォームに p_addme という名前の要素が含まれている場合、InterSystems IRIS は 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 はユーザが提供したパスワードです。ユーザが既にログインしている場合、InterSystems IRIS は空の文字列の 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.PropertiesOpens in a new tab クラスには以下の基本プロパティがあります。これらのプロパティは、カスタム・コードの内部処理の情報の伝達に使用されます。

RequestProperties

Property RequestProperties as array of %String (MAXLEN="");

承認要求のクエリ・パラメータが含まれています。

このプロパティは配列であるため、通常の配列インタフェースを使用して操作します。(これは、このクラスの他のプロパティでも同様です。)例えば、クエリ・パラメータの値を取得するには、RequestProperties.GetAt(parmname) を使用します。ここで、parmname はクエリ・パラメータの名前です。

ResponseProperties

Property ResponseProperties as array of %String (MAXLEN="");

トークン要求への JSON 応答オブジェクトに追加されるプロパティがすべて含まれます。このプロパティは必要に応じて設定します。

CustomProperties

Property CustomProperties as array of %String (MAXLEN="");

さまざまなカスタマイズ・コード間の通信に使用されるカスタム・プロパティが含まれます。"properties.CustomProperties の更新" を参照してください。

ServerProperties

Property ServerProperties as array of %String (MAXLEN="");

承認サーバがカスタマイズ・コードと共有するプロパティが含まれます。認証クラスで使用するために、クライアント・プロパティの logo_uri、client_uri、policy_uri、tos_uri がこの方法で共有されます。

クレーム関連のプロパティ

%OAuth2.Server.PropertiesOpens in a new tab クラスには、IntrospectionClaims、IDTokenClaims、UserinfoClaims、JWTClaims プロパティがあります。これらのプロパティは、必須のクレーム、特にカスタム・クレームに関する情報を伝達します。

このクラスには、実際のクレーム値を伝達する ClaimValues プロパティもあります。カスタマイズ・コードでクレームの値を設定する必要があります (通常は ValidateUser クラス内で)。

以下のリストで、これらのプロパティについて説明します。

IntrospectionClaims

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 クラスで設定されます。

IDTokenClaims

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 を参照してください)。

UserinfoClaims

Property UserinfoClaims as array of %OAuth2.Server.Claim;

Userinfo エンドポイントが返すクレームを指定します (必須クレームの基本セットの範囲を超えて指定)。承認サーバは sub クレームを (このプロパティに含まれていない場合でも) 返します。

ほとんどの場合、このプロパティの値には空の文字列を使用できます。このプロパティは、OpenID Connect Core のセクション 5.5 をサポートするために提供されます。

このプロパティはオブジェクトの配列です。詳細は、IntrospectionClaims プロパティの項目を参照してください。

クレームは、スコープと要求のクレーム・パラメータに基づいて定義されます。クレームの戻り値は、ClaimValues プロパティの同じキーを持ちます。通常、クレームの値は ValidateUser クラスで設定されます。

JWTClaims

Property JWTClaims as array of %OAuth2.Server.Claim;

JWT ベースの既定のアクセス・トークン・クラス (%OAuth2.Server.JWTOpens in a new tab) が返す JWT アクセス・トークンで必要とされるクレームを必須クレームの基本セットの範囲を超えて指定します。承認サーバは、iss、sub、exp、aud、jti クレームを (このプロパティに含まれていない場合でも) 返します。

このプロパティはオブジェクトの配列です。詳細は、IntrospectionClaims プロパティの項目を参照してください。

このクレームはカスタマイズ・コードによって定義されます。通常、クレームの値は ValidateUser クラスで設定されます。

ClaimValues

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 プロパティの操作を簡素化するために使用できるインスタンス・メソッドも提供します。

SetClaimValue()

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 となります。

RemoveClaimValue()

Method RemoveClaimValue(name As %String)

name 引数で指定したクレームを削除することで、ClaimValues プロパティを更新します。

GetClaimValue()

Method GetClaimValue(name As %String, output type) As %String

ClaimValues プロパティを調べて、name 引数で指定されたクレームの値を返します。出力として返される type 引数はクレームの型を示します。SetClaimValue() を参照してください。

NextClaimValue()

Method NextClaimValue(name As %String) As %String

指定されたクレームの後にある (ClaimValues プロパティの) 次のクレームの名前を返します。

承認サーバのキーの回転の API

承認サーバでキーをプログラムによって回転させるには、OAuth2.Server.ConfigurationOpens in a new tab の RotateKeys() メソッドを呼び出します。

新しいクライアントの JWKS を取得するには、OAuth2.Server.ClientOpens in a new tab の UpdateJWKS() メソッドを呼び出します。

これらのメソッドの詳細は、クラス・リファレンスを参照してください。

サーバ記述の作成

サーバ記述は、OAuth2.ServerDefinitionOpens in a new tab のインスタンスです。サーバ記述を作成するには次の手順に従います。

1. %SYS ネームスペースに切り替えます。

2. 承認サーバが Discovery をサポートする場合は、%SYS.OAuth2.RegistrationOpens in a new tab の Discover() メソッドを呼び出します。このメソッドは、以下のとおりです。

   ClassMethod Discover(issuerEndpoint As %String,
                        sslConfiguration As %String,
                        Output server As OAuth2.ServerDefinition) As %Status
   

   

   以下はその説明です。

   • issuerEndpoint は、承認サーバの識別に使用するエンドポイントの URL を指定します。

   • sslConfiguration は、Discover() メソッドの呼び出しに使用する InterSystems IRIS SSL/TLS 構成のエイリアスを指定します。

   • 出力として返される server は、OAuth2.ServerDefinitionOpens in a new tab のインスタンスです。

3. 次に、返された OAuth2.ServerDefinitionOpens in a new tab インスタンスを保存します。

また、承認サーバが Discovery をサポートしない場合、次の手順を実行します。

1. %SYS ネームスペースに切り替えます。

2. OAuth2.ServerDefinitionOpens in a new tab のインスタンスを作成します。

3. インスタンスのプロパティを設定します。ほとんどの場合、プロパティの名前は管理ポータルに表示されるラベルと一致します (スペースと大文字化を除く)。詳細は、"サーバ記述の手動による作成" を参照してください。これらのプロパティは、以下のとおりです。

   • IssuerEndpoint

   • SSLConfiguration

   • InitialAccessToken。[登録アクセストークン] フィールドに対応します。

   • Metadata。OAuth2.Server.Metadata のインスタンスで、多くのプロパティが含まれます。OpenID Provider Metadata (https://openid.net/specs/openid-connect-discovery-1_0.htmlOpens in a new tab) を参照してください。

   ServerCredentials の詳細は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 承認サーバの証明書の使用" を参照してください。

4. インスタンスを保存します。

クライアント構成の生成

クライアント構成は、OAuth2.ClientOpens in a new tab のインスタンスです。クライアント構成を作成するには、次の手順を実行します。

1. %SYS ネームスペースに切り替えます。

2. OAuth2.ClientOpens in a new tab のインスタンスを作成します。

3. インスタンスのプロパティを設定します。ほとんどの場合、プロパティの名前は管理ポータルに表示されるラベルと一致します (スペースと大文字化を除く)。詳細は、"クライアントの構成および動的な登録" を参照してください。これらのプロパティは、以下のとおりです。

   • ApplicationName

   • ClientId。クライアントを動的に登録する場合、手動で設定する必要はありません。

   • ClientSecret。クライアントを動的に登録する場合、手動で設定する必要はありません。

   • DefaultScope

   • Description

   • Enabled

   • JWTInterval

   • Metadata。OAuth2.Client.Metadata のインスタンスで、多くのプロパティが含まれます。詳細は、Client Metadata (http://openid.net/specs/openid-connect-registration-1_0-19.htmlOpens in a new tab) を参照してください。

   • RedirectionEndpoint。[応答を受信するために承認サーバに対して指定されるクライアント URL] オプションに対応します。このプロパティのタイプは %OAuth2.Endpoint です。OAuth2.EndpointOpens in a new tab クラスは、UseSSL、Host、Port、Prefix のプロパティを持つシリアル・クラスです。

   • SSLConfiguration

   • ServerDefinition。以前に作成した OAuth2.ServerDefinitionOpens in a new tab のインスタンスであることが必要です。

   ClientCredentials の詳細は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 クライアントの証明書の使用" を参照してください。

4. 承認サーバがダイナミック・クライアント登録をサポートする場合は、%SYS.OAuth2.RegistrationOpens in a new tab の RegisterClient() メソッドを呼び出します。このメソッドは、以下のとおりです。

   ClassMethod RegisterClient(applicationName As %String) As %Status
   

   

   applicationName はクライアント・アプリケーションの名前です。

   このメソッドはクライアントを登録し、(クライアント ID およびクライアント秘密鍵を含む) クライアント・メタデータを取得した後、OAuth2.ClientOpens in a new tab のインスタンスを更新します。

承認サーバ構成の作成

認証サーバ構成は、OAuth2.Server.ConfigurationOpens in a new tab のインスタンスです。承認サーバ構成を作成するには、次の手順を実行します。

1. %SYS ネームスペースに切り替えます。

2. OAuth2.Server.ConfigurationOpens in a new tab のインスタンスを作成します。

3. インスタンスのプロパティを設定します。 ほとんどの場合、プロパティの名前は管理ポータルに表示されるラベルと一致します (スペースと大文字化を除く)。詳細は、"承認サーバの構成" を参照してください。これらのプロパティは、以下のとおりです。

   • AccessTokenInterval

   • AllowUnsupportedScope

   • AudRequired。[対象者は必須] オプションに対応します

   • AuthenticateClass

   • AuthorizationCodeInterval

   • ClientSecretInterval

   • CustomizationNamespace

   • CustomizationRoles

   • DefaultScope

   • Description

   • EncryptionAlgorithm

   • GenerateTokenClass

   • IssuerEndpoint。[発行者エンドポイント] オプションに対応します。OAuth2.EndpointOpens in a new tab タイプです。OAuth2.EndpointOpens in a new tab クラスは、UseSSL、Host、Port、Prefix のプロパティを持つシリアル・クラスです。

   • JWKSFromCredentials

   • KeyAlgorithm

   • Metadata。OAuth2.Server.Metadata のインスタンスで、多くのプロパティが含まれます。OpenID Provider Metadata (https://openid.net/specs/openid-connect-discovery-1_0.htmlOpens in a new tab) を参照してください。

   • RefreshTokenInterval

   • ReturnRefreshToken

   • SSLConfiguration

   • SessionClass

   • SessionInterval。[セッション終了間隔] オプションに対応します

   • SigningAlgorithm

   • SupportSession。[ユーザ・セッションのサポート] オプションに対応します

   • SupportedScopes。[スコープ] と [説明] の列を持つテーブルに対応します。このプロパティは文字列の配列であるため、SetAt()、GetAt() などの通常の配列インタフェースを使用します。

   • ValidateUserClass

   署名、キー管理、暗号化のアルゴリズムに使用できる値については、%OAuth2.JWTOpens in a new tab のクラス・リファレンスを参照してください。

   ServerCredentials および ServerPassword の詳細は、"証明書と JWT (JSON Web Token)" の "OAuth 2.0 承認サーバの証明書の使用" を参照してください。

4. OAuth2.Server.Configuration.Save() メソッドを使用してインスタンスを保存します。%Save() メソッドではなく Save() メソッドを使用する必要があります。このメソッドには、Web アプリケーションの作成などの追加の機能が用意されているからです。

InterSystems IRIS では、このクラスの複数インスタンスの使用はサポートされていません。

また、このインスタンスを保存するには、%Admin_OAuth2_Server リソースの USE 権限を持つユーザとしてログインする必要があります。

クライアント記述の作成

クライアント記述は、OAuth2.Server.ClientOpens in a new tab のインスタンスです。クライアント記述を作成するには、次の手順を実行します。

1. %SYS ネームスペースに切り替えます。

2. OAuth2.Server.ClientOpens in a new tab のインスタンスを作成します。

3. インスタンスのプロパティを設定します。 ほとんどの場合、プロパティの名前は管理ポータルに表示されるラベルと一致します (スペースと大文字化を除く)。詳細は、"クライアント記述の作成" を参照してください。これらのプロパティは、以下のとおりです。

   • ClientCredentials

   • ClientType

   • DefaultScope

   • Description

   • LaunchURL

   • Metadata。OAuth2.Client.Metadata のインスタンスで、多くのプロパティが含まれます。詳細は、Client Metadata (http://openid.net/specs/openid-connect-registration-1_0-19.htmlOpens in a new tab) を参照してください。

   • Name

   • RedirectURL。[リダイレクト URL] オプションに対応します。このプロパティは文字列の配列であるため、SetAt()、GetAt() などの通常の配列インタフェースを使用します。

4. インスタンスを保存します。

   システムは、ClientId および ClientSecret プロパティの値を生成します。

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

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 で定義されているヘッダ値をオーバーライドすることはできません。入れ子になった署名または暗号化を行う場合、カスタム・ヘッダは "内部" (署名された) トークンにのみ追加されます。