HowTo: Using GAM and Windows Authentication

Official Content
This documentation is valid for:

Consider a scenario where a .NET Web application authenticates using IIS Windows Authentication, but GeneXus Access Manager has to be used to manage the entire security of the application.

In this scenario, since GAM does not support Windows Authentication, it can delegate the authentication to IIS and solve the security concerns of the application after the user has logged in successfully (which means that IIS recognizes the user logged into Windows).

The main goal of this feature is to allow the user to access the web application using his or her Windows credentials without the need to enter the credentials in a dialog box.

Below are the steps to follow:

Step 1

The condition is that the virtual directory in IIS web server allows Windows Authentication (it is enabled). Besides, consider SAC #11464.

Step 2

In GeneXus, the solution consists of implementing Custom Authentication Type, where in this case the Procedure will get the information of the user who is logged into the application and return this information to GAM. This is a GeneXus Procedure that implements the authentication.

In this example, a custom authentication external service version 1.0 is implemented using the guide in [GAM External Authentication: version 1. link.

The Procedure which implements the authentication looks as follows (named "gamwslogin" in this example):

Parm( in:&GAMWSLoginInStr ,out:&GAMWSLoginOutStr ); //&GAMWSLoginInStr and &GAMWSLoginOutStr are varchar(256)

&GAMWSLoginIn.FromJson(&GAMWSLoginInStr) //&GAMWSLogin is GAMWSLogin SDT data type
&UserLogin = &GAMWSLoginIn.GAMUsrLogin
if not &UserLogin.IsEmpty() //If there is no error, load the out parameters of the authentication Procedure.
   &GAMWSLoginOut             = New GAMWSLoginOutSDT()
   &GAMWSLoginOut.WSVersion   = !"1."
   &GAMWSLoginOut.User        = New GAMWSLoginOutUserSDT()

   &GAMWSLoginOut.WSStatus          = 1 //Success
   &GAMWSLoginOut.User.Code         = &UserLogin

else
   &GAMWSLoginOut.WSStatus = 2 //User unknown
endif

&GAMWSLoginOutStr = &GAMWSLoginOut.ToJson()

Note: The data type of &GAMWSLoginOut is GAMWSLoginOut SDT, which is available here.

Step 3

Suppose the name of the GAM custom authentication type is "Windows Authentication".

[24036]
Figure 1. Definition of the Custom Authentication type, which is implemented by "gamwslogin" GeneXus Procedure.


Using GAM Backoffice configure the following:

reposettingswinauth
Figure 2. Repository settings. 

Step 4

The behavior of the Web Panel and Web Transactions which have Integrated Security Level property = Authentication / Authorization, is that when they execute and there is no valid user session, the object specified in Login Object for Web property (GAMExampleLogin Web Panel) is launched.

Then you need to program the Start Event of this object so that the GAMRepository.Login method is executed before showing any screens.

In this case, the login method calls the external authentication Procedure, which returns the user given by UserId function, and GAM creates a session for that user.

Below is the code of the Login object. Note that you execute the GAMRepository.Login method, and when the operation is successful, there is a redirect to the web object which had thrown the user session invalid exception.

Start Event
    ........................
    &UserName = userid() //Get the user login using the [[UserId Function]].
    &LoginOK = GAMRepository.Login(&UserName, "", &AdditionalParameter, &Errors ) //Login using external Procedure which is called automatically.
    If &LoginOK
       &URL = GAMRepository.GetLastErrorsURL()
       If &URL.IsEmpty()
          Home()
       Else
          Link(&URL) //return and continue with the flow of the application.
       Endif
    Else
       If &Errors.Count > 0
          ........................
       Endif
    EndIf
  
EndEvent

The first time the user executes the application, GAM registers it in the GAM User table. This registration is done automatically (see GAM Registration for more information).

Since then, each time the web session expires, the login is performed again, but a different session is given to the user.

Download the sample here. The xpz file contains the Procedure which implements the authentication (gamwslogin) and all the SDTs needed. Besides, it contains a SampleLogin Web Panel which should be configured as Login Object for Web property.

See Also

UserId function
GAM - Authentication Types