Configuring Securosys Key Manager

This guide walks through the settings most deployments need after install: sign-in, e-mail, alerts, syslog, and the audit log.

Admin role required

All changes in this guide require a user account with the Admin role.

It applies to every platform. All of these settings live inside the Key Manager itself, so you configure them the same way whether you run it in Docker, in Kubernetes, or on a virtual machine. Nothing here requires editing a compose file, a Helm chart, or an environment variable.

Before you start

Everything below is under Administration in the left sidebar:

Page	What it covers
General Settings	Sessions, logging, branding, password policy, alert policy
Identity Provider	Sign-in flow and OAuth provider details
Notifications	Outbound e-mail (SMTP) and who receives which alerts
Alerts	Alerts that have been raised, and their history
Audit Log	The audit log itself, plus rotation and signing
Syslog forwarding	TLS syslog forwarding of the audit log
Secrets	All passwords, client secrets, and certificates

Most changes take effect as soon as you save; the Key Manager applies the new values and tells the other services to reload. A few values are only read when a service starts, so changing them needs a service restart: the allowed CORS origins and the audit log file settings (directory, size, backups).

Secrets are stored separately. A password or client secret is never typed into the same form as the rest of the configuration. Instead, all secret values go to Administration > Secrets. They are encrypted before they are written and shown masked once saved. You can replace a secret at any time; but you cannot read it out. This split is why most sections below have two steps: fill in the settings on one page, then add the matching secret under Secrets.

Everything is stored in HSM-backed data objects, not in an external database.

note

Some values are fixed at install time and are not editable in the UI: the TSB endpoint, the service ports, and the paths used before the Key Manager is unsealed. Those stay with your deployment's environment configuration.

Sign-in and OAuth

Password sign-in is always available and cannot be switched off. OAuth providers are added alongside it.

An OAuth provider appears on the login screen once both of the following are true:

1. Its client details and client secret are configured, and
2. The Partition Security Config of the Base Partition has KEY_MANAGEMENT_SYSTEM enabled.

If a provider you configured does not appear on the login screen, check the HSM license and Partition Configuration.

Adding a new OAuth provider

To add a new OAuth provider:

1. Register the Key Manager with your provider. Create an application in Microsoft Entra ID, GitHub, or Keycloak. You will get a client ID and a client secret.

2. Set the redirect URI. The provider must redirect back to the Key Manager at:

   https://<your-key-manager-host>/auth/callback/<provider>

   where <provider> is microsoft, github, or keycloak. Enter exactly the same value in both places, in the provider's application settings and in the Key Manager. A mismatch is the most common cause of a failed login, and providers compare the string literally.

3. Enter the public details. Go to Administration > Identity Provider and fill in the fields for your provider:

   Provider	Fields
   Microsoft	Tenant ID, Client ID, Redirect URI, Scope, Allowed group ID
   GitHub	Client ID, Redirect URI
   Keycloak	Server URL, Realm, Client ID, Redirect URI

   For Microsoft, the default scope is openid profile email offline_access. Allowed group ID is optional: set it to restrict sign-in to members of one Entra ID group.

4. Store the client secret. Go to Administration > Secrets, pick the entry for your provider (OAuth: Microsoft, OAuth: GitHub, or OAuth: Keycloak) and save the client secret there.

5. Save and test. Open the Key Manager UI in a private browser tab and confirm that the provider appears on the login screen.

E-mail

Alerts are always recorded on the Alerts page. Without e-mail delivery, security-relevant events such as an unseal, a failed audit signing, or a deleted key are only visible when someone opens the dashboard. Configuring e-mail ensures that these events reach an operator when they happen, which is also what audits typically require.

E-mail delivery consists of two parts that must be configured in this order:

1. SMTP transport: the mail server the Key Manager sends through (Administration > Notifications, steps 1 and 2 below).
2. Subscriptions: which alert types are sent to which recipients (Add-ons > Alerts > Configuration, step 3 below).

To configure e-mail sending:

1. Set the SMTP password. Go to Administration > Secrets and set the SMTP credential.

2. Define a mail server. Go to Administration > Notifications and enter your SMTP server's connection details: host, port, TLS and authentication mode, and FROM address.

3. Send a test e-mail before switching Enabled on. The test uses whatever is currently in the form, so you can validate a server or a new password saving. If you leave the password blank, the test uses the one already in the secret store.

The Key Manager UI is now able to send e-mails. Next, go the Alerts section to configure which alerts get send and to whom.

Alerts

Alerts are raised by the Key Manager when something noteworthy happens. Alerts are based on the local audit log (not the HSM log).

Every alert has a type, a short identifier that names what happen (for example key_deleted), and a severity that says how serious it is. The type is what you reference when you subscribe to alerts or tune the policy.

The following alerts are available:

Break-glass alerts (default severity critical)

• unseal_executed: the Key Manager was unsealed and regained access to its sealed state and secrets.
• unseal_requested: an unseal was requested. Raised on every unseal request, even before it completes.
• admin_secret_rotated: a secret under Administration > Secrets was replaced or removed.
• audit_signing_failed: the HSM refused to sign the audit log for a verifiable export. Until the signing key is restored, no signed audit export can be produced.

Lifecycle alerts (default severity warning)

• ca_root_initialised: a CA root was set up for the first time. Also raised when the KMIP User CA is created and pinned.
• ca_rolled_over: an issuing CA was rotated to a new key. Also raised when the KMIP User CA is replaced.
• ska_policy_changed: the SKA approval policy of a key was changed. The alert details list what changed in the policy.
• approver_deleted: an SKA approver was deleted.
• user_deleted: a Key Manager user account was deleted.
• partition_deleted: a partition entry was removed from the registry.

Situational alerts (default severity info)

• key_created, key_deleted, key_rotated, key_blocked, key_unblocked: key lifecycle operations performed through the Key Manager.
• user_created: a Key Manager user account was created.
• user_modified: an account was changed. Covers role grants, partition re-assignment, and password rotation.
• partition_created, partition_modified: a partition entry was added to or changed in the registry.
• backup_downloaded: a backup was downloaded from the Key Manager.

warning

Only actions and events that happen through Key Manager create alerts. Your HSM operator should set up syslog forwarding and monitoring to capture HSM events that are triggered through other channels.

To view the list of past alerts, go to Add-ons > Alerts. To configure the alert settings, go to Administration > Alerts.

General alert settings

Under Administration > Alerts > Alerts you can configure which alerts are raised. You can turn each alert type on and off and override its severity. Alerts that are raised are always shown in the Key Manager UI.

Alert subscriptions

Subscriptions trigger an e-mail being sent when an alert is raised. A subscription is a rule that routes a set of alert types to a list of e-mail recipients. It has the following fields:

Field	Meaning
Name	A label for you
Events	Comma-separated list of alert types. Use * to match every type
Min severity	Events with severity equal and above this will match.
Recipients	Comma-separated e-mail addresses.

An alert matches a subscription when its event type matches and its severity is at or above the minimum. A subscription with no events (or no recipients) matches nothing and sends no mail.

To create and manage the alert subscriptions, go to Administration > Alerts > Subscriptions. Sending alerts requires SMTP to be configured (see e-mail).

Audit log

The audit log contains activity from the Key Manager services. These are stored in a local file.

Administration > Audit Log shows the log and its settings.

Setting	Default	Notes
Log directory	logs	Where the log file is written
Maximum size (MB)	10	Size at which the file rotates
Maximum backups	10	How many rotated files to keep
Signing key label	-	HSM key used to sign entries
Signing algorithm	NONESHA512_WITH_RSA

The signing key's password is stored under Administration > Secrets in Audit signing key.

This secret is treated differently from the others: by default it is protected by an approval-gated HSM key, so reading it requires the HSM approver workflow. That is deliberate. It is read once when the service starts, so the extra step costs little. Other secrets are read frequently and are not gated this way.

Syslog forwarding

The Key Manager can stream its local audit log to a syslog collector, so that audit events also appear in a central SIEM or log platform. The events and message formats are documented in the Log Reference.

Please note:

• Syslog is a mirror. The local audit log file remains as a the durable, signed copy. If the collector is unreachable, the Key Manager logs the problem, backs off, and retries. It never blocks or drops audit writes.
• TLS is required (RFC 5425, default port 6514). If your collector only accepts clear-text syslog, run a local forwarder that terminates TLS and re-emits.

To configure audit log forwarding:

1. Configure TLS/mTLS:
   • If your collector uses a public CA: nothing to configure.
   • If your collector uses a private CA or requires mTLS: Go to Administration > Secrets. In the Syslog TLS certificates field you can add: server CA certificate (to trust a collector with a private CA), client certificate and client private key (for mutual TLS). All three are optional; leave out what your collector does not need.
2. Configure syslog destination:
   • Go to Administration > Audit Log > Syslog forwarding.
   • Configure the collector host, port, facility, and tag. You can also enable skipping server certificate validation (for testing only!).
   • Click Save.
   • Click Test connection.

Troubleshooting

An OAuth provider is missing from the login screen. Check that both the client details and the client secret are saved, then confirm KEY_MANAGEMENT_SYSTEM is enabled in the Partition Security Config of the Base Partition.

Sign-in fails after redirecting to the provider. The redirect URI almost certainly differs between the provider and the Key Manager. They must match character for character.

The test e-mail arrives, but alerts do not. Work through the chain: is Enabled on, is the alert type still enabled under General Settings > Alerts, does a subscription include that type, and is the alert's severity at or above the subscription's minimum?

Nothing reaches the syslog collector. Syslog is best-effort by design, so failures are logged rather than surfaced. Check the audit log for connection errors, and confirm the certificates match what the collector expects.

The settings page is replaced by a "Stale configuration envelope" message. The stored configuration was encrypted for a previous installation, usually after a re-install against the same partition. Use the recovery action shown there, then restart the auth service (or wait for the next unseal) so the configuration is written afresh.