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:

Open Cloud Shell or a local terminal.

Open Cloud Shell
Authorize gcloud:
```
gcloud auth login
```
You can skip this step if you're using Cloud Shell.
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.

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

Create an empty directory and enter the directory:
```
mkdir -p deployment && cd deployment
```
Set an environment variable to contain the primary domain of your Cloud Identity or Workspace account:
```
PRIMARY_DOMAIN=MY_DOMAIN
```
Replace MY_DOMAIN with the primary domain of your Cloud Identity or Workspace account. The primary domain is equivalent to the name of your Google Cloud organization (such as example.com).

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"
  primary_domain = "$PRIMARY_DOMAIN"
  organization_id = "$(gcloud organizations list --filter "displayName=$PRIMARY_DOMAIN" --format "value(name)")"
  customer_id = "$(gcloud organizations list --filter "displayName=$PRIMARY_DOMAIN" --format "value(owner.directoryCustomerId)")"
}

provider "google" {
  project    = local.project_id
}

EOF

Print the locals section of the configuration file:
```
grep locals _project.tf  -A 5
```
Verify that the values for project_id, primary_domain, organization_id, and account_id are set correctly.

If some of the values are empty, then it's possible that you dont' have Organization Viewer access to the Google Cloud organization. In this case, amend the values manually.

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.

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

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                 = local.customer_id
    primary_domain              = local.primary_domain
    organization_id             = local.organization_id

    admin_email                 = "ADMIN_EMAIL"
    location                    = "LOCATION"
    iap_users                   = [
        # "domain:${local.primary_domain}"
    ]
    environments                = []

    # groups_domain             = "GROUPS_DOMAIN"
    options                     = {
        # "APPROVAL_TIMEOUT"    = "90"
    }
}

output "url" {
    value                       = module.application.url
}

output "service_account" {
    value                       = module.application.service_account
}

Replace values of the following variables:

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, uncomment the line
```
"domain:${local.primary_domain}"
```
environments List of environment service accounts, leave empty for now.
groups_domain (optional): the domain to use for Cloud Identity groups. By default, the application uses the primary domain for groups.
options (optional): Map of additional configuration options.

Initialize Terraform:
```
terraform init 
```
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.

Open the Google Admin console and sign in as a super-admin user.
Go to Account > Admin Roles:

Open Admin Roles
Click Groups Admin > Admins.
Click Assign service accounts.
Enter the email address of the application's service account that you obtained after running terraform apply. Then click Add.
Click Assign role.

Access the JIT Groups web interface

You can now access the JIT Groups web interface:

Open a browser and navigate to the URL that you obtained after running terraform apply.
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:

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:
  
  Select app: Select Mail
  
  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.

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=-)

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
Apply the configuration change:
```
terraform apply 
```

Optional: Submit your configuration to Git

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

Initialize a git repository:
```
git init
```

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

Commit your changes:

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

What's next

Add an environment