DEV Community: Aleksandr Sorokin

OIDC: Keycloak JWT Federation

Aleksandr Sorokin — Thu, 15 Oct 2026 11:11:44 +0000

Introduction

In my previous posts, I mentioned the important topic of zero static credentials. This is especially relevant today, as interactions with AI agents in protected environments can unexpectedly expose credentials.

In this part, I explain how to authenticate GitHub Actions jobs so they can provision Keycloak without static credentials. A dirty trick is involved, and I explain it below.

In the same way, I can access resource servers from GitHub Actions workflows by using Keycloak as an identity broker.

GitHub OIDC Provider

GitHub provides a GitHub Actions OIDC provider, so our repository, refs, pull requests, and even environments can act as identities for resource servers that accept OIDC tokens.

The token format and the sub claim are covered in my previous post.

For AWS authentication, I used an official action that helps retrieve a token from the GitHub OIDC provider. Keycloak does not currently have an official action, so I had to use custom steps to obtain the token.

action.yml

name: Keycloak Token Action
description: 'Action to obtain a Keycloak token'
inputs:
  keycloak-url:
    description: 'The URL of the Keycloak server'
    required: true
  keycloak-realm:
    description: 'The Keycloak realm'
    required: true
  keycloak-base-path:
    description: 'The base path for Keycloak (optional)'
    required: false
runs:
  using: "composite"
  steps:
    - name: Get JWT token
      id: get-gh-token
      env:
        KEYCLOAK_AUDIENCE: "${{ inputs.keycloak-url }}${{ inputs.keycloak-base-path || '' }}/realms/${{ inputs.keycloak-realm }}"
      uses: actions/github-script@v9
      with:
        script: |
          const audience = process.env['KEYCLOAK_AUDIENCE'];
          let ghToken = await core.getIDToken(audience);
          core.setOutput('ghToken', ghToken);

          function decodeJWT(jwtToken) {
            try {
              // A JWT has 3 parts: Header, Payload, Signature
              const [header, payload, signature] = jwtToken.split('.');

              // Decode base64url string to standard UTF-8 text
              const decodedPayload = Buffer.from(payload, 'base64').toString('utf8');

              // Parse the string into a readable JavaScript object
              return JSON.parse(decodedPayload);
            } catch (error) {
              console.error("Invalid JWT format", error);
              return null;
            }
          }

          console.log('----');
          console.log(decodeJWT(ghToken));
          console.log('----');

This composite action uses actions/github-script and the core.getIDToken(audience) function with a custom audience value. Keycloak expects the aud claim to match the issuer_url of the Keycloak realm endpoint.

The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.

Example of a decoded GitHub token from the test workflow:

{
  actor: 'AleksandrSor',
  actor_id: '...',
  aud: 'https://<KEYCLOAK_URL>/auth/realms/demo-infra-project',
  ...
  environment: 'test-keycloak',
  ...
  iss: 'https://token.actions.githubusercontent.com',
  ...
  sub: 'repo:AleksandrSor/demo-infra:environment:test-keycloak',
  ...
}

More information about a custom way of obtaining a GitHub OIDC token can be found here.

Now I need to exchange my GitHub token for a Keycloak token with the correct permissions to manage my Keycloak instance. Before I can do that, I need to register the GitHub OIDC provider in Keycloak.

Keycloak JWT Federation

I want to eliminate the need to store static credentials, and Keycloak JWT federation helps me achieve that.

The first step in setting up federated client authentication is to define a trust relationship between Keycloak and the external identity providers. This is done by creating a new identity provider in the realm.

Keycloak currently supports three identity provider types for federated client authentication:

OpenID Connect
SPIFFE
Kubernetes

More information is available in this blog post.

Since the GitHub OIDC provider does not expose a client authentication endpoint, it cannot be registered properly as an OpenID Connect provider. It also cannot be used as a SPIFFE provider.

This is where the dirty trick comes in. I register the GitHub OIDC provider as Kubernetes. This works because Keycloak expects an OIDC discovery endpoint at <ISSUER URL>/.well-known/openid-configuration, and GitHub exposes it there: https://token.actions.githubusercontent.com/.well-known/openid-configuration.

Register Identity Provider

github-actions.tf

locals {
  github_actions_issuer = "https://token.actions.githubusercontent.com"
}

resource "keycloak_kubernetes_identity_provider" "github_actions" {
  alias  = "github-actions"
  realm  = keycloak_realm.realm.id
  issuer = local.github_actions_issuer

  lifecycle {
    prevent_destroy = true
  }
}

Create a client for GitHub OIDC

This client uses the Service Account Roles authentication flow with
JWT Federated Client Authentication.
github-actions.tf

resource "keycloak_openid_client" "github_actions" {
  realm_id                     = keycloak_realm.realm.id
  client_id                    = "repo:${local.config.env.repository.name}:environment:${local.config.env.repository.protected_environment}"
  name                         = "github-actions-${replace(local.config.env.repository.name, "/[^a-zA-Z0-9]/", "-")}-env-${local.config.env.repository.protected_environment}"
  enabled                      = true
  access_type                  = "CONFIDENTIAL"
  standard_flow_enabled        = false
  direct_access_grants_enabled = false
  service_accounts_enabled     = true
  client_authenticator_type    = "federated-jwt"

  extra_config = {
    "jwt.credential.issuer" = keycloak_kubernetes_identity_provider.github_actions.alias
    "jwt.credential.sub"    = "repo:${local.config.env.repository.name}:environment:${local.config.env.repository.protected_environment}"
  }

  description = jsonencode(local.config.common_tags)

}

Next, assign roles to the service account used by the GitHub Actions workflow.
github-actions.tf

resource "keycloak_openid_client_service_account_role" "github_actions_service_account_role_realm_admin" {
  realm_id                = keycloak_realm.realm.id
  service_account_user_id = keycloak_openid_client.github_actions.service_account_user_id
  client_id               = data.keycloak_openid_client.realm_management.id
  role                    = data.keycloak_role.realm-admin.name
}

resource "keycloak_openid_client_service_account_role" "github_actions_service_account_role_query_realms" {
  realm_id                = keycloak_realm.realm.id
  service_account_user_id = keycloak_openid_client.github_actions.service_account_user_id
  client_id               = data.keycloak_openid_client.realm_management.id
  role                    = data.keycloak_role.query-realms.name
}

realm-management.tf

data "keycloak_openid_client" "realm_management" {
  realm_id  = keycloak_realm.realm.id
  client_id = "realm-management"
}

data "keycloak_role" "realm-admin" {
  realm_id  = keycloak_realm.realm.id
  client_id = data.keycloak_openid_client.realm_management.id
  name      = "realm-admin"
}

data "keycloak_role" "query-realms" {
  realm_id  = keycloak_realm.realm.id
  client_id = data.keycloak_openid_client.realm_management.id
  name      = "query-realms"
}

Token Exchange

Now I can exchange my GitHub token for a Keycloak token.

action.yml

inputs:
  ...
  keycloak-client-id:
    description: 'The Keycloak client ID for token retrieval'
    required: true
  ...
runs:
  using: "composite"
  steps:
  ...
    - name: Get KC token
      id: get-kc-token
      shell: bash
      run: |
        KEYCLOAK_RESPONSE=$(curl -s "${{ inputs.keycloak-url }}${{ inputs.keycloak-base-path || '' }}/realms/${{ inputs.keycloak-realm }}/protocol/openid-connect/token" \
          -H 'Content-Type: application/x-www-form-urlencoded' \
          -d 'grant_type=client_credentials' \
          -d 'scope=openid' \
          -d 'client_id=${{ inputs.keycloak-client-id }}' \
          -d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
          -d 'client_assertion=${{ steps.get-gh-token.outputs.ghToken }}' | jq -r '.')
        KEYCLOAK_TOKEN=$(echo $KEYCLOAK_RESPONSE | jq -r '.access_token')
        echo "keycloakAccessToken=${KEYCLOAK_TOKEN}" >> $GITHUB_OUTPUT
        echo "keycloakIdToken=${KEYCLOAK_TOKEN}" >> $GITHUB_OUTPUT
        echo "----"
        echo "KC Response:"
        echo "${KEYCLOAK_RESPONSE}"
        echo "----"
        echo "Decoded KC Token:"
        echo "${KEYCLOAK_TOKEN}" | jq -R 'split(".") | .[0],.[1] | @base64d | fromjson'
        echo "----"

The most important parts of the request are:

grant_type=client_credentials: specifies the authentication flow type.
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer: specifies the assertion type used for client authentication.
client_assertion=${{ steps.get-gh-token.outputs.ghToken }}: passes the GitHub token as the client assertion.
client_id=${{ inputs.keycloak-client-id }}: the client ID of the Keycloak client resource created in IaC (keycloak_openid_client.github_actions).

Documentation is available here.

Example of a decoded Keycloak token from the test workflow:

{
    ...
    "iss": "https://<KEYCLOAK_URL>/auth/realms/demo-infra-project",
    "aud": [
      "realm-management",
      "account"
    ],
    "sub": "2a428d3a-4359-49f4-abcd-607fdb23aa8f",
    ...
    "azp": "repo:AleksandrSor/demo-infra:environment:test-keycloak",
    "resource_access": {
      "realm-management": {
        "roles": [
          "view-realm",
          "query-realms"
        ]
      },
      "account": {
        "roles": [
          "manage-account",
          "manage-account-links",
          "view-profile"
        ]
      }
    },
    ...
    "client_id": "repo:AleksandrSor/demo-infra:environment:test-keycloak"
  }

Testing the Keycloak token

To run a quick test, we can execute the following job against our Keycloak instance:

name: test JWT
on:
  push:
    branches:
      - test/test-jwt

permissions:
  contents: read  
  id-token: write # # Required to request a GitHub OIDC token for Keycloak authentication

jobs:
  test-jwt:
    runs-on: ubuntu-24.04-arm
    environment: 
      name: test-keycloak
      deployment: false
    env:
      DEPLOY_ENV: test-keycloak
      KEYCLOAK_URL: ${{ vars.KEYCLOAK_URL }}
      KEYCLOAK_REALM: ${{ vars.KEYCLOAK_REALM }}
      KEYCLOAK_AUDIENCE: "${{ vars.KEYCLOAK_URL }}${{ vars.KEYCLOAK_BASE_PATH || '' }}/realms/${{ vars.KEYCLOAK_REALM }}"
      KEYCLOAK_BASE_PATH: ${{ vars.KEYCLOAK_BASE_PATH || '' }} # legacy path /auth
    steps:
      - uses: actions/checkout@v4
      - id: keycloak-token
        name: Get KC token
        uses: .https://github.com/AleksandrSor/demo-infra/blob/main/.github/actions/keycloak-token
        with:
          keycloak-url: ${{ env.KEYCLOAK_URL }}
          keycloak-realm: ${{ env.KEYCLOAK_REALM }}
          keycloak-client-id: repo:${{ github.repository }}:environment:${{ env.DEPLOY_ENV }}
          keycloak-base-path: ${{ env.KEYCLOAK_BASE_PATH || ''}}
      - name: Test KC token
        run: |
          KEYCLOAK_RESPONSE=$(curl -s "${KEYCLOAK_URL}${KEYCLOAK_BASE_PATH}/realms/$KEYCLOAK_REALM/protocol/openid-connect/userinfo" \
            -H "Authorization: Bearer ${{ steps.keycloak-token.outputs.id-token }}" | jq -r '.')
          echo "----"
          echo "${KEYCLOAK_RESPONSE}"
          echo "----"
      - name: Admin Test KC token
        run: |
          KEYCLOAK_RESPONSE=$(curl -s "${KEYCLOAK_URL}${KEYCLOAK_BASE_PATH}/admin/realms/$KEYCLOAK_REALM" \
            -H "Authorization: Bearer ${{ steps.keycloak-token.outputs.access-token }}" \
            -H "Accept: application/json" | jq -r '.')
          echo "----"
          echo "${KEYCLOAK_RESPONSE}"
          echo "----"

Output:

Run KEYCLOAK_RESPONSE=$(curl -s "${KEYCLOAK_URL}${KEYCLOAK_BASE_PATH}/realms/$KEYCLOAK_REALM/protocol/openid-connect/userinfo" \
----
{
  "sub": "2a428d3a-4359-49f4-abcd-607fdb23aa8f",
  "email_verified": false,
  "preferred_username": "service-account-repo:aleksandrsor/demo-infra:environment:test-keycloak"
}

Keycloak Terraform/OpenTofu provider

Let’s put everything together in the IaC workflow. The provider documentation is available here and explains how to set up credentials to manage a Keycloak instance.

Keep in mind that there is an initial chicken-and-egg problem: you need to run the Keycloak stack outside the GitHub workflow first so you can bootstrap the client used for GitHub Actions workflows.

deploy-IaC.yml

name: deploy-IaC
on:
  workflow_call:

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    name: IaC Deploy
    environment: 
      name: production
      deployment: true
    runs-on: ubuntu-24.04-arm
    env:
      DEPLOY_ENV: production
      KEYCLOAK_URL: ${{ vars.KEYCLOAK_URL }}
      KEYCLOAK_REALM: ${{ vars.KEYCLOAK_REALM }}
      KEYCLOAK_BASE_PATH: ${{ vars.KEYCLOAK_BASE_PATH || ''}}
    defaults:
      run:
        working-directory: ${{ env.working_dir }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 

      ...

      - id: keycloak-token
        name: Get KC token
        uses: .https://github.com/AleksandrSor/demo-infra/blob/main/.github/actions/keycloak-token
        with:
          keycloak-url: ${{ env.KEYCLOAK_URL }}
          keycloak-realm: ${{ env.KEYCLOAK_REALM }}
          keycloak-client-id: repo:${{ github.repository }}:environment:${{ env.DEPLOY_ENV }}
          keycloak-base-path: ${{ env.KEYCLOAK_BASE_PATH || ''}}

      - name: Apply terragrunt configuration
        env:
          KEYCLOAK_ACCESS_TOKEN: ${{ steps.keycloak-token.outputs.access-token }}
          KEYCLOAK_CLIENT_ID: ${{ vars.KEYCLOAK_CLIENT_ID || 'admin-cli' }}
        run: |
          terragrunt run --all --non-interactive --log-format bare -- apply -auto-approve

The Keycloak provider can be configured through environment variables:

KEYCLOAK_URL: Base URL of the Keycloak server (for example, https://keycloak.example.com).
KEYCLOAK_REALM: Realm
KEYCLOAK_BASE_PATH: Optional base path for Keycloak endpoints (for example, /auth for legacy distributions).
KEYCLOAK_CLIENT_ID: Client ID used by the provider to manage an instance (commonly admin-cli ).
KEYCLOAK_ACCESS_TOKEN: Access token obtained through token exchange.

Conclusion

I can manage the Keycloak instance without static credentials by using a token from the GitHub OIDC provider. I can also use Keycloak as an identity broker to exchange my GitHub Actions token for a Keycloak token and access resource servers in the same way when they accept OIDC tokens.

Additional links

OIDC: AWS OIDC Federation

Aleksandr Sorokin — Wed, 30 Sep 2026 15:06:44 +0000

Introduction

In my previous posts, I briefly mentioned the important topic of zero static credentials. This is especially relevant today, as interactions with AI agents in protected environments can unexpectedly expose credentials.

In this part, I explain how to authenticate my GitHub Actions jobs with the AWS API to provision AWS resources without static credentials.

GitHub OIDC Provider

GitHub provides a GitHub Actions OIDC provider, so our repository, refs, pull requests, and even environments can act as identities for resource servers that accept OIDC tokens.

Token

Token example from the official documentation:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automationhttps://github.com/AleksandrSor/demo-infra/blob/main/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

The most important part is the sub claim.

sub is the stable subject identifier for the token issuer, and it is usually the safest way to correlate a returning principal.

The sub claim can vary depending on whether the job runs against a ref, tag, pull request, or environment.

Environment

The subject claim includes the environment name when the job references an environment.

Syntax:

repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME

Example:

repo:octo-org/octo-repo:environment:Production

Specific branch

The subject claim includes the branch name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event.

Syntax:

repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME

Example:

repo:octo-org/octo-repo:ref:refs/heads/demo-branch

More information is available in the official documentation.

Token request

There is an official GitHub Action that helps not only with requesting a token, but also with configuring the AWS CLI to use it in a simple way.

name: AWS example workflow
on:
  push
env:
  AWS_REGION : "AWS-REGION"
  ROLE-TO-ASSUME: "ROLE-ARN"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  AWSGetCallerIdentity:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: ${{ env.ROLE-TO-ASSUME }}
          aws-region: ${{ env.AWS_REGION }}
          output-credentials: true
      - name: get caller identity
        run: |
            aws sts get-caller-identity

More information is available in the GitHub Action repository.

AWS Federation

AWS OIDC Federation allows us to use any OIDC IdP (Identity Provider) to obtain AWS STS tokens with role permissions, which we can then use to manage AWS resources.

First, I need to register the GitHub OIDC provider as an IdP in my AWS account. This can be done through the AWS Console or CLI, as described here.

aws iam create-open-id-connect-provider --url \
"https://token.actions.githubusercontent.com" --thumbprint-list \
"6938fd4d98bab03faadb97b34396831e3780aea1" --client-id-list \
'sts.amazonaws.com'

Next, I need to create a role with the correct trust policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:<ORG-NAME/REPO-NAME>:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Pay attention to the sub claim. It can vary depending on the event type described in the previous section. When using the aws-actions/configure-aws-credentials action, the token includes the "aud": "sts.amazonaws.com" claim.

GitHub Actions Job

Let's put all of this together in a working workflow for the demo project.

Registering GitHub OIDC as an IdP in AWS

oidc.tf

resource "aws_iam_openid_connect_provider" "github" {
  url            = "https://token.actions.githubusercontent.com"
  client_id_list = ["sts.amazonaws.com"]
}

Create a role for GitHub Actions jobs

role.tf

data "aws_iam_policy_document" "tf_execution_role_policy" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]
    effect  = "Allow"

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:${local.config.env.repository.name}:environment:${local.config.env.repository.protected_environment}"]
    }
  }
}

resource "aws_iam_role" "tf_execution_role" {
  name               = local.config.env.tf_role_name
  assume_role_policy = data.aws_iam_policy_document.tf_execution_role_policy.json
}

Note that I allow tokens only from a specific environment in the sub claim.

Create a GitHub Actions workflow

deploy-IaC.yml

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    name: IaC Deploy
    environment: 
      name: production
    runs-on: ubuntu-24.04-arm

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Configure AWS Credentials
        id: creds
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
            aws-region: ${{ vars.AWS_REGION }}
            role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME_ARN }}
            output-credentials: true

      - name: get caller identity
        run: |
            aws sts get-caller-identity

Additional links

Use IAM roles to connect GitHub Actions to actions in AWS - AWS Security Blog

OIDC: EKS Pod Identity

Aleksandr Sorokin — Sun, 20 Sep 2026 10:02:17 +0000

Introduction

In my last post, I briefly mentioned the important topic of zero static credentials. This is especially relevant today, as interactions with AI agents in protected environments can unexpectedly expose credentials.

My entire demo flow requires zero static credentials. Let me explain it in more detail in three parts. Follow along for future posts.

Kubernetes as an OIDC-compliant identity provider

You may be surprised to learn that a ServiceAccount token issued by the Kubernetes control plane is an OIDC-compliant JWT. This makes Kubernetes an OIDC-compliant identity provider for external services.

The Kubernetes API server even publishes an OpenID Provider Configuration document at /.well-known/openid-configuration and a related JSON Web Key Set (JWKS) at /openid/v1/jwks.

However, there are a few limitations.
First, the issuer URL is set out of the box to either https://kubernetes.default.svc.cluster.local or https://kubernetes.default.svc, depending on the distribution.
Second, the OpenID Provider Configuration endpoint (/.well-known/openid-configuration) and the JWKS endpoint are not publicly accessible by default.
You can address this by configuring the API server with the --service-account-issuer and --service-account-jwks-uri flags and by mirroring the OIDC endpoints to a public server.

You may be surprised to learn (yes, again) that AWS EKS addresses this out of the box. Thanks to IRSA, it uses OIDC to integrate with AWS IAM.

Run the following command:

aws eks describe-cluster \
  --name <your-cluster-name> \
  --query "cluster.identity.oidc.issuer" \
  --output text

Then append the OIDC discovery path /.well-known/openid-configuration to the returned issuer URL.

EKS Pod Identity Agent

EKS Pod Identity is a new way to grant an IAM role to an application running in a pod. AWS recommends using EKS Pod Identity whenever possible to grant pods access to AWS resources. A comparison table is also available here.

How it works

1. Create a Pod Identity association

Create it outside Kubernetes, for example:
eso-addon.tf

resource "aws_eks_pod_identity_association" "eso_addon" {
  cluster_name    = aws_eks_cluster.cluster.name  #eks cluster name
  namespace       = local.eso_namespace
  service_account = local.eso_service_account
  role_arn        = aws_iam_role.eso_role.arn     #role for service account
}

This association can be created before the namespace and service account are created.

2. When Amazon EKS starts a new pod

When a new pod uses a service account with an EKS Pod Identity association, Amazon EKS adds the following content to the pod manifest:

    env:
    - name: AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
      value: "/var/run/secrets/pods.eks.amazonaws.com/serviceaccount/eks-pod-identity-token"
    - name: AWS_CONTAINER_CREDENTIALS_FULL_URI
      value: "http://169.254.170.23/v1/credentials"
    volumeMounts:
    - mountPath: "/var/run/secrets/pods.eks.amazonaws.com/serviceaccount/"
      name: eks-pod-identity-token
  volumes:
  - name: eks-pod-identity-token
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          audience: pods.eks.amazonaws.com
          expirationSeconds: 86400 # 24 hours
          path: eks-pod-identity-token

Pay attention to the volume configuration: it uses a projected volume with a TokenRequest.
Kubernetes places a service account token with a specific audience at /var/run/secrets/pods.eks.amazonaws.com/serviceaccount/eks-pod-identity-token.
You can inspect it with:

cat /var/run/secrets/pods.eks.amazonaws.com/serviceaccount/eks-pod-identity-token \
  | cut -d. -f2 \
  | base64 -d 2>/dev/null \
  | jq .

It looks like this:

{
  "aud": [
    "pods.eks.amazonaws.com"
  ],
  "iss": "https://oidc.eks.us-east-1.amazonaws.com/id/<EKS_CLUSTER_ID>",
  "kubernetes.io": {
    "namespace": "external-secrets",
    "node": {
      "name": "<EKS_NODE_NAME>"
    },
    "pod": {
      "name": "external-secrets-debug"
    },
    "serviceaccount": {
      "name": "external-secrets"
    }
  },
  "sub": "system:serviceaccount:external-secrets:external-secrets"
}

3. An application running in a pod obtains AWS STS credentials

through the AWS SDK by using eks-pod-identity-token with AWS_CONTAINER_CREDENTIALS_FULL_URI:

    env:
    - name: AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
      value: "/var/run/secrets/pods.eks.amazonaws.com/serviceaccount/eks-pod-identity-token"
    - name: AWS_CONTAINER_CREDENTIALS_FULL_URI
      value: "http://169.254.170.23/v1/credentials"

Note that this is a local bind address. The Pod Identity Agent must run on the node.

Installation

Prerequisites and documentation are available here.
Examples from this demo project are shown below.
Since my node role already includes AmazonEKSWorkerNodePolicy:

eks-nodes-iam-roles

resource "aws_iam_role_policy_attachment" "eks_worker_node_policy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy"
  role       = aws_iam_role.nodes.name
}

I only need to install the add-on:

eks-addon-pod-identity-agent

data "aws_eks_addon_version" "latest_pod_identity_agent" {
  addon_name         = "eks-pod-identity-agent"
  kubernetes_version = aws_eks_cluster.cluster.version
  most_recent        = true
}


resource "aws_eks_addon" "pod_identity_agent" {
  cluster_name  = aws_eks_cluster.cluster.name
  addon_name    = "eks-pod-identity-agent"
  addon_version = data.aws_eks_addon_version.latest_pod_identity_agent.version

  resolve_conflicts_on_update = "OVERWRITE"
}

External Secrets configuration for Pod Identity

Documentation is available here.

eso-addon.tf

Assume role policy and IAM role:

locals {
  eso_namespace       = "external-secrets"
  eso_service_account = "external-secrets"
}

data "aws_iam_policy_document" "eso_assume_role" {
  statement {
    effect = "Allow"

    principals {
      type        = "Service"
      identifiers = ["pods.eks.amazonaws.com"]
    }

    actions = [
      "sts:AssumeRole",
      "sts:TagSession"
    ]

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-namespace"
      values   = [local.eso_namespace]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-service-account"
      values   = [local.eso_service_account]
    }
  }
}

resource "aws_iam_role" "eso_role" {
  name               = "${local.config.project.name}-external-secrets-addon"
  assume_role_policy = data.aws_iam_policy_document.eso_assume_role.json
}

IAM role policy:

# Reference: https://external-secrets.io/latest/provider/aws-secrets-manager/
data "aws_iam_policy_document" "eso_addon" {
  statement {
    effect = "Allow"

    actions = [
      "secretsmanager:ListSecrets",
      "secretsmanager:BatchGetSecretValue"
    ]

    resources = ["*"]
  }

  statement {
    effect = "Allow"

    actions = [
      "secretsmanager:GetResourcePolicy",
      "secretsmanager:GetSecretValue",
      "secretsmanager:DescribeSecret",
      "secretsmanager:ListSecretVersionIds"
    ]

    resources = [
      "arn:aws:secretsmanager:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:secret:${local.config.project.name}-*"
    ]
  }
}

resource "aws_iam_policy" "eso_addon" {
  name   = "${local.config.project.name}-external-secrets-addon"
  policy = data.aws_iam_policy_document.eso_addon.json
}

resource "aws_iam_role_policy_attachment" "eso_addon_policy_attachment" {
  role       = aws_iam_role.eso_role.name
  policy_arn = aws_iam_policy.eso_addon.arn
}

Pod Identity association:

resource "aws_eks_pod_identity_association" "eso_addon" {
  cluster_name    = aws_eks_cluster.cluster.name
  namespace       = local.eso_namespace
  service_account = local.eso_service_account
  role_arn        = aws_iam_role.eso_role.arn
}

External DNS configuration for Pod Identity

externaldns-iam-role-and-identity.tf

Assume role policy and IAM role:

data "aws_iam_policy_document" "externaldns_assume_role" {
  statement {
    effect = "Allow"

    principals {
      type        = "Service"
      identifiers = ["pods.eks.amazonaws.com"]
    }

    actions = [
      "sts:AssumeRole",
      "sts:TagSession"
    ]

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-namespace"
      values   = [local.externaldns_namespace]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-service-account"
      values   = [local.externaldns_service_account]
    }
  }
}

resource "aws_iam_role" "externaldns_role" {
  name               = "${local.config.project.name}-externaldns-addon"
  assume_role_policy = data.aws_iam_policy_document.externaldns_assume_role.json
}

IAM role policy:

data "aws_iam_policy_document" "externaldns_policy" {
  statement {
    effect = "Allow"

    actions = [
      "route53:ChangeResourceRecordSets",
      "route53:ListResourceRecordSets",
      "route53:ListTagsForResources"
    ]

    resources = [
      for zone in aws_route53_zone.managed : zone.arn
    ]
  }

  statement {
    effect = "Allow"

    actions = [
      "route53:ListHostedZones",
      "route53:ListHostedZonesByName"
    ]

    resources = ["*"]
  }
}

resource "aws_iam_policy" "externaldns_policy" {
  name   = "${local.config.project.name}-externaldns-policy"
  policy = data.aws_iam_policy_document.externaldns_policy.json
}

resource "aws_iam_role_policy_attachment" "externaldns_policy_attachment" {
  role       = aws_iam_role.externaldns_role.name
  policy_arn = aws_iam_policy.externaldns_policy.arn
}

Pod Identity association:

resource "aws_eks_pod_identity_association" "externaldns" {
  cluster_name    = var.eks_cluster_name
  namespace       = local.externaldns_namespace
  service_account = local.externaldns_service_account
  role_arn        = aws_iam_role.externaldns_role.arn
}

AWS Load Balancer Controller configuration for Pod Identity

Documentation is available here.

alb-role.tf

Assume role policy and IAM role:

locals {
  alb_namespace       = "kube-system"
  alb_service_account = "aws-load-balancer-controller"
}

data "aws_iam_policy_document" "alb_assume_role" {
  statement {
    effect = "Allow"

    principals {
      type        = "Service"
      identifiers = ["pods.eks.amazonaws.com"]
    }

    actions = [
      "sts:AssumeRole",
      "sts:TagSession"
    ]

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-namespace"
      values   = [local.alb_namespace]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-service-account"
      values   = [local.alb_service_account]
    }
  }
}

resource "aws_iam_role" "alb_controller_role" {
  name               = "${local.config.project.name}-alb-controller-role"
  assume_role_policy = data.aws_iam_policy_document.alb_assume_role.json
}

IAM role policy:

locals {
  alb_policy_url      = "https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/install/iam_policy.json"
}

data "http" "alb_iam_policy_source" {
  url = local.alb_policy_url

  request_headers = {
    Accept = "application/json"
  }
}


resource "aws_iam_policy" "alb_load_balancer_controller" {
  name        = "${local.config.project.name}-alb-controller-policy"
  description = "IAM policy for AWS ALB Load Balancer Controller"
  policy      = data.http.alb_iam_policy_source.response_body
}

resource "aws_iam_role_policy_attachment" "alb_controller_role_attachment" {
  policy_arn = aws_iam_policy.alb_load_balancer_controller.arn
  role       = aws_iam_role.alb_controller_role.name
}

Pod Identity association:

resource "aws_eks_pod_identity_association" "alb_controller" {
  cluster_name    = aws_eks_cluster.cluster.name
  role_arn        = aws_iam_role.alb_controller_role.arn
  namespace       = local.alb_namespace
  service_account = local.alb_service_account
}

OIDC: Deliver OIDC parameters unattended using External Secrets, AWS Secrets Manager, and FluxCD.

Aleksandr Sorokin — Wed, 09 Sep 2026 13:08:29 +0000

Introduction

In one of my previous posts, I described how I tested new possibilities for using the Gateway API implementation of the AWS Load Balancer Controller for JWT validation.

I also covered how to configure Keycloak as an identity provider for issuing JWTs to access Kubernetes through a JWT-validated load balancer endpoint.

In this post, I want to describe how to deliver OIDC parameters from a Keycloak client all the way down to the actual load balancer configuration in an unattended manner.

Moreover, the entire flow does not require any static credentials to be stored. I promise to explain how to achieve a zero-static-credentials setup in a future post. Follow me!

AWS Secret Manager

As a first step, let OpenTofu/Terraform store the client parameters in AWS Secrets Manager. From there, they can be delivered further using the pull-based approach of the External Secrets Operator.

I am using an ephemeral resource to avoid storing the client secret in the state.

kube-api-client.tf

locals {
  client_secret_version = 10
}

ephemeral "random_password" "kube_api_client_secret" {
  length  = 86
  special = false
}

resource "keycloak_openid_client" "kube_api" {
  ...
  client_secret_wo          = ephemeral.random_password.kube_api_client_secret.result
  client_secret_wo_version  = local.client_secret_version
  ...
}

A small abstraction layer helps loosen the coupling between the Keycloak stack and AWS Secrets Manager.

aws-secretmanager.tf

module "aws_secretmanager" {
  source         = "./modules/aws-secretmanager"
  secret_name    = local.client_config.name
  secret_version = local.client_secret_version
  secret_value = jsonencode({
    name          = local.client_config.name
    client_id     = local.client_config.client_id
    client_secret = ephemeral.random_password.kube_api_client_secret.result
    issuer_url    = local.client_config.issuer_url
    audience      = local.client_config.audience

    groups_claim  = local.client_config.groups_claim
    groups_prefix = local.client_config.groups_prefix

    username_claim  = local.client_config.username_claim
    username_prefix = local.client_config.username_prefix

    required_claims = local.client_config.required_claims
    jwksEndpoint    = local.client_config.jwksEndpoint
  })
}

The entire configuration is stored as JSON.
main.tf

resource "aws_secretsmanager_secret" "secret" {
  name = var.secret_name
}

resource "aws_secretsmanager_secret_version" "secret_version" {
  secret_id                = aws_secretsmanager_secret.secret.id
  secret_string_wo         = var.secret_value
  secret_string_wo_version = var.secret_version
}

External Secret Operator

External Secrets Operator is a Kubernetes operator that retrieves information from external APIs and automatically injects the values into a Kubernetes Secret.

ESO supports AWS Secrets Manager and also EKS Pod Identity as a way to access secrets securely without static credentials.

Let's create a role for ESO.

eso-addon.tf

# Reference: https://external-secrets.io/latest/provider/aws-access/

locals {
  eso_namespace       = "external-secrets"
  eso_service_account = "external-secrets"
}

data "aws_iam_policy_document" "eso_assume_role" {
  statement {
    effect = "Allow"

    principals {
      type        = "Service"
      identifiers = ["pods.eks.amazonaws.com"]
    }

    actions = [
      "sts:AssumeRole",
      "sts:TagSession"
    ]

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-namespace"
      values   = [local.eso_namespace]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:RequestTag/kubernetes-service-account"
      values   = [local.eso_service_account]
    }
  }
}

resource "aws_iam_role" "eso_role" {
  name               = "${local.config.project.name}-external-secrets-addon"
  assume_role_policy = data.aws_iam_policy_document.eso_assume_role.json
}

# Reference: https://external-secrets.io/latest/provider/aws-secrets-manager/
data "aws_iam_policy_document" "eso_addon" {
  statement {
    effect = "Allow"

    actions = [
      "secretsmanager:ListSecrets",
      "secretsmanager:BatchGetSecretValue"
    ]

    resources = ["*"]
  }

  statement {
    effect = "Allow"

    actions = [
      "secretsmanager:GetResourcePolicy",
      "secretsmanager:GetSecretValue",
      "secretsmanager:DescribeSecret",
      "secretsmanager:ListSecretVersionIds"
    ]

    resources = [
      "arn:aws:secretsmanager:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:secret:${local.config.project.name}-*"
    ]
  }
}

resource "aws_iam_policy" "eso_addon" {
  name   = "${local.config.project.name}-external-secrets-addon"
  policy = data.aws_iam_policy_document.eso_addon.json
}

resource "aws_iam_role_policy_attachment" "eso_addon_policy_attachment" {
  role       = aws_iam_role.eso_role.name
  policy_arn = aws_iam_policy.eso_addon.arn
}

And an identity association. It can be created before the namespace and service account are created.

resource "aws_eks_pod_identity_association" "eso_addon" {
  cluster_name    = aws_eks_cluster.cluster.name
  namespace       = local.eso_namespace
  service_account = local.eso_service_account
  role_arn        = aws_iam_role.eso_role.arn
}

Installing ESO via FluxCD.

external-secrets.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: external-secrets
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: external-secrets
  namespace: external-secrets
spec:
  url: https://charts.external-secrets.io
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: external-secrets
  namespace: external-secrets
spec:
  chart:
    spec:
      chart: external-secrets
      version: "2.10.x"
      sourceRef:
        kind: HelmRepository
        name: external-secrets
  interval: 30m
  releaseName: external-secrets
  values:
    serviceAccount:
      name: external-secrets

external-secrets.yaml

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: external-secrets
  namespace: flux-system
spec:
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: .https://github.com/AleksandrSor/demo-infra/blob/main/fluxcd/infra/external-secrets/prod
  prune: true
  interval: 30m
  retryInterval: 5m
  timeout: 5m

ESO custom resources: SecretStore and ExternalSecret

The SecretStore specifies how External Secrets accesses the external API.

ClusterSecretStore.yaml

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: aws-secretmanager
spec:
  provider:
    aws:
      service: SecretsManager
      region: "${region}"

The ExternalSecret resource describes what data should be fetched, how it should be transformed, and where it should be stored as a Kubernetes Secret.

ExternalSecret.yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: oidc-params
  namespace: flux-system
spec:
  refreshInterval: 1h0m0s
  secretStoreRef:
    kind: ClusterSecretStore
    name: aws-secretmanager
  target:
    name: oidc-params
    creationPolicy: Owner
  dataFrom:
  - extract:
      key: "${projectName}-keycloak"

The result is a Kubernetes Secret that can be used by FluxCD to substitute values in custom resources for the AWS Load Balancer Controller.

apiVersion: v1
kind: Secret
metadata:
  name: oidc-params
  namespace: flux-system
data:
  audience: demo-infra-kube-api
  client_id: demo-infra-kube-api
  client_secret: <secret_value>
  groups_claim: roles
  groups_prefix: "oidc:"
  issuer_url: https://<keycloak_url>/auth/realms/demo-infra-project
  jwksEndpoint: https://<keycloak_url>/auth/realms/demo-infra-project/protocol/openid-connect/certs
  name: demo-infra-keycloak
  required_claims: {}
  username_claim: username
  username_prefix: oidc-

FluxCD post-build variable substitution

With .spec.postBuild.substituteFrom, you can provide a list of ConfigMaps and Secrets from which variables are loaded. The ConfigMap and Secret data keys are used as the variable names.

Let's implement this in the ListenerRuleConfiguration for the AWS Load Balancer Controller.

ListenerRuleConfiguration.yaml

apiVersion: gateway.k8s.aws/v1
kind: ListenerRuleConfiguration
metadata:
  name: envoy-kube-proxy-jwt-validation
spec:
  actions:
    - type: "jwt-validation"
      jwtValidationConfig:
        jwksEndpoint: "${jwksEndpoint}"
        issuer: "${issuer_url}"
        additionalClaims:
          - name: "aud"
            format: "single-string"
            values: ${audience}

envoy-kube-proxy.yaml

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: envoy-kube-proxy
  namespace: flux-system
spec:
  ...
  postBuild:
  ...
      - kind: Secret
        name: oidc-params

Conclusion

Voilà! I have implemented an unattended flow to deliver OIDC parameters to the AWS Load Balancer.
In a future post, I will explain the zero-static-credentials setup in more detail. Stay in touch!

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.