Authentication

For authorization and authentication purposes an entici instance requires a Keycloak server with a preconfigured trustcenter realm.

Figure 1. Overview of required Keycloak clients.

Figure 1 shows an overview of all relevant clients. The legend at the top visualizes the OAuth2 roles by using different background colors. It can be seen that in Keycloak a client can act both as resource server and as client at the same time (e.g. entitylist-webapp). The client trustcenter-test is available for testing an external interface of the trustcenter (e.g. /v1/process/). See Smoke Test for more details about how to run the test.

Keycloak Roles#

Generally, true to the microservice architecture, access between different apps within entici is implemented in a binary manner. This means a token issued for a specific app grants access to all REST interfaces of that app or none. To this end, a single role, e.g. usage-allowed, has to be provided to the respective bearer-only or public client.

An exception is the “Depsn-Service”, which provides depseudonymization functionality based on an optional query parameter target-system. Access is decided based on the existence and value of this parameter:

• If role default-case-allowed is provided, all queries without query parameter are granted access. This role is a wildcard and should not be used lightly.
• If role all-systems-allowed is provided, all queries with any value for the target-system query parameter are granted access. This role is a wildcard and should not be used lightly.
• For any role <some-target-system>, access is only granted if this specific target system is specified as query parameter.

Keycloak Clients#

Table 1 shows an overview of all required clients including their types as well as the entici version with which it was introduced.

Table 1. Overview of required Keycloak clients.

Table 2 shows an overview of required and optional roles and service account roles, respectively.

Table 2. Overview of (required) (service account) role(s) for each required Keycloak client.

KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_PSN_SERVICE=backend-entitylist
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_DEPSN_SERVICE=entitylist-depsn-service
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_WEBAPP=entitylist-webapp
KEYCLOAK_CLIENT_CLIENT_ID_FOR_INTERFACE=trustcenter-interface
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_INTERFACE=trustcenter-facade

Keycloak Configuration#

The required trustcenter realm can either be created by importing an existing configuration or by creating all relevant clients manually.

Import Realm#

A default configuration in form of a json file which can be imported into a Keycloak server can be downloaded here. If you are using a template, replace all occurrences of ---REPLACE-WITH-<CLIENT_SECRET>--- with the appropriate secrets of the trustcenter-interface and trustcenter-test clients, respectively.

Manual configuration#

Create public client#

1. Login to the administration console with the admin user
2. Go to Clients > Create
3. In General Settings, enter Client ID
4. Click Next
5. In Capability config, check Standard flow
6. Click Next
7. In Login settings
   • Add relevant Valid Redirect URIs in the form <http(s):://host(:port)/*>
   • Add relevant Web Origins in the form <http(s):://host(:port)>
8. Click Save
9. In Roles, add required role(s)

Create confidential client#

1. Login to the administration console with the admin user
2. Go to Clients > Create
3. In General Settings, enter Client ID
4. Click Next
5. In Capability config, enable Client authentication and check Service accounts roles
6. Click Next
7. In Login settings, leave everything as is
8. Click Save
9. In Service Account Roles for this newly created client, assign appropriate roles
10. You will find the client secret in Credentials

Create bearer-only client#

1. Login to the administration console with the admin user
2. Go to Clients -> Create
3. In General Settings, enter Client ID
4. Click Next
5. In Capability config, uncheck Standard flow and Direct access grants (make sure that all options are disabled)
6. Click Next
7. In Login settings, leave everything as is
8. Click Save
9. In Roles, add required role(s)

Create client to access REST interfaces#

In order to grant access to a specific REST interface a new client has to be created with specific Service account roles. The following table shows an overview of which roles are required in order to access which REST interface.

Create user to access the entici webapp#

1. Login to the administration console with the admin user
2. Go to Users -> Add user
3. Enter username (of your own choosing) and additional information (e.g. name) if applicable
4. Click Create
5. In Credentials, set password
6. In Role mapping, assign appropriate roles

Create access token#