Kubernetes and Google Workspace

Google Workspace offers an identity provider that can be used with your Kubernetes clusters. In addition to providing authentication and SSO, Google Workspace provides a directory and groups API that lets you manage access to your clusters without creating RBAC bindings to specific users. This makes it much easier to audit usage of your clusters and to quickly change permissions for users as their roles change. Getting SSO to work with Google Workspace is pretty straight forward, but getting group information is not provided in the user info endpoint used by OpenID Connect clients. In this post, we'll walk you through how to configure OpenUnison to use your Google Workspace for authentication and to retrieve group memberships for your cluster users.

Why Use OpenUnison?

Since Google Workspace is an OpenID Connect (OIDC) provider, why would we use OpenUnison? Why not just use the kube-login oidc plugin for kubectl? There are a few good reasons to use OpenUnison:

Groups Support - The kube-login plugin only retrieves an id_token from your identity provider (in this case Google Workspace) and hands it off to Kubernetes. It doesn't have any capability to use Google Workspace's APIs to generate an id_token that includes group information.
Multi Cloud - OpenUnison supports your deployments regardless of if your cluster is running on-prem or in a public cloud. The kube-login plugin can only work when you're using a cluster that supports direct integration with OpenID Connect, which excludes most public cloud offerings.
Multi Cluster - OpenUnison can be the authentication services for not just one cluster, but for all of your clusters without setting up specific trusts with Google Workspace. This can become important if you want to automate cluster rollout without having to involve the Workspace team.
Support Cluster Management Applications - Your clusters are generally made up of more then just Kubernetes. Grafana dashboards, ArgoCD, the Kubernetes Dashboard, etc. OpenUnison can provide authentication to all of those applications without getting the Workspace team involved.

Configuring Google Workspace

There are several steps to getting Google Workspace working with Kubernetes. It can be broken down into two high level steps:

Configure an OpenID Connect Identity Provider (IdP) - This is where you'll setup Google Workspace for SSO
Configure a service account to retrieve groups - The only reliable way to retrieve group memberships is to make a call to the Google Directory API. This step sets up the correct delegation to let OpenUnison call the api to retrieve the logged in user's groups.

The first step is to download the default OpenUnison values.yaml and uncomment the oidc section. Next, we'll configure SSO.

Configure Google Workspace for OpenID Connect

First, login to your Google Workspace API console and create a new project.

Once you have a project, within that project setup your consent screen.

Usually you'll want to configure your application as "Internal", so that any gmail user can't access your cluster, only users from inside your domain. You also don't need Google to approve internal consent screens.

Next, configure the consent screen's logo and other information. This is all just informational.

Once your consent screen is configured, the next step is to configure scopes. Click on ADD OR REMOVE SCOPES and choose the three shown below:

These scopes will give OpenUnison very basic profile information. Primarily your name and email address. Once you complete your scopes and consent screen, click on Credentials to create an OAuth 2.0 Client ID.

Configure your client id as a web application. Your Authorized redirect URIs will be https://ou.yourdomain/auth/oidc

Click on the download button next to your Client ID, to get your client id and secret. Use the Client ID as the value of oidc.client_id in your values.yaml and store your Client secret in a file on the system where you'll be running ouctl to deploy OpenUnison.

Finally, finish configuring your values.yaml's oidc section. Use the below example, but with your own clientid:

oidc:
 client_id: 431...
 issuer: https://accounts.google.com
 user_in_idtoken: false
 domain: ""
 scopes: openid email profile
 claims:
   sub: email
   email: email
   given_name: given_name
   family_name: family_name
   display_name: name
   groups: groups

Now that SSO is configured, the next step is to create a service account for retrieving user's group memberships.

Create a Google Workspace Service Account

Google doesn't provide any way to access your groups from an the OIDC transaction as a claim. The only way to load a user's groups from Google Workspace is to use the directory API, which requires administrator privileges. Since most administrators won't want to give you an administrator account just to lookup groups, Google gives you a way to create a service account for the API that can impersonate an administrator for very specific permissions. The next step is what to create to make this service account. First, go to the Credentials screen in your APIs & Services dashboard and click on CREATE CREDENTIALS to create a new Service Account:

Give your service account a name, id, and description. Don't worry about granting any service access or user access. Once the service account is created, click on it and get the Unique ID on the next screen. Also, click on KEYS and then ADD KEY. Choose a JSON file and then download it. The JSON file will contain a PEM encoded private key. Create a Secret in the openunison namespace called googlews with a single key called key that contains the private key (and ONLY the private key, do not include the rest of the json). It should look like:

apiVersion: v1
kind: Secret
metadata:
  name: googlews
  namespace: openunison
type: Opaque
data:
  key: LS0tLS1CRUdJ...

With your service account created and your key added to your cluster, the next step is to delegate permissions to your service account to read directory members from the Google Directory API. Next, have your administrator go to https://admin.google.com/ac/owl/domainwidedelegation. Click on Add New, use the Unique ID from the credentials screen you used earlier. For OAuth scopes use https://www.googleapis.com/auth/admin.directory.group.readonly. Finally, click AUTHORIZE.

In your values.yaml, add a google_ws section with the email address of your service account and the email address of the user that authorized delegation on their behalf:

google_ws:
  admin_email: "some.admin@domain.com"
  service_account_email: "openunison@project-XXXXXX.iam.gserviceaccount.com"

With OpenUnison's values.yaml file configured and your Google Workspace setup for SSO and retrieving groups, the last step is to deploy OpenUnison.

Deploying OpenUnison

Now that Google Workspace is configured, the rest of the OpenUnison values.yaml needs to be configured. Follow the instructions for deploying the OpenUnison authentication portal, but don't run the ouctl command yet. One of the many features that makes OpenUnison unique in the cloud native world is our ability to quickly be customized in a way that is maintainable and doesn't require building a new container. This is very common, especially in enterprises that have legacy identity systems that weren't built with Kubernetes in mind. To retrieve the logged in user's groups from Google's Directory API we'll create a custom AuthenticationChain that will generate the proper token, lookup the user's groups, then add them to the user's object. Since this is pretty repeatable per environment, we created a helm chart called orchestra-login-googlews. This custom AuthenticationChain is written in JavaScript, so we have everything we need from OpenUnison to make the calls.

Prior to running the deployment, add openunison.include_auth_chain: google-ws-load-groups to your values.yaml. This will tell OpenUnison to run our custom AuthenticationChain. Finally, run the ouctl command, including the additional helm chart:

ouctl install-auth-portal -s /tmp/oidc -r orchestra-login-googlews=tremolo/orchestra-login-googlews  /path/to/openunison.yaml

This command will deploy OpenUnison's helm charts for you in the correct order and make sure that each one is run successfully before moving on to the next one. If everything is configured correctly, you'll be able to create RBAC bindings to your groups and login to OpenUnison with your Google Workspace accounts. Users can then use kubectl or the Kubernetes Dashboard with their new Workspace based identity.

What's Next?

Once Kubernetes authentication is setup, you can configure your other cluster based applications to use OpenUnison for authentication so that they can also gain access to the user's groups, even if they don't know how to work with Google's Directory API. You can also configure additional clusters to use OpenUnison so that you don't need each cluster to have access to the Google Workspace secrets.

Contact Us

If you're interested in learning more about what OpenUnison can do for your enterprise or you're interested in a commercial support contract, please reach out to us to let us know!