Security

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

Configuring security for the API

Basic authentication

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

values.yaml

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

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; the sections that follow describe each one.

values.yaml

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

api:
  config:
    security:
      enabled: true
      oidc:
        issuerUri: <issuer-uri>
        audience: <audience>
        principalClaimName: <claim>

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.

Azure Entra ID example

Create an app registration for Kannika Armory in the 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

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.

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. When OIDC is configured, set this to true to allow both authentication methods. (Enabled by default)
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.
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.

Azure Entra ID example

values.yaml

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

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 as a Kubernetes Secret and reference it in the Helm values.

Create a Secret containing the PEM-encoded CA certificate files:

kubectl create secret generic my-ca-certs \
  --from-file=root-ca.pem=root-ca.pem \
  --from-file=intermediate-ca.pem=intermediate-ca.pem

Then reference the Secret in the Helm values:

values.yaml

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

On startup, the API merges the provided certificates into the JVM’s default truststore. This applies to all outbound TLS connections, not just OIDC.

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