HERO user authentication is managed by Keycloak.
In Keycloak, each application has its own Realm with different users and authorization settings. HERO authorization settings are stored in a Realm named HERO.
In HERO Realm, the nginx client uses Keycloak to manage user authentication to the remote machines providing a single sign-on solution.
For details about Keycloak, see Keycloak documentation.
The steps to configure the security for your HERO installation, including the generation of a new secret, and the customization of SSL certificates, are run automatically by the installation script.
The installation script generates two HERO users:
userid test, password test, with user role
userid admin, password admin, with administrator role
To add additional users, roles, or to change the default passwords, see the steps in Creating a new user below.
To properly customize Keycloak in your environment, run the following steps:
In the <BUILD_DIR> directory, find the .tomcat.env file.
In the .tomcat.env file, find the variables:
CLIENT_SECRET
KEYCLOAK_URL
In the KEYCLOAK_URL {"realm": "hero","url": "https://hero.hcltech.com/keycloak/auth","clientId": "nginx"}, replace the hero.hcltech.com part with <IP>:<PORT> of the host machine.
If the port used in the docker-compose.yml file is the default one (443), only the <IP> value must be added.
In the <BUILD_DIR>\CONFIGURATION\HERO\ui.properties configuration file (see Installing and Configuring), set the variable keycloak to the same value assigned to KEYCLOAK_URL in step 3.
After the execution of the docker-compose up --d command, the user test, with password test, is automatically created and authorized to access the HERO dashboard https://<your_host_machine_address:port>/Dashboard.
To create a user with administrator role, see the steps in Creating a new user below.
The installation process generates a Keycloak default realm named HERO and a default client named nginx.
For additional information about Keycloak realms and clients, see Keycloak documentation.
Use the Keycloak administration console to define new users, new roles, or change user passwords.
For example, to create a new HERO user with administrator role, run the following steps:
Access Keycloak administration console https://<IP:PORT>/keycloak/auth/admin by using the following credentials:
userid=admin
password=password
If you want, you can change Keycloak default password:
From Keycloak administrator console, in the upper right corner, click Admin:
Select Manage account -> password
Under Clients -> nginx -> roles tab, click the Add role button
Provide the role name admin and click save
Under users, click the add user button
Provide a user name and click save
Under Credentials, provide a password for the user, turn the temporary field to off, click the Reset Password button and confirm
Under Role Mappings, in the Client Roles dropdown, select nginx. Some boxes appear on the right
Under Available Roles, select admin and click the Add Selected button. The admin role appears in the Assigned Roles box
On the left navigation bar, select the Realm Settings page and go to the Themes tab
In the Login Theme parameter, select the Keycloak theme, then click save
For security reasons, you are recommended to generate a new client secret, in place of the default one. To generate a new client secret and customize HERO accordingly, run the following steps:
From Keycloak administration console, in the left side navigation bar, select Clients->nginx.
From the tab Credentials, click Regenerate Secret.
Copy the content of the field Secret.
From the <BUILD_DIR> directory, run the commands:
docker-compose down
docker volume rm <BUILD_DIR>_hero-home (to remove the configuration volume)
In the <BUILD_DIR>\CONFIGURATION\HERO directory, find the .tomcat.env file.
Paste the content you copied from the field Secret into the CLIENT_SECRET parameter.
In the <BUILD_DIR>\CONFIGURATION\HERO\ui.properties configuration file, paste the same content into the clientSecret parameter.
From the <BUILD_DIR> directory, run the commands docker-compose up --build
To install your own SSL certificates, run the following procedure:
In the <BUILD_DIR>\config folder, replace the hero.key and hero.crt default certificate files with your own files (do not change the default names).
Complete the installation procedure, or run the following command from the <BUILD_DIR> directory to update a pre-existing installation:
docker-compose up -d –build
In the Keycloak administration console, selecting Client -> nginx, the parameter Redirect URIs has a default value set to "*", which means that the login can be redirected to every URI. To avoid this is identified as an issue by AppScan, modify the Redirect URIs parameter by adding only the URIs requested by HERO:
HOSTNAME\Dashboard
HOSTNAME\tomcat
HOSTNAME\keycloak
HOSTNAME\elasticsearch
HOSTNAME\kibana
HOSTNAME\prediction
where HOSTNAME is the hostname of the machine where HERO is installed.