This document provides instructions for adding users from Google G Suite (G Suite) as PrivX users. By following these instructions, you can allow users from your G Suite 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 G Suite, 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 G Suite, 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 G Suite domain must include the users and groups that are to access PrivX.
  • You will need administrative access to G Suite Admin Console.
  • You will need superuser access to PrivX.

Integration Steps

The high-level workflow for allowing G Suite users to log into PrivX:

  1. Set up clients for integration.
  2. Allow clients to access G Suite.
  3. Configure G Suite as a user directory in PrivX.

These steps are described in more detail in the following sections.

Set Up Clients for Integration

To integrate G Suite to PrivX, you need to create the following clients:

  • A service account with a JSON key, for fetching user data from G Suite.
  • A web application, for authenticating G Suite 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 G Suite domain by Organization and Location.

    Further operations are performed under this project. Ensure it is selected before proceeding.
  3. Enable the Admin SDK for the project: Under APIs & Services→Library, click Admin SDK, then click Enable.
  4. 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.
  2. Enable G Suite 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 <privx-fqdn> 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
  2. 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 G Suite

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

  1. Access the G Suite 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.


    Always use the numerical Client ID instead of the service-account email for the Client Name. G Suite contains an error where it may silently fail to authorize clients by email.

    You can obtain the numerical Client ID of your service account from the client_id field in its JSON key, or from GDC under APIs & Services→Credentials.

    You only need to authorize your service-account client in G Suite (not the web-application client)

G Suite now allows sufficient access to clients.

Add G Suite Directory to PrivX

Add G Suite as a user directory in PrivX. To do this:

  1. Access the PrivX GUI as a superuser.
  2. On the Settings→Directories page, click Add Directory.

    Provide the required information about your G Suite and clients. You will at least have to provide:
    • A Name.
    • The directory Type: Google G Suite.
    • 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 G Suite directory is OK back on the Settings→Directories page.

G Suite users can log into PrivX after PrivX finishes retrieving their data.

PrivX Login for G-Suite 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 (mathcing 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 G Suite users can access target hosts, they must be given permissions via PrivX roles.

For more information about configuring roles for permissions, refer to the PrivX Administrator Manual.

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.