Skip to content

Headlamp OIDC integration

This package can use the Big Bang SSO integration to configure Headlamp OIDC. The umbrella package controls the sso settings, including whether OIDC is enabled and the client credentials. When SSO is enabled, the umbrella provides the Headlamp client ID and issuer URL to the package, enables PKCE, and creates the package secret when credentials are supplied. Secret creation alone does not prove that the upstream Headlamp Deployment consumes those credentials; review its rendered references when using a confidential client.

Configure Headlamp under packages.headlamp with packageConfiguration.version: v1, or use the legacy addons.headlamp path for an existing Big Bang 3.x configuration. The sso settings are part of the umbrella package configuration; do not place credentials in this repository or in a committed values file.

Big Bang configuration example

This umbrella example assumes an existing mesh/gateway, a registered public OIDC client using authorization-code flow with PKCE, and an API server already configured for the issuer and audience. Replace the example URLs and client ID before use. No client secret belongs in this example:

packageConfiguration:
  version: v1
sso:
  url: https://sso.example.com/realms/platform
packages:
  headlamp:
    enabled: true
    sso:
      enabled: true
      client_id: headlamp
    values:
      upstream:
        clusterRoleBinding:
          create: false
        config:
          oidc:
            scopes: "email,profile,groups"
            callbackURL: https://headlamp.example.com/oidc-callback
      bigbang:
        rbac:
          enabled: true
          clusterRoles:
            - name: headlamp-readonly
              create: true
              rules:
                - apiGroups: [""]
                  resources: ["pods", "services", "namespaces"]
                  verbs: ["get", "list", "watch"]
          clusterRoleBindings:
            - name: headlamp-readonly-users
              roleRef: headlamp-readonly
              subjects:
                - kind: Group
                  name: oidc:headlamp-readers
                  apiGroup: rbac.authorization.k8s.io

The umbrella supplies upstream.config.oidc.clientID, issuerURL, and usePKCE. The example overrides scopes to request a provider-defined groups scope; configure its mapper to include group membership in the ID token. Headlamp requests openid itself. Register the exact callback URI in the IdP and align it with the actual external route, including any base path. This example assumes the API server adds group prefix oidc: to a claim containing headlamp-readers; use the actual mapped subject, including full group paths when the IdP emits them. The role is deliberately small: other UI views may remain forbidden. Do not add blanket permissions to make every view work.

Disable the upstream chart’s default service-account cluster-admin binding explicitly as shown; enabling bigbang.rbac does not disable it. Review any existing bindings for that service account too. Legacy umbrella configuration uses addons.headlamp; direct chart values omit the umbrella nesting and must configure OIDC and network access themselves.

For a confidential client, provision credentials through the approved secret workflow and explicitly wire them to the bundled chart. Its upstream.config.oidc.externalSecret interface expects OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_ISSUER_URL keys (plus OIDC_SCOPES when hasScopes: true); disable chart-generated OIDC Secret creation when using it. The umbrella’s separate headlamp Secret uses key oidc-secret, not this external-Secret schema. Do not assume those interfaces are interchangeable or print Secret values to troubleshoot them. See the versioned upstream values and the verified umbrella mapping and client-Secret template.

Authorization boundary

OIDC login identifies a user to Headlamp. Kubernetes authorization is evaluated separately by the Kubernetes API server. For group-based access, the API server must be configured to accept the issuer’s tokens and map the selected username and group claims. The subject names in bigbang.rbac.clusterRoleBindings must match the names the API server evaluates, including any configured prefixes or group paths.

The Headlamp chart does not configure the API server or the identity provider. Use your platform’s documented OIDC configuration and the identity provider’s documentation to create the client, allowed redirect URI, and claim mappings. For Headlamp-specific setup, use the version-appropriate upstream OIDC documentation.

Network and CA considerations

With Big Bang network policies enabled, the umbrella enables outbound access to the configured SSO host when Headlamp SSO is enabled. Ensure that the issuer is reachable from the workload and from users’ browsers through the applicable network and mesh configuration.

OIDC Custom CA

For a private-CA issuer, provision a Secret in the Headlamp namespace containing the trusted PEM CA bundle at key ca.pem, using the approved GitOps secret workflow. The example references tls-ca-sso, the umbrella’s default SSO CA Secret name. Set the global sso.certificateAuthority.secretName consistently if using another name. Creating the Secret alone does not mount it in Headlamp.

Apply this additional umbrella values overlay alongside the SSO example:

packages:
  headlamp:
    values:
      upstream:
        volumes:
          - name: oidc-ca
            secret:
              secretName: tls-ca-sso
              items:
                - key: ca.pem
                  path: ca.pem
        volumeMounts:
          - name: oidc-ca
            mountPath: /etc/headlamp/oidc-ca
            readOnly: true
        config:
          extraArgs:
            - "-oidc-ca-file=/etc/headlamp/oidc-ca/ca.pem"

These are the bundled 0.45.0 chart’s volumes and volumeMounts keys, not the unsupported extraVolumes/extraVolumeMounts from the old example. The Headlamp 0.45.0 configuration source defines oidc-ca-file. These arrays replace existing entries: preserve any other required mounts, volumes, and extra arguments. Legacy umbrella values use addons.headlamp.values.

Render and inspect the Deployment’s Secret name, key, mount, and argument before applying. After CA rotation, arrange a controlled Deployment restart through the approved deployment process so the application reloads trust, then retest login. Browser trust and API-server trust in the issuer are separate requirements; this mount configures Headlamp’s OIDC trust only. Do not use TLS-verification bypasses to resolve certificate errors.

Troubleshooting

User authenticates but sees no resources

  1. Inspect the failed Kubernetes request’s status in the browser without sharing cookies or tokens. 401 points to authentication: check issuer, audience, expiration, API-server OIDC configuration, and API-server issuer trust. 403 points to authorization: check the requested verb, resource, namespace, and matching bindings. Connection or TLS errors need network/trust investigation.
  2. Confirm the selected Headlamp cluster/context and namespace. A successful IdP redirect does not establish Kubernetes API authorization for that cluster.
  3. Using approved local tooling, inspect the relevant ID-token claims without pasting a token into an online decoder, ticket, or log. Compare username and groups with the API server’s claim mappings and prefixes. A groups claim only in the access token will not satisfy the default ID-token flow.
  4. Verify the group scope/mapper and membership in Keycloak. Check whether it emits a short group name or a full path such as /platform/headlamp-readers. Reauthenticate after changes so the session uses new claims.
  5. Follow the RBAC authorization checks for the exact mapped user and groups. If they succeed but the UI request fails, compare its actual resource, verb, namespace, and identity; do not grant cluster-admin or enable shared service-account authentication as a shortcut.

For redirect/token-exchange failures, verify the registered callback and PKCE client settings, then inspect Headlamp’s application logs for provider discovery, TLS, and token-exchange errors. Review the selected pod’s containers before requesting logs; redact tokens and request metadata. Check workload and browser issuer reachability separately, and verify confidential-client Secret references without displaying their data.

Validation

Test the complete redirect, return, and Kubernetes API authorization flow in a disposable environment using the intended user and group claims. A Helm render cannot confirm client registration, certificate trust, browser redirect reachability, or effective Kubernetes RBAC.

See Headlamp RBAC for package-managed role and binding guidance.