Container Service for Kubernetes:Use Keycloak as an OIDC provider to verify identities

Prepare a domain name

Prepare a domain name for the Keycloak Service. You will use this domain name throughout the setup.

Generate TLS certificates

To secure Keycloak in a production environment, generate a root certificate and a server certificate. The server certificate must include the Keycloak Service domain name as a Subject Alternative Name (SAN).

# Generate a CA (Certificate Authority) key
openssl genrsa -out rootCA.key 2048

# Generate a CA certificate (valid for 10 years)
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 3650 -out rootCA.crt

# Generate a server key
openssl genrsa -out server.key 2048

# Create a Certificate Signing Request (CSR)
openssl req -new -key server.key -out server.csr

# Generate the server certificate with the Keycloak domain as SAN
openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial \
  -out server.crt -days 3650 -sha256 -extensions v3_req \
  -extfile <(echo '[v3_req]'; echo 'subjectAltName = DNS:${Service domain name}')

Prepare a database

By default, Keycloak persists data to local files. For production environments, use an external database. Keycloak supports the following database engines:

This guide uses ApsaraDB RDS for MySQL with a database named Keycloak. See Create an ApsaraDB RDS for MySQL instance.

1.1 Create the Keycloak Service

Create keycloak.yaml with the following content:

apiVersion: v1
kind: Service
metadata:
  labels:
    app: keycloak
  name: keycloak
  namespace: default
spec:
  ports:
    - name: http
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: keycloak
  type: ClusterIP

Apply the Service:

kubectl apply -f keycloak.yaml

1.2 Create the credentials Secret

Create keycloak-secret.yaml. This Secret stores Base64-encoded database credentials and the initial Keycloak admin account.

apiVersion: v1
data:
  db_passwd: ${Database password encoded by Base64}
  db_username: ${Database username encoded by Base64}
  db_url: ${Database URL or host encoded by Base64}
  keycloak_admin: ${Keycloak administrator username encoded by Base64}
  keycloak_admin_password: ${Keycloak administrator password encoded by Base64}
kind: Secret
metadata:
  name: keycloak-secret
  namespace: default
type: Opaque

Apply the Secret:

kubectl apply -f keycloak-secret.yaml

1.3 Create the TLS Secret

Create keycloak-pki.yaml with the server certificate and key generated in Generate TLS certificates:

apiVersion: v1
data:
  tls.crt: ${Server certificate encoded by Base64}
  tls.key: ${Server key encoded by Base64}
kind: Secret
metadata:
  name: keycloak-pki
  namespace: default
type: IngressTLS

Apply the TLS Secret:

kubectl apply -f keycloak-pki.yaml

1.4 Create the Ingress

Create keycloak-ingress.yaml. Replace ${Service domain name} with the domain name you prepared.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    ingress-controller: nginx
  name: keycloak
  namespace: default
spec:
  ingressClassName: nginx
  rules:
    - host: ${Service domain name}
      http:
        paths:
          - backend:
              service:
                name: keycloak
                port:
                  number: 80
            path: /
            pathType: ImplementationSpecific
  tls:
    - hosts:
        - ${Service domain name}
      secretName: keycloak-pki

Apply the Ingress:

kubectl apply -f keycloak-ingress.yaml

After the Ingress is created, a public IP address is assigned. Point your domain name DNS to this IP address.

Verify Keycloak is running

Open https://${Keycloak Service domain name} in a browser. If the Keycloak welcome page appears, the deployment is successful.

User settings

1. On the Keycloak welcome page, click Administration Console and log in with the admin credentials from keycloak-secret.yaml.

2. In the upper-left corner, open the realm drop-down list and click Create Realm.

   

3. Set Realm name to myrealm and click Create.

4. Switch to the myrealm realm. In the left navigation pane, click Users, then click Add user.

   

5. Set Username to myuser and click Create.

6. On the myuser page, click Attributes. Add an attribute with Key name and Value ack, then click Save. This attribute will be injected into the ID token.

   

7. Click Credentials, then click Set Password. Set Temporary to On and click Save. The user must change their password on first login. Users can log in to their Keycloak account at https://${Keycloak Service domain name}/realms/${Your realm}/account.

   

Client settings

1. In the left navigation pane, click Clients, then click Create client.

2. Complete the three-step client creation wizard:

   1. General settings: Set both Client ID and Name to ack, then click Next.

   2. Capability config: Set Client authentication to On (this makes the client confidential), keep other defaults, and click Next.

   3. Login settings: Set Valid redirect URIs to http://* to allow all HTTP redirect URIs, then click Save.

Client scope settings

Client scopes let you share protocol mappings across clients. Set up a scope that injects the user's name attribute into the ID token.

1. In the left navigation pane, click Client scopes, then click Create client scope.

2. Set Name to ack-kubernetes, keep other defaults, and click Save.

   

3. On the ack-kubernetes page, click Mappers, then click Configure a new mapper.

   

4. On the Add mapper page, configure the mapper to inject the name: ack attribute into the ID token: Keep other defaults and click Save.

   • Name: name

   • User Attribute: name

   • Token Claim Name: name

   

5. In the left navigation pane, click Clients and select the ack client.

6. Click the Client scopes tab, then click Add client scope. Select ack-kubernetes and click Add.

   

Get an ID token

Run the following command to request an ID token from Keycloak:

curl -ks -X POST https://${Keycloak Service domain name}/realms/myrealm/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=ack \
  -d username=myuser \
  -d password=${myuser password} \
  -d scope=openid \
  -d client_secret=${client secret}

Replace the following placeholders:

The response body contains the id_token field. Copy that value.

(Optional) Parse the ID token

Use jwt-cli to decode the token and confirm the claims:

jwt decode <id_token>

The output should show iss matching your oidcIssuerURL and name set to ack — the user attribute injected by the client scope mapper.

Set up RBAC and call the API server

Create a ClusterRole and ClusterRoleBinding that grant the ack user read access to namespaces:

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: keycloak-example
rules:
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list"]
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ack-crb
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: keycloak-example
subjects:
  - kind: User
    name: ack
    apiGroup: rbac.authorization.k8s.io

Call the API server with the ID token:

curl -k https://${API server address}/api/v1/namespaces \
  -H "Authorization: Bearer ${id_token}"

Replace ${API server address} with the public or internal endpoint of your cluster. Find these in the ACK console under Cluster Information > Basic Information > Network: API server Public Endpoint or API server Internal Endpoint.

The API server returns the list of namespaces, confirming that OIDC authentication is working.

To verify that role-based access control (RBAC) authorization also works, request a resource the ack user is not authorized to access. The API server identifies the user and denies the request, confirming that both authentication and authorization are enforced.