Accessing using OpenID Connect

    Headlamp supports OIDC for cluster users to effortlessly log in using a “Sign in” button.

    screenshot the login dialog for a cluster

    For OIDC to be used, Headlamp needs to know how to configure it, so you have to provide the different OIDC-related arguments to Headlamp from your OIDC provider. Those are:

    • the client ID: -oidc-client-id
    • the client secret: -oidc-client-secret
    • the issuer URL: -oidc-idp-issuer-url
    • (optionally) the OpenId scopes: -oidc-scopes

    and you have to tell the OIDC provider about the callback URL, which in Headlamp it is your URL + the /oidc-callback path, e.g.: https://YOUR_URL/oidc-callback.


    Besides the mandatory openid scope, Headlamp also requests the optional profile and email scopes . Scopes can be overridden by using the -oidc-scopes option. Remember to include the default ones if you need them when using that option. For example, if you need to keep the default scopes and add Github’s repo, then add them all to the option:


    Note: Before Headlamp 0.3.0, a scope groups was also included, as it’s used by Dex and other services, but since it’s not part of the default spec, it was removed in the mentioned version.

    Example: OIDC with Dex

    If you are using Dex and want to configure Headlamp to use it for OIDC, then you have to:

    • Add the callback URL (e.g. https://YOUR_URL/oidc-callback) to Dex’s staticClient.redirectURIs
    • Set -oidc-client-id as Dex’s
    • Set -oidc-client-secret as Dex’s staticClient.secret
    • Set -oidc-idp-issuer-url as Dex’s URL (same as in --oidc-issuer-url in the Kubernetes APIServer)
    • Set -oidc-scopes if needed, e.g. -oidc-scopes=profile,email,groups