Chapter 25. Configuring Credentials


*Note that this chapter only focuses on `DOC`* applications deployed on a single machine Docker environment and does not apply to bare metal or cloud deployments.** We recommend keeping default passwords in the source code during development and changing them for each deployed environment. Here, an environment can be regarded as an instance of a deployment. For more details, refer to Chapter Deploying the Application. In addition to using credentials, the Gateway Service also can be extended when securing the application. For more details, refer to Section Extending the Gateway Service.

Note that this chapter only focuses on DOC applications deployed on a single machine Docker environment and does not apply to bare metal or cloud deployments.

We recommend keeping default passwords in the source code during development and changing them for each deployed environment. Here, an environment can be regarded as an instance of a deployment. For more details, refer to Chapter Deploying the Application.

In addition to using credentials, the Gateway Service also can be extended when securing the application. For more details, refer to Section Extending the Gateway Service.

Applications based on DOC are composed of multiple components that communicate with each other. Communications are secured by technical and user credentials, which are set, by default, by the environment. For more details, refer to Section Accessing the Application Endpoints.

As convenient as it is for the development and testing phases, these default credentials should not be used in deployments.

Updating credentials involves changing the credentials and updating all the software components that need to connect with these credentials. Below is an example of the software components that connect to PostgreSQL

Figure 25.1. Understanding PostgreSQL Connections

DOC credentials can be divided into two categories:

Infrastructure credentials, depending on the software component, require:
- Configuring Postgres Credentials: postgres-r00t-us3rn4m3, data_server and Keycloak.
- Configuring MongoDB Credentials: mongo-r00t-us3rn4m3, scenario-db, execution-db, permission-db and session-tracking-db.
- Configuring Keycloak 'admin' Credentials: keycloak-r00t-us3rn4m3.
- Configuring RabbitMQ Credentials: rabbit-r00t-us3rn4m3.
Applicative credentials are centralized and managed by Keycloak and require Configuring User Credentials: backend-service, data-service, execution-service, gene_admin, optimserver, scenario-service, user1, user2, user3, and user4.

1. Configuring Infrastructure Credentials

1.1. Configuring Postgres Credentials

There are several Postgres accounts: postgres-r00t-us3rn4m3 (i.e. admin account), data_server and keycloak.

1.1.1. Configuring Postgres 'admin' Credentials

The Postgres postgres-r00t-us3rn4m3 admin credentials are defined in the infrastructure Docker descriptor. You need it to do maintenance operations on your database engine, but the application never uses it as an identity.

Procedure 25.1. To Configure Postgres 'admin' Credentials

In deployment/docker/infra/docker-compose.yml, change the POSTGRES_PASSWORD environment variable of the postgres service.
```
services:
  postgres:
    ...
    environment:
      - POSTGRES_PASSWORD=NEW_PASSWORD # <= Change me
    ...
```
The change needs the container to be recreated to be effective. Run the following command:
```
docker compose down postgres && docker compose up -d
```

1.1.2. Configuring Postgres 'data_server' Credentials

The Postgres data_server credentials have to be changed with an SQL query directly done in the PostgreSQL instance connected with postgres-r00t-us3rn4m3 admin account.

Procedure 25.2. To Configure Postgres 'data_server' Credentials

With the tools of your choice, connect to the database with the postgres user at the JDBC URL: jdbc:postgresql://localhost:5432/postgres.

Run the following SQL query:

ALTER ROLE data_server WITH PASSWORD ...NEW_PASSWORD...;

Only on the target machine, i.e. the machine that hosts the deployments script and the Docker file, open the script deployment/docker/infra/postgres/start/10-create_user.sh and edit the password in the CREATE USER query.
```
...
echo "Creating database role: data_server"
psql --username "$POSTGRES_USER" <<-EOSQL
CREATE USER data_server WITH CREATEDB PASSWORD 'NEW_PASSWORD';
EOSQL
```
This ensures the change survives to volume removing.
Note that the script files must be executable. Run chmod +x if needed.
Change the password configuration in the microservices that need to connect to Postgres through this user (in this particular case it is data-service).
1. Edit deployment/docker/infra/docker-compose.yml and add the SPRING_DATASOURCE_PASSWORD environment variable.
```
data-service:
     ...
     environment:
     - SPRING_DATASOURCE_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
```
2. Edit the .env file located in docker-compose.yml parent folder and add an environment variable SPRING_DATASOURCE_PASSWORD with the password you have chosen.
  Note that you can also add the environment variable to the host machine.


Note that the script files must be executable. Run `chmod +x` if needed.


Note that you can also add the environment variable to the host machine.

1.1.3. Configuring Postgres 'Keycloak' Credentials

The Postgres keycloak credentials have to be changed with an SQL query directly done in the PostgreSQL instance connected with postgres-r00t-us3rn4m3 admin account

Procedure 25.3. To Configure Postgres 'Keycloak' Credentials

With the tools of your choice, connect to the database with the postgres user at the JDBC URL: jdbc:postgresql://localhost:5432/postgres.

Run the following SQL query:

ALTER ROLE keycloak WITH PASSWORD 'NEW_PASSWORD';

Only on the target machine, i.e. the machine that hosts the deployments script and the Docker file, open the script deployment/docker/infra/postgres/start/10-create_user.sh and edit the password in the CREATE USER query.
```
...
echo "Creating database role: keycloak"
${POSTGRES} <<-EOSQL
CREATE USER keycloak WITH CREATEDB PASSWORD 'NEW_PASSWORD';
EOSQL
```
This ensures the change survives to volume removing.
Note that the script files must be executable. Run chmod +x if needed.
Change the password configuration in the microservices that need to connect to Postgres through this user (in this particular case it is keycloak).
1. Edit deployment/docker/infra/docker-compose.yml and add the DB_PASSWORD environment variable.
```
keycloak:
    ...
    environment:
    - DB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
```
2. Edit the .env file located in docker-compose.yml parent folder and add an environment variable DB_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.


Note that the script files must be executable. Run `chmod +x` if needed.

1.2. Configuring MongoDB Credentials

There are several MongoDB accounts: mongo-r00t-us3rn4m3, optimserver, scenario-db, execution-db, permission-db and session-tracking-db.

1.2.1. Configuring MongoDB 'admin' Credentials

The MongoDB admin credentials are defined in the infrastructure Docker descriptor. They are used for MongoDB database user creation and by the Optimization server master.

Procedure 25.4. To Configure MongoDB 'admin' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGO_INITDB_ROOT_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGO_INITDB_ROOT_USERNAME=admin
    - MONGO_INITDB_ROOT_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGO_INITDB_ROOT_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/dbos/docker-compose.yml and change the environment variable SPRING_DATA_MONGODB_ADMIN_PASSWORD.

dbos-master:
    ...
    environment:
    - SPRING_DATA_MONGODB_ADMIN_USER=admin
    - SPRING_DATA_MONGODB_ADMIN_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_DBOS_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

1.2.2. Configuring MongoDB 'optimserver' Credentials

The MongoDB optimserver credentials are defined in the infrastructure Docker descriptor. They are used by the Optimization server master.

Procedure 25.5. To Configure MongoDB 'optimserver' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGODB_DBOS_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGODB_DBOS_DATABASE=optimserver-master-db
    - MONGODB_DBOS_USER=optimserver
    - MONGODB_DBOS_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_DBOS_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/dbos/docker-compose.yml and change the MONGODB_DBOS_PASSWORD environment variable.

dbos-master:
...
environment:
  - SPRING_DATA_MONGODB_USERNAME=optimserver
  - SPRING_DATA_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable SPRING_DATA_MONGODB_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

1.2.3. Configuring MongoDB 'scenario' Credentials

The MongoDB scenario credentials are defined in the infrastructure Docker descriptor. They are used by the Scenario Scervice.

Procedure 25.6. To Configure MongoDB 'scenario' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGODB_SCENARIO_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGODB_SCENARIO_DATABASE=scenario-db
    - MONGODB_SCENARIO_USER=scenario
    - MONGODB_SCENARIO_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_SCENARIO_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/app/docker-compose.yml and add a variable SPRING_DATA_MONGODB_PASSWORD for the scenario-service and the data-service.

  scenario-service:
    ...
    environment:
      - SPRING_DATA_MONGODB_HOST=mongo
      - SPRING_DATA_MONGODB_PASSWORD=CHANGE_ME #  <= Your new password
  data-service:
    ...
    environment:
      - SPRING_DATA_MONGODB_HOST=mongo
      - SPRING_DATA_MONGODB_PASSWORD=CHANGE_ME #  <= Your new password

1.2.4. Configuring MongoDB 'execution' Credentials

The MongoDB execution credentials are defined in the infrastructure Docker descriptor. They are used by the Execution Service.

Procedure 25.7. To Configure MongoDB 'execution' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGODB_EXECUTION_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGODB_EXECUTION_DATABASE=execution-db
    - MONGODB_EXECUTION_USER=execution
    - MONGODB_EXECUTION_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_EXECUTION_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/app/docker-compose.yml and add a variable SPRING_DATA_MONGODB_PASSWORD for the execution-service.

  execution-service:
    ...
    environment:
      - SPRING_DATA_MONGODB_HOST=mongo
      - SPRING_DATA_MONGODB_PASSWORD=CHANGE_ME #  <= Your new password

1.2.5. Configuring MongoDB 'permission' Credentials

The MongoDB permission credentials are defined in the infrastructure Docker descriptor. They are used to manage permissions.

Procedure 25.8. To Configure MongoDB 'permission' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGODB_PERMISSION_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGODB_PERMISSION_DATABASE=permission-db
    - MONGODB_PERMISSION_USER=permission
    - MONGODB_PERMISSION_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_PERMISSION_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/app/docker-compose.yml and add a variable SERVICES_PERMISSION_MONGODB_PASSWORD for the backend-service, the data-service, the execution-service, and the scenario-service.

backend-service:
    ...
    environment:
    - SERVICES_PERMISSION_MONGODB_HOST=mongo
    - SERVICES_PERMISSION_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
data-service:
    ...
    environment:
    - SERVICES_PERMISSION_MONGODB_HOST=mongo
    - SERVICES_PERMISSION_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
execution-service:
    ...
    environment:
    - SERVICES_PERMISSION_MONGODB_HOST=mongo
    - SERVICES_PERMISSION_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
scenario-service:
    ...
    environment:
    - SERVICES_PERMISSION_MONGODB_HOST=mongo
    - SERVICES_PERMISSION_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable SERVICES_PERMISSION_MONGODB_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

1.2.6. Configuring MongoDB 'session-tracking' Credentials

The MongoDB session-tracking credentials are defined in the infrastructure Docker descriptor. They are used by to monitor the application activity.

Procedure 25.9. To Configure MongoDB 'session-tracking' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the MONGODB_SESSION_TRACKING_PASSWORD environment variable.

mongo:
    ...
    environment:
    - MONGODB_SESSION_TRACKING_DATABASE=session-tracking-db
    - MONGODB_SESSION_TRACKING_USER=session-tracking
    - MONGODB_SESSION_TRACKING_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable MONGODB_SESSION_TRACKING_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit deployment/docker/app/docker-compose.yml and add a variable SERVICES_SESSIONTRACKING_MONGODB_PASSWORD for the scenario-service.

scenario-service:
    ...
    environment:
    - SERVICES_SESSIONTRACKING_MONGODB_HOST=mongo
    - SERVICES_SESSIONTRACKING_MONGODB_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable SERVICES_SESSIONTRACKING_MONGODB_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

1.3. Configuring Keycloak 'admin' Credentials

The Keycloak admin credentials are defined in the infrastructure Docker descriptor. It allows connecting to the master realm and changing the global Keycloak configuration.

Procedure 25.10. To Configure Keycloak 'admin' Credentials

Edit deployment/docker/infra/docker-compose.yml and change the KEYCLOAK_PASSWORD environment variable.

keycloak:
    ...
    environment:
    - KEYCLOAK_USER=admin
    - KEYCLOAK_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
    ...

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable KEYCLOAK_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

1.4. Configuring RabbitMQ Credentials

The RabbitMQ default credentials are defined in the infrastructure Docker descriptor. It allows connecting the application components and requires updating the password for each of them.

Procedure 25.11. To Configure RabbitMQ 'admin' Credentials

Edit deployment/docker/infra/docker-compose.yml and add/change the RABBITMQ_DEFAULT_PASS environment variable.

rabbitmq:
    image: ${DOCKER_PULL_REGISTRY}/infra/rabbitmq:4.0.7-management
    container_name: gene-sample-rabbitmq
    environment:
    - RABBITMQ_DEFAULT_PASS # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable RABBITMQ_DEFAULT_PASS with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit RabbitMQ password for Keycloak service in deployment/docker/infra/docker-compose.yml.

keycloak:
    ...
    environment:
    - RABBIT_USERNAME=guest
    - RABBIT_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable RABBIT_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit RabbitMQ password for dbos-master service in deployment/docker/dbos/docker-compose.yml.

dbos-master:
    ...
    environment:
    - SPRING_RABBITMQ_USERNAME=guest
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable SPRING_RABBITMQ_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit RabbitMQ password for the following services in deployment/docker/app/docker-compose.yml.

backend-service:
    ...
    environment:
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
data-service:
    ...
    environment:
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
execution-service:
    ...
    environment:
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
scenario-service:
    ...
    environment:
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit the .env file placed in the docker-compose.yml parent folder and add an environment variable SPRING_RABBITMQ_PASSWORD with the password you have chosen. Note that you can also add the environment variable to the host machine.

Edit RabbitMQ password for the following services in deployment/docker/app/docker-compose-workers.yml.

checker-worker:
    ...
    environment:
    - SPRING_RABBITMQ_USERNAME=guest
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
engine-worker:
    ...
    environment:
    - SPRING_RABBITMQ_USERNAME=guest
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.
python-engine-worker:
    ...
    environment:
    - SPRING_RABBITMQ_USERNAME=guest
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

Edit RabbitMQ password for the python-wml-worker service in deployment/docker/app/docker-compose-wml-worker.yml.

python-wml-worker:
    ...
    environment:
    - SPRING_RABBITMQ_USERNAME=guest
    - SPRING_RABBITMQ_PASSWORD # Not specifying a value allow to transmit environment variable to the container.

2. Configuring User Credentials

Application users and passwords are managed using the Keycloak web administration console. For more details, refer to Section Managing Users.

Some users are associated with components, which credentials must be updated accordingly in their respective configurations. This especially applies to the Keycloak administration console. For more details, refer to Section Configuring Infrastructure Credentials.

Procedure 25.12. To Configure User Credentials

In a browser, open the Keycloak web administration console. For a locally deployed Docker installation, you should be able to access it through the following URL: http://localhost:9090/admin (Remember that you have probably changed the Keycloak admin password recently, use your new password).
List the available users by clicking on Users and View all users.
Figure 25.2. Listing All Keycloak Users
Select a user, let say backend-service by clicking on its id.
Figure 25.3. Selecting a Keycloak User by ID
Change its password by:
1. Clicking on Credentials.
2. Changing the password
3. For the user account, you can toggle on the Temporary switch. For a technical account, you have to toggle off the Temporary switch.
4. Click on Reset Credentials.
  Figure 25.4. Updating a Keycloak User Credentials
5. The following users are technical accounts:
  - backend-service
  - data-service
  - execution-service
  - scenario-service
  They need to be updated in their respective configurations, either:
  - In the file application.yml in the development phase as it applies to all deployments, or
  - Using environment variables in specific deployments, as enabled by tools such as Helm charts.