Google Workspace Plugin for OPKSSH

• Google Workspace Plugin for OPKSSH
  • Overview
    • Why do I need a custom OAuth application instead of using the default one?
    • Why do I need a custom plugin for OPKSSH?
  • Configuration
    • Google Workspace (Google Admin)
    • OpenSSH Client and Server (End-User and DevOps)
  • How it works

Overview

Read the article from Cloudflare: Open-sourcing OpenPubkey SSH (OPKSSH): integrating single sign-on with SSH

This plugin enables opkssh to authenticate users from Google Workspace and authorize them based on Google Groups.

Why do I need a custom OAuth application instead of using the default one?

Aspect	Default OPKSSH configuration	Your custom OAuth App
Control over who can log in	Open to all Google accounts	You control domain or allow-list via policy
OAuth consent screen branding	Generic (Cloudflare/OpenPubkey)	Shows your company name
Visibility into usage/logs	None	Full via Google Cloud Console
User trust during login	"Unknown app" warning	Branded with your organization—more trustworthy
Best practice	Not suitable for enterprise/prod use	Recommended for production use

Why do I need a custom plugin for OPKSSH?

Requirement	opkssh	opkssh-plugin-google-workspace (internal audience of OAuth App)	opkssh-plugin-google-workspace (external audience of OAuth App)
Group-based authorization (organization users)	❌	✅	✅
Group-based authorization (external members)	❌	❌	✅

Configuration

Google Workspace (Google Admin)

• Create a Google Cloud project "opkssh" to hold the necessary OAuth application and Service Account within your Google Workspace. Complete this guide to obtain:

  • Google Cloud Project to hold the OAuth application and Service Account

• Create an OAuth application "opkssh" to enable authentication of your employees and contractors via the opkssh client. Complete this guide to obtain:

  • Client ID of the OAuth application
  • Client Secret of the OAuth application

• Create a Service Account "opkssh" to allow opkssh-plugin-google-workspace to perform group-based authorization of your employees on your servers. Complete this guide to obtain:

  • Email of the Service Account
  • JSON file with the API Key of the Service Account
  • Customer ID of Google Workspace

⚠️ You need a Service Account only if you want to use the opkssh-plugin-google-workspace plugin.

OpenSSH Client and Server (End-User and DevOps)

• Configure SSH on both client and server.

How it works

The latest github.com/openpubkey/opkssh provides "policy plugins" functionality.

Please see the official documentation from opkssh about this.

The "opkssh-plugin-google-workspace" is a "policy plugin". It receives the following environment variables from "opkssh":

• OPKSSH_PLUGIN_U - principal, your system user name to authorize
• OPKSSH_PLUGIN_EMAIL - user's email from the incoming token
• OPKSSH_PLUGIN_EMAIL_VERIFIED - whether the user's email in the incoming token is verified
• OPKSSH_PLUGIN_AUD - audience of the user's token

You can configure your policies in the configuration file /etc/opkssh-plugin-google-workspace/config.yaml. Example:

policy:
  foo:
    users:
      - work@company.name
      - personal@gmail.com
  bar:
    groups:
      - employee-group@company.name
      - contractor-group@company.name

To authorize an incoming user, the plugin needs to access the Google Admin API to fetch group members:

google:
  oauth:
    client_id: <Client ID from the "Create OAuth application 'opkssh'" guide>
  service_account:
    email:    <Service Account Email from the "Create Service Account 'opkssh'" guide>
    key_file: <Path to API Key file from the "Create Service Account 'opkssh'" guide>
  workspace:
    customer_id: <Customer ID from the "Create Service Account 'opkssh'" guide>

The plugin saves the content of the group cache to /var/cache/opkssh-plugin-google-workspace/cache.json. Default cache settings:

cache:
  path: /var/cache/opkssh-plugin-google-workspace/cache.json
  duration: 15min

The plugin writes logs to /var/log/opkssh-plugin-google-workspace.log.

A full example config with all settings:

cache:
  path: /var/cache/opkssh-plugin-google-workspace/cache.json
  duration: 15min
google:
  oauth:
    client_id: <Client ID from the "Create OAuth application 'opkssh'" guide>
  service_account:
    email:    <Service Account Email from the "Create Service Account 'opkssh'" guide>
    key_file: <Path to API Key file from the "Create Service Account 'opkssh'" guide>
  workspace:
    customer_id: <Customer ID from the "Create Service Account 'opkssh'" guide>
policy:
  foo:
    users:
      - work@company.name
      - personal@gmail.com
  bar:
    groups:
      - employee-group@company.name
      - contractor-group@company.name