Skip to main content

AKS Cluster Setup with Azure Entra Login and RBAC Using OAuth2Proxy

This guide walks you through configuring Headlamp in an AKS cluster using OAuth2Proxy for authentication via Azure Entra ID (Microsoft Entra ID) and RBAC.

We'll cover:

  1. Setting up AKS with OIDC
  2. Creating an Azure App Registration
  3. Deploying Headlamp via Helm
  4. Setting up OAuth2Proxy

Step 1: Set Up AKS Cluster with OIDC Enabled

  1. Go to Kubernetes Services in the Azure portal and click Create Cluster.

Create AKS Cluster Step 1

  1. In the Authentication and Authorization step:
    • Select Microsoft Entra ID authentication.
    • Enable Kubernetes RBAC.

Create AKS Cluster Step 2

  1. Under Cluster Admin ClusterRoleBinding, choose an Entra group that should have cluster-admin privileges.

Create AKS Cluster Step 3

  1. Continue with your preferred settings for the agent pool, networking, etc., and create the cluster.

Make sure to enable OIDC Issuer while creating the cluster.


Step 2: Create an Azure App Registration

  1. In the Azure portal, navigate to Microsoft Entra ID > App registrations.

App Registration Step 1

  1. Click + New registration.

  2. Provide:

    • Name of your choice.
    • Supported account type (usually Accounts in this organizational directory only).
    • Redirect URI: For local testing, you can use:
      http://localhost:8000/oidc-callback

App Configuration

  1. Click Register.

  2. Record the Application (client) ID and Directory (tenant) ID.

App Configuration Client


Step 3: Configure API Permissions for OAuth2Proxy

  1. Go to API permissionsAdd a permission.
  2. Choose Microsoft GraphDelegated permissions.
  3. Add: openid, profile, email.
  4. Click Grant admin consent.

Step 4: Create a Client Secret for OAuth2Proxy

  1. Go to Certificates & secretsNew client secret.
  2. Add and copy the value.

Step 5: Deploy Headlamp to AKS

Prerequisites:

  • Install Helm
  • Download kubeconfig for the AKS cluster

Add Headlamp Helm repo:

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update

Create a values.yaml for any customizations (optional) and deploy:

helm install my-headlamp headlamp/headlamp --namespace kube-system

Verify Headlamp is running:

kubectl get pods -n kube-system

Port-forward to access the UI:

kubectl port-forward svc/my-headlamp 8000:80 -n kube-system

Headlamp should now show an Authentication screen.

Headlamp Authentication Screen


Step 6: Deploy OAuth2Proxy via Helm

Add the Helm repo:

helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
helm repo update

Prepare your values.yaml

Below is an example configuration you can start with. Be sure to replace placeholders like <Client-ID>, <Client-Secret>, <Tenant-ID>, etc.

config:
configFile: |-
email_domains = ["*"]
cookie_secret = <Cookie-Secret>

alphaConfig:
enabled: true
configFile: |-
injectRequestHeaders:
- name: Authorization
values:
- claim: access_token
prefix: 'Bearer '
providers:
- clientID: <Client-ID>
clientSecret: <Client-Secret>
id: entra
oidcConfig:
issuerURL: https://login.microsoftonline.com/<Tenant-ID>/v2.0
audienceClaims:
- aud
emailClaim: email
insecureAllowUnverifiedEmail: true
provider: oidc
scope: 6dae42f8-4368-4678-94ff-3960e28e3630/user.read openid email profile User.Read
upstreamConfig:
upstreams:
- id: main
path: /
uri: http://<your-headlamp-service-name>.<your-headlamp-namespace>.svc.cluster.local

Deploy OAuth2Proxy:

helm install my-release oauth2-proxy/oauth2-proxy -f values.yaml

Verify it's up:

kubectl get pods

Step 7: Set Kubernetes RBAC Policies Based on Azure Entra Groups

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: read-only-binding
subjects:
- kind: Group
apiGroup: rbac.authorization.k8s.io
name: "<AzureEntraGroupObjectID>"
roleRef:
kind: ClusterRole
name: view
apiGroup: rbac.authorization.k8s.io

Apply:

kubectl apply -f your-rbac-binding.yaml

Step 8: Login Flow

  • Navigate to the port-forwarded Headlamp UI.
  • Click Sign in.
  • Follow the Entra login prompt.

Login Page

Note: In a development environment, OAuth2Proxy may try to redirect to https:// by default. For local testing, ensure your redirect URI and settings use http://.

Once authenticated, you'll be redirected back to Headlamp and should have access to your cluster UI.


Step 9: Test Authentication Flow

  • Access your protected endpoint.
  • Login via Entra.
  • Validate RBAC access.