Authenticating with Keycloak demo

This page is for platform administrators.

Keycloak is an open source software identity and access management product. You can set it up as an OIDC provider for a quick demo.

Before you begin

To install and enable Keycloak, you need to have a Kubernetes cluster that has an Ingress address that is accessible from your Anthos private mode deployment. An Anthos private mode admin cluster is used as an example in this page.

You also must have created a custom domain name for Anthos private mode Management Center. See Configure domain name to access Management Center.

  1. Export the Management Center domain name as a variable, for example:

    export ANTHOS_MANAGEMENT_CENTER=anthos.example.com
    
  2. Export a private registry as a variable, for example:

    export PRIVATE_REGISTRY=10.200.0.2/library
    

Download Keycloak image and push to the private registry

  1. Download the Keycloak image from dockerhub:

    actl images save \
      --output keycloak-image \
      jboss/keycloak:12.0.2
    
  2. Push the Keycloak image to the private registry:

    actl images push \
      --images keycloak-image \
      --private-registry=${PRIVATE_REGISTRY}
    

Deploy Keycloak

Update your DNS configuration and generate a certificate to deploy Keycloak.

  1. Create the Keycloak service to expose the IP for Keycloak:

    kubectl create -f - <<EOF
    apiVersion: v1
    kind: Namespace
    metadata:
      name: keycloak
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: keycloak-svc
      namespace: keycloak
      labels:
        app: keycloak
    spec:
      ports:
      - name: http
        port: 80
        targetPort: 8080
      - name: https
        port: 443
        targetPort: 8443
      selector:
        app: keycloak
      type: LoadBalancer
    EOF
    
  2. After an IP is allocated by the LoadBalancer, export the IP into a variable, for example:

    export KEYCLOAK_SVC_IP=$(kubectl get services -n keycloak \
        -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')
    
  3. Add an "A record" to your DNS domain configuration and set it to ${KEYCLOAK_SVC_IP}:

    export KEYCLOAK_SVC=keycloak.example.com
    
  4. Generate a self-signed certificate for Keycloak to use for TLS.

    openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -subj \
        "/CN=${KEYCLOAK_SVC}" \
        -addext "subjectAltName = DNS:localhost,DNS:${KEYCLOAK_SVC},IP:${KEYCLOAK_SVC_IP}" \
        -out "tls.crt" -keyout "tls.key"
    
  5. Upload the certificate and private key into the cluster:

    kubectl create secret tls tls-config -n keycloak --cert=tls.crt \
        --key=tls.key
    
  6. Run the following command to deploy Keycloak:

    kubectl create -f - <<EOF
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: keycloak
      namespace: keycloak
      labels:
        app: keycloak
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: keycloak
      template:
        metadata:
          labels:
            app: keycloak
        spec:
          volumes:
          - name: tls-config-volume
            secret:
              secretName: tls-config
              items:
              - key: tls.crt
                path: tls.crt
              - key: tls.key
                path: tls.key
          containers:
          - name: keycloak
            # Set the image as original path but the actual image will be pulled from the registry mirror,
            # which was configured by 'actl push' command.
            image: jboss/keycloak:12.0.2
            # Keycloak uses certificates stored in /etc/x509/https to set up TLS.
            # https://github.com/keycloak/keycloak-containers/blob/master/server/README.md#setting-up-tlsssl
            volumeMounts:
            - name: tls-config-volume
              mountPath: "/etc/x509/https"
            env:
            - name: KEYCLOAK_USER
              value: "admin"
            - name: KEYCLOAK_PASSWORD
              value: "admin"
            - name: PROXY_ADDRESS_FORWARDING
              value: "true"
            ports:
            - name: http
              containerPort: 8080
            - name: https
              containerPort: 8443
            readinessProbe:
              httpGet:
                path: /auth/realms/master
                port: 8080
    EOF
    

Set up the Keycloak user and client

Open the Keycloak console on the admin workstation and log in with KEYCLOAK_USER and KEYCLOAK_PASSWORD in the keycloak.yaml file. By default these values are KEYCLOAK_USER=admin and KEYCLOAK_PASSWORD=admin. If needed, accept the self-signed certificate in your browser. If you are prompted in Chrome with a warning about an untrusted certificate, enter thisisunsafe in the dialog.

echo "Keycloak console: https://${KEYCLOAK_SVC}"

Create a realm

  1. Hover over Master on the top left, and click Add realm.
  2. Enter anthos as the name of your new realm, and click Create.
  3. In Realm settings > Tokens, change the Access Token Lifespan to 1 Hour to prevent the token from expiring too early and click Save.

Create a user

  1. In the left navigation bar, click Users, and then click Add user.
  2. Configure the following settings for the user, and then click Save.
    1. Username: anthos-platform-admin
    2. Email: anthos-platform-admin@example.com
    3. User enabled: ON
    4. Email Verified: ON
  3. In the Credentials tab, fill in the Password and Password Confirmation fields. Click Set Password, and validate when prompted.

Create a client

  1. In the left navigation bar, click Clients, and then click Create.
  2. Configure the following settings for the client, and then click Save. ANTHOS_MANAGEMENT_CENTER is the custom domain name you use for Management center.
    1. Client ID: anthos
    2. Client protocol: openid-connect
    3. Root URL: https://ANTHOS_MANAGEMENT_CENTER
  3. Go to the management page of the newly created client.
  4. On the Settings tab of the client management page, perform the following steps:
    1. Set the Access Type to confidential.
    2. Add the following URIs to Valid Redirect URIs.
      • http://localhost:9879/callback
      • https://ANTHOS_MANAGEMENT_CENTER/_gcp_anthos_oidc_callback
    3. Click Save.
  5. In the Credentials tab of the client management page, select Client ID and Secret as Client Authenticator.
  6. Note the secret somewhere.
    1. In the left navigation bar, click Groups, and then click New.
    2. Enter the name of your group: anthos-platform-admin-group.
    3. Navigate back to the User tab on the left, and click View all users.
    4. Click the user that you just created (anthos-platform-admin) and click the Groups tab.
    5. Under Available Groups, select the group that you created, anthos-platform-admin-group, and click Join.
    6. Navigate back to the anthos client management page.
    7. Click Mappers tab and then click Create:
      1. Enter the name for this mapper: anthos-platform-admin-group-mapper.
      2. From the Mapper Type drop-down list, select Group Membership.
      3. Token Claim Name is the attribute value shown in the authentication token. The default value in Anthos private mode is "groups", so you can use groups in this field. Remember that you'll need to modify the OIDC configuration's GroupsClaim field with this value if the Token Claim Name name is not groups.
      4. Make sure Full group path is disabled.
      5. Make sure Add to ID Token, Add to access token and Add to userinfo are all enabled.
      6. Click Save.

Enable OIDC authentication

Obtain the OIDC provider URL to use in the following steps.

  1. Run the following command:

    export ISSUER_URL=https://${KEYCLOAK_SVC}/auth/realms/anthos
    echo "Issuer URL: ${ISSUER_URL}"
    
  2. Using the tls.crt from earlier, generate the Base64 encoded certificate.

    export BASE64_CERT=$(openssl base64 -A -in tls.crt)
    echo "Use the following string as the base64-encoded certificate for the OIDC provider: ${BASE64_CERT}"
    
  1. In Management Center Console, open the Identity and Access menu.
  2. In the Identity tab, click Set Up Anthos Identity Service (OIDC)
  3. Create the profile for Keycloak by completing the following fields, and then click Submit:

    1. Profile Name: keycloak
    2. OIDC Provider URL: The Issuer URL from the Enable OIDC authentication section.
    3. OIDC Client ID: anthos
    4. OIDC Client Secret: the client secret from the Create a client section
    5. Username Claim: email
    6. Username Prefix: keycloak-
    7. Groups Claim: the Groups Claim from the Set up group membership section. If you leave this field empty, the value is groups.
    8. Group Prefix: keycloak-
    9. Scopes: email openid
    10. Extra Parameters: access_type=offline
    11. Certificate Authority Data: Use the base64-encoded certificate from the Enable OIDC authentication section.
  4. Click Apply profiles to clusters, and click the Admin Cluster tab.

  5. For Profiles, choose the "keycloak" profile that you just created.

  6. For the Domain name, enter ANTHOS_MANAGEMENT_CENTER.

  7. For Initial Platform Admin, always add the user prefix before your username. For example, if you are adding anthos-platform-admin@example.com, enter keycloak-anthos-platform-admin@example.com.

  8. Click Submit and wait a minute for the various system components to be reconfigured.

  9. In an incognito window, navigate to https://ANTHOS_MANAGEMENT_CENTER. You are redirected to a Keycloak login page, where you can log in as anthos-platform-admin (after setting a permanent password).

Alternate approach by applying a YAML file

  1. Set the IDP provider for the Domain. If the DomainConfig is already created for the domain, patch the object to set the authentication method name to use for the domain with this command:

    kubectl patch domainconfig anthos.example.com --type=json -p='[{"op": "replace", "path":
    "/spec/authMethodName", "value":"keycloak"}]'
    

    If the DomainConfig is not created for the domain, create it with this command:

    kubectl create -f - <<EOF
    apiVersion: managementcenter.anthos.cloud.google.com/v1
    kind: DomainConfig
    metadata:
      name: anthos.example.com
    spec:
      authMethodName: keycloak
    EOF
    
  2. Create clientconfig-patch.yaml with the following content:

    # Use this to set the OIDC configuration of Keycloak:
    # kubectl patch ClientConfig default -n kube-public --type=merge --patch $(cat clientconfig-patch.yaml)
    spec:
      authentication:
      # The name of the OIDC configuration to create.
      - name: keycloak
        oidc:
          # ID for the client application that makes authentication requests to the OpenID provider.
          clientID: anthos
          # ID for the client application that makes authentication requests to the OpenID provider.
          clientSecret: YOUR_CLIENT_SECRET
          # The URI to redirect users going through the OAuth flow using cloud console.
          # This is not supported by Anthos private mode.
          cloudConsoleRedirectURI: http://cloud.console.not.enabled
          # Additional key-value parameters (comma-separated) to send to the OpenID provider.
          extraParams: access_type=offline
          # URL where authorization requests are sent to your OpenID.
          issuerURI: YOUR_ISSUER_URI
          # The redirect URL that kubectl uses for authorization.
          kubectlRedirectURI: http://localhost:9879/callback
          # Additional scopes to send to the OpenID provider.
          scopes: openid email
          # JWT claim to use as the username. You can choose other claims, such as email or name,
          # depending on the OpenID provider. However, claims other than email are prefixed
          # with the issuer URL to prevent naming clashes.
          userClaim: email
          # A base64-encoded PEM-encoded certificate for the OIDC provider. To create the string,
          # encode the certificate, including headers, into base64. Include the resulting string
          # in certificateAuthorityData as a single line.
          certificateAuthorityData: YOUR_CERTIFICATE
    
  3. Edit clientconfig-patch.yaml with the settings for Keycloak.

    sed -i "s|YOUR_ISSUER_URI|${ISSUER_URL}|g" clientconfig-patch.yaml
    sed -i "s|YOUR_CERTIFICATE|${BASE64_CERT}|g" clientconfig-patch.yaml
    
  4. Replace YOUR_CLIENT_SECRET with the client secret obtained from the Credentials tab in Keycloak.

  5. Run the following command to configure OIDC:

    kubectl patch ClientConfig default -n kube-public --type=merge \
        --patch "$(cat clientconfig-patch.yaml)"
    
  6. Wait a minute for the various system components to be reconfigured.

  7. Follow the instructions in Configure authorization roles to set up the initial platform admin account.

  8. In an incognito window, navigate to https://ANTHOS_MANAGEMENT_CENTER. You are redirected to a Keycloak login page, where you can log in as anthos-platform-admin (after setting a permanent password).

Delete Keycloak

After you have finished using the Keycloak demo, delete the Keycloak installation.

kubectl delete ns keycloak

What's next