Installing authentication service

Important note:

All passwords and keys in this section are given for illustration purposes.

During a real installation, it is recommended to use more complex and reliable passwords.

1. Before installing

Consider getting familiar with:
- Authentication service documentation
- On-Premise solution architecture
Make sure the necessary preparation steps are completed:
1. Preparation for installation
2. Fetching installation artifacts

Collect the necessary information that was set or retrieved on previous steps:

Object	Example value	How to get value
Docker Registry mirror endpoint	`docker.storage.example.local:5000`	See Fetching installation artifacts
Kubernetes secret for accessing Docker Registry	`onpremise-registry-creds`	See Fetching installation artifacts

Make sure that the system requirements, given at the Helm chart, are met. For more information on how to do this, refer to the System requirements document.

Note

Contents of the Helm chart described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.
Choose the domain names for the services.

Example:
- Admin web interface: keycloak.example.com

2. Prepare infrastructure required for the service

Configure PostgreSQL

Place a PostgreSQL cluster with the domain name keyсloak-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

Connect to the cluster a superuser (usually postgres).
Create the database user that will be used for the service. Set passwords for the user.
```
create user dbuser_keycloak password '650D7AmZjSR1dkNa';
```

Create a database owned by the user.

create database onpremise_keycloak owner dbuser_keycloak;

3. Install Keycloak

Create a Helm configuration file. See here for more details on the available settings.

The example is prefilled with the necessary data collected on previous steps.
values-keycloak.yaml
```
dgctlDockerRegistry: docker.storage.example.local:5000

imagePullSecrets:
    - name: onpremise-registry-creds

imagePullPolicy: IfNotPresent

replicaCount: 2

postgres:
    host: keycloak-postgresql.storage.example.local
    port: 5432
    name: onpremise_keycloak
    username: dbuser_keycloak
    password: TZ3CYljrlNDrnP5fIpjoWPBCzejQ5qJEUNr9WiplRHyNksdhN1GsVrS90d9HQhhp

auth:
    adminUser: keycloak
    adminPassword: GsVrS90d9HQhhp

defaultUser:
    enabled: true
    name: test
    email: test@test.com
    password: JEUNr9WiplRH

ingress:
    enabled: true
    className: nginx
    annotations:
        nginx.ingress.kubernetes.io/affinity: cookie
        nginx.ingress.kubernetes.io/session-cookie-expires: '86400'
        nginx.ingress.kubernetes.io/session-cookie-max-age: '86400'
        nginx.ingress.kubernetes.io/session-cookie-name: keycloak
        nginx.ingress.kubernetes.io/proxy-buffer-size: '128k'
    hosts:
        - host: keycloak.example.com
          paths:
              - path: /
                pathType: Prefix
    tls:
        - hosts:
              - keycloak.example.com
          secretName: secret.tls
```
Where:
- dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.
- imagePullSecrets: Kubernetes Secrets for accessing the Docker Registry endpoint where On-Premise services' images reside.
  - name: the name of the secret.
- imagePullPolicy: order of downloading an image from the repository. IfNotPresent (recommended) – the image download is performed, if there is no actual one available.
- replicaCount: amount of the service pods. Two is recommended.
- postgres: access settings for the PostgreSQL server.
  - host: hostname or IP address of the PostgreSQL server.
  - port: listening port of the PostgreSQL server.
  - name: database name.
  - username and password: credentials for accessing the database specified in the name setting. The user must be the owner of this database or a superuser.
- auth: superuser credentials for logging into Keycloak administrative interface.
  - adminUser: superuser login.
  - adminPassword: superuser password.
- defaultUser: data for creating a test user. You may create it not on the current stage, but later, via the interface of the deployed system – see the "User registration" instruction. In this case, it is not obligatory to define these settings.
  - enabled: availability of the test user.
  - name: test user name.
  - email: test user email.
  - password: test user password.
- ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL. Note that the path for the host should point to the root directory (/).
  - annotations: the Cookies settings: name, lifetime. This group of settings is needed to support “sticky sessions”: if there are two or more pods, then they find each other and create a cluster. If there is only one, this settings group is not required.
    - proxy-buffer-size: proxy buffer size. Needs to be defined to prevent 502 errors during the login process.
  - tls: the HTTPS settings.
    - ingress.tls.hosts.secretName – the HTTPS certificate, stored in Kubernetes in the base64 format.

Deploy the service with Helm using the created values-keycloak.yaml configuration file:

helm upgrade --install --version=1.21.0 --atomic --values ./values-keycloak.yaml keycloak 2gis-on-premise/keycloak

4. Test deployment

To test the operability of the authentication service, do the following:

Open the admin web interface in a browser (use the hosts.host value from the values-keycloak.yaml file):
```
keycloak.example.com
```
Log in to the Keycloak web interface using your admin user credentials (auth.adminUser and auth.adminUser)

What's next?

Find out how to update the service:
- Updating Authentication service
Install other On-Premise products: