GAM - OAuth 2.0 Endpoints to use GAM as Web IDP Server

Official Content
This documentation is valid for:

This article describes the GeneXus Access Manager (GAM) Endpoints in order to explain authentication with GAM as IDP using the OAuth 2.0 protocol

Requirements:

Define a GAM Application that will be the client that you want to connect to the IDP Server. Get the Client ID and the Client Secret credentials from this application.

image1_202382310406_1_png

When creating the application, you must assign it a name, enable the Allow Authentication property within the WEB Identity Provider. Configure the URL of the Login Object and in the Callback URL property configure the address of the application to integrate. When confirming, the ClientID and Client Secret will be generated.

OAuth2.0 protocol flow with GAM Endpoints as IDP (Identity Provider) 

FlujoOauth_png

Endpoints:

1. Signin

The endpoint is: https://gamidentityprovider.com/virtual_dir/oauth/gam/signin.

Parms:

oauth: This should be the first parameter and must have the value "auth."
scope: Scope of the user account you wish to access. (gam_user_data is required; gam_user_roles and gam_user_additional_data can also be included).
client_id: Client ID of the application.
redirect_uri: Callback URL (it must match the one configured in the application). https://<your_server>/<virtual_directory>/oauth/gam/callback.
state: Random string that stores the status before the request.

If your application does not contain that Friendly URL (/oauth/gam/callback), you can specify another Custom URL. For example if your application have https://<your_server>/<virtual_directory>/oauth/return you must configure this URL in the IDP Server and check Custom Callback URL property.

Redirect to:

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>

After authenticate you will be automatically redirected to redirect_uri, including the following parameters: state and code.

For example: https://<your_server>/<virtual_directory>/oauth/gam/callback?state=<random_alphanumeric>&code=e8279ad27bfd4e6ca717191cfc74fe4d413494378b53da98ca954924ac6791eb0ab56c06

The developer must validate that the value of the state is the same as the one sent to the IDP Server.

2. Access Token

The endpoint is: https://gamidentityprovider.com/virtual_dir/oauth/gam/access_token

POST
Headers:

Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded

Body:

grant_type: In this case, it must be "authorization_code."
code: Code obtained in the Step 1.
client_id: Client ID of the application.
client_secret: Client Secret of the application.
redirect_uri: Callback URL (it must match the one configured in the application). https://<your_server>/<virtual_directory>/oauth/gam/callback.
 

POSTMAN Example:

Accesstokenheaders_202261415224_1_png
Accesstokenbody_2022614162527_1_png

Response:

In response, you will receive a JSON with the following format:

{
    "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"
}

Note

To receive a refresh token, you must change the default value of the property Maximum OAuth token renewals in GAM Security Policies.

3. User Info

The endpoint is: https://gamidentityprovider.com/virtual_dir/oauth/gam/userinfo.

GET
Headers:

Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded
Authorization: access_token obtained in the Step 2.

POSTMAN Example:

UserinfoHeaders_2022614152513_1_PNG

Response:

In response, you will receive a JSON with the following format:

{
   "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":""
}

4. Refresh Token

The endpoint is: https://gamidentityprovider.com/virtual_dir/oauth/gam/access_token

POST
Headers:

Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded

Body:

client_id: Client ID of the application.
client_secret: Client Secret of the application.
grant_type: must be "refresh_token."
refresh_token: refresh_token received when requesting the access_token obtained in Step 2.

POSTMAN Example:

RefreshtokenHeaders_202261416125_1_PNG

Refreshtokenbody_PNG

Response:

In response, you will receive a JSON with the following format:

{
    "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"
}

When to call the Refresh Token

When a Rest service is called and the access token has expired, 401 and Error 103 are returned. If this happens and there is a Refresh Token saved, it can be used as detailed above; otherwise, a new Access Token must be requested.

POSTMAN Example:

procrest_png

Response:

In response, you will receive a JSON with the following format:

{
    "error": {
        "code": "103",
        "message": "Token expired, log in again."
    }
}