GAM を使用したセキュリティトークンサービスによるクライアント認証

この機能の目的は、複数の分散クライアントアプリケーション間に認証/承認を実装し、その処理を一元化することです。
セキュリティトークンサービス (STS) 標準を使用する典型的なシナリオでは、クライアントアプリケーション (A) から別のアプリケーション (B) のサービスを実行する必要がある場合などに、アプリケーション A からアプリケーション B へのアクセスがリクエストされます。アプリケーション A はセキュリティトークンサービスにリダイレクトされ、このサービスにより、クライアントの認証とセキュリティトークンの付与が行われます。
その後、アプリケーション B によって提供されているリソースへのアクセスを得るために、クライアント A からこのアプリケーションにトークンが提示されます。このトークンは STS サーバーに照らして検証され、A に該当するリソースへのアクセス許可が与えられているかどうかが確認されます。問題なければ、A からリクエストされたサービスが実行されます。

使用例の 1 つとして AGESIC PDI が挙げられます。
このソリューションは OAuth プロトコルに基づいています。OAuth プロトコル用に実装した STS 標準を使用して、GAM サーバー ID プロバイダーとクライアントアプリケーションが対話するようにしているため、GAM を使用していない (つまり、GeneXus を使用していない) クライアントアプリケーションでは、STS ID プロバイダーとして GAM サービスを使用することが求められます。
GAM を使用して STS を設定する方法については、「セキュリティトークンサービスを使用するように GAM を設定する方法」を参照してください。
このソリューションのアーキテクチャを理解するには、次の図を参照してください:

AppA から AppB のリソースにアクセスする必要があるものとします。ここで、GAM を使用する STS メカニズムの個々のステップについて説明します。一部のコンポーネントについては、(GAM を使用することなく) 手動で実装する必要がある場合があるため、HTTP リクエストで使用される HTTP ヘッダーの詳細とその他の詳細を具体的に取り上げます。

(1) トークンサービスのリクエスト
(2) STS からの応答 (アクセストークンまたはエラー)
(3) AppA による AppB リソースのリクエスト
(4) アクセストークンの照会
(5) アクセス許可の付与または拒否
(6) AppB リソースの応答

(1) トークンサービスのリクエスト

AppA から STS に対してアクセストークンがリクエストされます。このステップは GAM によって自動的に行われます。呼び出されるサービスは RequestTokenService です。

POST {ServerURL}/oauth/RequestTokenService HTTP/1.1

ヘッダー: 
Content-Type: application/x-www-form-urlencoded
Authorization:  Basic {ClientCredentials}

本文:
grant_type=client_credentials
scope={Scopes}
repository={RepositoryGUID}

入力値の説明

{ServerURL}: 認証サービス URL (STS サーバー) です。
{ClientCredentials}: STS サーバー上のアプリケーションの ClientID:UserPassword 文字列です。これは base64 で表されます。
{Scopes}: 認証リクエストの適用範囲です。リクエストの対象となるリソースの範囲をプラス記号 (+) で区切って指定したリストです。トークンは複数のアプリケーションへのアクセスのためにリクエストされることもあるため、各アクセス許可は AppName.Permission 形式にする必要があります。AppName は、STS ID プロバイダーサーバー上のアプリケーションの名前に対応します。
{RepositoryGUID}: サーバーにおけるリポジトリの GUID です。これはオプションです。トークンサーバーでマルチテナント GAM が使用されている場合にのみ必要です。

(2) STS からの応答 (アクセストークンまたはエラー)

資格情報とすべての適用範囲が正しければ、次の応答が返されます。

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "{Access Token}",
  "token_type": "Bearer",
  "expires_in": {Lifetime In Seconds},
  "scope": "{Scopes}"
}

入力値の説明

{Access Token}: リクエストに対して発行されたアクセストークンです。
{Lifetime In Seconds}: トークンの有効期間 (秒) です。
{Scopes}: アクセストークンに事実上付与された適用範囲です。

エラーが返された場合は、次のようになります:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"{detail}"
}

{detail} の内容は次のとおりです。

{invalid_request}: リクエストにおいて、一部の必須パラメーターが欠落しているか、同じパラメーターが複数回使用されているか、所定の動詞以外が使用されているか、何らかの形式エラーがあるかのいずれかです。
{invalid_client}: クライアント認証でエラーが発生しました。
{unsupported_grant_type}: リクエストの認可方法が予期されたものと異なります。
{unauthorized_client}: クライアントに指定の適用範囲に対する権限が与えられません。

(3) AppA による AppB リソースのリクエスト

AppA により、AppB のサービスを利用するために必要なトークンを使用して、該当するサービスが呼び出されます。

POST {ServerURL}/rest/{ServiceName} HTTP/1.1

ヘッダー:
Content-Type: application/x-www-form-urlencoded
GeneXus-Agent: STSOAuth Application
Authorization: {AccessToken}
本文:
client_id={ClientID}
repository={RepositoryGUID}
入力値の説明:

{ServerURL}: AppB の URL です。
{ServiceName}: 利用するサービスの名前です。
{AccessToken}: STS サーバーから取得されたトークンです (ステップ 2)。
{ClientID}: AppB におけるクライアントアプリケーションの ID です。
{RepositoryGUID}: AppB におけるリポジトリの GUID です。これはオプションです。AppB でマルチテナント GAM が使用されている場合にのみ必要です。

(4) アクセストークンの照会

AppB の REST サービスで POST を受信した時点で、受信したクライアント ID が GAM によって自動的に検証されます。それがローカル GAM に存在するかどうか、また STS が有効になっているかどうかが確認されます。
問題なければ、アクセストークンが検証されます。そのために、STS サーバーに対して HTTP POST が実行されます。

POST {ServerURL}/oauth/QueryAccessToken HTTP/1.1

ヘッダー:
Content-Type: application/x-www-form-urlencoded
OAUTH-TOKEN: {AccessToken}

本文:
grant_type= authorization_code

入力値の説明:

{ServerURL}: STS サーバーの URL です。
{AccessToken}: ヘッダーで受信したトークンです。

(5) アクセス許可の付与または拒否

トークンが正しく、まだ有効であれば、次の応答が返されます:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "client_id": "{ClientID}",
  "scope": "{Scopes}"
}

入力値の説明:

{ClientID}: トークンをリクエストしたクライアントアプリケーションの ID です。
{Scopes}: アクセストークンに事実上付与された適用範囲です。

エラーが返された場合は、次のようになります:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"{Detalle}"
}

(6) AppB リソースの応答

AppB リソースにより AppA に応答が返されます。
注:
AppB では、GAM により、該当するリモートトークンに対するリクエストがローカルデータベース内のセッション GAM テーブルに登録されます。
また、GeneXus ユーザーが GAMSession.Get メソッドを使用して GAMSession にアクセスできるように、ローカルトークンが生成され、受信したリモートトークンに関連付けた状態で保持されます。したがって、GeneXus ユーザーは、追加の検証が必要な場合にサービスの現在の利用者を特定できます。
STS を使用するように GAM を設定する方法については、「セキュリティトークンサービスを使用するように GAM を設定する方法」を参照してください。
実装の詳細
設定ファイル (web.xml および web.config) では、フレンドリー URL を使用して、サービス RequestTokenService および QueryAccessToken を呼び出すことができます。

/oauth/RequestTokenService --> artech.security.api.agamstsauthappgetacccesstoken を呼び出します。
/oauth/QueryAccessToken --> artech.security.api.agamstsauthappvalidacccesstoken を呼び出します。

使用可能バージョン
GeneXus 16 Upgrade 4 以降で利用できます。