OAuth 2.0 クライアントとしての InterSystems IRIS Web アプリケーションの使用法
このページでは、OAuth 2.0 フレームワークを使用するクライアント・アプリケーションとして InterSystems IRIS® の Web アプリケーションを使用する方法について説明します。
このページでは、InterSystems IRIS Web アプリケーションが Web サーバ/クライアント・アプリケーションのクライアントとして機能し、承認コード付与タイプを使用するシナリオについて主に説明します。その他の付与タイプとバリエーションの詳細は、バリエーションのセクションを参照してください。
OAuth 2.0 クライアントが Active Directory フェデレーション・サービス (ADFS) 承認サーバと通信する際、クライアント・コードで承認エンドポイントに特別なキーと値のペアを付加する必要があります。詳細は、"メソッドの詳細" の "GetAuthorizationCodeEndpoint()" の説明を参照してください。
InterSystems IRIS クライアントの前提条件
このページに記載されているタスクを開始する前に、以下のものが利用可能であることを確認します。
-
OAuth 2.0 承認サーバ。後で、このサーバの具体的な詳細情報が必要になります。以下に示す詳細項目の一部は、InterSystems IRIS 内でクライアントを構成するときに適用されます。
-
承認サーバの場所 (発行者エンドポイント)
-
承認エンドポイントの場所
-
トークン・エンドポイントの場所
-
Userinfo エンドポイントの場所 (サポートされている場合。OpenID Connect CoreOpens in a new tab を参照)
-
トークン・イントロスペクション・エンドポイントの場所 (サポートされている場合。RFC 7662Opens in a new tab を参照)
-
トークン取り消しエンドポイントの場所 (サポートされている場合。RFC 7009Opens in a new tab を参照)
-
承認サーバによるダイナミック登録のサポートの有無
以下に示すその他の詳細情報は、クライアント・コードの作成時に必要になります。
-
このサーバがサポートする付与タイプ
-
このサーバがサポートするスコープ。例えば、OpenID Connect CoreOpens in a new tab で定義されている特別なスコープである openid および profile をサーバがサポートすることもあれば、サポートしないこともあります。
-
このサーバに対して行われる要求に関するその他の要件
-
-
承認サーバがダイナミック・クライアント登録をサポートしない場合、InterSystems IRIS アプリケーションを OAuth 2.0 承認サーバのクライアントとして登録する必要があります。また、このクライアントのクライアント ID とクライアント秘密鍵が必要です。詳細は、承認サーバの実装環境によって異なります。(サーバがダイナミック登録をサポートする場合、このページの説明に従って構成するときにクライアントを登録できます。)
構成要件
OAuth 2.0 クライアントとして InterSystems IRIS Web アプリケーションを使用するには、次の構成タスクを実行します。
-
InterSystems IRIS にサービスを提供している Web サーバでは、その Web サーバが SSL を使用するように構成します。SSL を使用するように Web サーバを構成する方法は、このドキュメントの対象外であるため、ここでは取り上げません。
-
クライアントが使用する InterSystems IRIS の SSL 構成を作成します。
これはクライアント SSL 構成です。証明書は不要です。この構成は Web サーバへの接続に使用されます。この接続を通じて、クライアントは、承認サーバと通信してアクセス・トークンを取得し、Userinfo エンドポイントの呼び出し、イントロスペクション・エンドポイントの呼び出しなどを行います。
SSL 構成の作成の詳細は、インターシステムズの "TLS ガイド" を参照してください。
それぞれの SSL 構成には一意の名前が付いています。参照用に、このドキュメントではこの SSL 構成を sslconfig と呼びますが、一意の名前を任意に付けることができます。
-
クライアントの OAuth 2.0 構成項目を作成します。そのためには、サブセクションの説明に従って最初にサーバ記述を作成し、次にクライアント構成を作成します。
両項目の必要なオプションを管理ポータルで見つけるために、[システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。このページには、(承認サーバとして使用されているマシン以外の) クライアント・マシンで OAuth 2.0 構成を作成するときに必要なオプションが表示されます。
クライアント・マシンでは、[システム管理]→[セキュリティ]→[OAuth 2.0]→[サーバ構成] のメニューを使用しないでください。
サーバ記述の作成 (Discovery の使用)
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。
このインスタンスで利用可能なサーバ記述を示すページが表示されます。どの行でも、[発行者エンドポイント] 列はサーバ記述の発行者エンドポイントを示します。[クライアント数] 列は、指定されたサーバ記述に関連付けられたクライアント構成の数を示します。最後の列では [クライアント構成] リンクにより、関連付けられているクライアント構成の作成、表示、編集、削除を行うことができます。
-
[サーバ構成の作成] を選択します。
管理ポータルに、サーバ記述の詳細を入力できる新たなページが表示されます。
-
以下の詳細を指定します。
-
[発行者エンドポイント] (必須) — 承認サーバの識別に使用するエンドポイントの URL を入力します。
-
[SSL/TLS 構成] (必須) — ダイナミック・クライアント登録要求時に使用する SSL/TLS 構成を選択します。
-
[登録アクセス・トークン] — オプションで、ダイナミック・クライアント登録要求を承認するためのベアラー・トークンとして使用する初期登録アクセス・トークンを入力します。
-
-
[検出と保存] を選択します。
次に 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 承認サーバの証明書の使用" を参照してください。
これらのオプションのいずれかにアクセスするには、まず [ダイナミック登録以外のソース] を選択します。
-
これらの値を指定し、[保存] を選択します。
クライアントの構成および動的な登録
ここでは、クライアントの構成を作成し、クライアントを動的に登録する方法について説明します。
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。
管理ポータルにサーバ記述の一覧が表示されます。
-
このクライアント構成を関連付けるサーバ記述の行で [クライアント構成] リンクをクリックします。
管理ポータルに、サーバ記述に関連付けられているクライアント構成の一覧が表示されます。これは、最初は空のリストです。
-
[クライアント構成の作成] をクリックします。
管理ポータルに、詳細を入力できる新たなページが表示されます。
-
[一般] タブで、以下の詳細を指定します。
-
[アプリケーション名] — アプリケーションの短い名前を指定します。
-
[クライアント名] — エンド・ユーザに表示するクライアント名を指定します。
-
[説明] — アプリケーションの説明を入力します (オプション)。
-
[有効] — このアプリケーションが使用されないようにする場合は、このチェック・ボックスのチェックを外すこともできます。
-
[クライアント・タイプ] — 以下のいずれかを選択します。
-
[機密] — 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 でサポートされる任意のアルゴリズムが使用されます。
-
-
[クライアント情報] タブで、以下の詳細を指定します。
-
[ロゴ URL] — クライアント・アプリケーションのロゴの URL です。
-
[クライアント・ホームページ URL] — クライアント・アプリケーションのホーム・ページの URL です。
-
[ポリシー URL] — クライアント・アプリケーションのポリシー・ドキュメントの URL です。
-
[サービス条件の URL] — クライアント・アプリケーションのサービス条件ドキュメントの URL です。
-
[既定のスコープ] — アクセス・トークン要求の既定のスコープを空白で区切られたリストで指定します。この既定値は、承認サーバで許可されているスコープと一致している必要があります。
-
[連絡先電子メール] — クライアント・アプリケーションの責任者への連絡に使用する適切な電子メール・アドレスをコンマで区切ったリストです。
-
[既定の最長経過時間] — 既定の最長認証経過時間 (秒単位) を指定します。このオプションを指定した場合、最長認証経過時間に達したとき、エンド・ユーザをアクティブに再認証する必要があります。max_age 要求パラメータは、この既定値をオーバーライドします。このオプションを省略した場合に、既定で最長認証経過時間は設定されません。
-
-
[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 を暗号化しない場合は空白のままにします。
-
-
承認サーバがダイナミック登録をサポートする場合は、入力したすべてのデータを再確認した後、[ダイナミック登録と保存] をクリックします。次に、InterSystems IRIS は承認サーバを接続し、クライアントを登録して、クライアント ID とクライアント秘密鍵を取得します。
承認サーバがダイナミック登録をサポートしない場合については、この後のサブセクションを参照してください。
クライアントの構成 (ダイナミック登録なし)
承認サーバがダイナミック登録をサポートしない場合は、上記の最後の手順に代わって以下の手順を実行します。
-
[クライアント資格情報] タブを選択し、次の詳細を指定します。
-
[クライアント ID] — 承認サーバが提供したクライアント ID を入力します。
-
[クライアント秘密鍵] — 承認サーバが提供したクライアント秘密鍵を入力します。[クライアント・タイプ] が [機密] の場合は、この値が必須となります。
このページでは、クライアントが承認コード付与タイプを使用するシナリオについて主に説明します。このシナリオでは、[クライアント秘密鍵] の値を指定します。その他の付与タイプは、"バリエーション" を参照してください。
[クライアント ID 発行日時]、[クライアント秘密鍵有効期限]、および [登録クライアント URI] の値を入力しないでください。
-
-
[保存] を選択します。
コード要件の概要
このセクションでは、トークンの要求時にクライアントが承認コード付与タイプを使用するときに必要とされるコードについて説明します。その他の付与タイプは、"バリエーション" を参照してください。
InterSystems IRIS Web アプリケーションが OAuth 2.0 クライアントとして機能するには、この Web アプリケーションで以下のようなロジックを使用する必要があります。
-
アクセス・トークンと ID トークン (必要な場合) を取得します。"トークンの取得" を参照してください。
-
アクセス・トークンと (必要に応じて) ID トークンを検証し、要求されたリソースの使用に必要な権限をユーザが保有しているかどうかを確認します。"トークンの検証" を参照してください。
-
権限が適切な場合は、"HTTP 要求へのアクセス・トークンの追加" の説明に従ってリソース・サーバを呼び出します。
以降のセクションでこれらの手順に関する情報を提供します。
トークンの取得
このセクションでは、トークンの要求時にクライアントが承認コード付与タイプを使用するときに必要とされるコードに関する情報を提供します。既定では、この承認コード付与タイプには、Proof Key for Code Exchange (PKCE) 拡張が含まれます。その他の付与タイプおよび PKCE なしの承認コードについては、"バリエーション" を参照してください。
トークンを取得するには、以下のようなトークン取得の手順を使用します。サブセクションでは、ここで使用するメソッドを詳しく説明します。
-
%SYS.OAuth2.AccessTokenOpens in a new tab クラスの IsAuthorized() メソッドを呼び出します。その際、最初にアクセス・トークンの適切なスコープ (1 つ以上) を決定する必要があります。
以下に例を示します。
set myscopes="openid profile scope1 scope2" set isAuth=##class(%SYS.OAuth2.AccessToken).IsAuthorized("myclient",,myscopes, .accessToken,.idtoken,.responseProperties,.error)
このメソッドは、アクセス・トークンが既にローカルに保存されているかどうかを確認します。
-
error 引数がエラーを返したかどうかを確認し、返した場合はそのエラーを適切に処理します。この引数にエラーが含まれる場合、関数 $ISOBJECT() は 1 を返します。それ以外の場合、$ISOBJECT() は 0 を返します。
if $isobject(error) { //error handling here }
-
IsAuthorized() が 1 を返す場合は "トークンの検証" へ進みます。
-
それ以外の場合は、%SYS.OAuth2.AuthorizationOpens in a new tab クラスの GetAuthorizationCodeEndpoint() メソッドを呼び出します。その際、以下の情報を必要とします。
-
アクセス・トークンを返した後に承認サーバがリダイレクトされる完全な URL。これは、クライアントのリダイレクト・ページです (元のページと同じにすることも、別のページにすることもできます)。
-
要求のスコープ (1 つ以上)。
-
要求に含まれるパラメータ。例えば、場合によっては claims パラメータを渡す必要があります。
以下に例を示します。
set scope="openid profile scope1 scope2" set redirect="https://localhost/csp/openid/SampleClientResult.csp" set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myclient", scope,redirect,.properties,.isAuthorized,.sc) if $$$ISERR(sc) { //error handling here }
このメソッドは、InterSystems IRIS OAuth 2.0 クライアントが必要とする内部宛先の完全な URL (クエリ・パラメータを含む) を返します。
このメソッドに対する Proof Key for Code Exchange (PKCE) の既定の動作を変更するには、"メソッドの詳細" で properties 引数の詳細を参照してください。
-
-
GetAuthorizationCodeEndpoint() が返した URL を開くオプション (ボタンなど) を提供することで、ユーザは要求を承認することができます。
InterSystems IRIS は、ユーザには表示されないこの内部 URL で承認コードを取得し、それをアクセス・トークンに交換し、クライアントのリダイレクト・ページにブラウザをリダイレクトします。
メソッドの詳細
このサブセクションでは、前のサブセクションで使用したメソッドについて詳しく説明します。
場所:このメソッドはクラス %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 つの文字列プロパティを持ちます。
場所:このメソッドはクラス %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) をオーバーライドする場合のみこれを指定します。
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 内でのリダイレクトの実行" も参照してください。
トークンの検証
アクセス・トークンと (必要に応じて) ID トークンを受け取ったクライアントは、追加のチェックを実行して、要求されたリソースの使用に必要な権限をユーザが保有しているかどうかを確認します。この検証を実行するために、クライアントは、ここで説明するメソッドを使用して追加情報を取得することができます。
場所:このメソッドはクラス %SYS.OAuth2.ValidationOpens in a new tab にあります。
ClassMethod ValidateIDToken(applicationName As %String,
IDToken As %String,
accessToken As %String,
scope As %String,
aud As %String,
Output jsonObject As %RegisteredObject,
Output securityParameters As %String,
Output sc As %Status) As %Boolean
このメソッドは署名済みの OpenID Connect ID トークン (IDToken) を検証し、オブジェクト (jsonObject) を作成して ID トークンのプロパティを格納します。ID トークンを検証するために、このメソッドは、対象者 (aud が指定されている場合)、エンドポイント (サーバ記述で指定されているものとの一致が必要)、スコープ (scope が指定されている場合)、シグニチャを確認します。このメソッドは、ID トークンの有効期限が切れていないことも確認します。
さらに、ID トークンの at_hash プロパティに基づいてアクセス・トークン (accessToken) も検証します。
このメソッドは ID トークンが有効な場合は 1 を返し、それ以外の場合は 0 を返します。さらに、複数の引数を出力として返します。
引数は以下のとおりです。
-
applicationName はクライアント・アプリケーションの名前です。
-
IDToken は ID トークンです。
-
accessToken はアクセス・トークンです。
-
scope は、スペースで区切られたスコープのリストです。例えば、"scope1 scope2 scope3" のような形式をとります。
-
aud は、このトークンを使用する対象者を指定します。トークンに関連付けられた aud プロパティがある場合 (通常、対象者はトークンの要求時に指定されているため)、aud はトークンの対象者と一致します。aud が指定されていない場合、対象者のチェックは行われません。
-
出力として返される jsonObject は、IDToken のプロパティを含むダイナミック・オブジェクトです。ID トークンは JWT です。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。
-
出力として返される securityParameters は、ヘッダから取得されたセキュリティ情報を含む多次元配列です。このセキュリティ情報は、シグニチャや復号化の検証で必要に応じて追加使用されます。ValidateJWT() の securityParameters 引数を参照してください。
-
出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。
このメソッドが成功 (1) を返す場合は、jsonObject を検証し、必要に応じて含まれているクレームを使用して、要求されたリソースへのアクセスを許可するかどうかを決定します。 必要に応じて securityParameters を使用します。
場所:このメソッドはクラス %SYS.OAuth2.AccessTokenOpens in a new tab にあります。
ClassMethod GetUserinfo(applicationName As %String,
accessToken As %String,
IDTokenObject As %RegisteredObject,
Output jsonObject As %RegisteredObject,
Output securityParameters As %String) As %Status
このメソッドはアクセス・トークンを Userinfo エンドポイントへ送信し、クレームを含む応答を受信し、このエンドポイントが返したクレームを含むオブジェクト (jsonObject) を作成します。 応答が JWT を返すとその応答は復号化され、署名が確認されてから jsonObject が作成されます。引数 IDTokenObject が指定されている場合、このメソッドは、Userinfo エンドポイントの sub クレームが IDTokenObject の sub クレームと一致していることも検証します。
要求は、指定されたアクセス・トークンによって承認されます。
引数は以下のとおりです。
-
applicationName はクライアント・アプリケーションの名前です。
-
accessToken はアクセス・トークンです。
-
IDTokenObject (オプション) は、ID トークンを含むダイナミック・オブジェクトです。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。
-
出力として返される jsonObject は、Userinfo エンドポイントが返したクレームを含むダイナミック・オブジェクトです。
-
出力として返される securityParameters は、ヘッダから取得されたセキュリティ情報を含む多次元配列です。このセキュリティ情報は、シグニチャや復号化の検証で必要に応じて追加使用されます。ValidateJWT() の securityParameters 引数を参照してください。
このメソッドが成功 (1) を返す場合は、jsonObject を検証し、必要に応じて含まれているクレームを使用して、要求されたリソースへのアクセスを許可するかどうかを決定します。 必要に応じて securityParameters を使用します。
HTTP 要求へのアクセス・トークンの追加
アクセス・トークンを受信して検証したクライアント・アプリケーションは、リソース・サーバへの HTTP 要求を作成できます。アプリケーションによっては、この HTTP 要求でアクセス・トークンを必要とすることもあります。
(ベアラー・トークン HTTP 承認ヘッダとして) アクセス・トークンを HTTP 要求へ追加するには、以下の手順を実行します。
-
%Net.HttpRequestOpens in a new tab のインスタンスを作成し、必要に応じてプロパティを設定します。
このクラスの詳細は、"インターネット・ユーティリティの使用法" の" HTTP 要求の送信" を参照してください。
-
%SYS.OAuth2.AccessTokenOpens in a new tab の AddAccessToken() メソッドを呼び出します。このメソッドにより、アクセス・トークンが HTTP 要求に追加されます。このメソッドは、以下のとおりです。
ClassMethod AddAccessToken(httpRequest As %Net.HttpRequest, type As %String = "header", sslConfiguration As %String, applicationName As %String, sessionId As %String) As %Status
このメソッドは、指定されたアプリケーションおよびセッションに関連付けられているベアラー・アクセス・トークンを RFC 6750Opens in a new tab で定義されているリソース・サーバへの要求に追加します。引数は以下のとおりです。
-
httpRequest は変更する %Net.HttpRequestOpens in a new tab のインスタンスです。
-
type は、HTTP 要求にアクセス・トークンを含める方法を指定します。
-
"header" — ベアラー・トークン HTTP ヘッダを使用します。
-
"body" — フォームエンコードされた本文を使用します。この場合の要求は、本文がフォームエンコードされた POST でなければなりません。
-
"query" — クエリ・パラメータを使用します。
-
-
sslConfiguration は、この HTTP 要求で使用する InterSystems IRIS SSL 構成です。これを省略すると、InterSystems IRIS はクライアント構成に関連付けられている SSL 構成を使用します。
-
applicationName はクライアント・アプリケーションの名前です。
-
sessionId はセッション ID を指定します。既定のセッション (%session.SessionId) をオーバーライドする場合のみこれを指定します。
このメソッドは、ステータス・コードを返すので、コードでこのステータス・コードを確認する必要があります。
-
-
"インターネット・ユーティリティの使用法" の "HTTP 要求の送信" の説明に従って HTTP 要求を送信します。そのためには、Get() や Put() などのメソッドを呼び出します。
-
前の手順で返されたステータスを確認します。
-
HTTP 要求の HttpResponse プロパティとして利用できる HTTP 応答を必要に応じて検証します。
"インターネット・ユーティリティの使用法" の "HTTP 要求の送信" を参照してください。
以下に例を示します。
set httpRequest=##class(%Net.HttpRequest).%New()
// AddAccessToken adds the current access token to the request.
set sc=##class(%SYS.OAuth2.AccessToken).AddAccessToken(httpRequest,,"sslunittest",applicationName)
if $$$ISOK(sc) {
set sc=httpRequest.Get("https://myresourceserver/csp/openid/openid.SampleResource.cls")
}
Web クライアントの代行認証の定義 (オプション)
必要に応じて、OAuth 2.0 クライアントとして使用する InterSystems IRIS Web クライアントの代行認証を定義できます。InterSystems IRIS には、これが可能な以下の 2 つの方法が用意されています。
-
ZAUTHENTICATE ルーチンを作成して使用する方法。OAuth 2.0 で使用するために用意されているサンプルから作成します。クライアント・コードで %session.Login() を呼び出す必要もあります。
-
カスタム・ログイン・ページを作成して使用する方法。ZAUTHENTICATE ルーチンを作成して使用する必要もあります (OAuth 2.0 で使用するために用意されている同じサンプルから作成)。ただし、クライアント・コードで %session.Login() を呼び出す必要はありません。
次のサブセクションで詳細を説明します。最後のサブセクションでは、ZAUTHENTICATE のサンプルについて説明します。
"REST サービスの作成" の "REST サービスの保護" にある "REST アプリケーションおよび OAuth 2.0" も参照してください。
HealthShare® で認証を使用している場合は、インターシステムズが提供する ZAUTHENTICATE ルーチンを使用する必要があります。独自のルーチンは作成できません。
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 配列のその他の部分を設定する必要もあります。"代行 (ユーザ定義) 認証コードの作成" と "代行認証" を参照してください。
バリエーション
このページでは、InterSystems IRIS Web アプリケーションが承認コード付与タイプを使用するシナリオについて主に説明します。このセクションでは、いくつかのバリエーションについて説明します。
-
OnPreHttp 内でのリダイレクトの実行 (承認コードおよび暗黙付与タイプに該当)
基本シナリオでは、クライアントは承認サーバからアクセス・トークンを受け取り、必要に応じて承認サーバの追加エンドポイント (イントロスペクション・エンドポイントか Userinfo エンドポイントまたはその両方) を呼び出します。その後、クライアントはリソース・サーバを呼び出します。リソース・サーバがこれらのエンドポイントを個別に呼び出すこともできます。
バリエーション : PKCE の無効化
既定では、承認コード付与タイプを使用するクライアントは、Proof Key for Code Exchange (PKCE) 拡張を活用します。ほとんどの場合、クライアントはこの既定の動作を変更するべきではありません。PKCE は広く受け入れられている重要なセキュリティ機能であるためです。ただし、まれに、PKCE を無効にしたいことがあります。
PKCE を無効にするには、メソッドを呼び出す前に、GetAuthorizationCodeEndpoint() の properties 引数を変更します。コードには、以下の行を含める必要があります。
Set properties("code_verifier")=""
GetAuthorizationCodeEndpoint() の properties 引数の詳細は、"メソッドの詳細" を参照してください。
バリエーション:暗黙付与タイプ
このバリエーションでは、クライアントはトークンの要求時に暗黙付与タイプを使用します。
構成要件 : "クライアントの構成" の手順を参照してください。ただし、[クライアント・タイプ] は使用事例に応じて指定します。
コード要件:全体の流れは承認コード付与タイプと似ていますが、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 パラメータです。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。
request または request_uri パラメータを使用する場合は、"JWT としての要求オブジェクトの受け渡し" セクションを参照してください。
-
このクライアントおよびセッションのアクセス・トークンがローカルに保存され、さらにそのアクセス・トークンが scope 引数で提供されるすべてのスコープを承認する場合、出力として返される isAuthorized の値は 1 になります。それ以外の場合、このパラメータの値は 0 になります。
-
出力として返される sc には、このメソッドが設定したステータス・コードが含まれます。
-
sessionId はセッション ID を指定します。既定のセッション (%session.SessionId) をオーバーライドする場合のみこれを指定します。
"バリエーション :OnPreHTTP 内でのリダイレクトの実行" も参照してください。
バリエーション:パスワード資格情報付与タイプ
このバリエーションでは、クライアントはトークンの要求時にパスワード資格情報付与タイプを使用します。リソース所有者に属するパスワードがクライアントにある場合は、この付与タイプを使用できます。クライアント・アプリケーションは、ページのリダイレクトは行わずにトークン・エンドポイントへの HTTP POST 操作を実行できます。InterSystems IRIS は、これを行うメソッドを提供します。
構成要件 : "クライアントの構成" の手順を参照してください。ただし、[クライアントの秘密鍵] を指定する必要はありません。(一般に、クライアント秘密鍵は、クライアント秘密鍵を必要とし、かつこれを保護できる場合にのみ使用してください。)
コード要件:アプリケーションは以下を実行します。
-
"トークンの取得" の説明に従って、%SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出し、戻り値 (およびエラーの有無) を確認します。
-
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 パラメータです。ダイナミック・オブジェクトの詳細は、"JSON の使用" を参照してください。
-
出力として返される error は、Null であるか、エラー情報を含む OAuth2.Error のインスタンスです。
このメソッドはトークン・エンドポイントへの HTTP POST 操作を実行し、アクセス・トークンを受信して保存します (存在する場合)。
-
-
error 引数を確認し、それに応じて処理を進めます。
-
"トークンの検証" と "HTTP 要求へのアクセス・トークンの追加" の説明に従って作業を進めます。
バリエーション:クライアント資格情報付与タイプ
このバリエーションでは、クライアントはトークンの要求時にクライアント資格情報付与タイプを使用します。この付与タイプを使用すると、クライアント・アプリケーションはユーザから独立してリソース・サーバと通信できます。ユーザ・コンテキストは存在しません。クライアント・アプリケーションは、ページのリダイレクトは行わずにトークン・エンドポイントへの HTTP POST 操作を実行できます。InterSystems IRIS は、これを行うメソッドを提供します。
構成要件 : "クライアントの構成" の手順を参照してください。[クライアント・タイプ] に [プライベート] を指定し、[クライアント秘密鍵] を指定します。
コード要件:アプリケーションは以下を実行します。
-
"トークンの取得" の説明に従って、%SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出し、戻り値 (およびエラーの有無) を確認します。
-
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 操作を実行し、アクセス・トークンを受信して保存します (存在する場合)。
-
-
error 引数を確認し、それに応じて処理を進めます。
-
"トークンの検証" と "HTTP 要求へのアクセス・トークンの追加" の説明に従って作業を進めます。
OnPreHTTP 内でのリダイレクトの実行
承認コードおよび暗黙付与タイプの場合、上記の説明では次の手順に従います。
-
%SYS.OAuth2.AccessTokenOpens in a new tab の IsAuthorized() メソッドを呼び出します。
-
GetAuthorizationCodeEndpoint() メソッド (承認コード付与タイプ用)、または GetImplicitEndpoint() メソッド (暗黙付与タイプ用) を呼び出します。
-
上記の手順で返された URL を開くオプション (ボタンなど) を提供することで、ユーザは要求を承認することができます。
その代わりに、(アプリケーション内で) ページ・クラスの OnPreHttp() メソッドを変更することもできます。この場合、GetAccessTokenAuthorizationCode() メソッド (承認コード付与タイプ用) または GetAccessTokenImplicit() メソッド (暗黙付与タイプ用) を呼び出します。このメソッドは、最初にページのコンテンツを表示せずに、承認サーバの認証フォームにブラウザを直接移動します (必要な場合)。
バリエーション:JWT としての要求オブジェクトの受け渡し
OpenID Connect Core 仕様のセクション 6Opens in a new tab で規定されているように、InterSystems IRIS は JWT としての要求オブジェクトの受け渡しもサポートしています。値または参照によって要求オブジェクトを渡すことができます。
いずれの場合も、%SYS.OAuth2.RequestOpens in a new tab クラスのメソッドを使用します。このセクションに記載されていないその他のメソッドについては、クラス・リファレンスを参照してください。
値による要求オブジェクトの受け渡し
request パラメータを使用して JWT として要求オブジェクトを渡すには、以下の手順を実行します。
-
%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)
-
-
GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() の引数として使用する properties 配列を変更します。前の手順で作成した JWT と等しくなるようにノード properties("request") を設定します。以下に例を示します。
set properties("request")=jwt
-
GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() を呼び出すときに properties 配列を指定します。以下に例を示します。
set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp", scope,redirect,.properties,.isAuthorized,.sc, responseMode)
参照による要求オブジェクトの受け渡し
request_uri パラメータを使用して JWT として要求オブジェクトを渡すには、以下の手順を実行します。
-
%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)
-
-
保存されている要求オブジェクトの URL を取得します。そのためには、このインスタンスの GetURL() メソッドを呼び出します。GetURL() は、最初の引数の出力としてステータス・コードを返すので、コードでこれを確認します。
Set requesturl=requestobject.GetURL()
-
GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() の引数として使用する properties 配列を変更します。前の手順で取得した URL と等しくなるようにノード properties("request_uri") を設定します。以下に例を示します。
set properties("request_uri")=requesturl
-
GetAuthorizationCodeEndpoint() または GetImplicitEndpoint() を呼び出すときに properties 配列を指定します。以下に例を示します。
set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp", scope,redirect,.properties,.isAuthorized,.sc, responseMode)
バリエーション:承認サーバの他のエンドポイントの呼び出し
%SYS.OAuth2.AuthorizationOpens in a new tab のメソッドを使用すると、承認サーバの特定のエンドポイント・セットを呼び出すことができます。承認サーバに他のエンドポイントがある場合は、以下の一般的なプロセスを使用してそのエンドポイントを呼び出します。
-
%Net.HttpRequestOpens in a new tab のインスタンスを作成し、そのプロパティの設定とメソッドの呼び出しを必要に応じて行い、要求を定義します。
Set httpRequest=##class(%Net.HttpRequest).%New() Set httpRequest.ContentType="application/x-www-form-urlencoded" ...
このクラスの詳細は、"インターネット・ユーティリティの使用法" の" HTTP 要求の送信" を参照してください。
-
この要求に認証を追加するには、%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 のインスタンスです。
InterSystems IRIS は指定されたクライアントを検索し、その [認証タイプ]、[SSL 構成]、その他の情報を使用して適切な認証を要求に追加します。
-
-
必要に応じてクライアント構成を開くことで、そこに含まれるプロパティを使用できます。そのためには、%SYS ネームスペースに切り替えて、OAuth2.ClientOpens in a new tab の Open() メソッドを呼び出し、クライアント名を引数として渡します。
New $NAMESPACE set $NAMESPACE="%SYS" Set client=##class(OAuth2.Client).Open(applicationName,.sc) If client="" Quit
-
HTTP 要求オブジェクトの Post()、Get()、または Put() メソッドを必要に応じて呼び出し、承認サーバのトークン・エンドポイントを引数として提供します。以下に例を示します。
set sc=httpRequest.Post(client.ServerDefinition.TokenEndpoint)
-
必要に応じて追加処理を実行します。
アクセス・トークンの取り消し
承認サーバがトークンの取り消しをサポートする場合、管理ポータル経由またはプログラムによってアクセス・トークンを取り消すことができます。
ユーザのアクセス・トークンの取り消し
指定されたユーザのアクセス・トークンをすべて取り消すには、次の手順を実行します。
-
[システム管理]→[セキュリティ]→[OAuth 2.0]→[管理] を選択します。
-
ユーザ ID を [ユーザのトークンの取り消し] フィールドに入力します。
-
[取り消す] を選択します。
このタスクを実行するには、%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() も提供します。このメソッドはクライアントからアクセス・トークンを削除しますが、サーバからはアクセス・トークンを削除しません。
JWT で使用するキーの回転
ほとんどの場合、新しい公開/秘密鍵ペアをクライアントに生成させることができます。これは、非対称の RS256、RS384、および RS512 の各アルゴリズムに使用する RSA 鍵にのみ適用されます。(例外は、[X509 証明書] として、[ダイナミック登録以外のソース] を指定する場合です。この場合、新しいキーは生成できません。)
新しい公開/秘密鍵ペアの生成は、キーの回転と呼ばれています。このプロセスは、新しい秘密 RSA 鍵および関連する公開 RSA 鍵を秘密と公開の JWKS に追加します。
クライアントでキーの回転を実行すると、クライアントは新しい秘密 RSA 鍵を使用して、承認サーバに送信する JWT に署名します。同様に、クライアントは新しい公開 RSA 鍵を使用して、承認サーバに送信する JWT を暗号化します。クライアントは、承認サーバから受信した JWT を解読するために新しい RSA 鍵を使用しますが、これが失敗したら古い RSA 鍵を使用するため、古い公開 RSA 鍵を使用して作成された JWT を解読できます。最後に、承認サーバから受信した署名済みの JWT をクライアントが検証できない場合、クライアントに承認サーバの公開の JWKS の URL があると、クライアントは新しい公開の JWKS を取得し、署名の検証を再試行します。(クライアントが動的に登録された場合や、構成で [URL から JWKS] オプションが指定された場合、クライアントは承認サーバの公開の JWKS の URL を持っています。それ以外の場合にはクライアントはこの URL を持っていません。)
指定されたクライアント構成に対してキーを回転するには、次の手順を実行します。
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。
-
クライアント構成が関連付けられたサーバ記述を選択します。
これによってシステムは、サーバ記述に関連付けられたクライアント構成をすべて表示します。
-
キーを回転させたいクライアントの構成を選択します。
-
[キーの回転] ボタンを選択します。
対称の HS256、HS384、および HS512 の各アルゴリズムは、常に対称鍵としてクライアントの秘密鍵を使用します。
クライアント用のキーの回転の API
クライアントでキーをプログラムによって回転させるには、OAuth2.ClientOpens in a new tab の RotateKeys() メソッドを呼び出します。
新しい承認サーバの公開の JWKS を取得するには、OAuth2.ServerDefinitionOpens in a new tab の UpdateJWKS() メソッドを呼び出します。
これらのメソッドの詳細は、クラス・リファレンスを参照してください。
承認サーバからの新しい公開の JWKS の取得
ほとんどの場合、承認サーバは JWKS の公開/秘密鍵ペアを生成します。公開の JWKS をクライアントが受信する方法はさまざまです。1 つの方法は、承認サーバが URL で公開の JWKS を提供する方法です。"サーバ記述の手動による作成 (Discovery なし)" の [URL から JWKS] オプションを参照してください。
承認サーバが [URL から JWKS] で定義されていて、承認サーバが JWKS の新しいペアを生成する場合、同じ URL から新しい公開の JWKS をクライアントに取得させることができます。そのためには、以下の操作を実行します。
-
管理ポータルで [システム管理]→[セキュリティ]→[OAuth 2.0]→[クライアント構成] を選択します。
-
クライアント構成が関連付けられたサーバ記述を選択します。
これによってシステムは、サーバ記述に関連付けられたクライアント構成をすべて表示します。
-
クライアントの構成を選択します。
-
[JWKS の更新] ボタンを選択します。
承認サーバが [URL から JWKS] で定義されておらず、承認サーバが JWKS の新しいペアを生成する場合、公開の JWKS を取得し、これをクライアントに送信し、ファイルからロードする必要があります。