OAuth 2.0 クライアントとしての Caché Web アプリケーションの使用法

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     

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

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

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

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

   • [認証署名アルゴリズム] — トークン・エンドポイントでこのクライアントを認証するために使用される 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:

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

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

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

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

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

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

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

メソッドの詳細

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

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 を返します。(このメソッドは CACHESYS データベースでアクセス・トークンを探します。これらのトークンは、有効期限が切れると自動的に削除されます。)

それ以外の場合、このメソッドは 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

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

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

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

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

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

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

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

  配列ノード	配列値
  properties(parametername)、ここで parametername はパラメータの名前です。	指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。 JSON オブジェクトの値を持つパラメータを要求に含める場合は、ダイナミック・オブジェクトを使用します。その 1 つのシナリオが OpenID Connect で定義されている claims パラメータです。ダイナミック・オブジェクトの詳細は、"Caché での JSON の使用" を参照してください。 request または request_uri パラメータを使用する場合は、“JWT としての要求オブジェクトの受け渡し” セクションを参照してください。

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

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

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

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

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

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

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

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

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

  このルーチンを作成するには、OAUTH2.ZAUTHENTICATE.mac を SAMPLES ネームスペースから %SYS ネームスペースにコピーし、名前を ZAUTHENTICATE.mac に変更します。次にこのルーチンを必要に応じて変更します。このセクションで後述する “OAUTH2.ZAUTHENTICATE.mac サンプルの注意事項” を参照してください。一般的な詳細は、"Caché セキュリティ管理ガイド" の “代行認証の使用法” の章の “代行 (ユーザ定義) 認証コードの作成” を参照してください。

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

  この手順と次の手順の詳細は、"Caché セキュリティ管理ガイド" の “代行認証の使用法” の章を参照してください。

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

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

OAuth 2.0 クライアントとして使用する Caché 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 サンプルは、前のセクションで説明した両方のシナリオをサポートします。このサンプルでは、GetCredentials() サブルーチンは以下のようになります。

GetCredentials(ServiceName,Namespace,Username,Password,Credentials) Public {
    If ServiceName="%Service_CSP" {
        // 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_CSP では、このサンプルは、ユーザ名とパスワードを (後の処理で呼び出す) 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

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

• アクセス・トークンが JWT の場合には JWT から取得。この場合、%SYS.OAuth2.Validate の ValidateJWT() メソッドを呼び出します。

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

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

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

また、アプリケーションの要件に応じて、ルーチンでロールおよび Properties 配列のその他の部分を設定する必要もあります。"Caché セキュリティ管理ガイド" の “代行認証の使用法” の章の “代行 (ユーザ定義) 認証コードの作成” を参照してください。

バリエーション：暗黙付与タイプ

このバリエーションでは、クライアントはトークンの要求時に暗黙付与タイプを使用します。

構成要件：“クライアントの構成” の手順を参照してください。ただし、[クライアント・タイプ] は使用事例に応じて指定します。

コード要件：全体の流れは承認コード付与タイプと似ていますが、GetAuthorizationCodeEndpoint() は呼び出しません。代わりに、%SYS.OAuth2.AuthorizationOpens in a new tab クラスの GetImplicitEndpoint() メソッドを呼び出します。

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

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

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

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

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

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

• idtokenOnly は ID トークンのみを取得可能にします。この引数が 0 の場合、メソッドはアクセス・トークンと ID トークン (要求に適切なスコープが含まれている場合) の両方を取得します。この引数が 1 の場合、メソッドはアクセス・トークンを取得しません。

• responseMode は、承認サーバの応答モードを指定します。このモードは "query" (既定値)、"fragment"、または "form_post" にできます。

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

  配列ノード	配列値
  properties(parametername)、ここで parametername はパラメータの名前です。	指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。 JSON オブジェクトの値を持つパラメータを要求に含める場合は、ダイナミック・オブジェクトを使用します。その 1 つのシナリオが OpenID Connect で定義されている claims パラメータです。ダイナミック・オブジェクトの詳細は、"Caché での JSON の使用" を参照してください。 request または request_uri パラメータを使用する場合は、“JWT としての要求オブジェクトの受け渡し” セクションを参照してください。

• このクライアントおよびセッションのアクセス・トークンがローカルに保存され、さらにそのアクセス・トークンが scope 引数で提供されるすべてのスコープを承認する場合、出力として返される isAuthorized の値は 1 になります。それ以外の場合、このパラメータの値は 0 になります。

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

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

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

バリエーション：パスワード資格情報付与タイプ

このバリエーションでは、クライアントはトークンの要求時にパスワード資格情報付与タイプを使用します。リソース所有者に属するパスワードがクライアントにある場合は、この付与タイプを使用できます。クライアント・アプリケーションは、ページのリダイレクトは行わずにトークン・エンドポイントへの HTTP POST 操作を実行できます。Caché は、これを行うメソッドを提供します。

構成要件：“クライアントの構成” の手順を参照してください。ただし、[クライアント秘密鍵] を指定する必要はありません。(一般に、クライアント秘密鍵は、クライアント秘密鍵を必要とし、かつこれを保護できる場合にのみ使用してください。)

コード要件：アプリケーションは以下を実行します。

1. この章で前述した “トークンの取得” の説明に従って、%SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出し、戻り値 (およびエラーの有無) を確認します。

2. IsAuthorized() が 0 を返した場合は、%SYS.OAuth2.AuthorizationOpens in a new tab の GetAccessTokenPassword() メソッドを呼び出します。

   ClassMethod GetAccessTokenPassword(applicationName As %String, 
                                      username As %String, 
                                      password As %String, 
                                      scope As %String, 
                                      ByRef properties As %String,
                                      Output error As %OAuth2.Error) As %Status
   

   

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

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

   • username はユーザ名です。

   • password は対応するパスワードです。

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

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

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

     配列ノード	配列値
     properties(parametername)、ここで parametername はパラメータの名前です。	指定されたパラメータの値。この値は、スカラ値、ダイナミック・オブジェクトのインスタンス、ダイナミック・オブジェクトの UTF-8 のシリアル化されたエンコード形式のいずれかです。 JSON オブジェクトの値を持つパラメータを要求に含める場合は、ダイナミック・オブジェクトを使用します。その 1 つのシナリオが OpenID Connect で定義されている claims パラメータです。ダイナミック・オブジェクトの詳細は、"Caché での JSON の使用" を参照してください。

   • 出力として返される error は、Null であるか、エラー情報を含む OAuth2.Error のインスタンスです。

   このメソッドはトークン・エンドポイントへの HTTP POST 操作を実行し、アクセス・トークンを受信して保存します (存在する場合)。

3. error 引数を確認し、それに応じて処理を進めます。

4. “トークンの検証” と “HTTP 要求へのアクセス・トークンの追加” の説明に従って作業を進めます。

バリエーション：クライアント資格情報付与タイプ

このバリエーションでは、クライアントはトークンの要求時にクライアント資格情報付与タイプを使用します。この付与タイプを使用すると、クライアント・アプリケーションはユーザから独立してリソース・サーバと通信できます。ユーザ・コンテキストは存在しません。クライアント・アプリケーションは、ページのリダイレクトは行わずにトークン・エンドポイントへの HTTP POST 操作を実行できます。Caché は、これを行うメソッドを提供します。

構成要件：“クライアントの構成” の手順を参照してください。[クライアント・タイプ] に [プライベート] を指定し、[クライアント秘密鍵] を指定します。

コード要件：アプリケーションは以下を実行します。

1. この章で前述した “トークンの取得” の説明に従って、%SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出し、戻り値 (およびエラーの有無) を確認します。

2. IsAuthorized() が 0 を返した場合は、%SYS.OAuth2.AuthorizationOpens in a new tab の GetAccessTokenClient() メソッドを呼び出します。

   ClassMethod GetAccessTokenClient(applicationName As %String, 
                                    scope As %String, 
                                    ByRef properties As %String, 
                                    Output error As %OAuth2.Error) As %Status
   

   

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

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

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

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

   • 参照によって渡される properties は、要求に追加されるパラメータを含む多次元配列です。前のサブセクションで説明した GetAccessTokenPassword() の properties 引数を参照してください。

   • 出力として返される error は、Null であるか、エラー情報を含む OAuth2.Error のインスタンスです。

   このメソッドはトークン・エンドポイントへの HTTP POST 操作を実行し、アクセス・トークンを受信して保存します (存在する場合)。

3. error 引数を確認し、それに応じて処理を進めます。

4. “トークンの検証” と “HTTP 要求へのアクセス・トークンの追加” の説明に従って作業を進めます。

OnPreHTTP 内でのリダイレクトの実行

承認コードおよび暗黙付与タイプの場合、上記の説明では次の手順に従います。

1. %SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出します。

2. GetAuthorizationCodeEndpoint() メソッド (承認コード付与タイプ用)、または GetImplicitEndpoint() メソッド (暗黙付与タイプ用) を呼び出します。

3. 上記の手順で返された URL を開くオプション (ボタンなど) を提供することで、ユーザは要求を承認することができます。

その代わりに、(アプリケーション内で) ページ・クラスの OnPreHttp() メソッドを変更することもできます。この場合、GetAccessTokenAuthorizationCode() メソッド (承認コード付与タイプ用) または GetAccessTokenImplicit() メソッド (暗黙付与タイプ用) を呼び出します。このメソッドは、最初にページのコンテンツを表示せずに、承認サーバの認証フォームにブラウザを直接移動します (必要な場合)。

バリエーション：JWT としての要求オブジェクトの受け渡し

OpenID Connect Core 仕様のセクション 6Opens in a new tab で規定されているように、Caché は JWT としての要求オブジェクトの受け渡しもサポートしています。値または参照によって要求オブジェクトを渡すことができます。

いずれの場合も、%SYS.OAuth2.RequestOpens in a new tab クラスのメソッドを使用します。このセクションに記載されていないその他のメソッドについては、クラスリファレンスを参照してください。

バリエーション：承認サーバの他のエンドポイントの呼び出し

%SYS.OAuth2.AuthorizationOpens in a new tab のメソッドを使用すると、承認サーバの特定のエンドポイント・セットを呼び出すことができます。承認サーバに他のエンドポイントがある場合は、以下の一般的なプロセスを使用してそのエンドポイントを呼び出します。

1. %Net.HttpRequestOpens in a new tab のインスタンスを作成し、そのプロパティの設定とメソッドの呼び出しを必要に応じて行い、要求を定義します。

   Set httpRequest=##class(%Net.HttpRequest).%New()
   Set httpRequest.ContentType="application/x-www-form-urlencoded"
   ...
   

   

   このクラスの詳細は、"Caché インターネット・ユーティリティの使用法" の “HTTP 要求の送信” を参照してください。

2. この要求に認証を追加するには、%SYS.OAuth2.AccessTokenOpens in a new tab の AddAuthentication() メソッドを呼び出します。

   ClassMethod AddAuthentication(applicationName As %String, httpRequest As %Net.HttpRequest) As %Status
   

   

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

   • applicationName は OAuth 2.0 クライアントの名前です。

   • httpRequest は %Net.HttpRequestOpens in a new tab のインスタンスです。

   Caché は指定されたクライアントを検索し、その [認証タイプ]、[SSL 構成]、その他の情報を使用して適切な認証を要求に追加します。

3. 必要に応じてクライアント構成を開くことで、そこに含まれるプロパティを使用できます。そのためには、%SYS ネームスペースに切り替えて、OAuth2.ClientOpens in a new tab の Open() メソッドを呼び出し、クライアント名を引数として渡します。

    New $NAMESPACE
    set $NAMESPACE="%SYS"
    Set client=##class(OAuth2.Client).Open(applicationName,.sc)
    If client="" Quit

   

4. HTTP 要求オブジェクトの Post()、Get()、または Put() メソッドを必要に応じて呼び出し、承認サーバのトークン・エンドポイントを引数として提供します。以下に例を示します。

    set sc=httpRequest.Post(client.ServerDefinition.TokenEndpoint)

   

5. 必要に応じて追加処理を実行します。

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

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

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

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

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

このタスクを実行するには、%Admin_Secure リソースの 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() メソッドを呼び出します。

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