Skip to content

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.

docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:4.12.0 \
    --https-p12-file kms.server.p12  --https-p12-password password \
    --authority-cert-file verifier.cert.pem

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:

Authorization: Bearer <TOKEN>

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

--jwt-issuer-uri=https://accounts.google.com
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs

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>

© Copyright 2018-2024 Cosmian. All rights reserved.