Products & Technology

Announcing the Google Workspace Provider for HashiCorp Terraform Tech Preview

A new Terraform provider allows you to manage users, groups, and domains in your Google Workspace (formerly G Suite).

Jun 23 2021Megan Bang

The Google Workspace provider for Terraform allows you to manage domains, users, and groups in your Google Workspace. This provider is a technical preview, which means it's a community supported project and will require incremental testing and polishing to mature into a HashiCorp officially supported project.

This post will include use cases, requirements, configuration, and examples and show how to create your first user, your first group, and add a user to the group. Please file issues and detail your experience while using the provider. We welcome your feedback.

»Use Cases

Here are some ways you can use the new Google Workspace provider to manage your Google Workspace account. Full examples with instructions are available in the provider repository.

Create users, with custom schemas, and add their attributes with one resource
Manage groups, group settings, and group membership
Update user information, reset passwords
Detect drift to user and group configuration performed outside Terraform

»Requirements

In order to use the Google Workspace provider, you will need:

Google Workspace subscription
A designated Google Workspace User to impersonate
Credentials to a Google Cloud service account with Domain-Wide Delegation enabled
admin.googleapis.com API must be enabled in Google Cloud
groupssettings.googleapis.com must be enabled in Google Cloud (for changes to group’s settings)

»Configuring the Provider

Terraform uses a Google Cloud service account to manage resources created by the provider. To create the service account and generate a service account key, see Google’s documentation.

Once the key has been generated, save the JSON file locally and set the GOOGLEWORKSPACE_CREDENTIALS environment variable to the path of the service account key. Terraform will use this for authentication.

To access user data on a Google Workspace domain, the service account that you created needs to be granted access by a super administrator for the domain. To delegate domain-wide authority to a service account, reference the instructions in Google’s documentation.

Furthermore, only users with access to the Admin APIs can access the Admin SDK Directory API, therefore your service account needs to impersonate one of those users to access the Admin SDK Directory API. You can do this by granting the GCP IAM role roles/iam.serviceAccountUser to your service account, with member user:<impersonated_user_email>. This user's email must be set in the environment variable GOOGLEWORKSPACE_IMPERSONATED_USER_EMAIL or in the impersonated_user_email attribute in the provider.

Another important step is to set the customer_id, which is provided with your Google Workspace subscription and can be found in the admin console under Account Settings.

provider "googleworkspace" {
 credentials             = "/Users/mscott/my-project-c633d7053aab.json"
 customer_id             = "A01b123xz"
 impersonated_user_email = "impersonated@example.com"
}

This screencast demos applying a user config and seeing the changes in the Workspace account.

»Creating Your First User

Here is an example configuration to create a user with a custom birthday attribute. First we define the birthday schema which contains a DATE field named "birthday". We can then reference that schema while defining our user, Dwight Schrute. In this example, we provide Dwight an encrypted password, an email alias, some biographical and organizational information, and then recall our custom schema (birthday) and fill in the correct information.

resource "googleworkspace_schema" "birthday" {
  schema_name = "birthday"
 
  fields {
    field_name = "birthday"
    field_type = "DATE"
  }
}
 
resource "googleworkspace_user" "dwight" {
  primary_email = "dwight.schrute@example.com"
  password      = "34819d7beeabb9260a5c854bc85b3e44"
  hash_function = "MD5"
 
  name {
    family_name = "Schrute"
    given_name  = "Dwight"
  }
 
  aliases = ["assistant_to_regional_manager@example.com"]
 
  emails {
    address = "dwight.schrute.dunder.mifflin@example.com"
    type    = "work"
  }
 
  addresses {
    country        = "USA"
    country_code   = "US"
    locality       = "Scranton"
    po_box         = "123"
    postal_code    = "18508"
    region         = "PA"
    street_address = "123 Dunder Mifflin Pkwy"
    type           = "work"
  }
 
  organizations {
    department = "sales"
    location   = "Scranton"
    name       = "Dunder Mifflin"
    primary    = true
    symbol     = "DUMI"
    title      = "member"
    type       = "work"
  }
 
  phones {
    type  = "home"
    value = "555-123-7890"
  }
 
  phones {
    type    = "work"
    primary = true
    value   = "555-123-0987"
  }
 
  keywords {
    type  = "occupation"
    value = "salesperson"
  }
 
  custom_schemas {
    schema_name = googleworkspace_schema.birthday.schema_name
 
    schema_values = {
      "birthday"         = jsonencode("1970-01-20")
    }
  }
 
  recovery_email = "dwightkschrute@example.com"
}

»Creating Your First Group

When creating a new group, a simple group email is the only required attribute, however, a name, description, and email aliases can also be provided.

resource "googleworkspace_group" "sales" {
  email       = "sales@example.com"
  name        = "Sales"
  description = "Sales Group"
 
  aliases = ["paper-sales@example.com", "sales-dept@example.com"]
}

»Add a User to Your Group

To add members to a Google Workspace group, it is simple to reference a group’s group_id and a user’s primary_email, and provide the appropriate role.

resource "googleworkspace_group_member" "manager" {
  group_id = googleworkspace_group.sales.id
  email    = googleworkspace_user.dwight.primary_email
 
  role = "MEMBER"
}

»Let’s Hear Your Feedback

We would love to hear your feedback on this project. You can post bugs and feature requests for the Google Workspace provider by opening an issue here. You can also engage with us and the community on HashiCorp Discuss.

Last but certainly not least, we’d like to thank Chase Sillevis for authoring the GSuite community provider, which inspired our work on this project.

Announcing the Google Workspace Provider for HashiCorp Terraform Tech Preview

»Use Cases

»Requirements

»Configuring the Provider

»Creating Your First User

»Creating Your First Group

»Add a User to Your Group

»Let’s Hear Your Feedback

Sign up for the latest HashiCorp news

More blog posts like this one

5 ways to improve DevEx and security for infrastructure provisioning

Fix the developers vs. security conflict by shifting further left

HashiCorp at AWS re:Invent: Your blueprint to cloud success