Fork me on GitHub
Teleport

SSH Authentication with Google Workspace (G Suite)

Using Google Workspace SSO with Teleport

Using Google Workspace SSO with Teleport

Length: 10:41

Google Workspace as SSO for SSH

This guide will cover how to configure Google Workspace to be a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like:

  • Only members of "DBA" Google group can SSH into machines running PostgreSQL.
  • Developers must never SSH into production servers.
  • ... and many others.
Version Warning
This guide requires an enterprise version of Teleport.

Prerequisites

Before you get started you’ll need:

  • An Enterprise version of Teleport downloaded from https://dashboard.gravitational.com/.
  • Be a Google Workspace Super Admin. As Google Best Practices, we would recommend setting up a separate super admin with 2FA vs using your user.
  • Ability to create GCP Project.
    • This might require signing up to GCP, but for this project it won’t require using any paid services. It’s just a side effect of G Suite and GCP being closely related.
  • Have a verified Domain.
  • Ability to Setup Google Workspace Groups

Configure G Suite

  1. Obtain OAuth 2.0 credentials https://developers.google.com/identity/protocols/OpenIDConnect
  2. Create a new Project.
    Create New Project
  3. Select OAuth client ID.
    Create OAuth Creds
  4. Make Application Type Public & Setup Domain Verification
    Setup Application Type
  5. Copy OAuth Client ID and Client Secret for YAML Below. Note: The redirect_url: https://teleport.example.com:3080/v1/webapi/oidc/callback
Copy Client Secret

Create a Service Account

Create OAuth Creds

Leave Service account users roles, and admin roles as blank.

Create OAuth Creds

Leave Service account permissions as blank.

Create OAuth Creds

Enable Account Delegation

Create OAuth Creds
Create OAuth Creds

Download Service Account JSON

Create OAuth Creds

This JSON file will need to be uploaded to the Authentication server, and will be later referenced by the OIDC Connector, under google_service_account_uri or inline with google_service_account.

Note
Teleport requires the service account JSON to be uploaded to all Teleport authentication servers when setting up in a High Availability config.

Manage API Scopes

Before setting the Manage API client access capture the client ID of the service account.

Within GSuite to access the Manage API client access go to Security -> Settings. Navigate to Advanced Settings and open Manage API client access. Put the client ID in the Client Name field and the below permissions in the API scopes as a single comma separated line. Press Authorize.

Warning
Do not use the email of the service account. The configuration display will look the same but the service account will not have the domain-wide delegation required. The client_id field must be the unique ID number captured from the admin UI. An indicator that this is misconfigured is if you see "Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested." in your log.
Note
The email that you set for google_admin_email must be the email address of a user that has permission to list all groups, users, and group membership in your G Suite account. This user will generally need super admin privileges.

Client Name: For Client Name: Use the Unique ID for the service account. See Video for instructions.

API Scopes: Copy these three API Scopes.

https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly
Create OAuth Creds

Create a OIDC Connector

Now, create a OIDC connector resource. There are two options for setting the google_service_account value. You can set the JSON file in the auth server and give a URI to the file. The second is populating the contents via inline. Inline is required for Teleport Cloud. Write down this template as gsuite-connector.yaml:

kind: oidc
metadata:
  name: google
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - auditor
    value: <[email protected]>
  - claim: groups
    roles:
    - access
    value: [email protected]
  client_id: <GOOGLE_WORKSPACE_CLIENT_ID>.apps.googleusercontent.com
  client_secret: <OAUTH_CLIENT_SECRET>
  display: Google
  google_admin_email: <GOOGLE_WORKSPACE_ADMIN_EMAIL>
  google_service_account_uri: file:///var/lib/teleport/gworkspace-creds.json
  issuer_url: https://accounts.google.com
  redirect_url: https://<cluster-url>:3080/v1/webapi/oidc/callback
  scope:
  - openid
  - email
version: v2

Create the connector using tctl tool:

$ tctl create gworkspace-connector.yaml

Testing

The Web UI will now contain a new button: "Login with Google". The CLI is the same as before:

$ tsh --proxy=proxy.example.com login

This command will print the SSO login URL (and will try to open it automatically in a browser).

Tip
Teleport can use multiple OIDC connectors. In this case a connector name can be passed via tsh login --auth=google

Troubleshooting

If you get "access denied" errors the number one place to check is the audit log on the Teleport auth server. It is located in /var/lib/teleport/log by default and it will contain the detailed reason why a user's login was denied.

Example of a user being denied due as the role clusteradmin wasn't setup.

{"code":"T1001W","error":"role clusteradmin is not found","event":"user.login","method":"oidc","success":false,"time":"2019-06-15T19:38:07Z","uid":"cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"}

Some errors (like filesystem permissions or misconfigured network) can be diagnosed using Teleport's stderr log, which is usually available via:

$ sudo journalctl -fu teleport

If you wish to increase the verbosity of Teleport's syslog, you can pass the --debug flag to teleport start command.

Have a suggestion or can’t find something?
IMPROVE THE DOCS