GAM - Repository Connections

This documentation is valid for:
GeneXus 18 Help

The purpose of the GeneXus Access Manager Repository connection is to add a security level to the GAM application. Therefore, to access the GAM application, you need to establish a Repository connection first. It's like having an API key.

Then, the GAM API methods execute only after the GAM repository connection is successfully established. More than one connection can be defined for each repository. This is particularly interesting when many Web or Native Mobile Applications access the same GAM repository. In this case, the administrator can control the access to the GAM by managing the repository connections defined in the database.

The user associated with the repository connection is called GAM Connection User.

The connection data is saved in the connection.gam file, under the web directory of the GeneXus model.

Considerations about the GAM Repository Connections

1. When security is set in the Knowledge Base (Enable Integrated Security Property = Yes) or, specifically, any time a new GAM database has to be created by GeneXus, a GAM repository connection is defined by default. In this case, the GAM Connection User Name is set by default with the name of the active version.
This information is generated by the GX IDE in the GAM database for prototyping purposes. Nevertheless, the GAM connection user can be changed as desired before the GAM database is created (see GeneXus Administration of GAM repository for more information).

Figure 1 shows the default repository connection created in the GAM database, for a KB called TestRestAuthorization.

Figure 1.

2. One possible scenario is to have N applications using the same GAM repository.

Once a GAM database has been defined, for any other environment or KB that needs to use the same GAM database you have to set existing values for Connection User Name Property and Connection User Password Property (the same as Administrator User Name Property). The best option is to define and set a different repository connection for each application in this case. This is for performance and security reasons.

The Repository ID property has to be the same in all KBs.

A new connection can be created using the GAM API. The GAM Backoffice also provides an easy way to manage repository connections, by clicking on Repository > connections to view the list of existing repository connections as shown below.

After clicking on the "ADD" button, the following will appear to create a new repository connection:

Figure 2.

After the GAM Connection has been created in the GAM database, you can generate a new key or associate the current key. All connections are kept in the database and not in the connection.gam file, as was the case in previous GeneXus versions. The connection.gam file only contains the key that can have N connections in the database.

Figure 3.

Figure 3 shows how to associate a key with the created connection:

You can use the current key by clicking on the USE CURRENT KEY button to add a new connection to the existing ones.
If you prefer to generate a key automatically, select the USE AUTOMATIC KEY button to create a new connection.gam with the entire XML.
You also have the option to manually add a key.

To get the content of the connection.gam file, press the FILE button and copy the generated XML into the new connection.gam file.

Additionally, you can save the key using the SAVE KEY button, remove a key with the DELETE button or delete the current connection with the Delete connection button.

Note: You can only have one connection per repository with the same connection key..

Important

By default GAM will try to establish the connection using the environment variable GX_GAMCONNECTIONKEY in case it is not defined it will use the connection.gam file.

To learn more about how to work with the environment variable, read HowTo: Use an environment variable to establish repository connections in GAM.

In summary:

A GAM repository connection is determined by a Connection User, and is used to establish a connection to the GAM database Repository each time the GAM API methods are used.
The GAM connection information is stored in the GAM database and has to be set under the connection.gam file, which has to be included in the server deployment.
A GAM database may have N GAM repository connections. Each Repository Connection may be used from a different Knowledge Base or environment that uses the same GAM database.
The Repository ID is what identifies the repository and has to be the same in all KBs that use the same GAM Repository.
Several Repositories can be stored in the same GAM database, and in this case, you need to define a connection for each Repository, updating the connection.gam file accordingly. See HowTo: Create New Repositories using GAM for details.
GAM Connection Key can be specified via environment variable GX_GAMCONNECTIONKEY. See SAC #49841.