Google Workspace as a User Directory

This document provides instructions for adding users from Google Workspace (G Suite) as PrivX users. By following these instructions, you can allow users from your Google Workspace to log into PrivX. Such users may then be granted SSH/RDP access similarly to regular AD users.

Disclaimers

This document includes instructions regarding third-party products by Google. These instructions are provided for general guidance only.

Documentation involving third-party products include configuring client permissions in Google Workspace, and setting up clients in Google Developers Console (GDC). The instructions in this manual were verified against the Google products current in March 2019. These instructions will need to be adapted when using other versions of Google products.

SSH Communications Security Corporation does not make any warranties as to the accuracy, reliability, or usefulness of these instructions, or guarantee that the content related to third-party products is up to date.

SSH Communications Security Corporation does not provide any warranties regarding third-party products, such as Google Workspace, nor provide any support or other services for third- party products.

For instructions about setting up and operating Google products, we always recommend that you consult the official Google documentation intended for the specific version(s) of Google products in your use, and/or directly contact Google representatives or support.

Prerequisites

Check and ensure the following before performing the procedures in this document:

• Your Google Workspace domain must include the users and groups that are to access PrivX.
• You will need administrative access to Google Workspace Admin Console.
• You will need superuser access to PrivX.

Integration Steps

The high-level workflow for allowing Google Workspace users to log into PrivX:

1. Set up clients for integration.
2. Allow clients to access Google Workspace.
3. Configure Google Workspace as a user directory in PrivX.
   These steps are described in more detail in the following sections.

Set Up Clients for Integration

To integrate Google Workspace to PrivX, you need to create the following clients:

• A service account with a JSON key, for fetching user data from Google Workspace.
• A web application, for authenticating Google Workspace users to PrivX.

First, you must create a project for containing the clients. To do this:

1. Access the Google Developers Console (GDC).
2. Create a new project. The project must be associated to your Google Workspace domain by Organization and Location.

Further operations are performed under this project. Ensure it is selected before proceeding.

1. Enable the Admin SDK for the project: Under APIs & Services→Library, click Admin SDK, then click Enable.
2. Authorize your PrivX domain for OAuth authentication: Under APIs & Services→Credentials→OAuth consent screen, specify the top private domain(s) of your PrivX deployment under Authorized domains. For example. If you access PrivX at privx.example.com, then the Authorized domains should include example.com

After creating the project, create the service account as follows:

1. Under IAM & Admin, click Create Service Account. Provide the required information with the following requirements in mind:

• Do not specify any roles nor users for the service account.
• Create a key for the service account. The key must be in JSON format. The key is required later for configuring PrivX.

1. Enable Google Workspace Domain Wide Delegation for the service account. To accomplish this, you must Edit the service account after it has been created.

Then create the web application:

1. Under APIs & Services→Credentials, click Create Credentials and select OAuth client ID. Provide at least the following information:

• For Application type, select Web application.
• For _Authorized redirect URIs, provide an address like the following (replace with the actual address of your PrivX deployment):
  https://<privx-fqdn>/auth/api/v1/oidc-cb
  For example, if you access PrivX at privx.example.com, then the Authorized redirect URI should be set to:
  https://privx.example.com/auth/api/v1/oidc-cb

1. After you Save the web application, note the client ID and the client secret. These are required later for configuring PrivX.

You have now created the necessary clients. You may verify your service account and web application back on the APIs & Services→Credentials page.

Client access to Google Workspace

The service-account client must be given access to user and user-group data from Google Workspace. To do this:

1. Access the Google Workspace Admin Console.
2. On the Admin-Console main page, click Security, then under Advanced settings, click Manage API client access.
3. Under Client name, provide the numerical Client ID of the service account (created earlier).

For API scopes, provide the following:
https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly

Click Authorize. You may verify that the service account was added with correct permissions.

Google Workspace now allows sufficient access to clients.

Add Google Workspace directory to PrivX

Add Google Workspace as a user directory in PrivX. To do this:

Access the PrivX GUI as a superuser.

On the Settings→Directories page, click Add Directory.

Provide the required information about your Google Workspace and clients. You will at least have to provide:

• A Name.
• The directory Type: Google Workspace.
• Your G-Suite Domain and the Domain admin email.
• The Config JSON of your service account (created earlier).
• The Client ID and the Client secret of your web application (not the service account).
• A Login button title.

After saving your changes, verify that the Status of the Google Workspace directory is OK back on the Settings→Directories page.

Google Workspace users can log into PrivX after PrivX finishes retrieving their data.

PrivX login for Google Workspace users

You may verify integration by logging in as a G-Suite user. To do this, go to the PrivX-GUI login screen and click the login button (matching the Login button title configured earlier).

On successful integration you will be directed to Google login. After providing your credentials you should be logged into PrivX. Integragration is now complete.

Post-integration actions

Before Google Workspace users can access target hosts, they must be given permissions via PrivX roles.
For more information about configuring roles for permissions, see Granting User Permissions.

Troubleshooting

Symptom: G-suite users can log in, but do not receive proper user name or group memberships.
Possible solution: Ensure that the service-account credentials are correct.