Azure AKS, Entra OIDC and Headlamp (In-Cluster)

Azure AKS has alot of functionality that can simplify identification with its built in (but not enabled by default) Entra integrations. This includes federated workload identity scenarios, where federation to a secretless identity allow easy and secure connection to Azure resources.

But it also allow more administrative focused ones where Entra Id and Entra RBAC are used to authorize access to the Kubernetes API of the AKS Mangement plane.

This allow kubectl, or other Kubernetes API based tools, authenticating and authorization using Azure Entra RBAC and Entra login with MFA.

Headlamp

Headlamp is a great Kubernetes Dashboard alternative. It can be deployed as a desktop tool.

But more interestingly Headlamp can be deployed ‘In-cluster’ as a web application exposed via ingress. To get this scenario to work I had to do some configuration which is the base for this post.

AKS Authentication and Authorization

In this scenario our cluster will use ‘Microsoft Entra ID for authentication and Azure RBAC’ for authentication and authorization (--enable-aad and --enable-azure-rbac).

OIDC

Headlamp, unlike Kubernetes Dashboard, actually do have OIDC (OpenID Connect) support built in. At first that sounds great but currently it does not work with Entra Id.

The root cause is that Headlamp after identification will place the users OIDC id-token, and not the access-token, in the Authorization header which then is passed along to the Kubernetes API. The id-token simply does not contain information on what roles you have as the purpose of the id-token is not related to authorization.

Solution

Lets use the popular identity proxy OAuth2Proxy that can protect workloads lacking OIDC/OAuth support. But we can use it here also for its capability to explicitly use the Entra access-token and not the id-token.

Entra Id

1. Add a client-secret (or preferably an identity federation to a workload identity which is supported in OAuth2Proxy)

2. Add redirect URL as https://{your-ingress-domain-for-headlamp}/oauth2/callback

3. Give your Entra Application Registration representing the Headlamp Web application, delegated API Permissions to Azure Kubernetes Services AAD Server. This built in application will allow us to request an token in the scope of Azure AKS. Note the ‘id’, this is a built-in application id that we will need later configuring OAuth2Proxy.

Do not forget to Grant Admin Consent for your tenant

Headlamp

No special configuration needed

OAuth2Proxy

There are two main areas that needed attention.

1. Request your access tokens with the scope ‘Azure Kubernetes Service AAD Server’. Use scope 6dae42f8-4368-4678-94ff-3960e28e3630/user.read for this.
2. Specifically inject the access_token in the Authorization header. To do this you must use the new shiny OAuth2Proxy configuration called Alpha Configuration.

Example config map

Configure OAuth2Proxy with values from my example with a ConfigMap below.

Use Helm directly with a values file or go for GitOps using Flux HelmRelease where you inject ConfigMap and secret.

Also inject your ClientSecret in alphaConfig.configData.providers[0].clientSecret. Or even better - go secretless with its support for FederatedTokenAuth/Workload Identities.

apiVersion: v1
kind: ConfigMap
metadata:
  name: oauth2proxy-headlamp-configmap
data:
  values.yaml: |
    config:
      configFile: |-
        email_domains = [ "*" ]
    extraArgs:
      reverse-proxy: true
      skip-provider-button: true 
      silence-ping-logging: true
      cookie-refresh: "15m"
      cookie-expire: "12h"
    alphaConfig:
      enabled: true
      configData:
        providers:
        - id: entra
          provider: oidc
          clientID: "..."
          #clientSecret: "not-here-its-better-to-use-federatedTokenAuth"
          scope: "6dae42f8-4368-4678-94ff-3960e28e3630/user.read openid email profile User.Read"
          oidcConfig:
            issuerURL: "https://login.microsoftonline.com/..your-tenant.../v2.0"
            insecureAllowUnverifiedEmail: true
            emailClaim: email
            audienceClaims:
            - aud
        injectRequestHeaders:
        - name: Authorization
          values:
          - claim: access_token
            prefix: "Bearer "
        upstreamConfig:
          upstreams:
            - id: main
              path: /
              uri: http://headlamp:80

Now when the ingress hit OAuth2Proxy it will redirect to Entra and make sure the correct header is proxied to Headlamp and Entra RBAC roles will dictate my access.