OAuth2 Proxy

OAuth2 Proxy is a lightweight, open-source authentication gateway that secures web applications using OAuth2 or OpenID Connect (OIDC). It acts as either a standalone reverse proxy or as middleware that integrates with existing reverse proxies or load balancers, making it highly adaptable to a variety of infrastructure setups.

When deployed, OAuth2 Proxy intercepts incoming requests and redirects unauthenticated users to a configured OAuth2/OIDC identity provider—such as Keycloak, Google, GitHub, Microsoft Entra ID, or login.gov—for secure login. After successful authentication, it injects user identity information (like email, groups, or usernames) as HTTP headers, which are then forwarded to the protected application.

This capability makes OAuth2 Proxy ideal for enforcing authentication in Kubernetes environments, especially when working with UIs that lack built-in support for auth—like Hubble UI. In our setup, we used OAuth2 Proxy in combination with Keycloak to secure Hubble UI and restrict access only to users belonging to a specific Keycloak group.

📌 Purpose

In modern Kubernetes environments, observability tools like Hubble UI offer critical insight into network flows and service communication. But without access control, Hubble UI remains open to any user within the cluster or exposed ingress — which is a security risk.

To address this, we’ve successfully implemented Single Sign-On (SSO) for Hubble UI using:

• 🛡 OAuth2 Proxy as an authentication gateway

• 🔑 Keycloak as the Identity Provider (IdP)

Only users who belong to a specific Keycloak group (/hubbleui) are authorised to access the Hubble dashboard.

🏗️ Architecture Overview

[ User ]
   ↓
[ OAuth2 Proxy ]
   ↔ Keycloak (OIDC)
   ↓
[ Hubble UI ]

• OAuth2 Proxy protects the Hubble UI by enforcing authentication

• Keycloak manages login, group membership, and token issuance

• Only members of /hubbleui group can access the dashboard

🛠️ Step 1: Set Up Keycloak as IdP

🔧 Create an OAuth Client for Hubble UI

1. In Keycloak Admin Console:

   • Go to Clients > Create

2. Configure:

   • Client ID: hubbleui-oauth

   • Client Protocol: openid-connect

   • Access Type: confidential

   • Root URL: https://<your-hubble-ui-domain>

   • Valid Redirect URIs:
     https://<your-hubble-ui-domain>/oauth2/callback

   • Save

🧩 Add Group Mapper to Include Groups in Tokens

1. In the OAuth Client:

   • Go to the Mappers tab

   • Click Create Mapper

👥 Create a Group /hubbleui and Assign Users

1. Navigate to Groups in Keycloak

2. Create /hubbleui

3. Add authorized users to this group

📦 Step 2: Configure OAuth2 Proxy

We deployed OAuth2 Proxy using Helm, with a custom values.yaml that connects it to Keycloak and protects Hubble UI.

📄 values.yaml

oauth2-proxy:
  config:
    clientID: "hubbleui"
    clientSecret: "xxxxxxxxxxxxxxxxxxxxxxx"
    cookieSecret: "xxxxxxxxxxxxxxxxxxxxxxx"
    configFile: |-
      email_domains = [ "*" ]
      upstreams = [ "http://hubble-ui.kube-system.svc.cluster.local:80" ]
      provider = "oidc"
      oidc_issuer_url = "https://<keycloak-domain>/realms/master"
      redirect_url = "https://<oath2-proxy-ingress-domain-or-hubbleui-domain>/oauth2/callback"
      insecure_oidc_allow_unverified_email = true
      allowed_groups = [ "/hubbleui" ]
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: "alb"
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/target-type: ip
      alb.ingress.kubernetes.io/certificate-arn: xxxxxxxxxx
      alb.ingress.kubernetes.io/healthcheck-path: "/ping"
      alb.ingress.kubernetes.io/backend-protocol: HTTP
      alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
      alb.ingress.kubernetes.io/ssl-redirect: "443"
    hosts:
      - <oath2-proxy-ingress-domain-or-hubbleui-domain>
    path: /
    pathType: Prefix

🚀 Step 3: Deploy OAuth2 Proxy with Helm

From your infrastructure repo:

helm dep build
helm install oauth2-proxy . -n kube-system

This deploys the proxy with ingress, secured behind ALB and integrated with Keycloak.

✅ Step 4: Test & Verify

• Visit: https://<oath2-proxy-ingress-domain-or-hubbleui-domain>

• You’ll be redirected to Keycloak Login

• Log in using a user assigned to /hubbleui

• You’ll be redirected to Hubble UI

• Unauthorised users will receive a 403 Forbidden

🎯 Final Thoughts

This integration:

• 🎯 Adds secure SSO to a previously open UI

• 🔐 Ensures only authorized users can access observability data

• 🧱 Leverages standard tools (Keycloak + OAuth2 Proxy)

• 📦 Is easily portable to other UIs like Grafana, ArgoCD, etc.