DEV Community: Aleksandr Sorokin

OIDC: Keycloak setup for ALB Gateway API

Aleksandr Sorokin — Sat, 22 Aug 2026 09:18:56 +0000

Introduction

In my previous article, I tested using ALB CRDs to offload JWT validation for OIDC-based authentication to the Amazon EKS Kubernetes API.

In this article, I will share the Terraform/OpenTofu stack required to set up Keycloak as the OIDC provider and explain how it works.

I am using the official Keycloak Terraform provider.
The provider documentation clearly explains how to connect Terraform/OpenTofu to a Keycloak instance.

For the testing setup, I used a service-account client configuration (Client Credentials grant in OAuth 2.0) and environment variables to configure the provider.

KEYCLOAK_URL='https://keycloak/auth/realms/demo-infra-project'
KEYCLOAK_REALM='demo-infra-project'
KEYCLOAK_BASE_PATH='/auth'
KEYCLOAK_CLIENT_ID='terraform'
KEYCLOAK_CLIENT_SECRET='secret'

This declaration is enough to make it work:

provider "keycloak" {

}

For GitHub Actions runners, I used a JWT-federated client. It deserves a dedicated article on how to set it up.

Client

A Keycloak client is the entry point your OIDC client uses to obtain authentication tokens.

kube-api-client.tf

  realm_id  = keycloak_realm.realm.id
  client_id = "${local.config.project.name}-kube-api"
  name      = "${local.config.project.name}-kube-api"

  enabled = true

  access_type = "CONFIDENTIAL"

  client_authenticator_type = "client-secret"

  standard_flow_enabled                     = true
  implicit_flow_enabled                     = false
  direct_access_grants_enabled              = false
  service_accounts_enabled                  = false
  standard_token_exchange_enabled           = false
  oauth2_jwt_authorization_grant_enabled    = false
  oauth2_device_authorization_grant_enabled = false

  full_scope_allowed = false

  valid_redirect_uris = [
    "http://localhost:8000",
    "http://localhost:18000",
    "https://oauth.pstmn.io/v1/callback",
    "https://oauth.pstmn.io/v1/browser-callback",
  ]

  web_origins = [
    "+",
  ]

Explanation

access_type = "CONFIDENTIAL"
client_authenticator_type = "client-secret"

Creates a non-public client with a client secret.

standard_flow_enabled                     = true

Enables the Authorization Code Grant flow.

full_scope_allowed = false

The token contains only the roles scoped for this client.

valid_redirect_uris = [
    "http://localhost:8000",
    "http://localhost:18000",
    "https://oauth.pstmn.io/v1/callback",
    "https://oauth.pstmn.io/v1/browser-callback",
]

These are the redirect URLs allowed for the standard flow.

    "http://localhost:8000",
    "http://localhost:18000",

For kubelogin.

    "https://oauth.pstmn.io/v1/callback",
    "https://oauth.pstmn.io/v1/browser-callback",

For Postman.

Client roles

Client roles are dedicated to this client.

kube-api-client-roles.tf

resource "keycloak_role" "kube_api_cluster_admin" {
  realm_id    = keycloak_realm.realm.id
  client_id   = keycloak_openid_client.kube_api.id
  name        = "admin"
  description = "cluster-admin role for kube-api"
}

This client-specific role will be included in the token's role claim if it is assigned to a user.

Groups

Groups in Keycloak manage role mappings for each user.

kube-groups.tf

resource "keycloak_group" "kube_admin" {
  realm_id = keycloak_realm.realm.id
  name     = "kube-admin"
}

resource "keycloak_group_roles" "kube_admin_group_roles" {
  realm_id = keycloak_realm.realm.id
  group_id = keycloak_group.kube_admin.id

  role_ids = [
    keycloak_role.kube_api_cluster_admin.id,
  ]
}

I'm mapping a client-specific role to a group.

Users

Managing users.

kube-users.tf

resource "keycloak_user" "kube_user" {
  realm_id       = keycloak_realm.realm.id
  for_each       = { for user in local.config.keycloak.users : user.username => user }
  username       = each.value.username
  email          = each.value.email
  email_verified = true

  lifecycle {
    ignore_changes = [
      first_name,
      last_name,
    ]
  }
}

kube-user-groups.tf assigns them to groups.

resource "keycloak_user_groups" "kube_admin_user_groups" {
  for_each = {
    for user in local.config.keycloak.users : user.username => user
    if contains(try(user.groups, []), keycloak_group.kube_admin.name)
  }
  realm_id   = keycloak_realm.realm.id
  user_id    = keycloak_user.kube_user[each.key].id
  exhaustive = false

  group_ids = [
    keycloak_group.kube_admin.id
  ]
}

Client scope

Shared client configuration is an entity called a client scope. In my example, it is simply a set of protocol mappers.

kube-api-client-scope.tf

resource "keycloak_openid_client_scope" "kube_api" {
  realm_id = keycloak_realm.realm.id
  name     = "kube-api"
}

Client scope mappers

OIDC token mappers for the kube-api client scope.

kube-api-client-scope-mapper.tf

Username mapper

resource "keycloak_openid_user_attribute_protocol_mapper" "kube_api_username" {
  realm_id        = keycloak_realm.realm.id
  client_scope_id = keycloak_openid_client_scope.kube_api.id
  name            = "username"

  user_attribute = "username"
  claim_name     = "username"

  add_to_access_token = true
  add_to_id_token     = true
}

add_to_access_token — adds this mapping to an access token

add_to_id_token — adds this mapping to an OIDC ID token

Role mapper — the most important one

resource "keycloak_openid_user_client_role_protocol_mapper" "kube_api_user_client_role_mapper" {
  realm_id        = keycloak_realm.realm.id
  client_scope_id = keycloak_openid_client_scope.kube_api.id
  name            = "kube-api-roles"

  claim_name       = "roles"
  claim_value_type = "String"
  multivalued      = true

  client_id_for_role_mappings = keycloak_openid_client.kube_api.client_id
  client_role_prefix          = "kube-"

  add_to_access_token = true
  add_to_id_token     = true
}

claim_name — claim name

client_id_for_role_mappings — client used for role mapping

client_role_prefix — prefix for the role value

As a result, the roles claim contains a flat, single-level list of assigned roles.

Audience mapper

Mapping the clientID to the audience claim enables additional token validation.

resource "keycloak_openid_audience_protocol_mapper" "audience_mapper" {
  realm_id        = keycloak_realm.realm.id
  client_scope_id = keycloak_openid_client_scope.kube_api.id
  name            = "audience-mapper-client-id"

  included_client_audience = keycloak_openid_client.kube_api.client_id
  add_to_access_token      = true
  add_to_id_token          = true
}

Role scope mapping

Role scope mapping limits the roles declared inside the client access token.

kube-api-client-scope-roles.tf

resource "keycloak_generic_role_mapper" "kube_api_cluster_admin" {
  realm_id        = keycloak_realm.realm.id
  client_scope_id = keycloak_openid_client_scope.kube_api.id
  role_id         = keycloak_role.kube_api_cluster_admin.id
}

Default and optional client scopes

Linking between a client scope and a client.

kube-api-client-scope.tf.

resource "keycloak_openid_client_default_scopes" "kube_api" {
  realm_id  = keycloak_realm.realm.id
  client_id = keycloak_openid_client.kube_api.id

  default_scopes = [
    data.keycloak_openid_client_scope.acr.name,
    data.keycloak_openid_client_scope.basic.name,
    data.keycloak_openid_client_scope.web_origins.name,
    keycloak_openid_client_scope.kube_api.name,
  ]
}

resource "keycloak_openid_client_optional_scopes" "kube_api" {
  realm_id  = keycloak_realm.realm.id
  client_id = keycloak_openid_client.kube_api.id

  optional_scopes = [

  ]
}

acr, basic, and web_origins are default pre-existing mappers.
This configuration keeps the token simple, clean, and not overly verbose.

Result

Now I can get a token with Postman to explore it.

{
  "exp": ...,
  "iat": ...,
  "auth_time": ...,
  "jti": "onrtac:4bb64894-da54-df2b-8879-7c4429366d81",
  "iss": "https://keycloak/auth/realms/demo-infra-project",
  "aud": "demo-infra-kube-api",
  "sub": "f321b181-dc87-47fc-97c4-9e9b579e8c1f",
  "typ": "Bearer",
  "azp": "demo-infra-kube-api",
  "sid": "5y5bl3zlY6tbLXHAWcT8s1Zf",
  "acr": "1",
  "allowed-origins": [
    "https://oauth.pstmn.io",
    "http://localhost:18000",
    "http://localhost:8000"
  ],
  "scope": "openid kube-api",
  "roles": [
    "kube-admin"
  ],
  "username": "kube-admin-1"
}

The important claims are:

iss — issuer
aud — target audience
roles — mapping for Kubernetes groups in RBAC
username — username for Kubernetes

What next

Now I can pass parameters from a provisioned client into a Kubernetes secret via the External Secrets Operator (ESO) and Flux CD variable substitution, and use them as parameters in ALB CRDs. I will cover this in my next article. Follow me!

OIDC: JWT validation with ALB controller and Gateway API

Aleksandr Sorokin — Thu, 06 Aug 2026 11:02:42 +0000

Introduction

AWS recently announced the general availability of Amazon Web Services (AWS) Load Balancer Controller support for Kubernetes Gateway API.

Furthermore, AWS added custom resource definitions (CRDs) to implement ELB listeners and target rules via a declarative approach.

Let's put these new possibilities into practice.

Since exposing a public endpoint to an EKS cluster is considered unsafe, I am going to add OIDC authorization to my EKS cluster and add JWT token validation with the ALB controller.

In this setup, I will place all security responsibilities for validation and authentication on the AWS side (at no extra cost) and only run Envoy to proxy the Kubernetes API at Layer 4.

ALB installation

Here are the full instructions, and here is my deployment via FluxCD.

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: eks
  namespace: kube-system
spec:
  url: https://aws.github.io/eks-charts
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: aws-load-balancer-controller
  namespace: kube-system
spec:
  chart:
    spec:
      chart: aws-load-balancer-controller
      version: "3.x"
      sourceRef:
        kind: HelmRepository
        name: eks
  interval: 30m
  releaseName: aws-load-balancer-controller
  values:
    replicaCount: 1
    serviceAccount:
      create: true
      name: aws-load-balancer-controller
    clusterName: demo-infra-eks-cluster
    defaultTargetType: ip
    defaultLoadBalancerScheme: internal
    ingressClassConfig:
      default: true

ALB controller AWS api access granted via pod identity.
Here is a terraform/tofu example to provision it.

Gateway class

Default Gateway settings. A full working example can be found here.

apiVersion: gateway.k8s.aws/v1
kind: TargetGroupConfiguration
metadata:
  name: tg-config-default
  namespace: kube-system
spec:
  defaultConfiguration:
    targetType: ip
---
# GatewayClass LBC references it
apiVersion: gateway.k8s.aws/v1
kind: LoadBalancerConfiguration
metadata:
  name: lb-internet-default
  namespace: kube-system
spec:
  mergingMode: prefer-gateway 
  scheme: internet-facing
  ipAddressType: dualstack
  defaultTargetGroupConfiguration:
    name: tg-config-default
---
# GatewayClass points to the LBC
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: default
spec:
  controllerName: gateway.k8s.aws/alb
  parametersRef:
    group: gateway.k8s.aws
    kind: LoadBalancerConfiguration
    name: lb-internet-default
    namespace: kube-system

Keycloak

I am going to use Keycloak as an OIDC identity provider. Cloud-IAM lets you have a managed Keycloak instance for 1 realm and 100 users for free. It is ideal for a testing playground.

Keycloak configuration is beyond the scope of this article for the sake of simplicity.
You can find a detailed explanation in this dedicated article.

EKS OIDC provider

Instructions from AWS can be found here.

Terraform/tofu example here.

resource "aws_eks_identity_provider_config" "eks_oidc_provider" {
  cluster_name = var.eks_cluster_name
  oidc {
    identity_provider_config_name = "demo-infra-keycloak"
    client_id                     = "demo-infra-kube-api"
    issuer_url                    = "https://<keycloak_url>/auth/realms/<keycloak_realm>"

    groups_claim  = "roles"
    groups_prefix = "oidc:"

    username_claim  = "username"
    username_prefix = "oidc-"
  }
}

Envoy

A full working example can be found here.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: envoy-kube-proxy
  labels:
    app: envoy-kube-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: envoy-kube-proxy
  template:
    metadata:
      labels:
        app: envoy-kube-proxy
    spec:
      containers:
      - name: envoy
        image: envoyproxy/envoy:v1.37-latest
        ports:
        - containerPort: 8443
          name: proxy
        - containerPort: 9901
          name: admin
        volumeMounts:
        - name: config-volume
          mountPath: /etc/envoy
      volumes:
      - name: config-volume
        configMap:
          name: envoy-kube-proxy-config
---
apiVersion: v1
kind: Service
metadata:
  name: envoy-kube-proxy
spec:
  selector:
    app: envoy-kube-proxy
  ports:
  - name: proxy
    port: 8443
    targetPort: 8443
  - name: admin
    port: 9901
    targetPort: 9901

envoy-kube-proxy-config

admin:
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901
  allow_paths:
    - exact: /ready
    - prefix: /stats
static_resources:
  listeners:
  - name: k8s_tls_passthrough_listener
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 8443
    filter_chains:
    - filters:
      - name: envoy.filters.network.tcp_proxy
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy"
          stat_prefix: k8s_passthrough_proxy
          cluster: kubernetes_api_passthrough_cluster
          idle_timeout: 0s
  clusters:
  - name: kubernetes_api_passthrough_cluster
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    # Envoy will not attempt to negotiate TLS; it forwards raw TCP data.
    load_assignment:
      cluster_name: kubernetes_api_passthrough_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: kubernetes.default.svc.cluster.local
                port_value: 443

Gateway

A fully working example can be found here.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: envoy-kube-proxy-gateway
spec:
  gatewayClassName: default
  listeners:
    - name: https
      protocol: HTTPS
      port: 8443
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: envoy-kube-proxy-httproute
  labels:
    app: envoy-kube-proxy
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: envoy-kube-proxy-gateway
      sectionName: https
  hostnames:
    - "envoy-kube-proxy.example.com"
  rules:
    - backendRefs:
        - name: envoy-kube-proxy
          port: 8443
      filters:
        - extensionRef:
            group: gateway.k8s.aws
            kind: ListenerRuleConfiguration
            name: envoy-kube-proxy-jwt-validation
          type: ExtensionRef

TargetGroupConfiguration.

TargetGroupConfiguration is needed to set up the backend as an HTTPS target rather than an HTTP target.

apiVersion: gateway.k8s.aws/v1
kind: TargetGroupConfiguration
metadata:
  name: envoy-kube-proxy-tgc
spec:
  targetReference:
    name: envoy-kube-proxy
  defaultConfiguration:
    protocol: HTTPS
    healthCheckConfig:
      healthCheckPath: /ready
      healthCheckPort: '9901'
      healthCheckProtocol: HTTP

ListenerRuleConfiguration

apiVersion: gateway.k8s.aws/v1
kind: ListenerRuleConfiguration
metadata:
  name: envoy-kube-proxy-jwt-validation
spec:
  actions:
    - type: "jwt-validation"
      jwtValidationConfig:
        jwksEndpoint: "https://<keycloak_url>/auth/realms/<keycloak_realm>/protocol/openid-connect/certs"
        issuer: "https://<keycloak_url>/auth/realms/<keycloak_realm>"
        additionalClaims:
          - name: "aud"
            format: "single-string"
            values: ["demo-infra-kube-api"]

Validation

An OIDC token can be obtained with Postman.

Set up the request in Postman.
Auth Type --> OAuth2
Auth URL --> from the Keycloak .well-known/openid-configuration
Access Token URL --> from the Keycloak .well-known/openid-configuration
Client ID --> from the client configuration
Client Secret --> from the client configuration

and click on "Get new access token"

Adding Postman's callback URL to the client "Valid redirect URIs" should not be forgotten.

This token can be used with kubectl like this.

kubectl auth whoami --token <oidc_token>

If everything were set correctly, kubectl returns the username and group with OIDC prefixes similar to this,

Username                                            oidc-keyuser1
Groups                                              [oidc:kube-admin system:authenticated]

and the ALB endpoint should not return a 401 response code.

Conclusion

Kubelogin plugin can be used now to provide OIDC access tokens for kubectl.

Moreover, it is now possible to authenticate a GitHub Actions token using Keycloak as an identity broker middleware with no static credentials.

And I have an interesting idea to implement SSO and JWT authentication on the ALB next time. Follow me!

Feel free to leave a comment with your feedback.