Authenticating users to the server
The KMS server can start in authenticated or non-authenticated mode (the default).
Determining the user¶
In non-authenticated mode, the server maps all requests to the default user, configured using the --default-username option (or the KMS_DEFAULT_USERNAME environment variable). This user will default to admin if not set.
--default-username <DEFAULT_USERNAME>
The default username to use when no authentication method is provided
[env: KMS_DEFAULT_USERNAME=]
[default: admin]
In authenticated mode, the server requires authentication for all requests. The authentication method can be either:
- a TLS client certificate and the server extracts the username from the certificate’s subject common name (CN)
- or a JWT access token and the server extracts the username from the token’s subject (sub) claim
However, If the --force-default-username option (or the KMS_FORCE_DEFAULT_USERNAME environment variable) is set, the server still performs the authentication but maps all requests to the default username.
Using TLS client certificates¶
The server must be started using TLS, and the certificate used to verify the clients’ certificate must be provided in PEM format using the --authority-cert-file option.
Example client TLS authentication.
The server extracts the username from the client certificate’s subject common name (CN) unless the --force-default-username option (or the KMS_FORCE_DEFAULT_USERNAME environment variable) is set, in which case the server uses the default username.
Using JWT access tokens¶
The server supports JWT access tokens which are compatible with Open ID Connect.
The server validates the JWT tokens signatures using the token issuer JSON Web Key Set (JWKS) that is pulled on server start.
The JWT token¶
The JWT token must be passed to the endpoints of the KMS server using the HTTP Authorization header:
The JWT token should contain the following claims:
iss: The issuer of the token. This should be the authorization server URL.sub: The subject of the token. This should be the email address of the user.aud: The audience of the token. OPTIONAL: this should be identical to the one set on the KMS server.exp: The expiration time of the token. This should be a timestamp in the future.iat: The time the token was issued. This should be a timestamp in the past.
On the ckms command line interface, the token is configured in the client configuration. Please refer to the CLI documentation for more details.
Configuring the KMS server for JWT authentication¶
The KMS server JWT authentication is configured using three command line options (or corresponding environment variables):
Example of JWT Configuration
Below is an example of a JWT configuration for the KMS server using Google as the authorization server.
docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:4.15.0 \
--jwt-issuer-uri=https://accounts.google.com \
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs \
--jwt-audience=cosmian_kms
JWT issuer URI¶
The issuer URI of the JWT token is called to validate the token signature.
- server option:
--jwt-issuer-uri <JWT_ISSUER_URI> - env. variable:
KMS_JWT_ISSUER_URI=[<JWT_ISSUER_URI>]
JWKS URI¶
The optional JWKS (JSON Web Key Set) URI of the JWT token is called to retrieve the keyset on server start.
Defaults to <jwt-issuer-uri>/.well-known/jwks.json if not set.
- server option:
--jwks-uri <JWKS_URI> - env. variable:
KMS_JWKS_URI=[<JWKS_URI>]
JWT audience¶
The KMS server validates the JWT aud claim against this value if set
- server option:
--jwt-audience <JWT_AUDIENCE> - env. variable:
KMS_JWT_AUDIENCE=[<JWT_AUDIENCE>]
Using Google ID tokens¶
Use the following options to configure the KMS server for Google ID tokens:
Using Auth0¶
Use the following options to configure the KMS server for Auth0:
--jwt-issuer-uri=https://<your-tenant>.<region>.auth0.com/
--jwks-uri=https://<your-tenant>.<region>.auth0.com/.well-known/jwks.json
Note: the / is mandatory at the end of the issuer URL; if not present the iss will not validate
Using Google Firebase¶
Use the following options to configure the KMS server for Google Firebase:
--jwt-issuer-uri=https://securetoken.google.com/<YOUR-PROJECT-ID>
--jwks-uri=https://www.googleapis.com/service_accounts/v1/metadata/x509/[email protected]
Using Okta¶
Use the following options to configure the KMS server for Okta:
--jwt-issuer-uri=https://<OKTA_TENANT_NAME>.com
--jwks-uri=https://<OKTA_TENANT_NAME>.com/oauth2/v1/keys
--jwt-audience=<OKTA_CLIENT_ID>
Using Microsoft Entra ID¶
Use the following options to configure the KMS server for Microsoft Entra Id: