Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

IDP (Keycloak)

Overview

The Identity Provider (IDP) service is based on Keycloak and provides OpenID Connect (OIDC) authentication and authorization for the basebox AI platform. It manages user identities, realms, clients, and authentication flows.

Deployment

The IDP is deployed via Helm chart to Kubernetes clusters with an integrated PostgreSQL database managed by CloudNativePG.

Helm Chart Configuration

Basic Settings

Parameter	Default	Description
`replicaCount`	`1`	Number of IDP pod replicas
`image.repository`	`gitea.basebox.health/basebox-distribution/idp`	Container image repository
`image.pullPolicy`	`IfNotPresent`	Image pull policy
`image.tag`	`latest`	Image tag to deploy
`fullnameOverride`	`idp`	Override the full name of the deployment

Service Configuration

Parameter	Default	Description
`service.type`	`ClusterIP`	Kubernetes service type
`service.port`	`8080`	Service port

Resource Management

Parameter	Default	Description
`resources.requests.cpu`	`250m`	Minimum CPU allocation
`resources.requests.memory`	`512Mi`	Minimum memory allocation
`resources.limits.cpu`	`1000m`	Maximum CPU allocation
`resources.limits.memory`	`2Gi`	Maximum memory allocation

Autoscaling

Parameter	Default	Description
`autoscaling.enabled`	`false`	Enable horizontal pod autoscaling (recommended for production)
`autoscaling.minReplicas`	`1`	Minimum number of replicas
`autoscaling.maxReplicas`	`3`	Maximum number of replicas
`autoscaling.targetCPUUtilizationPercentage`	`80`	Target CPU utilization for scaling
`autoscaling.targetMemoryUtilizationPercentage`	`80`	Target memory utilization for scaling

Health Checks

Parameter	Default	Description
`livenessProbe.httpGet.path`	`/health/live`	Liveness probe endpoint
`livenessProbe.initialDelaySeconds`	`30`	Delay before first liveness probe
`livenessProbe.periodSeconds`	`10`	How often to perform the probe
`livenessProbe.failureThreshold`	`10`	Number of failures before restart
`readinessProbe.httpGet.path`	`/health/ready`	Readiness probe endpoint
`readinessProbe.initialDelaySeconds`	`30`	Delay before first readiness probe
`readinessProbe.periodSeconds`	`10`	How often to perform the probe
`readinessProbe.failureThreshold`	`10`	Number of failures before marking unready

Keycloak Configuration

Core Settings

Parameter	Description	Example
`keycloak.url`	Internal Keycloak URL	`http://idp:8080`
`keycloak.realm`	Default Keycloak realm	`basebox`
`keycloak.clientId`	Keycloak client ID	`idp`
`keycloak.clientSecret`	Keycloak client secret	`<generate-secure-secret>`
`keycloak.keycloak_admin_user`	Keycloak admin username	`admin`
`keycloak.keycloak_admin_password`	Keycloak admin password	`<secure-password>`

Database Configuration

The IDP uses CloudNativePG for PostgreSQL database management.

Database Settings

Parameter	Default	Description
`database.enabled`	`true`	Enable database creation
`database.imageName`	`ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm`	PostgreSQL image
`database.host`	`idp-db-rw`	Database host (read-write service)
`database.port`	`5432`	Database port
`database.username`	`idp`	Database username
`database.password`	`<secure-password>`	Database password
`database.name`	`idp`	Database name

CloudNativePG Cluster Settings

Parameter	Default	Description
`idp-db.cluster.instances`	`1`	Number of PostgreSQL instances
`idp-db.cluster.storage.size`	`5Gi`	Storage size for database
`idp-db.cluster.storage.storageClass`	`default`	Storage class to use
`idp-db.cluster.monitoring.enablePodMonitor`	`false`	Enable Prometheus monitoring

Environment Variables

Database Connection (from Secrets)

Variable	Source	Description
`KC_DB_URL_HOST`	`idp-database` secret	Database hostname
`KC_DB_URL_PORT`	`idp-database` secret	Database port
`KC_DB_URL_DATABASE`	`idp-database` secret	Database name
`KC_DB_USERNAME`	`idp-database` secret	Database username
`KC_DB_PASSWORD`	`idp-database` secret	Database password

Keycloak Core Configuration

Variable	Description
`KC_DB_VENDOR`	Database vendor (`POSTGRES`)
`KC_DB_SCHEMA`	Database schema (`public`)
`KC_HEALTH_ENABLED`	Enable health endpoints
`KC_METRICS_ENABLED`	Enable metrics endpoints
`KC_PROXY`	Proxy mode (`edge` for reverse proxy)
`KC_PROXY_HEADERS`	Proxy header handling (`xforwarded`)
`KC_HTTP_RELATIVE_PATH`	Relative path for Keycloak (`/auth`)
`KC_HOSTNAME`	Public hostname for Keycloak
`KC_HOSTNAME_STRICT`	Strict hostname checking

Integration Configuration

Variable	Description
`KEYCLOAK_URL`	Internal Keycloak URL for API calls
`AISRV_URL`	URL of the AISRV backend service
`REALM_NAME`	Default realm name to create/use

Organization and Admin Configuration

Variable	Description
`ORGANIZATION_NAME`	Default organization name
`ADMIN_EMAIL`	Administrator email address
`ADMIN_PASSWORD`	Administrator password
`ADMIN_LANG`	Administrator language (`en`, `de`, etc.)
`KEYCLOAK_ADMIN`	Keycloak admin username (from secret)
`KEYCLOAK_ADMIN_PASSWORD`	Keycloak admin password (from secret)

Operational Configuration

Variable	Default	Description
`MAX_RETRIES`	`30`	Maximum retries for initialization
`RETRY_INTERVAL`	`20`	Seconds between retries
`JAVA_OPTS_APPEND`	`-Dinfinispan.shutdown.hook.enabled=false`	JVM options
`QUARKUS_MICROMETER_ENABLED`	`true`	Enable Quarkus metrics

Configuration Examples

Production Configuration

# values-production.yaml
replicaCount: 2

image:
  repository: gitea.basebox.health/basebox-distribution/idp
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
  hosts:
    - host: auth.company.com
      paths:
        - path: /auth
          pathType: Prefix
  tls:
    - secretName: idp-tls
      hosts:
        - auth.company.com

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 75

keycloak:
  url: http://idp:8080
  realm: basebox
  clientId: idp
  clientSecret: "<generate-secure-secret-32-chars>"
  keycloak_admin_user: admin
  keycloak_admin_password: "<generate-secure-password>"

database:
  enabled: true
  imageName: ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm
  host: idp-db-rw
  port: 5432
  username: idp
  password: "<generate-secure-database-password>"
  name: idp

idp-db:
  cluster:
    instances: 3
    storage:
      size: 20Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

env:
  # Database connection (from secrets)
  KC_DB_URL_HOST:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: host
  KC_DB_URL_PORT:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: port
  KC_DB_URL_DATABASE:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: name
  KC_DB_USERNAME:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: username
  KC_DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: password

  # Keycloak configuration
  KC_DB_VENDOR: POSTGRES
  KC_DB_SCHEMA: public
  KC_HEALTH_ENABLED: "true"
  KC_METRICS_ENABLED: "true"
  KC_PROXY: "edge"
  KC_PROXY_HEADERS: "xforwarded"
  KC_HTTP_RELATIVE_PATH: "/auth"
  KC_HOSTNAME: "auth.company.com"
  KC_HOSTNAME_STRICT: "false"

  # Integration
  KEYCLOAK_URL: "http://idp:8080"
  AISRV_URL: "http://aisrv:8888"
  REALM_NAME: "production"

  # Organization
  ORGANIZATION_NAME: "company"
  ADMIN_EMAIL: "admin@company.com"
  ADMIN_PASSWORD: "<secure-admin-password>"
  ADMIN_LANG: "en"

  # Admin credentials (from secrets)
  KEYCLOAK_ADMIN:
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: KEYCLOAK_ADMIN
  KEYCLOAK_ADMIN_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: KEYCLOAK_ADMIN_PASSWORD

  # Operational
  MAX_RETRIES: "30"
  RETRY_INTERVAL: "20"
  JAVA_OPTS_APPEND: "-Dinfinispan.shutdown.hook.enabled=false"
  QUARKUS_MICROMETER_ENABLED: "true"

High Availability Configuration

# values-ha.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 65
  targetMemoryUtilizationPercentage: 70

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 3000m
    memory: 6Gi

idp-db:
  cluster:
    instances: 3
    storage:
      size: 50Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values:
                - idp
        topologyKey: kubernetes.io/hostname

Gateway API Configuration

# values-gateway.yaml
httpRoute:
  enabled: true
  annotations:
    example.com/rate-limit: "100"
  parentRefs:
    - name: company-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - auth.company.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /auth

env:
  KC_HOSTNAME: "auth.company.com"
  KC_HTTP_RELATIVE_PATH: "/auth"
  KC_PROXY: "edge"
  KC_PROXY_HEADERS: "xforwarded"

Installation

Prerequisites

Kubernetes cluster (1.23+)
Helm 3.x
kubectl configured
CloudNativePG operator installed (for database management)
Storage provisioner with dynamic provisioning

Install CloudNativePG Operator

# Install CloudNativePG operator (if not already installed)
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

Install IDP Chart

# Install with custom values
helm install idp oci://hub.basebox.ai/helm/idp \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=idp
kubectl get cluster -n basebox idp-db

Upgrade

# Upgrade with new values
helm upgrade idp oci://hub.basebox.ai/helm/idp \
  --values values-production.yaml \
  --namespace basebox

# Check rollout status
kubectl rollout status deployment/idp -n basebox

Uninstall

# Uninstall the chart
helm uninstall idp --namespace basebox

# Note: Database PVCs are not automatically deleted
# Delete manually if needed:
kubectl delete pvc -n basebox -l cnpg.io/cluster=idp-db

Verification

Check Deployment

# Check IDP pods
kubectl get pods -n basebox -l app.kubernetes.io/name=idp

# Check database cluster
kubectl get cluster -n basebox idp-db

# Check database pods
kubectl get pods -n basebox -l cnpg.io/cluster=idp-db

# View IDP logs
kubectl logs -n basebox -l app.kubernetes.io/name=idp --tail=100

# View database logs
kubectl logs -n basebox idp-db-1

Test Health Endpoints

# Port forward IDP service
kubectl port-forward -n basebox svc/idp 8080:8080

# Test liveness endpoint
curl http://localhost:8080/health/live

# Test readiness endpoint
curl http://localhost:8080/health/ready

# Test metrics endpoint (if enabled)
curl http://localhost:8080/metrics

Access Keycloak Admin Console

# Port forward for admin access
kubectl port-forward -n basebox svc/idp 8080:8080

# Access admin console at:
# http://localhost:8080/auth/admin

Secrets Management

The chart creates two Kubernetes secrets automatically:

idp-database Secret

Contains database connection information: - host - Database hostname - port - Database port - name - Database name - username - Database username - password - Database password

keycloak-admin-secret Secret

Contains Keycloak admin credentials: - KEYCLOAK_ADMIN - Admin username - KEYCLOAK_ADMIN_PASSWORD - Admin password

Important: Change default passwords in production deployments.

Database Management

Backup and Recovery

CloudNativePG provides built-in backup capabilities:

# Add to idp-db configuration
idp-db:
  cluster:
    backup:
      barmanObjectStore:
        destinationPath: s3://backups/idp-db
        s3Credentials:
          accessKeyId:
            name: backup-s3-creds
            key: ACCESS_KEY_ID
          secretAccessKey:
            name: backup-s3-creds
            key: SECRET_ACCESS_KEY
      retentionPolicy: "30d"

Database Monitoring

Enable monitoring with Prometheus:

idp-db:
  cluster:
    monitoring:
      enablePodMonitor: true

Database Scaling

Scale PostgreSQL replicas:

idp-db:
  cluster:
    instances: 3  # Primary + 2 replicas

Security Considerations

Password Security

Generate secure passwords for all accounts using cryptographically secure methods
Rotate passwords regularly for admin and database accounts
Use Kubernetes secrets or external secret management (Vault, AWS Secrets Manager)
Never commit secrets to version control

Network Security

Use ClusterIP service type for internal-only access
Configure ingress with TLS/SSL certificates
Implement Network Policies to restrict traffic
Use KC_PROXY=edge when behind reverse proxy

Database Security

Enable SSL/TLS for database connections in production
Use separate credentials for application and admin access
Regular backup and test restore procedures
Monitor database logs for suspicious activity

RBAC Configuration

Grant SUPERUSER privilege to database user (required for initialization)
Review and minimize permissions after initial setup
Use separate service accounts for different components

Performance Tuning

JVM Configuration

Adjust Java heap size for better performance:

env:
  JAVA_OPTS_APPEND: >-
    -Xms1g -Xmx2g
    -XX:MetaspaceSize=256m
    -XX:MaxMetaspaceSize=512m
    -Dinfinispan.shutdown.hook.enabled=false

Connection Pooling

Configure database connection pool in Keycloak settings through admin console or environment variables.

Caching

Keycloak uses Infinispan for distributed caching. For multi-replica deployments, ensure proper cache configuration.

Monitoring and Metrics

Prometheus Metrics

Enable metrics collection:

env:
  KC_METRICS_ENABLED: "true"
  QUARKUS_MICROMETER_ENABLED: "true"

Metrics available at /metrics endpoint.

Health Checks

Liveness: /health/live - Checks if Keycloak is running
Readiness: /health/ready - Checks if Keycloak is ready to serve requests

Database Monitoring

CloudNativePG exports metrics for: - Connection pool status - Replication lag - Query performance - Storage usage

High Availability Setup

For production deployments requiring high availability:

Multiple IDP Replicas: Set replicaCount: 3 or use autoscaling
PostgreSQL Cluster: Set idp-db.cluster.instances: 3
Pod Anti-Affinity: Distribute pods across nodes
Health Check Tuning: Adjust thresholds for your environment
Resource Allocation: Ensure adequate CPU/memory
Persistent Storage: Use reliable storage class with replication

Integration with Other Services

AISRV Integration

The IDP integrates with AISRV for user and organization management:

env:
  AISRV_URL: "http://aisrv:8888"
  REALM_NAME: "production"
  ORGANIZATION_NAME: "your-org"

Frontend Integration

Frontend applications connect to IDP using OIDC:

Authority URL: https://auth.company.com/auth/realms/{realm}
Token Endpoint: /auth/realms/{realm}/protocol/openid-connect/token
Authorization Endpoint: /auth/realms/{realm}/protocol/openid-connect/auth

Initialization Process

On first startup, the IDP performs:

Database schema initialization
Keycloak bootstrap
Realm creation (specified in REALM_NAME)
Organization setup (specified in ORGANIZATION_NAME)
Admin user creation
Client configuration

The process uses MAX_RETRIES and RETRY_INTERVAL to handle dependencies.