This article describes the GAM Endpoints in order to explain authentication with GAM as IDP using the OAuth 2.0 protocol.
Unlike the article HowTo: Use GAM as an OAuth 2.0 provider where this concept is applied within GAM itself, this article explains how it can be used by any external client.
OAuth2.0 protocol flow with GAM Endpoints as IDP (Identity Provider): 
Endpoints:
The /oauth/gam/signin endpoint is used to request authorization. In its response, it provides an access code that will be necessary to obtain an access token later on.
Endpoint:
$ServerURL/oauth/gam/signin
GET
Headers:
Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded
Parms:
oauth: This parameter must have the value "auth."
redirect_uri: Callback URL of the requesting application.
client_id: Client ID of the application.
redirect_uri: Callback URL (it must match the one configured in the application).
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).
state: Random string that stores the status before the request.
repository_ssorest: Requester repository ID (optional).
POSTMAN Example:
Response:
It will be a redirection to the callback URL that will have the state and code in its Parms.
For example: domain:port/<virtual directory>/<callback>?state=GRESTD6059555651b947e98bbd9935&code=e8279ad27bfd4e6ca717191cfc74fe4d413494378b53da98ca954924ac6791eb0ab56c06
The /oauth/gam/access_token is used to obtain an access token or refresh token.
Endpoint:
$ServerURL/oauth/gam/access_token
POST
Headers:
Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded
Body:
code: Code obtained in the authorization step.
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).
grant_type: In this case, it must be "authorization_code."
redirect_uri: Callback URL (it must match the one configured in the application).
POSTMAN Example:
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"
}
To receive a refresh token, you must change the default value of the property Maximum OAuth token renewals in GAM Security Policies.
With an access token, you can consume the /oauth/gam/userinfo endpoint to obtain information about a user.
Endpoint:
$ServerURL/oauth/gam/userinfo
GET
Headers:
Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded
Authorization: access_token obtained.
POSTMAN Example:
Response:
In response, you will receive a JSON with the following format:
{
"guid":"139f4332-3f40-47b0-8fb4-ee7b3dbddc4f",
"username":"admin",
"email":"admin",
"verified_email":true,
"first_name":"Administrator",
"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":"",
"roles":["is_gam_administrator"]
}
To use the refresh token, a request must be made to the same access token endpoint /oauth/gam/access_token, using the grant type "refresh_token."
See Access Token Note.
Endpoint:
$ServerURL/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: In this case, it must be "refresh_token."
refresh_token: refresh_token received when requesting the access_token.
POSTMAN Example:
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:
Response:
In response, you will receive a JSON with the following format:
{
"error": {
"code": "103",
"message": "Token expired, log in again."
}
}