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

Prerequisites

• An ACK managed cluster is created, and the cluster is version 1.22 or later.

• You have obtained the cluster's kubeconfig file and connected to the cluster with kubectl.

• The Nginx Ingress Controller is installed.

• (Optional) jwt-cli is installed, which is used to parse JSON Web Tokens (JWTs).

Set up the environment

• Prepare a domain name for the Keycloak Service.

• Certificates

  To ensure the security of Keycloak in a production environment, run the following command to generate a root certificate and a server certificate. The Subject Alternate Name (SAN) of the server certificate must contain the domain name that you prepared for the Keycloak Service.

  openssl genrsa -out rootCA.key 2048 #Generate a CA key.
  openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 3650 -out rootCA.crt #Generate a CA certificate.
  openssl genrsa -out server.key 2048 #Generate a server key.
  openssl req -new -key server.key -out server.csr
  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}')

• Databases

  By default, Keycloak data is persisted to local files. In a production environment, you need to persist the data to a database. The following table describes the database engines and versions supported by Keycloak.

  Database	Option value	Version
  MariaDB Server	mariadb	10.11
  Microsoft SQL Server	mssql	2022
  MySQL	mysql	8.0
  Oracle Database	oracle	19.3
  PostgreSQL	postgres	15

In this example, ApsaraDB RDS for MySQL is used to persist Keycloak data. A database named Keycloak is created. For more information about how to create and use database instances, see Create and configure an ApsaraDB RDS for MySQL instance.

Step 1: Deploy Keycloak in an ACK managed cluster

1. Deploy a Keycloak Service in an ACK managed cluster.

   1. Create a file named keycloak.yaml and add the following content to the file:

      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

   2. Run the following command to deploy a Keycloak Service in an ACK managed cluster and expose the Service to internal access:

      kubectl apply -f keycloak.yaml

2. Deploy relevant configurations.

   1. Create a file named keycloak-secret.yaml and add the following content to the file.

      The following database configuration is used to connect to the database named Keycloak. The administrator configuration is used to log on to Keycloak for the first time.

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

   2. Run the following command to deploy the configurations:

      kubectl apply -f keycloak-secret.yaml

   3. Create a file named keylock-pki.yaml and add the following content to the file:

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

   4. Run the following command to deploy the server certificate:

      kubectl apply -f keycloak-pki.yaml

3. Create an Ingress.

   1. Create a file named keycloak-ingress.yaml and add the following content to the file.

      Replace the Service domain name in the following code block with the domain name that you prepared for the Keycloak Service:

      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

   2. Run the following command to deploy the Ingress:

      kubectl apply -f keycloak-ingress.yaml

      After the Ingress is deployed, a publicly accessible IP address is generated. The Service domain name is resolved to the IP address.

4. Deploy the Keycloak Deployment.

   1. Create a file named keycloak-deploy.yaml and add the following content to the file:

      View content of the keycloak-deploy.yaml file

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        labels:
          app: keycloak
        name: keycloak
        namespace: default
      spec:
        selector:
          matchLabels:
            app: keycloak
        template:
          metadata:
            labels:
              app: keycloak
          spec:
            containers:
              - args:
                  - start-dev
                env:
                  - name: KEYCLOAK_ADMIN
                    valueFrom:
                      secretKeyRef:
                        key: keycloak_admin
                        name: keycloak-secret
                  - name: KEYCLOAK_ADMIN_PASSWORD
                    valueFrom:
                      secretKeyRef:
                        key: keycloak_admin_password
                        name: keycloak-secret
                  - name: KC_PROXY
                    value: edge
                  - name: KC_DB_URL_HOST
                    valueFrom:
                      secretKeyRef:
                        key: db_url
                        name: keycloak-secret
                  - name: KC_DB
                    value: mysql
                  - name: KC_DB_USERNAME
                    valueFrom:
                      secretKeyRef:
                        key: db_username
                        name: keycloak-secret
                  - name: KC_DB_PASSWORD
                    valueFrom:
                      secretKeyRef:
                        key: db_passwd
                        name: keycloak-secret
                image: 'quay.io/keycloak/keycloak:latest'
                imagePullPolicy: Always
                name: keycloak
                ports:
                  - containerPort: 8080
                    name: http
                    protocol: TCP
                readinessProbe:
                  httpGet:
                    path: /realms/master
                    port: 8080

   2. Run the following command to deploy a Keycloak Deployment:

      kubectl apply -f keycloak-deploy.yaml

5. In a browser, enter https://${Keycloak Service domain name} to access the Keycloak Service. If the following page appears, the Service is successfully deployed.

Step 2: Deploy Keycloak

Step 3: Configure Kube API Server parameters

Kubernetes supports the OIDC protocol and can be interfaced with external identity providers (IdPs) to verify identities. To enable identity verification, you need to configure OIDC parameters related to the Kube API Server component of the ACK managed cluster.

1. Log on to the ACK console. In the left navigation pane, click Clusters.

2. On the Clusters page, find the one you want to manage and click its name. In the left navigation pane, click Add-ons.

3. On the Add-ons page, find the Kube API Server component on the Core Components tab and click Configuration in the lower-right corner of the card.

4. On the Kube API Server Parameters page, configure the following parameters, keep the default settings for the other parameters, and then click OK.

   Parameter	Description
   oidcIssuerURLOIDC The URL of the OIDC provider	Access https://${Keycloak Service domain name}/realms/myrealm/.well-known/openid-configuration, and enter the value corresponding to issuer into oidcIssuerURL. In this example: https://${Keycloak Service domain name}/realms/myrealm. Important The API Server in the cluster will access the address specified in the oidcIssuerURL configuration item. If your service domain name is a public domain name, make sure that the cluster has Internet access enabled. For more information, see Enable Internet access for a cluster. If the API Server still cannot access the address specified in the oidcIssuerURL configuration item after Internet access is enabled for the cluster, you can use kubectl get endpoints to check the number of IP addresses in the Kubernetes backend. If there are more than one IP address, log on to the Worker node and try to access the oidcIssuerURL, then check the Internet configuration, security group rules, and other settings. If there is only one IP address, please submit a ticket for assistance.
   oidcClientIdOIDC The client ID of the OIDC token	Enter the client ID specified in Step 2 of the Client settings section. In this example, ack is entered.
   oidcUsernameClaim The JWT claim that is used as the username	Enter the value of the Token Claim Name parameter specified in Step 5 of the Client scope settings section. In this example, name is entered, which is the identity of the user in the cluster.
   oidcUsernamePrefix The prefix of the username	Enter a hyphen (-), which means that no prefix is specified.
   oidcCAContent The CA certificate that is required for sending requests to the URL of the OIDC provider. You must specify a Base64-encoded certificate	Enter the Base64-encoded root certificate generated in Certificates in the Set up the environment section.

Step 4: Verify identities

1. Run the following command to request an ID token. Then, obtain the ID token from the request body.

   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=${Password used to log on to Keycloak} -d scope=openid \
   -d client_secret=${client credential}

   You need to replace the following variables:

   Variable to replace	Description
   Keycloak Service domain name	Replace it with the domain name that you prepared for the Keycloak Service.
   password	Replace it with the password specified in Step 2.a of Step 1.
   client_secret	Log on to the Keycloak console. On the Clients page, select the client named ack, click Credentials, and then copy the value of the Client secret parameter.

2. Optional: When you parse the token using jwt-cli, the output shows that iss is the oidcIssuerURL configured for the API server, and the name field is the User Attribute set in Step 5 of the preceding Client scopes section.

3. Use the following YAML content to create a ClusterRole:

   kind: ClusterRole
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: keycloak-example
   rules:
     - apiGroups: [""]
       resources: ["namespaces"] 
       verbs: ["get","list"] # Allow the role to read namespace information.
   ---
   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

4. Run the following command to send a request to the API server:

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

   • API server address: Enter the API server address based on the network where your cluster is deployed. On the Cluster Information page of the Container Service Management Console, go to the Basic Information tab and view the API server Public Endpoint and API server Internal Endpoint in the Network section.

   • id token: Specify the ID token obtained in Step 1.

   After the request is sent, the following namespace information is returned.

   Send another request to request a resource that the current user is unauthorized to access. The output indicates that Kubernetes identifies the ack user and verifies the permissions of the user.