この記事では、
OAuth 2.0 プロトコルを使用し、
GeneXus Access Manager (GAM) を IDP とする認証を行うために、GAM エンドポイントについて説明します。
要件:
IDP サーバーに接続するクライアントとなる GAM アプリケーションを定義します。このアプリケーションから、クライアント ID とクライアントシークレットの資格情報を取得します。
アプリケーションを作成する際には、名前を割り当て、Web ID プロバイダー内で [ Allow Authentication ] プロパティを有効にする必要があります。Login オブジェクトの URL を設定し、 [ Callback URL ] プロパティで統合するアプリケーションのアドレスを設定します。確認すると、クライアント ID とクライアントシークレットが生成されます。
エンドポイント:
エンドポイントは https://gamidentityprovider.com/virtual_dir
/oauth/gam/signin です。
パラメーター:
oauth: これは最初のパラメーターで、値は "auth" であることが必要です。
scope: アクセスするユーザーアカウントの適用範囲。(gam_user_data が必要です。gam_user_roles と gam_user_additional_data も含めることができます)
client_id: アプリケーションのクライアント ID。
redirect_uri: コールバック URL (アプリケーションで設定した値と一致する必要があります)。 https://<your_server>/<virtual_directory>
/oauth/gam/callback.
state: リクエスト前のステータスを保存するランダムな文字列。
アプリケーションにフレンドリー URL (/oauth/gam/callback) が含まれていない場合、別のカスタム URL を指定できます。たとえば、アプリケーションに https://<your_server>/<virtual_directory>
/oauth/return がある場合、この URL を IDP サーバーで設定し、 [ Custom Callback URL ] プロパティを確認する必要があります。
リダイレクト先:
https://gamidentityprovider.com/virtual_dir
/oauth/gam/signin?oauth=auth
&scope=gam_user_data
&client_id=<Client_ID>
&redirect_uri=https://<your_server>/<virtual_directory>/oauth/gam/callback
&state=<random_alphanumeric>
認証後、パラメーター
state と
code を含め、redirect_uri に自動的にリダイレクトされます。
例: https://<your_server>/<virtual_directory>
/oauth/gam/callback?state=<random_alphanumeric>
&code=e8279ad27bfd4e6ca717191cfc74fe4d413494378b53da98ca954924ac6791eb0ab56c06
開発者は、state の値が、IDP サーバーに送信されるものと同じであることを確認する必要があります。
エンドポイントは https://gamidentityprovider.com/virtual_dir
/oauth/gam/access_token です。
POST
ヘッダー:
Content-Type: 返されるコンテンツのタイプ。application/x-www-form-urlencoded を使用します。
本文:
grant_type: この場合は、"authorization_code" である必要があります。
code: 手順 1 で取得したコード。
client_id: アプリケーションのクライアント ID。
client_secret: アプリケーションのクライアントシークレット。
redirect_uri: コールバック URL (アプリケーションで設定した値と一致する必要があります)。https://<your_server>/<virtual_directory>
/oauth/gam/callback
POSTMAN の例:
応答:
応答では、次の形式の JSON を受け取ります:
{
"access_token": "7032f1fd-e7a9-48bc-b9db-88a35b121b09!3964ab5e6ab7d771c6c5744122eaac8da2363a041fbfa96828441cd4a2b4c19d1319bb0dc775aa@SSORT!7032f1fd-e7a9-48bc-b9db-88a35b121b09!0c6fe15b76f14f5b8a0805c1b6c20appA",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "00167b653abbc064b5982a1fd15e0f974b5",
"scope": "gam_user_data",
"user_guid": "139f4332-3f40-47b0-8fb4-ee7b3dbddc4f"
}
リフレッシュトークンを受け取るには、
GAM のセキュリティポリシーで、 [
Maximum OAuth token renewals ] プロパティの既定値を変更する必要があります。
エンドポイントは https://gamidentityprovider.com/virtual_dir
/oauth/gam/userinfo です。
GET
ヘッダー:
Content-Type: 返されるコンテンツのタイプ。application/x-www-form-urlencoded を使用します。
認証: 手順 2 で取得した access_token。
POSTMAN の例:
応答:
応答では、次の形式の JSON を受け取ります:
{
"guid":"139f4332-3f40-47b0-8fb4-ee7b3dbddc4f",
"username":"user",
"email":"user@example.com",
"verified_email":true,
"first_name":"user",
"last_name":"User",
"external_id":"",
"birthday":"2000-01-01",
"gender":"N",
"url_image":"https://",
"url_profile":"",
"phone":"+598",
"address":".",
"city":".",
"state":".",
"post_code":".",
"language":"Eng",
"timezone":".",
"CustomInfo":""
}
エンドポイントは https://gamidentityprovider.com/virtual_dir
/oauth/gam/access_token です。
POST
ヘッダー:
Content-Type: 返されるコンテンツのタイプ。application/x-www-form-urlencoded を使用します。
本文:
client_id: アプリケーションのクライアント ID。
client_secret: アプリケーションのクライアントシークレット。
grant_type: "refresh_token" である必要があります。
refresh_token: 手順 2 で取得した、access_token を要求したときに受け取った refresh_token。
POSTMAN の例:
応答:
応答では、次の形式の JSON を受け取ります:
{
"access_token": "85a3006c-0606-41d2-980e-223f88463ec2!b1b3e778247c870560d49d17ffd514a2a8467747208b1cf4a641780a267466bc65fba8034c9bbc",
"token_type": "Bearer",
"expires_in": 180,
"refresh_token": "002b9ec850f78b845d883779fa52c91a01",
"scope": "gam_user_data",
"user_guid": "139f4332-3f40-47b0-8fb4-ee7b3dbddc4f"
}
リフレッシュトークンを呼び出すタイミング
REST サービスが呼び出され、アクセストークンの期限が切れると、401 エラーおよび 103 エラーが返されます。このエラーが発生した場合、保存済みの
リフレッシュトークンがあれば、上記で詳しく説明したとおりに使用できます。それ以外の場合は新しい
アクセストークンをリクエストする必要があります。
POSTMAN の例:
応答:
応答では、次の形式の JSON を受け取ります:
{
"error": {
"code": "103",
"message": "Token expired, log in again."
}
}