Home / BeaverDeck / Docs / Configuration Guide / Auth config reference

Auth Config Reference

This page documents the complete YAML snapshot stored in the auth configuration Secret. The same format is produced by Admin export, accepted by Admin import, and loaded from the Secret during startup.

Complete Secret Example

apiVersion: v1
kind: Secret
metadata:
  name: beaverdeck-config
  namespace: beaverdeck
  labels:
    app.kubernetes.io/name: beaverdeck
    app.kubernetes.io/component: config
type: Opaque
stringData:
  config.yaml: |
    schema_version: 1
    initialized: true
    roles:
      - name: admin
        mode: admin
      - name: platform-operator
        mode: viewer
        permissions:
          namespaces:
            - apps
            - monitoring
          resources:
            pods: view
            workloads: edit
            nodes: view
            services: view
            ingresses: view
            configmaps: view
            secrets: view
            pvcs: view
            events: view
            insights: edit
            exec: edit
            apply: edit
    users:
      - username: admin
        role: admin
        password_hash: bdk1$180000$<REPLACE_SALT_HEX>$<REPLACE_DIGEST_HEX>
      - username: local-operator
        role: platform-operator
        password_hash: bdk1$180000$<REPLACE_SALT_HEX>$<REPLACE_DIGEST_HEX>
    google:
      config:
        client_id: REPLACE_GOOGLE_CLIENT_ID
        client_secret: REPLACE_GOOGLE_CLIENT_SECRET
        hosted_domain: example.com
        service_account_json: |-
          {
            "type": "service_account",
            "project_id": "REPLACE_GOOGLE_PROJECT_ID",
            "private_key_id": "REPLACE_GOOGLE_PRIVATE_KEY_ID",
            "private_key": "-----BEGIN PRIVATE KEY-----\nREPLACE_GOOGLE_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
            "client_email": "REPLACE_SERVICE_ACCOUNT@example-project.iam.gserviceaccount.com",
            "client_id": "REPLACE_GOOGLE_SERVICE_ACCOUNT_CLIENT_ID",
            "token_uri": "https://oauth2.googleapis.com/token"
          }
        delegated_admin_email: google-admin@example.com
      mappings:
        - group_email: platform-operators@example.com
          role: platform-operator
    oidc:
      config:
        provider_name: OpenID Connect
        issuer_url: https://idp.example.com
        client_id: REPLACE_OIDC_CLIENT_ID
        client_secret: REPLACE_OIDC_CLIENT_SECRET
        scopes: openid email profile groups
        hosted_domain: example.com
        email_claim: email
        groups_claim: groups
      mappings:
        - group_name: platform-operators
          role: platform-operator

To leave a provider disabled, keep all of its credential fields empty and use mappings: []. BeaverDeck supports one Google provider and one generic OIDC provider. Azure Entra ID uses the OIDC block rather than a separate top-level section.

Configure From Scratch

1. Create a password hash for every local user. Never place a raw or base64-only password in password_hash.
2. Copy the full Secret manifest to a protected file and replace all placeholders.
3. Remove the Google or OIDC credentials and mappings for providers you do not use.
4. Verify that every user and group mapping references an existing role.
5. Apply the Secret before installing BeaverDeck, or restart BeaverDeck after applying it to an existing installation.
6. Read the startup log and confirm that auth config import and normalization succeeded.

kubectl apply -f beaverdeck-config-secret.yaml
kubectl -n beaverdeck rollout restart deployment/beaverdeck
kubectl -n beaverdeck logs deployment/beaverdeck

When the Secret is pre-created before the first pod starts, the rollout restart is unnecessary. If an existing Secret is invalid, startup fails without overwriting it. Fix the Secret, or delete it to return to UI initialization.

Top-Level Fields

Roles and Users

Google Fields

OIDC and Entra Fields

Validation and Normalization

• The YAML decoder is strict and rejects unknown fields.
• The decoded snapshot is limited to 2 MiB.
• Duplicate role names, usernames, Google groups, or OIDC groups are rejected.
• Every user and mapping must reference an existing role.
• An initialized configuration must contain a local user assigned to an admin-mode role.
• Missing provider defaults and the default admin role are filled during successful normalization.
• After a successful startup import, BeaverDeck writes the normalized YAML back to the same Secret.