Using a Keycloak service with FQDN

Issue a Keycloak instance

The YAML code below creates the service VSHNKeycloak with a Full Qualified Domain Name(FQDN).

apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNKeycloak
metadata:
  name: keycloak-app1-prod
  namespace: prod-app
spec:
  parameters:
    service:
      version: "26"
      fqdn: my-keycloak.example.com (1)
    size:
      plan: standard-2
  writeConnectionSecretToRef:
    name: keycloak-creds-connection (2)
1 Your full qualified domain name
2 Credentials to access the keycloak

Configure your DNS server

On APPUiO Cloud we provide you with a cert-manager setup which you can use to create, sign, install and renew certificates for your domains running on APPUiO Cloud.

To create a certificate for the Keycloak FQDN in your domain, you need to create a CNAME record in your domain’s DNS pointing to your APPUiO Zone’s well-defined cname record.

my-keycloak  IN  CNAME  cname.cloudscale-lpg-0.appuio.cloud.

Access Keycloak

Once the Keycloak instance is running in the cluster and DNS server has been configured with the new CNAME then the service should be accessible in your browser via FQDN my-keycloak.example.com with credentials from keycloak-creds-connection secret. The admin password can be changed but be aware the secret credentials will not be valid anymore.

Our keycloak service uses an internal administrator account named internaladmin. It’s used by VSHN for various scripts and configurations. Changing the user credentials of internaladmin account may break your instance!

Restrict Admin Interface Access

By default, the Keycloak admin interface is accessible on the same domain as Keycloak itself. You can move it to a dedicated domain and optionally disable public access entirely using adminConsole.

apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNKeycloak
metadata:
  name: keycloak-app1-prod
  namespace: prod-app
spec:
  parameters:
    service:
      fqdn: my-keycloak.example.com (1)
      adminConsole:
        fqdn: my-admin.example.com (2)
        private: true (3)
  writeConnectionSecretToRef:
    name: keycloak-creds-connection
1 Primary Keycloak domain for end users
2 Dedicated domain for the admin interface
3 Removes the admin interface from public access entirely (port-forward only)

Behavior

  • adminConsole not set (default): Admin interface accessible at the same domain as Keycloak (fqdn).

  • adminConsole.fqdn set: Admin interface moves to that domain. No redirect from fqdn; navigate to adminConsole.fqdn directly.

  • adminConsole.private: true, no adminConsole.fqdn: Admin interface removed from public access. Accessible only via port-forward.

Accessing the Admin Interface via Port-Forward

When adminConsole.private: true is set without an adminConsole.fqdn, the admin interface is only reachable through a local port-forward into the instance namespace.

Find the instance namespace in the service status, then run:

kubectl port-forward -n <instance-ns> svc/keycloak-prod-app-85lf9-keycloakx-http 8080:80

The admin interface is then available at localhost:8080.

Debug the service

To check the status and potential issues or errors in the service, check the status field of the new object:

$  oc describe vshnkeycloak.vshn.appcat.vshn.io my-keycloak-example
[...]
Status:
  Conditions:
    Last Transition Time:  2024-03-28T10:08:04Z
    Reason:                ReconcileSuccess
    Status:                True
    Type:                  Synced
    Last Transition Time:  2024-03-28T10:09:30Z
    Reason:                Available
    Status:                True
    Type:                  Ready
  Connection Details:
    Last Published Time:  2024-03-28T10:09:30Z