Authentication service | On-Premise | 2GIS Documentation

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. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
  3. 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
  4. 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.

  5. Choose the domain names for the services.

    Example:

    • Admin web interface: keycloak.example.com

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:

  1. Connect to the cluster a superuser (usually postgres).

  2. Create the database user that will be used for the service. Set passwords for the user.

    create user dbuser_keycloak password '650D7AmZjSR1dkNa';
    
  3. Create a database owned by the user.

    create database onpremise_keycloak owner dbuser_keycloak;
    
  1. 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.
  2. Deploy the service with Helm using the created values-keycloak.yaml configuration file:

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

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

  1. Open the admin web interface in a browser (use the hosts.host value from the values-keycloak.yaml file):

    keycloak.example.com
    
  2. Log in to the Keycloak web interface using your admin user credentials (auth.adminUser and auth.adminUser)

What's next?