Deploy JIT Groups

This article describes how to deploy JIT Groups in your Google Cloud organization. The deployment uses Terraform and creates the following resources:

• An App Engine application that runs JIT Groups and can be accessed through Identity-Aware Proxy.
• An OAuth consent screen and client ID for Identity-Aware Proxy.
• A service account that JIT Groups uses to access Google Cloud and Cloud Identity APIs. The service account is attached to the App Engine application.
• A Secret Manager secret to store credentials for your SMTP server.
• A Cloud Storage bucket to store Terraform state.

Before you begin

To complete the deployment, you need the following:

• A Google Cloud project to deploy the JIT Groups application in.
• Super-admin access to your Cloud Identity or Google Workspace account.

You also need one of the following premium subscriptions:

• Cloud Identity Premium
• Google Workspace Enterprise Standard, Plus, or Education

Tip

It's sufficient to purchase licenses for a subset of your users, or even a single user.

JIT Groups requires a premium subscription, but doesn't require a premium license for all users. The presence of a subscription is sufficient to enable all users to use JIT Groups, including those users that only have a Cloud Identity Free license.

JIT Groups requires one of these premium subscription because it uses group membership expirations, which is a premium feature. Without a premium subscription, you can deploy JIT Groups, but attempting to join a group will fail.

If you don't have a Cloud Identity Premium or Google Workspace Enterprise subscription, you can trial Cloud Identity Premium for free:

Trial Cloud Identity Premium

Prepare the project

Create a Cloud Storage bucket and configure Terraform to use this Cloud Storage bucket for storing its state:

1. Open Cloud Shell or a local terminal.

   Open Cloud Shell

2. Authorize gcloud:

   gcloud auth login
   

   You can skip this step if you're using Cloud Shell.

3. Set an environment variable to contain your project ID:

   gcloud config set project PROJECT_ID
   

   Replace PROJECT_ID with the ID of the project to deploy JIT Groups in.

4. Create a Cloud Storage bucket to store the Terraform state and enable object versioning:

   PROJECT_ID=$(gcloud config get core/project)
   gcloud services enable cloudresourcemanager.googleapis.com storage-api.googleapis.com
   gcloud storage buckets create gs://$PROJECT_ID-state --uniform-bucket-level-access
   gcloud storage buckets update gs://$PROJECT_ID-state --versioning
   

5. Create an empty directory and enter the directory:

   mkdir -p deployment && cd deployment
   

6. Create a configuration file that instructs Terraform to store its state in the Cloud Storage bucket:

   cat <<EOF > _project.tf
   terraform {
     backend "gcs" {
       bucket   = "$PROJECT_ID-state"
       prefix   = "terraform"
     }
   }
   
   locals {
     project_id = "$PROJECT_ID"
   }
   
   provider "google" {
     project    = local.project_id
   }
   
   EOF
   

7. Authorize terraform:

   gcloud auth application-default login &&
     gcloud auth application-default set-quota-project $PROJECT_ID
   

   You can skip this step if you're using Cloud Shell.

Deploy the application

Use Terraform to deploy JIT Groups to App Engine.

Note

JIT Groups can be deployed to either App Engine or Cloud Run. Cloud Run requires a more complex configuration than deploying the application to App Engine. This article therefore focuses on App Engine.

1. Clone the GitHub repository to the target directory and switch to the jitgroups/latest branch:

   git clone https://github.com/GoogleCloudPlatform/jit-access.git --branch jitgroups/latest target
   

2. Create a Terraform configuration file named main.tf and paste the following content:

   module "application" {
       source                      = "./target/terraform/jitgroups-appengine"
       project_id                  = local.project_id
       customer_id                 = "CUSTOMER_ID"
       groups_domain               = "DOMAIN"
       admin_email                 = "ADMIN_EMAIL"
       location                    = "LOCATION"
       iap_users                   = []
       environments                = []
       options                     = {
           # "APPROVAL_TIMEOUT"    = "90"
       }
   }
   
   output "url" {
       value                       = module.application.url
   }
   
   output "service_account" {
       value                       = module.application.service_account
   }
   

   Replace the following:

   • CUSTOMER_ID: your Cloud Identity or Google Workspace account's customer ID.
   • DOMAIN: the domain to use for Cloud Identity groups, this can be the primary or a secondary domain of your Cloud Identity or Google Workspace account.
   • ADMIN_EMAIL: the email address to show as contact on the OAuth consent screen, this must be the email address of a Cloud Identity/Workspace user.
   • LOCATION: a supported App Engine location.

   • iap_users (optional): List of users or groups to allow access to the JIT Groups application.

     • Prefix users with user:, for example user:bob@example.com.
     • Prefix groups with group:, for example user:eng@example.com.
     • To allow all users of your Cloud Identity or Workspace account, use domain:PRIMARY_DOMAIN where PRIMARY_DOMAIN is the primary domain of your Cloud Identity or Google Workspace account.

   • environments List of environment service accounts, leave empty for now.

   • options (optional): Map of additional configuration options.

3. Initialize Terraform:

   terraform init 
   

4. Apply the configuration:

   terraform apply 
   

   Note

   Because of internal provisioning delays, you might encounter the following error when you run terraform apply for the first time:

   Error waiting for Creating StandardAppVersion: Error code 13, message:
   Failed to create cloud build
   

   If you encounter this error, rerun terraform apply.

   When the command completes, it prints the URL of the application and the email address of the application's service account. You need this URL and email address later.

Grant access to Cloud Identity/Workspace

To allow JIT Groups to manage Cloud Identity security groups, you must grant it the Groups Admin role in your Cloud Identity or Workspace account. Because this step requires super-admin access to your Cloud Identity or Workspace account, it's not performed automatically by Terraform.

You only need to perform these steps once.

1. Open the Google Admin console and sign in as a super-admin user.

2. Go to Account > Admin Roles:

   Open Admin Roles

3. Click Groups Admin > Admins.

4. Click Assign service accounts.
5. Enter the email address of the application's service account that you obtained after running terraform apply. Then click Add.
6. Click Assign role.

Access the JIT Groups web interface

You can now access the JIT Groups web interface:

1. Open a browser and navigate to the URL that you obtained after running terraform apply.

2. Authenticate with a user account that's allowed to access the JIT Groups application. These user accounts include:

   • The user configured as admin_email in the Terraform configuration.
   • All users or groups configured in iap_users in the Terraform configuration.

Because you haven't configured an environment yet, JIT Groups uses an example environment named example. This environment demonstrates some of the features provided by JIT Groups, but doesn't let you request access to any groups or resources.

To configure an environment, see Add an environment.

Optional: Configure email notifications

You can configure a JIT group so that joining the group requires approval from another user. To notify users about pending approvals, JIT Groups must be able to send emails.

To let JIT Groups send emails, you must grant it access to an SMTP mail server. You can use Google Workspace, Microsoft 365, or any other SMTP server for this purpose.

To configure email notifications, do the following:

1. Obtain credentials for your SMTP server:

   Google WorkspaceMicrosoft 365

   You can let JIT Groups send email through Google Workspace by using the Gmail SMTP server and a dedicated Google Workspace user account.

   To create a new user account in Google Workspace, do the following:

   1. Open the Google Workspace Admin Console and sign in as a super-admin user.
   2. In the menu, go to Directory > Users and click Add new user to create a user.

   3. Provide an appropriate name and email address such as the following:

      • First Name: a name such as JIT Groups
      • Last Name: a name such as Notifications
      • Primary email: an email address such as jitgroups-notifications

   4. Click Manage user's password, organizational unit, and profile photo and configure the following settings:

      • Password: Select Create password and set a password
      • Ask for a password change at the next sign-in: Disabled

   5. Click Add new user.

   6. Click Done.

   Assign a Google Workspace license to the new user account:

   1. Refresh the list of users.
   2. Open the details for the user account that you just created.
   3. Click Licenses.

   4. Set the status for Google Workspace to assigned.

      Important

      You must assign a Google Workspace license. Without a Google Workspace license, the Gmail SMTP server rejects email delivery.

   5. Click Save.

   Create an app password for the new user account:

   1. Open an incognito browser window and go to Google Accounts .
   2. Sign in with the new user account that you created.
   3. Go to Security > Signing in to Google > 2-step verification and follow the steps to turn on 2-step verification .

   4. Go to Security > Signing in to Google > App passwords

      Note

      The App passwords link isn't shown if you haven't turned on 2-step verification yet.

   5. On the App passwords page, use the following settings:

      1. Select app: Select Mail
      2. Select device: Select Other and enter a name such as JIT Access

   6. Click Generate.

      Take note of the generated app password, because you need it later.

   You can let JIT Groups send email through Microsoft 365 by using an Office 365 mailbox and SMTP AUTH .

   1. Open the Admin Center .

   2. Go to Users > Active users and add a new user . Provide an appropriate name and email address such as the following:

      • First Name: a name such as JIT Groups
      • Last Name: a name such as Notifications
      • Primary email: an email address such as jitgroups-notifications

      Take note of the user's password, because you need it later.

   3. Enable SMTP AUTH for the new user.

2. Save the SMTP password in Secret Manager:

   echo "Enter SMTP password:" && (read -s PASSWORD && \
     echo "Saving..." &&
     echo $PASSWORD | gcloud secrets versions add smtp --data-file=-)
   

3. Open your existing Terraform configuration and the following two lines to the application module:

   module "application" {
       source                      = ...
       project_id                  = ...
       ...
   
       smtp_host                   = "SMTP_HOST"
       smtp_user                   = "SMTP_USER"
   }
   

   Replace the following:

   Google WorkspaceMicrosoft 365Other email provider

   • SMTP_HOST: smtp.gmail.com
   • SMTP_USER: the email address of the Google Workspace user that you created previously, for example jitgroups-notifications@example.org

   • SMTP_HOST: smtp.office365.com
   • SMTP_USER: the email address of the Microsoft 365 user that you created previously, for example jitgroups-notifications@example.org

   • SMTP_HOST: DNS name of the SMTP server
   • SMTP_USER: user name for authentication

4. Apply the configuration change:

   terraform apply 
   

Optional: Submit your configuration to Git

To simplify future upgrades and configuration changes, submit your configuration to Git:

1. Initialize a git repository:

   git init
   

2. Create a .gitignore that excludes the JIT Groups source code and local Terraform files from being committed to the repository:

   cat << EOF > .gitignore
   # JIT Groups source code
   target/
   
   # Local .terraform directories
   **/.terraform/*
   .terraform.*
   EOF
   

3. Commit your changes:

   git add -A && git commit -m 'Initial JIT Groups deployment'
   

What's next

Add an environment