GAM provides an API that allows users to handle data types and methods to add security (Authentication and Authorization) to GeneXus applications (both Web applications and Smart Device applications).
When integrated security is enabled in the KB (Enable Integrated Security property is set to TRUE), external objects are incorporated to allow the user to interact with the GAM API. External objects are the way to access the GAM API and are consolidated in the GAM_Library folder.
GAMUser, GAMRepository, GAMPermission, GAMApplication, GAMError are part of the external objects comprising the GAM Library.
Figure 1. Some GAM Library objects
How to use the GAM API
As said before, the GAM API provides methods to extend the functionality of security mechanisms. To learn how to use this API, you can read the GAM Examples that offer a wide range of use cases solved. When GeneXus Access Manager is enabled in the KB, you can decide whether to import these examples; see GAM Activation Process for details.
Figure 2. GAM API usage sample
The external objects in the GAM Library have properties and methods; in particular, they implement the same methods as Business Component, which are as follows:
If you change any properties in the GAM objects, you need to call the save() method and run the Commit command.
GAM objects also have other methods implemented to create, update or delete objects (see the AddPermission method in the example below). With these methods, the Commit command has to be used after the method is successfully executed. The only GAM methods that execute an implicit Commit are those related to the login, and they run on a new logical unit of work (LWU). See SAC 31253.
If you are going to make changes in both ways (from a property and using a method) and need to cancel both changes - when an error occurs - you need to control it programmatically.
Here is an example where you need to change a role description using an external object property, and add a permission to it using a method:
&gamrole.Load(&gamroleid) // &gamrole is GAMRole data type. In this line of code, load the role to change.
&gamrole.Description = "Description" // Change the description property of the role.
&isok = &gamrole.AddPermission(&gampermission,&gamerror) // Add a permission through a method. &gampermission is GAMPermission data type. &gamerror is collection of GAMError.
if &isok // Check if the permission was added successfully. &isok is Boolean data type.
&gamrole.Save() // Save the changes in the properties. Save the "Description" of the role.
commit // Commit all the changes.
rollback // If the properties were not successfully saved, rollback the changes.
do "process errors"
sub "process errors"
For &Error in &Errors
Msg(Format(!"%1 (GAM%2)", &Error.Message, &Error.Code), status)
GAM Activation Process