Keycloak integration

SAYMON provides the possibility of its users to authorize via Keycloak server.

Integration is supported only with Keycloak v 21.1.1.

Server setup

In order to set up the interaction between the SAYMON server and the external Keycloak server, it is necessary to obtain at least one of the parameters:

Realm Certificate, which is used by the Keycloak to sign the user tokens;
Backend-client configuration file.

Setting up the client and obtaining parameters are implemented in the Keycloak Administration Console.

Realm Certificate

In order to obtain the Realm Certificate, it is necessary to:

Select the required realm from the list (SAYMON here):

Select Keycloak realm
In the Realm Settings section on the Tokens tab find the token signature algorithm (RS256 here):

Select token signature algorithm
On the Keys tab find the certificate for the algorithm:

Keys tab
The button in the corresponding line shows the certificate:

Key certificate on the Keys tab

It is recommended to save the data to the keycloak_realm_certificate file.

Backend-client

Clients are connection parameters to the Keycloak server for external applications which authorize users.

The main feature of the Backend-client is its own authentication: this client gets confidential access with the secret key.

In order to set up the Backend-client, it is necessary to:

Select the required realm from the list (SAYMON here):

Select Keycloak realm
Click the button in the Clients section:

Clients section
Enter the Backend-client’s name into the Client ID field:

Creating client, General Settings tab

and click the button.
Set the Client authentication slider to the On position:

Creating client, Capability config tab

and click the button.
Select Download adapter config in the Action menu:

Download adapter config button
Click the button to obtain the Backend-client configuration file in the JSON format:

Backend client config file

SAYMON Server configuring

In order to interact with the Keycloak server, on the SAYMON server it is necessary to:

Add the Keycloak section to the server configuration file /etc/saymon/saymon-server.conf:
```
"keycloak": {
  "realm_certificate": "<data from the keycloak_realm_certificate>",
  "realm_certificate_file": "/etc/saymon/keycloak_realm_certificate",
  "config_file": "/etc/saymon/keycloak_backend.json"
}
```
where
- realm_certificate is the data from the Keycloak Realm Certificate;
- realm_certificate_file is the path to the file with the Keycloak Realm Certificate;
- config_file is the path to the configuration file, generated by the Keycloak server for the Backend-client.
  
  The parameters are listed in descending order of priority when specified simultaneously. It is sufficient to specify one of the parameters in order to work with Keycloak.
Restart the saymon-server service:
```
$ sudo service saymon-server restart
```

Web interface setup

In order to get the possibility to authorize users via Keycloak in the SAYMON web interface, it is necessary to obtain the Frontend-client configuration file.

Setting up the client and obtaining the configuration file are implemented in the Keycloak Administration Console.

Frontend-client

The main feature of the Frontend-client is the absence of its own authentication: this client gets public access.

To set up the Frontend-client, perform the following actions:

Select the required realm from the list (SAYMON here):

Select Keycloak realm
Click the button in the Clients section:

Clients section
Enter the Frontend-client’s name into the Client ID field:

Creating client, General Settings tab

and click the button.
Set the Client authentication slider to the Off position:

Creating client, Capability config tab

and click the button.
On the Settings tab in the Access settings section specify the correct URI addresses, from which access to the Keycloak server will be implemented and to which users will be redirected after successful authentication and exit:

Access Settings section

and click the button.
Select Download adapter config in the Action menu:

Download adapter config button
Click the button to obtain the Frontend-client configuration file in the JSON format:

Frontend client configuration file

SAYMON web interface configuring

To activate the authorization via Keycloak in the system web interface, perform the following actions:

Add the Authentication section to the SAYMON client configuration file /etc/saymon/saymon-client.yaml:
```
authentication:
  availableMethods:
    - native
    - keycloak
  methodByDefault: keycloak
  services:
    keycloak:
      configUri: saymon.local/keycloak_frontend.json
      legacySupport: false
```
where
- availableMethods is the list of available authentication methods for users;
- methodByDefault is the authentication method offered to the user when displaying of the authentication form;
- configUri is the configuration file generated by the Keycloak server for the Frontend-client.
  
  The Frontend-client configuration file must be placed to the /etc/saymon folder.
Reload the SAYMON page in the web browser.