Federation

SampleDB supports sharing information with partnering databases.

First steps

  1. Create a UUID using the generate_uuid script (see: Administration Scripts)

  2. Set the SAMPLEDB_FEDERATION_UUID environment variable to the created UUID string

  3. Add a database via frontend after logging in as administrator:
    More -> Other Databases (<host>/other-databases/)
    To exchange data giving a UUID and address is mandatory

  4. Generate an export token by clicking the + button in the Export section

  5. Set up the other database’s export token as import token by clicking the + button in the Import section

Configured databases can be selected when editing the permissions for an object (see: Sharing with other databases). You can repeat the steps 3 to 5 for every additional database you want to exchange data with.

UUIDs and federated keys

To generate unique identifiers for objects in a federation and to identify individual databases, each database receives a universally unique identifier (UUID). Based on this identifier a composite federation key is created, consisting of the local id of the object, action, location, or other information entry id and the component’s UUID.

For example, a UUID can be created by using the generate_uuid administration script. Using pseudo-randomly generated UUIDs of version 4 is recommended. Since there is a sufficiently small probability of version 4 UUIDs being assigned twice, there is no mandatory need to check for duplicates with other databases.

After setting the UUID once and starting exchanging data with another database the UUID must not ever be changed, as this leads to unresolvable object references, duplicates, and confusion.

If no UUID is set using the environment variable SAMPLEDB_FEDERATION_UUID the federation feature is not activated.

Authentication

Databases verify themselves by tokens previously exchanged between them, similar to API tokens. These are created by the database administrators and have to be exchanged individually.

Export tokens are used by other databases to verify themselves and are generated automatically. A created export token is used by the partnering database as an import token to import the exported information.

Managing other databases

The administrator of a SampleDB instance manages the connections to other databases. Adding a database requires specifying its UUID, exchanging data also requires one import and one export token as well as the database URL. Additionally, a database should be given a name.

The administrator can also manually trigger the synchronization of data.

Managing other databases

Managing other databases

Federation Graph

The databases that are connected to a SampleDB instance either directly or via others are shown in the federation graph. This can help give an overview over the SampleDB instances in a federation and their connections with each other. To disable being shown in the federation graph of other databases, the environment variable SAMPLEDB_ENABLE_FEDERATION_DISCOVERABILITY can be set to false.

A federation graph

A federation graph

Federated Login

The federated login allows users to authenticate using the login of a federation partner.

To enable this feature, the environment variable SAMPLEDB_ENABLE_FEDERATED_LOGIN can be set to true. The federated login requires that both instances have set this environment variable.

After both instances have set up the environment variables, it is required to import updates on both instances so that metadata can be imported.

Note

To enable the login with a federation partner, it is required that, when importing updates, the other database already has the metadata. This means the database that imports updates as the first one after activating this feature must import a second time as soon as the other database has also imported updates.

If set up properly, an additional button (“Sign in with …”) will be added to the sign in page for each federation partner that is available for the federated login.

When using the federated login, the user must have a federated identity on the target database which links an existing local user with the used federated user from the other database. As an alternative to linking a local user, it is also possible to enable that new users can be created. To allow this, the environment variable SAMPLEDB_ENABLE_FEDERATED_LOGIN_CREATE_NEW_USER can be set to true.

Note

The federated login requires that the domain used in the configuration of the federated database is the same the user will use to access the database.