Security

This page describes how to configure security for Kannika Armory during the installation process.

Basic authentication

This is the default authentication method for the platform. Use the properties below to configure a username and password.

values.yaml

api:
  config:
    security:
      enabled: true
      basicAuth:
        enabled: true
        username: "<username>"
        password: "<password>"

Using a custom Secret

By default, a Secret resource is created in Kubernetes to store the username and password with the same name as the release. You can customize the Secret creation using the following properties.

values.yaml

api:
  config:
    security:
      enabled: true
      basicAuth:
        enabled: true
        username: "<username>"
        password: "<password>"
      secret:
        name: custom-secret
        usernameKey: custom-username-key
        passwordKey: custom-password-key

Using an existing Secret

If you want to use an existing Secret instead, e.g. one that integrates with a secret management system, set api.config.security.secret.create to false and provide the name of the Secret along with the keys that contain the username and password.

values.yaml

api:
  config:
    security:
      enabled: true
      basicAuth:
        enabled: true
      secret:
        create: false               # Disable default secret creation
        name: my-custom-secret      # Optional, defaults to release name
        # usernameKey: username     # Optional, defaults to `username`
        # passwordKey: password     # Optional, defaults to `password`

Disabling Secret creation

If you want to provide the username and password directly without using a Secret, set api.config.security.secret.create to false. This will cause the values to be injected directly into the environment variables of the API pod.

Caution

This is not recommended for production environments.

values.yaml

api:
  config:
    security:
      enabled: true
      basicAuth:
        enabled: true
        username: "<username>"
        password: "<password>"
      secret:
        create: false

OIDC authentication

OIDC authentication involves both the Console and the API, and you configure each of them separately.

The Console handles the interactive login. It redirects the user to the OIDC provider using the authorization code flow with Proof Key for Code Exchange (PKCE), obtains the access token, and sends it to the API with every request. You configure it under console.config.security.oidc.

The API validates the tokens. It checks each request’s access token against the configured issuer and audience before serving it. You configure it under api.config.security.oidc.

Both sides must point at the same OIDC provider for authentication to succeed.

The synopsis below shows the available options for both.

values.yaml

console:
  config:
    security:
      enabled: true
      oidc:
        enabled: true
        clientId: <client-id>
        audience: <audience>                 # Optional
        scope: <scope>                       # Optional, added to `openid offline_access`
        authEndpoint: <auth-endpoint>
        tokenEndpoint: <token-endpoint>
        redirectUri: <redirect-uri>          # Optional, defaults to the current origin
        logoutEndpoint: <logout-endpoint>    # Optional, no provider logout when unset
        displayNameTokenClaim: <claim>       # Optional

api:
  config:
    security:
      enabled: true
      oidc:
        issuerUri: <issuer-uri>
        audience: <audience>                 # Optional, not validated when unset
        principalClaimName: <claim>          # Optional, defaults to `sub`

Console configuration

The Console offers the following options to configure OIDC authentication. When logging in, the console will redirect the user to the authEndpoint using the authorization code flow with PKCE.

Key	Description
console.config.security.enabled	Boolean flag that enables or disables security features for the Console. When set to true, it activates security mechanisms like OIDC and Basic Auth. (Enabled by default)
console.config.security.oidc.enabled	Controls whether OpenID Connect (OIDC) is enabled for the console. Setting it to true initiates the OIDC flow for user authentication.
console.config.security.oidc.clientId	Client ID assigned to the Console by the OIDC provider. The OIDC provider uses this ID to validate your application’s requests.
console.config.security.oidc.audience	Intended recipient for the tokens issued by the OIDC provider.
console.config.security.oidc.scope	Level of access the Console requests from the OIDC provider. It’s a space-separated list of permission scopes (e.g., profile, email) that the provider grants access to.
console.config.security.oidc.authEndpoint	URL of the OIDC provider’s authorization endpoint. This is where the initial request for user authentication is directed.
console.config.security.oidc.tokenEndpoint	URL of the OIDC provider’s token endpoint. After successful user authentication, the Console retrieves tokens by sending a request to this endpoint.
console.config.security.oidc.redirectUri	Redirect URI sent to the OIDC provider during login and token exchange. Optional. Defaults to the current origin (for example https://<host>). Set it to a full URI when the provider requires a dedicated callback path, for example https://console.example.com/login/callback.
console.config.security.oidc.logoutEndpoint	URL of the OIDC provider’s logout endpoint. When the user logs out of the console, it can redirect them to this endpoint to terminate the OIDC session.
console.config.security.oidc.displayNameTokenClaim	Name of the claim within the OIDC token that contains the user’s display name. This value can be used by the Console to display the user’s name after successful authentication.

API configuration

To enable OIDC authentication for the API, the following properties can be configured.

When OIDC is configured, basic authentication is disabled by default. To use both OIDC and basic authentication simultaneously, set api.config.security.basicAuth.enabled to true.

Key	Description
api.config.security.enabled	Boolean flag that enables or disables security features for the API. When set to true, it activates security mechanisms like OIDC and Basic Auth. (Basic Auth is enabled by default)
api.config.security.basicAuth.enabled	Enable basic authentication. Enabled by default, unless OIDC is configured. When OIDC is configured, set this to true to allow both authentication methods.
api.config.security.oidc.issuerUri	URI that identifies the OIDC provider. The API will use this issuer URI to validate the identity of the provider sending the tokens.
api.config.security.oidc.audience	Intended recipient for the tokens issued by the OIDC provider. Optional. When unset, the aud claim is not validated, and any valid token from the issuer is accepted.
api.config.security.oidc.principalClaimName	Name of the claim within the OIDC token that contains the user’s identifier. This value will be used in the logs of the API to identify the user. Optional, defaults to sub.

Refresh tokens

The offline_access scope is requested by the Console, and it will use refresh tokens to keep the access tokens valid. If the OIDC provider doesn’t return a refresh token, the Console will continue to function. However, users will be redirected to the OIDC login page upon navigation when the access token is expired or about to.

Examples

Azure Entra ID

Create an app registration for Kannika Armory in Azure Entra ID.

values.yaml

console:
  config:
    security:
      enabled: true
      oidc:
        enabled: true
        clientId: YOUR_CLIENT_ID
        scope: api://kannika-armory/admin # or the scope you created
        authEndpoint: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize
        tokenEndpoint: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
        logoutEndpoint: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/logout
        displayNameTokenClaim: name

api:
  config:
    security:
      enabled: true
      oidc:
        issuerUri: https://sts.windows.net/YOUR_TENANT_ID/
        audience: api://kannika-armory
        principalClaimName: name

Amazon Cognito

Create a user pool with an app client for Kannika Armory, and add a hosted UI domain to obtain the authorization endpoints.

values.yaml

console:
  config:
    security:
      enabled: true
      oidc:
        enabled: true
        clientId: YOUR_CLIENT_ID
        scope: openid profile email
        authEndpoint: https://YOUR_DOMAIN.auth.YOUR_REGION.amazoncognito.com/oauth2/authorize
        tokenEndpoint: https://YOUR_DOMAIN.auth.YOUR_REGION.amazoncognito.com/oauth2/token
        logoutEndpoint: https://YOUR_DOMAIN.auth.YOUR_REGION.amazoncognito.com/logout
        displayNameTokenClaim: username

api:
  config:
    security:
      enabled: true
      oidc:
        issuerUri: https://cognito-idp.YOUR_REGION.amazonaws.com/YOUR_USER_POOL_ID
        principalClaimName: username

Caution

Cognito access tokens do not contain an aud claim, so api.config.security.oidc.audience must be left unset. The API then accepts any valid token from the issuer, including tokens issued to another app client in the same user pool.

Keycloak

For a full walkthrough, including the realm and client setup, please see the Authenticate with OIDC tutorial.

Create a realm with a client for Kannika Armory.

values.yaml

console:
  config:
    security:
      enabled: true
      oidc:
        enabled: true
        clientId: kannika-armory
        scope: profile email
        authEndpoint: https://YOUR_HOST/realms/YOUR_REALM/protocol/openid-connect/auth
        tokenEndpoint: https://YOUR_HOST/realms/YOUR_REALM/protocol/openid-connect/token
        logoutEndpoint: https://YOUR_HOST/realms/YOUR_REALM/protocol/openid-connect/logout
        displayNameTokenClaim: name

api:
  config:
    security:
      enabled: true
      oidc:
        issuerUri: https://YOUR_HOST/realms/YOUR_REALM
        audience: kannika-armory
        principalClaimName: email

Custom CA certificates

When the OIDC provider or other TLS endpoints use certificates signed by a private or internal CA, the API pod will fail to connect with a PKIX path building failed error. To resolve this, provide the CA certificates to the API and reference them in the Helm values.

The certificates can be provided through either a ConfigMap or a Secret.

Create a ConfigMap containing the CA certificate files:

kubectl create configmap my-ca-certs \
  --from-file=root-ca.crt=root-ca.crt \
  --from-file=intermediate-ca.crt=intermediate-ca.crt

Then reference the ConfigMap in the Helm values:

values.yaml

api:
  config:
    tls:
      customCaCertificates:
        configMapName: my-ca-certs

To use a Secret instead, reference it through secretName:

values.yaml

api:
  config:
    tls:
      customCaCertificates:
        secretName: my-ca-certs

Setting both configMapName and secretName is not supported, because they are mounted at the same path.

On startup, the API merges the provided certificates into the JVM’s default truststore. This applies to every TLS connection the API itself makes, not just OIDC.

Every entry in the ConfigMap or Secret is read, regardless of its name. The file extension does not matter, so both .crt and .pem work. Entries that do not contain a certificate are skipped with a warning.

Only PEM format is supported. If your certificates are in DER or PKCS12 format, convert them to PEM first.

Disable authentication

Basic authentication is enabled by default. To disable authentication, set the api.config.security.enabled configuration option to false.

api:
  config:
    security:
      enabled: false

Automatically logout inactive users

The console can track the user’s activity and log them out automatically if they haven’t interacted with the console for a given time. By default, the user will be shown a warning after 15 minutes of inactivity. Then the user can choose to extend the session or logout. After a minute, the user will be logged out automatically if neither option is chosen.

To change the default, set console.config.security.userInactivityTimeoutSeconds to the desired timeout in seconds. To disable this feature, set the timeout to 0.

console:
  config:
    security:
      userInactivityTimeoutSeconds: 0

Security for backups and restores

The settings on this page apply to the Kannika Armory control plane. Backups and restores run as separate workloads, and their security is configured elsewhere.

To connect to Kafka, schema registries, and storage, they use the credentials and certificates defined on the resources they reference. Please see the section on Authentication for more information.

Their pod and container security contexts are configured through the default pod settings. Please see the section on Default Pod Security Context for more information.