Skip to main content

Configuration of the Securosys Key Manager with Docker

This guide explains how to configure the Securosys Key Manager UI.

This includes:

  1. Customize the Key Manager UI
  2. Configure TLS HTTPS
  3. Configure User Authentication (Frontend)
  4. Configure Multi-Tenancy
  5. Configure mTLS with TSB (Backend)
  6. Configure AI Chat Assistant (MCP)
  7. Configure Audit Logging
  8. Setting a health checks for Key Manager UI.

Customize the Key Manager UI​

The customization of the Key Manager UI is done through secrets.toml file.

The file is mounted into the kms_ui container by enabling the volumes section:

volumes:
  - ./secrets.toml:/app/.streamlit/secrets.toml:ro      # Mount local secrets.toml into container (read-only)

Configure TLS (HTTPS)​

To use TLS, you need to provide the KMS UI container with a key and certificate that it should use. For this example, create a self-signed certificate:

# Generate self-signed certificate (valid for 1 year)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key \
  -out tls.crt \
  -subj "/CN=localhost/O=Securosys"

Create a config.toml file, see the API reference for config.toml:

[theme]
base="light"
primaryColor="#e30613"
redColor="#e30613"

[client]
toolbarMode = "viewer"

# -------------------------
# TLS for Key Manager UI
# -------------------------
[server]
sslCertFile = "/app/.streamlit/tls.crt"
sslKeyFile = "/app/.streamlit/tls.key"

Update the docker-compose.yml to mount the files into the KMS UI container:

volumes:
      - ./secrets.toml:/app/.streamlit/secrets.toml:ro
      - ./tls.crt:/app/.streamlit/tls.crt:ro
      - ./tls.key:/app/.streamlit/tls.key:ro
      - ./config.toml:/app/.streamlit/config.toml:ro

Restart the container:

docker compose down
docker compose up -d

Open a browser access the Key Manager UI: https://localhost:8501

Authentication (Frontend)​

The Key Manager UI supports multiple authentication mechanisms. When configuring choose either HSM Authentication or Managed Authentication:

  • Microsoft Entra ID - Managed (OAuth 2.0)
  • Keycloak - Managed (OpenID Connect)
  • GitHub OAuth - Managed (OAuth 2.0)
  • Local Service Users - HSM

Set the [authentication].provider to oauth or hsm_auth in the secrets.toml file.

# =====================================================================
# 1. AUTHENTICATION
# =====================================================================
# Controls how users log into the application.
#
#   ""           No authentication (open access - NOT recommended)
#   "hsm_auth"   Local users stored on the HSM partition (password + optional 2FA)
#   "oauth"      External OAuth providers (Microsoft Entra ID and/or GitHub)
#
# Combining providers:  provider = "oauth"  enables all configured
# [oauth.*] sections below.  provider = "hsm_auth" ignores them.
# =====================================================================
[authentication]
provider = "hsm_auth"                                       # REQUIRED - set to "hsm_auth" or "oauth"

Add the oauth.* configuration to the secrets.toml file.

# --- Microsoft Entra ID / Azure AD ------------------------------------
[oauth.microsoft]
client_id = "00000000-0000-0000-0000-000000000000"
client_secret = ""
redirect_uri = "http://localhost:8501"
scope = "openid profile email"
tenant_id = "00000000-0000-0000-0000-000000000000"
allowed_group_id = ""                              # Optional - restrict to an Azure AD group

Restart the container to enable the Identity Provider integration:

docker compose down
docker compose up -d

Verify your installation, by accessing the Key Manager UI. An authentication prompt appears with your provider of choice.

authentication mask

Multi-Tenancy​

Multi-tenancy allows multiple teams or organizations to share a single Key Manager deployment while maintaining strict partition-based isolation of cryptographic material.

Set the [multi_tenancy].vault_type in the secrets.toml file:

# =====================================================================
# 5. MULTI-TENANCY  (optional)
# =====================================================================
# Allows users to work with multiple HSM partitions / instances.
# Partition credentials are resolved at login from the configured vault.
#
# For OAuth: partitions are mapped from the token's "roles" claim.
# For hsm_auth: partitions are configured per-user in the Security tab.
#
# vault_type determines where partition credentials are stored:
#
#   "hsm"                 - HSM Data Objects on the [tsb] management partition
#                           (objects named KMS-PARTITION-{role})
#   "azure_key_vault"     - Azure Key Vault secrets (one per role)
#   "gcp_secret_manager"  - Google Cloud Secret Manager secrets
#
# Each secret/object contains a JSON payload:
# {
#   "api_url":       "https://...",
#   "access_token":  "eyJ...",
#   "display_name":  "Production",       ← shown in sidebar & top-bar
#   "color":         "#e30613"         ← optional hex color for top-bar indicator
# }
# =====================================================================

# --- Option A: HSM-based partition store ------------------------------
# Requires [tsb] to be configured (management partition).
[multi_tenancy]
vault_type = "hsm"

Partition credentials are stored as data objects on the management HSM partition.

When multi-tenancy is enabled, users can switch between HSM partitions at runtime via the sidebar partition selector. Each partition can be assigned a display name and color indicator.

When using OAuth providers (Microsoft Entra ID, Keycloak), partitions can be automatically mapped from user roles or group memberships.

mTLS with TSB (Backend)​

This step is required if your Transaction Security Broker (TSB) is configured to accept only mutual TLS (mTLS) connections — that is, when the Key Manager must present a client certificate to authenticate itself to TSB.

You can read more about enabling mTLS in TSB post-installation script.

# --- Mutual TLS (optional) -------------------------------------------
# Configure if the REST-API is set to mTLS = "need".
# Both client_key_path and client_certificate_path must be provided together.
# -----------------------------------------------------------------------
[tsb.mtls]
client_key_path = "./mtls/client.key"              # Client private key
client_certificate_path = "./mtls/client.crt"      # Client certificate
verify_ca_certificate = true                       # Verify server certificate (recommended)
ca_certificate_path = "./mtls/server.crt"          # CA / server cert path - omit if signed by a public CA
warning

Leave ca_certificate_path empty only if the TSB server certificate is signed by a public CA.

AI Chat Assistant (MCP)​

The Key Manager UI includes an optional AI-powered chat assistant that uses the Model Context Protocol (MCP) to interact with HSM operations using natural language.

Add the [mcp] configuration to the secrets.toml file:

# =====================================================================
# 7. AI / MCP INTEGRATION  (optional)
# =====================================================================
# Enables the "Chat" tab with an AI assistant connected to the HSM
# via the Model Context Protocol (MCP).
#
# [mcp]          — General settings (MCP server URL)
# [mcp.<name>]   — One sub-table per AI provider. Configure one or more.
#                   The user can switch between them at runtime in the Chat tab.
#
# Supported provider types:
#   "anthropic"  — Anthropic Claude  (claude-sonnet-4-20250514, claude-opus-4-20250514, …)
#   "openai"     — OpenAI GPT        (gpt-4o, gpt-4-turbo, o3, …)
#   "gemini"     — Google Gemini      (gemini-2.5-pro, gemini-2.0-flash, …)
#   "local"      — Any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …)
#
# Each provider sub-table requires:
#   provider     — provider type (see above)
#   model        — model identifier
#   api_key      — API key (can be empty for "local")
#   label        — (optional) display name shown in the provider switcher
#   base_url     — (optional) custom endpoint URL (for "local" / custom "openai")
#
# The first configured provider is selected by default.

[mcp]
url = "https://mcp-hsm-server.securosys.com/sse"                        # MCP server endpoint URL

#[mcp.claude]
#provider = "anthropic"
#label = "Claude Opus"
#model = "claude-opus-4-20250514"
#api_key = "sk-..."

#[mcp.gpt]
#provider = "openai"
#label = "GPT-4o"
#model = "gpt-4o"
#api_key = "sk-..."

#[mcp.gemini]
#provider = "gemini"
#label = "Gemini 2.5 Pro"
#model = "gemini-2.5-pro"
#api_key = "AIza..."

#[mcp.ollama]
#provider = "local"
#label = "Ollama (local) - not setup"
#model = "llama3"
#api_key = ""
#base_url = "http://localhost:11434/v1"

When enabled, the assistant supports multiple LLM providers (Anthropic Claude, OpenAI GPT, Google Gemini, and local LLMs) that can be switched at runtime from the Chat Assistant tab.

info

This requires a deployment of the Securosys MCP Server. Please contact us if you are interested in this.

Audit Logging​

The Key Manager UI can produce structured audit logs in JSON Lines format, covering all operations (authentication, key management, certificate management, crypto operations, and user management).

# =====================================================================
# 8. AUDIT LOGGING  (optional)
# =====================================================================
[audit]
log_dir = "logs"                                   # Directory for audit JSONL logs (default: "logs")

When enabled, audit events are written to rotating log files that can be analyzed through the Compliance tab or exported for external SIEM integration.

Add a Health Check​

The healthcheck is intended to assist with the container management. You can specify check interval and retry logic as shown below.

services:
  securosys_kms:
    healthcheck:                                        # Container health monitoring
      test: ["CMD", "bash", "-c", "wget -qO- http://localhost:8501/_stcore/health || exit 1"]
      interval: 30s                                     # Run healthcheck every 30 seconds
      timeout: 5s                                       # Fail if healthcheck takes more than 5 seconds
      retries: 5                                        # Mark as unhealthy after 5 failed checks
      start_period: 20s                                 # Allow 20s for the app to start before healthchecks kick in

Security Note​

  • Keep the secrets.toml file outside of version control.
  • Mount it as read-only inside the container (as shown in the example).
  • Rotate credentials (tokens, secrets, client IDs) regularly.
Get started withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?