Test Kubernetes access with a KeySigner code

Use a KeySigner code with Keycloak and check which resources the resulting account can read in a test Kubernetes cluster.

Before you start

KeySigner on iPhone or Mac, a browser and kubectl

  • Use a test cluster that trusts a Keycloak realm through OpenID Connect, a configured client, two test namespaces and an independent administrator. Give the test account permission to list pods in one namespace.

Data and access

Shared or checked
Keycloak checks the code and issues an identity token. Kubernetes validates the token and applies role bindings to the mapped user or groups.
Check separately
Cluster role bindings and existing credentials can provide access separately. Test the intended identity and namespace in a fresh session.
  1. Identify the cluster, realm and namespace

    Use a test cluster configured to trust your Keycloak realm through OpenID Connect. Ask the cluster administrator for the expected issuer, client ID and mapped username. Give a non-admin test account permission to list pods in one namespace and keep a second namespace out of scope. Keep an independent administrator context available.

    Check. The test cluster trusts the intended issuer. The test account, expected username and separate administrator are available.

  2. Enroll the account in KeySigner

    Ask the realm administrator to require Configure OTP for the test account. In the Keycloak Account Console, sign in as that account and open its setup QR code. In KeySigner, open Accounts, choose Add (+), then Sign-in codes and backup. Unlock Sign-in codes, choose Add account and scan the QR code. Choose Show code, complete the required approvals and enter the current code in Keycloak. Finish enrollment.

    Check. Keycloak accepts the enrollment code and lists the new authenticator for the test account.

  3. Sign in through the cluster’s client

    Start the test cluster’s configured OpenID Connect client in a fresh browser session. Confirm that the browser opens the expected Keycloak realm. Enter a current KeySigner code when prompted. Use the resulting session with the test kubeconfig. Run kubectl auth whoami and confirm that the mapped username matches the test account.

    Check. The client uses the test context and Kubernetes reports the expected username.

  4. Confirm allowed and denied access

    Run kubectl get pods -n <test-namespace> and confirm Kubernetes returns a pod list. Try the same read in the second test namespace and confirm access is forbidden. Use kubectl auth can-i create pods -n <test-namespace> to check that the account has no create permission without creating a pod.

    Check. The first namespace returns a pod list. The second read is forbidden and the create permission check says no.

  5. Start a fresh session and retest the code

    Use a private browser without the prior Keycloak session or cached client credentials. In this disposable test, try an invalid code and confirm Keycloak stays at the challenge. Enter a current KeySigner code. Check the mapped Kubernetes identity and both namespace reads again.

    Keycloak shows Invalid authenticator code under an empty one-time code field for the test namespace reader.
    Keycloak rejected an invalid code during a fresh Kubernetes test session. View full-size screenshot

    Check. Keycloak rejects the invalid code. The current code returns the same scoped Kubernetes identity.

Check your result

Keycloak verifies the code. Kubernetes validates the resulting ID token and applies its own role grants. Record the context, mapped identity and results of both reads. Test token expiration and workload or administrator access separately.

What we tested

Tested on . In a disposable lab with Kubernetes 1.34.8 and Keycloak 26.8.2, a browser test used a KeySigner enrollment code and a fresh KeySigner code. Keycloak rejected an invalid code before issuing a new token. With each valid session, kubectl reported the same identity. Kubernetes allowed the pod list in one namespace, denied the same read in a second namespace and denied pod creation.

How to verify your setup

If you get stuck

Keycloak accepts the code but the cluster refuses access

For Unauthorized, check the current context, token expiration, trusted issuer and client ID. For Forbidden, compare the mapped username or groups with the role binding in that namespace. If you skip the code prompt, clear the test client session and open a fresh browser.

Report a problem with this guide

Explore all setup guides →