GAM の認証タイプ: OAuth 2.0

GeneXus Access Manager (GAM) では、任意の OAuth 2.0 プロバイダーを使用した認証が可能です。以下ではその手順を説明します。
この GAM の認証タイプの定義は、GAM に既に存在するほかの認証タイプと同じです。ただし、このタイプの認証では、プロバイダーが使用するプロトコルの詳細な設定が必要です。
したがって、GAM で OAuth 2.0 認証タイプを設定するには、接続する ID プロバイダーのドキュメンテーションに従う必要があります。
実行時の処理は、Facebook や Google の認証の処理と似ています。このタイプの認証を選択すると、設定した ID プロバイダーにログインがリダイレクトされます。
プロバイダーによって表示されたログイン画面でユーザーが自分の資格情報を入力すると、アプリケーションにリダイレクトされます。
加えて、プロバイダーのアクセストークンがリフレッシュされたときの GAM セッションの更新が自動的に解決されます。この動作はオプションです。そうでない場合、トークンが提供されたときに GAM セッションが期限切れになります。詳細については、後述の情報を参照してください (¹)。
次のようなプロバイダーがあります:

Azure Active Directory
Facebook
Google
Instagram
LinkedIn
Mercado Libre
Office 365
WeChat

設定

このタイプの認証は、複数のタブで設定します。

[ 全般 ] タブ

OAuth 2.0 でアプリケーションを識別する基本情報 (クライアント ID、クライアントシークレット、リダイレクト URL) を示します。
クライアント ID とクライアントシークレットは ID プロバイダーから取得されます。
[ リダイレクト URL をカスタム ] が選択されると、GAM は URL を変更しません。そのため、開発者は受信した応答を適切に処理する必要があります。
[ 認証にリダイレクト ] オプションを選択解除すると、ID プロバイダーにリダイレクトせずに REST を使った OAuth 2.0 認証を行うことができます。

[ オーソライズ ] タブ

ユーザーが資格情報を入力するための URL を設定します。
この URL を呼び出すのに必要ないくつかのパラメーターを、このセクションで指定する必要があります。応答パラメーターについても同じです。
ユーザーが認証されると、ID プロバイダーがアクセスコードを返します。受け取ったアクセスコードを使用して、GAM がアクセストークンをリクエストします。
また、OAuth 2.0 を使用するときに、IDP に送信するパラメーターを追加できます。

例:

&CustomGAMProperty = new()
&CustomGAMProperty.Id = "language"
&CustomGAMProperty.Value = "en"
&AdditionalParameter.Properties.Add(&CustomGAMProperty)
&CustomGAMProperty = new()
&CustomGAMProperty.Id = "DeviceId"
&CustomGAMProperty.Value = "AZ-Prueba"
&AdditionalParameter.Properties.Add(&CustomGAMProperty)
&CustomGAMProperty = new()
&CustomGAMProperty.Id = "CustomerId"
&CustomGAMProperty.Value = "123456"
&AdditionalParameter.Properties.Add(&CustomGAMProperty)

&AdditionalParameter.AuthenticationTypeName = &NameAuthType
&LoginOK = GAMRepository.Login(&UserName, &UserPassword, &AdditionalParameter, &Errors)

その後、 [ オーソライズ ] タブで認証タイプを設定します:
追加パラメーター: DevId=$DeviceId&CusId=$CustomerId.

注: 前の例に示すコードを、Login イベントの Login Web パネル内の [ Events ] エレメントに追加します。

[ トークン ] タブ

トークンをリクエストするサービスの URL (*) を設定します。この呼び出しはバックグラウンドで行われ、アクセストークンの取得が試みられます。
この呼び出しへの応答は、Response セクションで設定します。
[ Authorization ヘッダーに Basic 値を含める ] : プロバイダーを使って OAuth 2.0 の認証を行う場合、トークンを取得するために、Content Type ヘッダーのみを定期的にリクエストします。ただし、Oracle Access Management (OAM) など、一部の OAuth 2.0 プロバイダーは Authorization ヘッダーをリクエストします。このチェックボックスは、Authorization ヘッダーを Base64 で追加 (ClientId:ClientSecret を Base64 で追加) するために使用します。

(¹) オプションで、ID プロバイダーのアクセストークンの有効期限を検証するように GAM を設定できます。その場合、アクセストークンがリフレッシュされると GAM でセッションが自動的に更新されるため、ユーザーが再度ログインする必要はありません。これは [ 外部トークンを検証 ] チェックボックスで行われます。
プロバイダーがリフレッシュトークンを返したときに、このアクションの URL を設定できます (リフレッシュトークン URL)。リフレッシュトークン URL を設定しない場合は、前に設定したのと同じ URL (*) を使用してトークンをリクエストします。

トークンが更新された場合は、GAMSession.ExternalToken メソッドを使用してアクセスできます。トークンの有効期限が切れ、リフレッシュされない場合、アプリケーションはそのユーザーをログアウトします (GAM セッションが終了します)。

[ ユーザー情報 ] タブ:

認証済みユーザーのデータを取得するサービスの URL を設定します。アプリケーションの認証を完了するには、このサービスが不可欠です。
応答は JSON 形式で、そこでユーザーのデータが取得されます。
プロバイダーのフィールドを GAM のフィールドにマッピングすることが必要な場合もあります。たとえば、ユーザーの性別を GAM の表記規則とマッピングする、Gender Values: (文字列) などです。
GAM では、M=male (男性)、F=female (女性) です。

カスタムのユーザー項目属性

User Information のフォームに含まれるフィールドにマッピングできない項目属性のために、ペア (項目属性名、項目属性タグ) を追加できます。これらの項目属性は GAM ユーザーの拡張項目属性として保存されます。

項目属性名: GAM データベースに保存される、GAM 拡張ユーザー項目属性の ID です。その ID を使って情報を取得できます。
項目属性タグ: 取得する項目属性に対応するユーザー情報を返す JSON サービスレスポンスタグです。

たとえば、項目属性名 = Amount、項目属性タグ = salaryAmount というペアがある場合、IDP のレスポンスからタグ「salaryAmount」が抽出され、その情報が、GAM テーブル内の「Amount」ID を使用して、ユーザーの拡張項目属性として保存されます。この情報は、GAM User オブジェクトの拡張項目属性メソッドを使って取得できます。

プロバイダーごとの設定

Azure Active Directory
Facebook の設定
Google の設定
Instagram の設定
LinkedIn の設定
Mercado Libre の設定
Office 365 の設定
WeChat の設定

使用可能バージョン

GeneXus 15 Upgrade 11 以降。

参考情報

OAuth 2.0 プロバイダーとして GAM を使用する方法
GAMUser オブジェクトの [ 外部 ID ] プロパティ