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.
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:

Warning

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"

Note

The UI login flow always uses PKCE (code_challenge_method=S256). The client secret is optional — see the PKCE Authentication guide for per-provider configuration instructions.

Note

API Token authentication is not supported by the UI.

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

macOS / Chrome compatibility

OpenSSL 3.x generates PKCS#12 files with AES-256 ciphers by default. macOS Security.framework (which Chrome on macOS uses) cannot import that format. The -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1 flags select the older 3DES format that macOS accepts.

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

Open chrome://settings/certificates (or Settings → Privacy and security → Security → Manage certificates).
Go to the Your certificates tab.
Click Import, select client.p12, and enter the password when prompted.

Chrome and Safari on macOS read client certificates from the system keychain — do not use Chrome's built-in certificate manager.

Double-click client.p12 in Finder, or run:

security import client.p12 -k ~/Library/Keychains/login.keychain-db

Open Keychain Access, find your certificate under My Certificates.
Double-click the certificate → expand Trust → set "When using this certificate" to Always Trust (or ensure the signing CA is already trusted).

Tip

After installing or changing a client certificate, fully close and relaunch the browser. Browsers cache TLS session state and will not renegotiate with the new certificate until all windows are closed.

Certificate CN = KMS username

The Common Name (CN) of the client certificate becomes the KMS username. Make sure the CN matches the identity you want to use for access control. A wildcard CN (*) is explicitly rejected by the server.

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"

Note

If the account requires a password change or has an expired password, the UI surfaces the Cosmian authentication server's message directly; the password must be changed through the Cosmian authentication server (or its own admin UI), not through the KMS.

Keyboard shortcuts