Docs

Docs

Identity Management

Configure and manage user authentication realms using Control Center and Keycloak.

Control Center includes a fully integrated instance of Keycloak, an open-source identity and access management solution. Keycloak provides authentication, authorization, and user federation features out-of-the-box. Control Center uses it to enable secure access to deployed applications and support identity features such as:

  • User login and role management

  • Multi-Factor Authentication (MFA)

  • Passwordless login with device passkeys

  • Integration with external identity providers

  • Password reset and email account verification

Hosting and Accessing Keycloak

Control Center deploys Keycloak as part of its Helm chart. By default, Keycloak is accessible at the same host as the Control Center app, under the path /keycloak.

The access URL can be customized during installation with the following Helm values:

Source code
my-values.yaml
keycloak:
  host: keycloak.example.com
  path: /

These values determine the public base URL where Keycloak is served, such as https://keycloak.example.com/.

To use a custom TLS certificate for Keycloak, reference a Secret with the certificate details setting the keycloak.tlsSecret value:

Source code
my-values.yaml
keycloak:
  tlsSecret: my-auth-cert

To create a Secret with certificate details, refer to Kubernetes documentation.

Tip
 If this value is not provided, Control Center automatically generates a certificate using its default issuer.

Realms

Keycloak organizes users and clients into realms. A realm is an isolated authentication namespace that manages its own users, credentials, roles, and authentication policies.

Control Center introduces a custom resource named Realm to provision and manage realms declaratively. A Realm resource can be applied using standard Kubernetes tools.

Source code
Example: Create a new realm
apiVersion: vaadin.com/v1alpha1
kind: Realm
metadata:
  name: my-realm
spec:
  name: my-realm
  displayName: My Realm

Apply the realm definition:

Source code
Terminal
kubectl apply -f my-realm.yaml

To view all available realms:

Source code
Terminal
kubectl get realms -n vaadin

Example output:

Source code
NAME             AGE   MESSAGE               STATE
control-center   30s   Realm is up-to-date   APPLIED
my-realm         10s   Realm is up-to-date   APPLIED

By default, Control Center creates a realm named control-center. This can be used immediately when deploying authenticated applications.

Customizing the Login Theme

The login screen presented to users can be customized using the loginTheme property in the Realm specification. Control Center includes a theme named control-center-lumo that applies the Vaadin Lumo design system.

Source code
Example: Set the login theme
spec:
  loginTheme: control-center-lumo

This results in a modern, tailored login page consistent with the Vaadin UI experience.

Email Settings for Password Reset and Verification

Keycloak uses email for several critical features:

  • Sending password reset links

  • Notifying users of account-related actions

  • Verifying email addresses at account registration

To enable these features, SMTP settings must be provided via a Kubernetes Secret. The Realm resource then references this secret via the smtpSettingsSecret property.

Source code
Example: SMTP settings secret
apiVersion: v1
kind: Secret
metadata:
  name: my-smtp-settings
stringData:
  from: "control-center@example.com"
  fromDisplayName: "Control Center"
  host: "smtp.example.com"
  port: "587"
  starttls: "true"
  auth: "true"
  user: "smtp-user"
  password: "smtp-password"

To apply it:

Source code
Terminal
kubectl apply -f my-smtp-settings.yaml

And reference it in the realm definition:

Source code
yaml
spec:
  smtpSettingsSecret:
    name: my-smtp-settings

Supported keys and their meaning:

Key Description

host

SMTP server hostname or IP address (required)

port

SMTP port (e.g., 25, 465, 587)

from

Email address to use in the From header (required)

fromDisplayName

Optional display name shown as sender

replyTo

Optional address for Reply-To header

replyToDisplayName

Optional display name for Reply-To header

ssl

true or false to enable SSL (usually used on port 465)

starttls

true or false to enable STARTTLS (commonly used on port 587)

auth

true if SMTP server requires authentication

user

SMTP username (required if auth: true)

password

SMTP password (required if auth: true)

Enabling Email-Based Login Features

Once SMTP settings are configured, the following options can be enabled in the realm:

Source code
yaml
spec:
  verifyEmail: true
  resetPasswordAllowed: true

These instruct Keycloak to require users to verify their email address before login and allow password reset via email links.

Note

When SMTP settings are configured, resetPasswordAllowed is enabled by default.