KMS User Interface

The KMS User Interface (UI) is a web-based application served from the KMS server, allowing users to perform key management operations easily.

Accessing the User Interface

Once the KMS server is running, open the following URL in your browser:

https://YOUR_KMS_URL/ui

Replace YOUR_KMS_URL with the actual KMS server address.

If the KMS is running behind a reverse proxy, set kms_public_url in the server configuration to the public-facing URL — this is required for the OIDC redirect flow to work correctly.

The UI bundle is served from the path configured by ui_index_html_folder (defaults to the built-in bundle shipped with the server).

Authentication Configuration

The UI automatically detects the authentication method configured on the KMS server and adapts its login flow accordingly:

• OIDC Authentication: The UI presents a LOGIN button that redirects to the identity provider. See Configuring OIDC Authentication below.
• Cosmian Authentication Server Login: The UI presents a username/password form (with an optional TOTP step) that authenticates directly against a Cosmian authentication server. See Configuring Cosmian Authentication Server Login below.
• SAML Single Sign-On: Users sign in at the organisation's SAML identity provider through the Authentication Verifier. See Configuring SAML Single Sign-On below.
• Certificate Authentication: The UI presents an ACCESS KMS button. The browser negotiates the mTLS handshake and submits the client certificate automatically. If no valid certificate is available, the login page is shown again with an error. See Configuring Certificate Authentication below.
• No authentication configured: No login is required — the UI takes you directly to the key management interface. However, a warning banner is displayed:

To remove the warning "Authentication is disabled on this KMS server", configure an [authentication method like explained in the next sections](#authentication-configuration).

Configuring OIDC Authentication

To enable authentication via OIDC, configure the KMS UI with details from the selected OIDC compliant tenant.

1. Using the Configuration File (.toml)

Add the following section to your KMS configuration file:

[ui_config.ui_oidc_auth]
ui_oidc_client_id = "your_client_id"
ui_oidc_client_secret = "your_client_secret"  # (optional)
ui_oidc_issuer_url = "https://your_oidc_issuer_url"
ui_oidc_logout_url = "https://your_oidc_logout_url"

If your KMS is accessible behind a proxy, also specify the public KMS URL in the generic section:

kms_public_url = "your_kms_public_url"

You may also need to register the following URIs in your Identity Provider (IdP) application settings:

• Allowed redirect/callback URI: https://YOUR_KMS_URL/ui/callback
• Application Login URI: https://YOUR_KMS_URL/ui/login
• Logout URI: https://YOUR_KMS_URL/ui/login

2. Using Command-Line Arguments

--ui-oidc-client-id "your_client_id" \
--ui-oidc-client-secret "your_client_secret" \
--ui-oidc-issuer-url "https://your_oidc_issuer_url" \
--ui-oidc-logout-url "https://your_oidc_logout_url"

Configuring Certificate Authentication (mTLS)

When the KMS server is started with mutual TLS and a client CA (clients_ca_cert_file), the UI switches to certificate-based login. See Enabling TLS for server-side configuration.

The browser handles the mTLS handshake transparently: Chrome presents the client certificate during the TLS handshake and the KMS server extracts the Subject CN of the certificate and uses it as the KMS username. For example, a certificate with CN=alice identifies the user as alice for all access-control decisions.

Users who have no valid client certificate installed will see a "CERT identity verification failed" error on the login page.

Step 1 — Obtain your client certificate

The client certificate must be signed by the CA configured in clients_ca_cert_file on the server. Obtain it from your PKI or administrator. If you are using the KMS setup wizard, it generates a client.crt + client.key pair automatically.

Step 2 — Convert PEM to PKCS#12 (if needed)

Browsers import certificates as PKCS#12 (.p12) bundles. If you have separate PEM files, convert them:

openssl pkcs12 -export \
  -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1 \
  -in client.crt \
  -inkey client.key \
  -certfile ca.crt \
  -out client.p12 \
  -passout pass:your-password

If you already have a .p12 file generated by the KMS wizard (client.p12), skip this step — it is already in the correct format.

Step 3 — Install the certificate in the browser

Configuring Cosmian Authentication Server Login

When the KMS is deployed alongside a Cosmian authentication server ("AS"), the UI can offer a native username/password (with optional TOTP) login form that authenticates end users directly against it — the same capability as ckms login cosmian, exposed in the browser.

The AS's session token is validated by the KMS server and never forwarded to the browser: only the resulting user identity is kept in the KMS's own session cookie.

1. Using the Configuration File (.toml)

[cosmian_auth]
cosmian_auth_server_url = "https://your-auth-server:8443"
cosmian_auth_realm = "your_realm"
cosmian_auth_accept_invalid_certs = false  # set true only for dev/test self-signed certs

Both cosmian_auth_server_url and cosmian_auth_realm must be set for the UI login form to appear — cosmian_auth_server_url alone only enables validation of bearer tokens already issued by the AS for direct API access.

2. Using Command-Line Arguments

--cosmian-auth-server-url "https://your-auth-server:8443" \
--cosmian-auth-realm "your_realm"

Configuring SAML Single Sign-On

When an Authentication Verifier realm is configured as a SAML 2.0 service provider, Web UI users can sign in at the organisation's identity provider (Microsoft Entra ID, Okta, ADFS, Keycloak, ...). The KMS does not process SAML itself: the Authentication Verifier validates the SAML response and issues its _ea_ session cookie, which the KMS then accepts as the Web UI credential for the configured realm only. Sessions of any other realm of the same Authentication Verifier are rejected.

Prerequisites

• Authentication Verifier 0.5.0 or later, built with the saml feature (Docker image ghcr.io/cosmian/auth-verifier-saml).
• The Authentication Verifier /saml/ routes are served from the KMS public origin, behind a reverse proxy, without changing the /saml/ path prefix. The _ea_ cookie is bound to the host the browser contacted, so it only reaches the KMS when both are served from the same host.
• kms_public_url uses https://. The server refuses to start otherwise.
• auth_verifier_url uses https:// and auth_verifier_saml_realm is a regular realm: not empty and not the admin realm _. The server refuses to start otherwise (the session cookie is sent to auth_verifier_url on logout, and admin-realm sessions must never authenticate to the KMS).
• State-changing API calls authenticated by the session cookie (POST to /kmip, /v1/crypto, /tokenize, ...) must send Content-Type: application/json or application/octet-stream; the Web UI does. Other content types are rejected, which stops forged cross-origin form posts. List any other UI origin in cors_allowed_origins.
• The reverse proxy reaches the Authentication Verifier over HTTPS, so that the _ea_ cookie carries the Secure flag.
• In the SAML realm of the Authentication Verifier, sp_acs_url is https://<kms host>/saml/<realm>/acs and allowed_return_origins contains https://<kms host>.

Example reverse-proxy configuration (nginx):

server {
    listen 443 ssl;
    server_name kms.example.com;

    location /saml/ { proxy_pass https://auth-verifier.internal:8443; }
    location /      { proxy_pass https://kms.internal:9998; }
}

Server configuration

kms_public_url = "https://kms.example.com"

[auth_verifier]
auth_verifier_url        = "https://auth-verifier.internal:8443"
auth_verifier_saml_realm = "kms-saml"

When auth_verifier_saml_realm is set, GET /ui/auth_method advertises AUTH_VERIFIER_SAML and the login page shows a Single sign-on (SSO) button, which starts sign-in at https://kms.example.com/ui/login_saml. The KMS redirects to /saml/<realm>/login, the identity provider authenticates the user, and the browser returns to the UI with the _ea_ cookie. Logging out of the UI revokes the Authentication Verifier session and expires the cookie.