OIDC Integration

Overview

knodex supports OpenID Connect (OIDC) for enterprise authentication with:

• Standard OIDC 1.0 compliance
• Support for major providers (Okta, Auth0, Azure AD, Google, Keycloak)
• Group-based role assignment
• Automatic user provisioning

Supported Providers

knodex is designed to work with any OIDC-compliant identity provider:

• Azure AD / Microsoft Entra ID
• Google Workspace
• Okta
• Auth0
• Keycloak
• Any OIDC 1.0 compliant provider

Configuration

OIDC providers are configured through the Settings UI or via Helm/ArgoCD-managed Kubernetes manifests. Both methods write to the same Kubernetes resources (ConfigMap + Secret), and the server automatically detects changes within seconds — no pod restart required.

Settings UI

Admins can manage OIDC providers directly from the knodex UI.

1. Navigate to Settings > SSO:

1. Log in as an admin
2. Open Settings from the sidebar
3. Click the SSO card

2. Add a Provider:

1. Click Add Provider
2. Fill in the required fields:

3. Click Save

3. Scopes:

The default scopes are openid,email,profile. These cover standard identity claims. Additional scopes depend on your IdP:

groups is typically a claim in the ID token, not a standard OIDC scope. Whether you need to request a groups scope depends on your IdP. See the provider-specific guides below.

4. Edit or Delete:

• Click a provider row to edit its configuration. Client secret is only updated if a new value is provided.
• Click the delete icon and type the provider name to confirm deletion.

Helm / ArgoCD (GitOps)

For GitOps-managed deployments, configure providers declaratively via Kubernetes manifests. Helm or ArgoCD manages the ConfigMap and Secret; the server watches for changes and reloads automatically.

ConfigMap (knodex-sso-providers):

apiVersion: v1
kind: ConfigMap
metadata:
  name: knodex-sso-providers
  namespace: knodex
  labels:
    app.kubernetes.io/managed-by: knodex
    knodex.io/config-type: sso
data:
  providers.json: |
    [
      {
        "name": "azure-ad",
        "issuerURL": "https://login.microsoftonline.com/{tenant-id}/v2.0",
        "redirectURL": "https://knodex.example.com/api/v1/auth/oidc/callback",
        "scopes": ["openid", "email", "profile"]
      }
    ]

Secret (knodex-sso-secrets):

apiVersion: v1
kind: Secret
metadata:
  name: knodex-sso-secrets
  namespace: knodex
  labels:
    app.kubernetes.io/managed-by: knodex
    knodex.io/config-type: sso
type: Opaque
stringData:
  azure-ad.client-id: "your-client-id"
  azure-ad.client-secret: "your-client-secret"

How SSO Configuration Works

Provider configuration is split across two Kubernetes resources:

ConfigMap schema (providers.json key):

[
  {
    "name": "provider-name",
    "issuerURL": "https://issuer.example.com",
    "redirectURL": "https://knodex.example.com/api/v1/auth/oidc/callback",
    "scopes": ["openid", "email", "profile"]
  }
]

Secret key format: each provider has two keys using the pattern {provider-name}.client-id and {provider-name}.client-secret.

How SSO Hot-Reload Works

The knodex server uses a Kubernetes informer to watch the knodex-sso-providers ConfigMap and knodex-sso-secrets Secret. When either resource changes, the server automatically reloads OIDC providers within seconds — no pod restart required.

Reload behavior:

The informer performs a full resync every 30 seconds, so even if a watch event is missed, configuration converges within 30 seconds.

In-flight authentication flows are not disrupted during a reload. Active OIDC login sessions complete using the provider configuration that was valid when the flow started.

Provider-Specific Guides

Only Azure AD (Microsoft Entra ID) has been tested in production. The other provider guides are based on standard OIDC configuration patterns but have not been validated.

We welcome contributions! If you successfully configure knodex with another provider, please submit a PR with any corrections or improvements to these guides.

Azure AD (Microsoft Entra ID)

1. Register Application:

1. Navigate to Azure Active Directory → App registrations → New registration
2. Configure:
   • Name: knodex
   • Redirect URI: https://knodex.example.com/api/v1/auth/oidc/callback

2. Create Client Secret:

1. Navigate to Certificates & secrets
2. Create new client secret
3. Copy the secret value

3. Configure Groups:

1. Navigate to Token configuration
2. Add optional claim:
   • Token type: ID
   • Claim: groups

Azure AD returns groups in the ID token via token configuration — no groups scope is needed. Use scopes openid,email,profile.

4. API Permissions:

1. Navigate to API permissions
2. Add permissions:
   • Microsoft Graph → Delegated permissions
   • Add: User.Read, GroupMember.Read.All
3. Grant admin consent

5. Configure in knodex:

Via the Settings UI, create a provider with:

Or via Helm/ArgoCD manifests — add an entry to the knodex-sso-providers ConfigMap providers.json and set credentials in the knodex-sso-secrets Secret (see Helm / ArgoCD above).

Session Cookie Configuration

After OIDC login, knodex stores the session token in an HTTP-only cookie. The cookie attributes are configurable via Helm values for production deployments behind load balancers or across subdomains.

Helm Values

server:
  config:
    cookie:
      # Requires HTTPS. Set to false for local HTTP development.
      secure: true        # default: true
      # Set for cross-subdomain auth (e.g., ".example.com").
      domain: ""          # default: "" (same-origin)

Configuration Reference

Setting cookie.secure: false in production disables HTTPS-only cookies, allowing session tokens to be transmitted over unencrypted connections. Only use this for local HTTP development.

Test Login Flow

1. Add a provider via the Settings UI or deploy via Helm/ArgoCD (changes take effect within seconds)
2. Navigate to knodex
3. Click "Login with SSO"
4. Authenticate with your OIDC provider
5. Verify redirect back to knodex
6. Check user profile shows correct email and groups

Next: Kubernetes RBAC →