GAM Remote Rest Authentication type (Oauth 2.0)

Official Content
This documentation is valid for:

The GAM Remote Rest authentication type allows an application using GAM to use another GAM as an Identity Provider. The user will log in to the application using credentials that are stored in an Identity Provider (IDP).

So, there is a client application (Web or SD, with its own GAM) and an Identity Provider (using GAM) where the user will be authenticated.

In general, this solution is used in a trusted environment, because the user's credentials are entered at the client and flow through that application. 

The following is a very simplified schema about this solution (implementation details are shown below).

  1. The user enters his credentials at the client application.
  2. These credentials (and other information, which we detail afterwards) are used to call the Identity Provider's Rest authentication services, where the user is authenticated.  
  3. The Identity Provider sends a response to the caller, and then it returns to the client application (with an error if the authentication fails).

image_20191213154257_1_png

It's very similar to GAM Remote Authentication Type (as it uses Oauth 2.0), but in this case the login is done using Rest. So there is no redirection to the Identity Provider's login as in the SSO scenario.



Some characteristics of this authentication type are:
  1. The user enters his credentials in a local login and is not redirected to the Identity Provider's login as in GAM Remote authentication. The Identity Provider is the owner of the user credentials, as always.
  2. In fact, the login is done using the same protocol as GAM Remote (Oauth 2.0).

Cases for use

As explained above, in general it will be used in a trusted environment, for credentials are entered at the client.

  1. It proves especially useful when you need a token to call a service running under another GAM. 

    After the login, a GAMSession is generated at the Identity Provider's GAM and at the client's (the same as with GAM Remote Authentication). The GAMSession has the local token and the external token, to be used for calling any Rest service (depending on whether the service is hosted at the client or at the server).

    So, if you need to consume a Rest service using GAM from an application that uses GAM as well, you may authenticate to the provider application using GAM Remote Rest authentication type to get a valid token, instead of using HTTP calls.

  2. In case of a Smart Devices app, where you need to authenticate against an Identity Provider and want to avoid the user from being redirected to the IDP's web login.


Architecture and implementation

The following is an architecture schema (though it does not fully show its complexity, it's useful for understanding what happens under the hoods).

image_201912413144_1_png

When the user logs in, instead of redirecting to the Identity Provider, the client makes a call to ask for a valid token, using the following URL:

$ServerURL/oauth/gam/v2.0/access_token

The information of the user is requested at this URL

$ServerURL/oauth/gam/v2.0/userinfo

Example

Calling a rest service running at the client's KB.

First, you log in using GAM Remote Rest.

&AdditionalParameter.AuthenticationTypeName = !"gamremoterest" //&AdditionalParameter is of GAMLoginAdditionalParameters data type
&LoginOK = GAMRepository.Login(&user, &password, &AdditionalParameter, &GAMErrors)

Then, at any time you can get the Token from the GAMSession to call the Rest service.

&AccessToken = GAMSession.GetToken()
//Here call Rest Service using the Authorization headers.
&httpclient.AddHeader(!"Authorization",!"OAuth " + &AccessToken)
&httpclient.AddHeader(!"GeneXus-Agent",!"SmartDevice Application")
&httpclient.Execute(&method,&getstring) //E.g: &httpclient.Execute(!"GET",!"http://server/baseurl/rest/GetCustomers")

The GAMSession.GetToken() method returns the local Token (useful for calling a service of the client KB). Note that for this token, applicable security policies are the web (not Oauth, so the time out expiration of this token is the Web session timeout).

If you want to call a service of the server KB, you must get the external token (to be passed in the authorization headers) using the following:

&GAMSession = GAMSession.Get(&GAMErrors)
&AccessToken = &GAMSession.ExternalToken

Configuration

Server side configuration

See Server side configuration for GAM Remote Rest Authentication type

Client side configuration

See Client side configuration for GAM Remote Rest Authentication type

Availability

As from GeneXus 16 upgrade 7

See also

Single Sign-on for Rest Services using GAM