Alibaba Cloud Service Mesh:Integrate Keycloak with ASM for single sign-on

Concepts

Procedure

Step 1: Deploy the demo application and Keycloak

1. Use the following YAML manifest to deploy the httpbin application to the default namespace in your ACK managed cluster. Run the kubectl apply -n default -f xxx.yaml command.

   View YAML

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: httpbin
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: httpbin
     labels:
       app: httpbin
       service: httpbin
   spec:
     ports:
     - name: http
       port: 8000
       targetPort: 80
     selector:
       app: httpbin
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: httpbin
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: httpbin
         version: v1
     template:
       metadata:
         labels:
           app: httpbin
           version: v1
       spec:
         serviceAccountName: httpbin
         containers:
         - image: docker.io/kennethreitz/httpbin
           imagePullPolicy: IfNotPresent
           name: httpbin
           ports:
           - containerPort: 80

2. Use the following YAML manifest to deploy the Keycloak application to the default namespace in your ACK managed cluster. Run the kubectl apply -n default -f xxx.yaml command.

   View YAML

   apiVersion: v1
   kind: Service
   metadata:
     name: keycloak
     labels:
       app: keycloak
   spec:
     ports:
     - name: http
       port: 8080
       targetPort: 8080
     selector:
       app: keycloak
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: keycloak
     labels:
       app: keycloak
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: keycloak
     template:
       metadata:
         labels:
           app: keycloak
       spec:
         containers:
         - name: keycloak
           image: quay.io/keycloak/keycloak:latest
           args: ["start-dev"]
           env:
           - name: KEYCLOAK_ADMIN
             value: "admin"
           - name: KEYCLOAK_ADMIN_PASSWORD
             value: "admin"
           - name: KC_PROXY
             value: "edge"
           ports:
           - name: http
             containerPort: 8080
           readinessProbe:
             httpGet:
               path: /realms/master
               port: 8080

Step 2: Expose the application and Keycloak via gateway

In this example, you access the demo application over HTTPS (port 443) and the Keycloak console over HTTP (port 80).

1. Create a certificate for the HTTPS service and name it myexample-credential. For more information, see Enable Secure HTTPS Services by Using an ASM Ingress Gateway.

2. Use the following YAML to create a Gateway and a VirtualService in the ASM cluster to expose Keycloak to the public network.

   1. In the ASM console, configure the Gateway for the corresponding ASM instance. For more information, see Manage gateway rules.

      View YAML

      apiVersion: networking.istio.io/v1beta1
      kind: Gateway
      metadata:
        name: ingressgateway
        namespace: istio-system
      spec:
        selector:
          app: istio-ingressgateway // Make sure that this selector matches the existing gateway.
        servers:
          - hosts:
              - '*'
            port:
              name: http-httpbin // Use HTTPS (port 443) to access the sample application.
              number: 443
              protocol: HTTPS
            tls:
              credentialName: myexample-credential
              mode: SIMPLE
          - hosts:
              - '*'
            port:
              name: keycloak // Use HTTP (port 80) to access the Keycloak console.
              number: 80
              protocol: HTTP
                                      

   2. Apply the following VirtualService to the ASM instance. For more information, see Manage virtual services.

      View YAML

      apiVersion: networking.istio.io/v1beta1
      kind: VirtualService
      metadata:
        name: ingressgateway-vs
        namespace: istio-system
      spec:
        gateways:
          - ingressgateway
        hosts:
          - '*'
        http:
          - match:
              - port: 80
            name: keycloak
            route:
              - destination:
                  host: keycloak.default.svc.cluster.local
                  port:
                    number: 8080
          - name: httpbin
            route:
              - destination:
                  host: httpbin.default.svc.cluster.local
                  port:
                    number: 8000

3. In your browser, navigate to http://${ASM_INGRESS_GATEWAY_ADDRESS} to access the Keycloak application.

4. Click Administration Console and log on with the admin credentials you configured during the Keycloak deployment.

Step 3: Configure Keycloak

1. In the left-side navigation pane of Keycloak, select Master from the dropdown list and click Create Realm.

2. On the new realm's configuration page, create a client. On the General Settings tab, set Client type to OpenID Connect and Client ID to oauth2proxy. On the Capability config tab, enable Client authentication, disable Authorization, and under Authentication flow, select only the Standard flow and Direct access grants checkboxes.

3. Create a user in the realm. Set Username to asm-test and enable Email verified. Then, click Save.

4. On the User details page, click the Credentials tab.

5. Set a password for the user. Set Temporary to Off and click Save.

6. Create a realm role. Set Role name to test-role and click Save.

7. On the User details page, select the Role mapping tab.

8. On the Role mapping page, click Assign role. Assign the test-role to the user.

9. Create a client scope. Set Name to test_scope and Protocol to OpenID Connect. Enable Display on consent screen and Include in token scope. Then, click Save.

10. On the Client Scope page, click the Mappers tab and add a mapper. Set Mapper type to Audience and Name to test-mapper. For Included Client Audience, select oauth2proxy, and enable Add to access token. Then, click Save.

11. Click the Scope tab, select the checkbox next to the test-role role, and then click Assign.

12. On the client settings page, click the Client scopes tab and add the test_scope client scope as a default scope.

13. Add the Valid redirect URIs for the cluster's oauth2-proxy. On the Settings tab, in the Access settings section, enter https://${ASM ingress gateway address}/oauth2/callback in the Valid redirect URIs field and click Save.

Step 4: Enable custom authorization and OIDC SSO

1. Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.

2. On the Mesh Management page, click the name of the ASM instance. In the left-side navigation pane, choose Mesh Security Center > Custom Authorization Service.

3. On the External Authorization Service page, click Register External Authorization Service and select OIDC Authz and Authn Service. Set the parameters for the OIDC Identity Authentication and Authorization Service and click Create.

   In the Associate Custom Authorization Service panel, select OIDC Identity Authentication and Authorization Service as the type and configure the parameters.

   Enter the information from the OIDC client that you created in Keycloak. You can use the ASM ingress gateway as the redirect URI for login. For more information about the cookie secret, see Generating a Cookie Secret.

   • IdP OIDC Issuer URL: http://${ASM_INGRESS_GATEWAY_ADDRESS}/realms/${REALM_NAME_IN_KEYCLOAK}.

   • ClientID and Client Secret: Use the values that you recorded in the previous step.

   • Scopes: OpenID is a required scope. You can specify other scopes.

4. Create a VirtualService by using the following YAML.

   apiVersion: networking.istio.io/v1beta1
   kind: VirtualService
   metadata:
     name: oauth2-vs
     namespace: istio-system
   spec:
     gateways:
       - ingressgateway
     hosts:
       - '*'
     http:
       - match:
           - uri:
               prefix: /oauth2
         name: oauth2
         route:
           - destination:
               host: asm-oauth2proxy-httpextauth-oidc.istio-system.svc.cluster.local
               port:
                 number: 4180

   Note

   • Replace the value of the host field in the route section with the service name of the oauth2-proxy in the istio-system namespace of your ACK cluster.

   • To prevent VirtualService conflicts, avoid having other VirtualServices match paths with the prefix /oauth2.

Step 5: Create an authorization policy

1. On the Mesh Management page, click the name of the ASM instance. In the left-side navigation pane, choose Mesh Security Center > AuthorizationPolicy.

2. On the AuthorizationPolicy page, click Create from YAML.

3. On the Create page, select a Namespaces and a Scenario Template, configure the following YAML manifest, and then click Create.

   apiVersion: security.istio.io/v1beta1
   kind: AuthorizationPolicy
   metadata:
     name: oidc
     namespace: istio-system
   spec:
     action: CUSTOM
     provider:
       name: httpextauth-oidc
     rules:
       - to:
           - operation:
               notPorts:
                 - '80'
     selector:
       matchLabels:
         istio: ingressgateway

   Note

   • This AuthorizationPolicy specifies that all requests to ports other than port 80 require authorization.

   • For provider.name, enter the name of your associated custom authorization service. You can find this name in the list on the Custom Authorization Service page.

Step 6: Verify the integration

1. In your browser, navigate to http://${ASM_INGRESS_GATEWAY_ADDRESS}:80.

   Expected result: The OAuth2 Proxy login page appears with a Sign in with OpenID Connect button, indicating that single sign-on is enabled.

2. Click Sign in with OpenID Connect. On the Keycloak login page, enter the credentials for the test user created in Step 3 and click Log In.

   Expected result: After you log in, the httpbin.org page is displayed. It includes API categories such as HTTP Methods, Auth, Status codes, and Request Inspection.

3. Click Request inspection, and then select /headers > try it out > Execute.

   Expected result: In the Server response section, the response body contains the request header information, including an Authorization: Bearer {JWT} field. This indicates that the request carries the JWT token issued by Keycloak.

4. Decode the JWT token from the previous step (the string that follows Bearer) by using a JWT debugger. For more information about JWT debuggers, see JWT debugger.

   Expected result: After the token is successfully decoded, the decoded token shows that the algorithm in the HEADER is RS256 and the PAYLOAD contains claims such as realm_access (role information), preferred_username (username), and client_id (oauth2proxy). This confirms that the JWT has been verified by ASM and includes the user information stored in Keycloak.