Identity providers

Koldan uses OpenID Connect (OIDC) for user and workload authentication. Operators own the provider availability, client registrations, redirect URIs, signing-key access, role claims, and credential lifecycle.

Prerequisites

Prepare a stable HTTPS issuer URL, public and pod-side DNS resolution, CA trust, a highly available provider, synchronized clocks, and separate administrative recovery access. Record the external Koldan HTTP URL and whether the Koldan desktop client is enabled.

The provider must expose authorization, token, and JWK Set endpoints. User clients require the authorization-code flow. Non-interactive Koldan identities require client credentials. Enable only the flows and scopes required for each client; do not reuse an identity-provider administrator account or a human account as a workload credential.

Configure the default tenant

Set the default tenant properties under koldan.oidc.default-tenant.*. At minimum, bootstrap requires a client ID, client secret, issuer URI, token URI, and JWK Set URI. Configure the engine client ID and secret when the enabled deployment requires service-to-service tokens.

config: |
  koldan:
    oidc:
      default-tenant:
        client-id: <oidc-client-id>
        client-secret: <injected-oidc-client-secret>
        issuer-uri: https://id.example.net/realms/koldan
        authorization-uri: https://id.example.net/realms/koldan/protocol/openid-connect/auth
        token-uri: https://id.example.net/realms/koldan/protocol/openid-connect/token
        jwk-set-uri: https://id.example.net/realms/koldan/protocol/openid-connect/certs
        end-session-uri: https://id.example.net/realms/koldan/protocol/openid-connect/logout
        engine:
          client-id: <service-client-id>
          client-secret: <injected-service-client-secret>

Use the exact properties in Application properties. All issuer and endpoint values must refer to the same security domain. Use public-issuer-uri only when the installed release and provider require distinct internal reachability and public token issuer names; tokens must still carry the issuer Koldan is configured to validate.

The chart renders config into a ConfigMap. The placeholders above must be supplied through the controlled process in Configuration and secrets, and access to both the rendered ConfigMap and Helm release data must be restricted.

Register redirect URIs as exact values rather than broad wildcards:

• The HTTPS callback path used by the installed Koldan web application.
• The koldan:// callback required by the desktop client, only when desktop access is enabled.

Derive the precise callback paths from the current release and external URL. Scheme, hostname, port, path, and trailing slash matching are provider-sensitive. Add a private issuer CA through TLS and custom CAs; never disable issuer or certificate verification.

Keycloak

The chart can install Keycloak with keycloak.install: true. Its values include the public Ingress or Route, administrator credential, and external PostgreSQL connection. Replace every placeholder, keep the administration endpoint private, and configure the external hostname so issuer metadata and browser redirects consistently use the public HTTPS URL.

Create a dedicated realm and separate confidential client registrations for browser access and Koldan workload identities. Use the client IDs configured in the matching chart values and application properties; chart defaults such as web.oauth.clientId, grpc.oauth.clientId, and workload OAuth values are part of the release contract. Give each registration its own secret. Apply PKCE S256 to user-facing authorization-code clients where supported, restrict redirect URIs, and enable service accounts only on clients that use client credentials.

If Keycloak uses the same PostgreSQL service as Koldan, give it a separate database and login. Back up the realm configuration, provider keys, federated mapping configuration, and database. A realm export without its secrets and signing keys is not a complete recovery set.

LDAP or Active Directory federation

Federate LDAP through the identity provider; Koldan remains an OIDC client.

• Use LDAPS or StartTLS with hostname verification and add the directory CA to the identity provider's trust configuration.
• Use a dedicated read-only bind identity with only the required search permissions.
• Scope the user and group base DNs and filters to the intended population.
• Map a stable, unique username attribute and immutable identifier where available.
• Map directory groups to the Koldan roles explicitly and test nested-group behavior.
• Define synchronization frequency and behavior for renamed, disabled, and deleted accounts.
• Keep a non-federated emergency provider administrator protected by a separate control.

Do not publish real DNs, bind usernames, directory hostnames, or group names in the values repository or support output.

Verify

Before enabling production access, verify:

1. OIDC discovery and JWK retrieval from the Koldan namespace.
2. Browser login and the desktop callback when enabled.
3. Non-administrator and administrator authorization boundaries.
4. Client-credentials token acquisition for every enabled workload identity.
5. Access-token refresh, logout, expiry, and provider session policy.
6. Signing-key rotation and JWK cache refresh in a staging environment.
7. Disabled-user and removed-group behavior.
8. Expected behavior during provider unavailability.

Rotate and recover

Rotate one client secret at a time. Create a second credential where the provider permits it, update Koldan, roll and test every affected workload, then revoke the old credential. For signing keys, publish the new JWK before issuing tokens with it and retain the old public key until previously issued tokens expire.

If login fails after a change, restore the previous client credential or provider configuration before making unrelated changes. Keep an administrator recovery path that does not depend on the failed federation.