Authentication¶
The KMS server offers flexible authentication options, supporting multiple authentication methods that can operate independently or in combination with each other, providing multi-factor authentication capabilities.
Authentication Modes¶
Non-authenticated Mode (Default)¶
By default, if no authentication methods are configured, the server operates in non-authenticated mode. All requests are mapped to the default user, which can be configured using:
--default-username <DEFAULT_USERNAME>
The default username to use when no authentication is configured
[env: KMS_DEFAULT_USERNAME=]
[default: admin]
Authenticated Mode¶
When one or more authentication methods are enabled, the server requires successful authentication for all requests. The authentication mechanism works in a cascading fashion, attempting each configured method until one succeeds.
Available Authentication Methods¶
The KMS server supports three primary authentication methods:
- TLS Client Certificates: Authentication based on X.509 client certificates
- JWT Tokens: Authentication with OpenID-compliant JWT access tokens
- API Tokens: Authentication using a pre-shared API token
These methods can be used individually or in combination for enhanced security.
Authentication Flow¶
When multiple authentication methods are configured, the server follows this process:
- If TLS Client Certificate authentication is enabled and a valid certificate is presented, the user is authenticated
- If JWT authentication is enabled and a valid JWT token is presented, the user is authenticated
- If API Token authentication is enabled and a valid token is presented, the user is authenticated
- If all configured authentication methods fail, access is denied with a 401 Unauthorized response
A successful authentication at any step will grant access and subsequent authentication methods will be skipped.
Configuring Authentication Methods¶
TLS Client Certificate Authentication¶
To enable certificate-based authentication, the server must be started with TLS and a certificate authority (CA) for client verification:
docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest \
--https-p12-file kms.server.p12 \
--https-p12-password password \
--authority-cert-file client_ca.cert.pem
The server extracts the username from the certificate’s Subject Common Name (CN) field. Specifically, the Common Name of the client certificate subject is used directly as the username for authentication purposes. If the certificate is valid but does not contain a Common Name, authentication will fail.
Example of a subject with a CN field:
C=FR, ST=Ile-de-France, L=Paris, O=Cosmian Tech, [email protected]
In this example, [email protected] would become the authenticated username.
Clients must present a valid certificate signed by the specified authority.
JWT Token Authentication¶
The server supports JWT tokens compatible with OpenID Connect. Configure JWT authentication with:
docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest \
--jwt-issuer-uri=https://accounts.google.com \
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs \
--jwt-audience=cosmian_kms
JWT tokens must be passed in the HTTP Authorization header:
The server extracts the username from the token’s email claim.
PKCE Support¶
The KMS authentication system supports PKCE (Proof Key for Code Exchange) for JWT authentication, which eliminates the need for client secrets. PKCE is a more secure OAuth 2.0 flow for public clients that don’t need to store client secrets. The client generates a code verifier and code challenge pair, using the code challenge during authorization and the code verifier during token exchange.
This is particularly useful for:
- Mobile applications
- Single-page applications
- Desktop applications
- Any client that cannot securely store a client secret
When using PKCE, client secrets become optional in the OAuth2 configuration. The authorization server validates the code verifier against the previously provided code challenge, ensuring secure authentication without exposing client secrets.
For detailed information about implementing PKCE authentication with the KMS, see the PKCE Authentication guide.
Multiple Identity Providers¶
To support multiple identity providers, repeat the parameters in matching order:
--jwt-issuer-uri=https://accounts.google.com \
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs \
--jwt-audience=cosmian_kms \
--jwt-issuer-uri=https://login.microsoftonline.com/<TENANT_ID>/v2.0 \
--jwks-uri=https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys \
--jwt-audience=<CLIENT_ID>
API Token Authentication¶
API Token authentication uses a symmetric key stored in the KMS as the authentication token:
- Generate a symmetric key and note its ID:
- Export the key in base64 format:
- Start the server with the API token ID:
- Configure the client to use the API token:
When using API token authentication, the authenticated user will be the default username.
Force Default Username¶
If you want to enforce a consistent username regardless of the authentication method, use:
--force-default-username <true|false>
Force using the default username regardless of the authentication method
[env: KMS_FORCE_DEFAULT_USERNAME=]
[default: false]
When enabled, the server still performs the authentication validation to ensure the client has valid credentials, but it ignores the username that would normally be extracted (such as the certificate’s Common Name or JWT email claim) and instead maps all authenticated requests to the default username.
This feature is particularly useful in scenarios where:
- You want consistent user identity across all requests regardless of authentication method
- You prefer to manage access control independently from the authentication credentials
- You’re transitioning between authentication methods but need to maintain consistent audit trails
When force-default-username is enabled with multiple authentication methods, the server will still cascade through the authentication methods, but always use the default username upon successful authentication.
Multi-Factor Authentication Examples¶
Example 1: Client Certificate and JWT Authentication¶
docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest \
--https-p12-file kms.server.p12 \
--https-p12-password password \
--authority-cert-file client_ca.cert.pem \
--jwt-issuer-uri=https://accounts.google.com \
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs
In this configuration:
- Clients can authenticate using either a valid client certificate or a valid JWT token
- If both are provided, the certificate is checked first
Example 2: JWT and API Token Authentication¶
docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest \
--jwt-issuer-uri=https://accounts.google.com \
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs \
--api-token-id <SYMMETRIC_KEY_ID>
In this configuration:
- Clients can authenticate using either a valid JWT token or the API token
- JWT authentication is attempted first, followed by API token verification
Common Identity Provider Configurations¶
Google ID Tokens¶
Auth0¶
--jwt-issuer-uri=https://<your-tenant>.<region>.auth0.com/
--jwks-uri=https://<your-tenant>.<region>.auth0.com/.well-known/jwks.json
Note: the trailing / is required in the issuer URI
Microsoft Entra ID (Azure AD)¶
--jwt-issuer-uri=https://login.microsoftonline.com/<TENANT_ID>/v2.0
--jwks-uri=https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys
--jwt-audience=<CLIENT_ID>