Configuring custom URL for Keycloak

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

Providing the ability to configure DNS names for the Keycloak user and role management service using the interface admin console.

1. General description

Design by DNS name configuration (separate on behalf of the OpenShift cluster) for the Cabinet of the official and the Cabinet of the recipient of services did not take into account the need in the configuration, also the appropriate name for the user and role management service (Keycloak) through the admin console.

Also, if the OpenShift cluster is created entirely in a private network, then certificate verification is performed at the subsystem level inter-service interaction management and Keycloak authentication are not working correctly with some registry components.

This transitional design offers a solution to these problems.

User roles

Technical registry administrator
Technical administrator of the Platform

2. Functional scenarios

Configuration of DNS names of the Keycloak component through the admin console at the Platform level
Choosing a DNS name for logging into user accounts through the admin console at the registry level
Removal of DNS names added to Keycloak

3. General provisions

The configuration of existing Keycloak DNS names is set by the technical administrator of the Platform
Along with the DNS name, the platform administrator must also specify the TLS certificate in .pem format for the domain
DNS names for user registry offices are configured by the registry technical administrator
The registered administrator can select a domain for Keycloak from the list of available ones
The list of domains available in the system is formed from the specified DNS names of the Keycloak platform
In the cabinet settings, it is possible to download separate TLS certificates in .pem format for each cabinet user
The Platform Administrator is responsible for the rotation of Keycloak certificates and user accounts
The system must be able to edit previously installed TLS certificates and DNS names
The admin console must validate that the downloaded TLS certificate really corresponds to the entered domain and is not self-signed and its validity period has not yet expired.
Access to HasiCorp Vault for reading certificates is only through a separate service user
In the case of deployment of the registry without a portal (official or citizen), appropriate UI elements for configuring DNS names should not be shown.
The specified URL for Keycloak and cabinets cannot be more than 63 characters and must be validated for correctness.

4. Design of an existing solution

4.1. Keycloak DNS

In the current version of the Platform, the DNS configuration of the Keycloak name is as follows:

Manually add the following setting to values.yaml of the registry:
```
keycloak:
  customHost: keycloak.example.com
```
Manually configure the Keycloak Frontend URL in the corresponding realm to the new DNS name
Manually create an OpenShift Route with an added TLS certificate
Manually change the Redash SAML URL

4.2. DNS names for administrative user interfaces

DNS name configuration design for user accounts

4.3. Disadvantages of the current implementation

Setting the DNS name of the central Keycloak component takes place from the registry configuration
Requires a lot of manual settings (route, request auth, keycloak realm, etc.)
The technical administrator of the Platform does not control the DNS settings of the Keycloak platform
DNS names are set at the common-web-app component level, not at the registry configuration level

5. Technical solution design

Before starting to configure a custom DNS name for Keycloak at the registry level, you must first add the appropriate one domain in the Platform settings.

With the configured Keycloak DNS name, it should appear in the dropdown item in the registry settings with the offer choose DNS names for logging into registry offices: the default cluster or one of the custom ones.

Figure 1. High-level interaction diagram at the level of subsystems

The platform and registry management subsystem stores received TLS certificates in the secrets management subsystem and encryption and adds to values.yaml the domain and path to the TLS certificate according to the example:

An example of configuration at the values.yaml level of the cluster-mgmt.git repository

keycloak:
  customHosts:
    - host: keycloak.example.com
      certificatePath: registry-kv/....
    - host: keycloak-login.instance.com
      certificatePath: registry-kv/....

An example of configuration at the values.yaml level of the registry repository

portals:
  officer:
    customHost:
       enabled: true
       host: officer.example.com
       certificatePath: registry-kv/....

Platform TLS certificates are stored in HashiCorp Vault (user-management:hashicorp-vault) with a path generated by convention:

registry-kv/cluster/domains/<domain-name>

key:caCertificate value:<caValue>
key:certificate value:<certificateValue>
key:key value:<keyValue>

Registered TLS certificates are stored in HashiCorp Vault (user-management:hashicorp-vault) with a path generated according to the convention:

registry-kv/registry/<registry-name>/domains/<portal-name>/<domain-name>

key:caCertificate value:<caValue>
key:certificate value:<certificateValue>
key:key value:<keyValue>

Figure 2. High-level interaction diagram at the configuration deployment level

With a given custom DNS name for Keycloak and for cabinets in the corresponding registry, the following should happen:

configuration of Redash Viewer:

Redash Viewer environment variable configuration example

REDASH_SAML_METADATA_URL # the default Keycloak URL of the OpenShift cluster
REDASH_SAML_REDIRECT_URL # external (custom) Keycloak DNS name

create additional istio request authentication to the already existing ones:

Istio RequestAuthentication Configuration Example for Registry Components

jwtRules:
    - forwardOriginalToken: true
      fromHeaders:
        - name: X-Access-Token
      issuer: {{ template "issuer.officer" . }}    #external (custom) Keycloak DNS name
      jwksUri: {{ template "jwksUri.officer" . }}  #default Keycloak URL of the OpenShift cluster

Must be configured for registry-rest-api, excerpt-service-api and registry-regulation-management

configuration of Keycloak Frontend URL:
Keycloak Frontend URL configuration example via KeycloakRealm CR
```
spec:
  frontendUrl: #external (custom) Keycloak DNS-імʼя
```

configuration of Keycloak redash viewer client web URL:
Example configuration of Redash client webURL
```
spec:
  webUrl: #external (custom) Redash DNS name
```

configuration of Kong OIDC plugin:

Example configuration of Kong OIDC plugin

config:
  issuers_allowed:        #external (custom) Keycloak DNS name
  discovery:              #default Keycloak URL of the OpenShift cluster
  introspection_endpoint: #external (custom) Keycloak DNS name

Istio Gateway configuration for user accounts:

Istio Gateway Configuration Example

spec:
  ....
  servers:
    - hosts:
        ....
        - #external (custom) officer-portal DNS-name

Istio Virtual Service configuration for user accounts:
Virtual Service configuration example
```
spec:
  gateways:
    - gateway
  hosts:
    - #external (custom) officer-portal DNS-name
```

5.1. Approximate layouts of the design of the admin console

Figure 3. Platform level DNS configuration layout

Cluster Keycloak default DNS name is read by the admin console from the Keycloak CR specification in user-management

Figure 4. Platform-level DNS configuration layout

Figure 5. Platform level DNS configuration layout

Figure 6. DNS configuration layout at the registry level

5.1.1. Service users to access HashiCorp Vault:

Each component accessing the Vault must be run from a separate OpenShift service account. Service users created in HashiCorp Vault must be of type Kubernetes Auth Method and created during the initial setup of HashiCorp Vault via the ConfigMap script-init execution.

Component

The name of the service account

Connected Namespaces

Capabilities

Jenkins

control-plane-jenkins

Registry namespace, user-management

["read"]

Example Capability Policy HashiCorp Vault

{
      "policy": "path \"registry-kv/registry/<registry-name>/domains/\" \"{ capabilities = [ \"read\" ]}\""}
}

An example of linking the OpenShift account service to HashiCorp Vault

{
      "bound_service_account_names": ["control-plane-jenkins"],
      "bound_service_account_namespaces": "ns",
      "policies": ["policy-name"],
      "ttl": "1h"
}

5.2. Registry components and their purpose within the design of the solution

Component

Official title

Purpose / The essence of the changes

Status

The web interface is the interface for managing the Platform and registries

control-plane-console

Changes to interfaces and logic for storing certificates in Vault

To Do

Deployment of the platform and registries

edp-library-stages-fork

Changing the logic for obtaining certificates from the Vault and deploying Keycloak and registries

To Do

User portals

common-web-app

Configuration of Kong plugins

Done

Report viewing service

redash-viewer

Configuration of environment variables

To Do

Registry settings

registry-configuration

Settings of Keycloak Frontend URL

To Do

Keycloak Operator

keycloak-operator

Configuration of Keycloak Frontend URL

To Do

HashiCorp Vault

vault

policy and service user configuration

To Do

6. Development plan

6.1. Technical examinations

BE
DevOps

6.2. Development plan

Add functionality to configure the Realm Frontend Url Keycloak operator
Change admin console UI according to layouts and general provisions
Develop functionality for configuring DNS names in pipelines and registry component charts

7. Data migration when updating the registry

Already configured custom DNS names should remain during migration.
If the DNS name for Keycloak was already configured, the pre-upgrade script should transfer it to values.yaml and Vault
Taking into account the number of manual actions that were performed on different prod clusters to configure domains, heterogeneity and the individuality of the settings after the update, the old resources are suggested to be deleted by the administrator of the registry/platform