Skip to main content

Google Workspace

In this tutorial, you will configure IAMbic to manage Google Groups, and then practice using IAMbic to to create, manipulate, and expire a test group. These are the steps you will complete.

Setup​

  1. Configure Iambic for Google Group Management
  2. Import existing Google Groups into your IAMbic templates repository

Practice​

  1. Create a Google Group with one or more users
  2. Add users / groups to a Google group
  3. Provide temporary ("break-glass") access to a Google Group
  4. Expire a Google Group

Prerequisites​

Before you begin, you will need the following:

  • A local Git repository to store your IAMbic templates (See Getting Started for guidance on setting this up)
  • A Google Workspace account, and administrative access to it
  • The following environment variables set in the terminal you will be using to run IAMbic commands. These are only needed for the duration of this tutorial. They are not required for the normal usage of IAMbic:
export DOMAIN=<your_gsuite_domain.com>
export EMAIL=<your_gsuite_email_address>

Setup​

1. Configure Iambic for Google Group Management​

In this section, you will set up a Google Cloud Identity that will be used by IAMbic to manage your Google Groups.

  1. Sign in to the Google Cloud Console.
  2. Create a new project for Iambic
  3. Enable the Admin SDK and the Cloud Identity API.
  4. Create a service account for Iambic with access to the Admin SDK API, and access to User Data.
Screenshot

Create Service Account

  1. Enable Domain Wide Delegation for the Google account with the following scopes:
https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group.member
Screenshot

Domain Wide Delegation

  1. Follow these instructions to assign an admin role to your service account.

  2. Download the JSON key file for your service account.

  3. Create an Iambic configuration file for your Google Workspace account. This configuration file will instruct Iambic to load a secrets.yaml file that will be created in the next step, and to enable google groups management. Run the following command from the root of your iambic-templates repository to generate the configuration file:

# Run from the root folder of your iambic-templates repository
mkdir -p config
cat <<EOF > config/config.yaml
template_type: NOQ::Core::Config
version: "1"
extends:
  - key: LOCAL_FILE
    value: secrets.yaml
google:
  groups:
    enabled: true
EOF

Create a secrets.yaml in your config directory with your service accounts secrets. An example is provided below, but you will need to replace the seven values maked with "..." with your own values. These secrets can be found in the JSON key file you downloaded in the previous step.

danger

Never commit secrets Git. Ensure that you have a .gitignore file in the root directory of your iambic-templates repository that is configured to ignore secrets.yaml files with **/secrets.yaml. Learn more about .gitignore files.

secrets:
  google_workspace:
    workspaces:
      - project_id: your-unique-project-id
        project_name: your-project-name
        subjects:
          - domain: "your-google-workspace-unqiue-domain"
            service_account: "your-service-account-name@your-project-id.iam.gserviceaccount.com"
        type: "service_account"
        private_key_id: "bfa86..."
        private_key: "-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----\n"
        client_email: "iambic-...@iambic-....iam.gserviceaccount.com"
        client_id: "1165324...."
        auth_uri: "https://accounts.google.com/o/oauth2/auth"
        token_uri: "https://oauth2.googleapis.com/token"
        auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs"
        client_x509_cert_url: "https://www.googleapis.com/robot/v1/metadata/x509/iambic..."

From the base directory of your IAMbic templates repository, your directory structure should resemble the following. You may have more files if you've recently imported your cloud resources.

tree .
.
├── config
│   ├── config.yaml
│   └── secrets.yaml

2. Import Existing Google Groups​

In this section, you will manually import existing Google Groups into your IAMbic templates repository. In a production environment, automation provided by Iambic would ensure that Git is updated with the cloud resources in your production environment. This allows you to monitor the history of these groups via Git History.

Run the following command in the root of your iambic-templates repository to import your existing Google Groups:

iambic import

If you have Google Workspace Groups defined, your iambic-templates repository should have a google_workspace/group directory with a subdirectory for each domain you have defined.

You've completed the setup configuration connecting your Google Groups to IAMBic. Now you will practice using IAMbic to execute basic group management skills.

Practice​

3. Create a Google group​

Iambic uses a YAML file to describe the desired state of a Google Group. In this section, you will create a group called iambic-test-group in your domain. Ensure that the environment variables for DOMAIN and EMAIL you've set previously are still configured, and also ensure that your credentials are working properly by running the iambic import command from the previous section. (If you just ran it, you can continue.)

Run the following set of commands from the root of your iambic-templates repository to create a new Google Group template:

mkdir -p resources/google_workspace/group/$DOMAIN
cat <<EOF > resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml
template_type: NOQ::GoogleWorkspace::Group
properties:
  name: iambic-test-group
  description: ''
  domain: $DOMAIN
  email: iambic-test-group@$DOMAIN
  members:
    - email: $EMAIL
      role: OWNER
EOF

You can inspect and cofirm the contents of the file by viewing it at resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

tip

You can add Subgroups to the google group with the type: GROUP property. Here's an example:

  - email: testgroup@DOMAIN.com
    type: GROUP

Apply the template to your Google Workspace account by running the following command:

info

In a production environment, this would be handled by a command issued on a Github Pull Request after the appropriate approvals have been made.

iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

Confirm that the group has been created by running the following command and visiting the URL in your browser:

echo https://groups.google.com/a/$DOMAIN/g/iambic-test-group
tip

If it doesn't exist, you should do some stuff...

By now the directory of your iambic-templates repository should resemble the following, and may include other resources that you've imported:

$ tree .
.
├── config
│   ├── config.yaml
│   └── secrets.yaml
├── resources
    ├── google_workspace
        └── group
            └── $DOMAIN
                ├── iambic-test-group.yaml

4. Add a user to the group​

In this section, we will add a user (testuser@example.com) to the group we created in the previous section. example.com is a reserved domain for tests and example use cases, and testuser@example.com is not a real user.

Run the following command to replace the previous group you created with a new one that includes the new user:

cat <<EOF > resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml
template_type: NOQ::GoogleWorkspace::Group
properties:
  name: iambic-test-group
  description: ''
  domain: $DOMAIN
  email: iambic-test-group@$DOMAIN
  members:
    - email: $EMAIL
      role: OWNER
    - email: testuser@example.com
EOF

Run the apply command to have IAMbic update the group:

iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

5. Provide temporary ("break-glass") access to a Google Group​

In this section, we will provide fakeuser@example.com with break-glass access to the iambic-test-group we created in the previous section. Our fakeuser only needs access for two minutes (this user works very quickly). In order to strive for least privilege while accomodating this request, we will add an expiration date to the user's membership in the group. Run the following command to replace the previous group you created with a new one that includes the additional user and an expiration date, and then apply that change:

tip

If a specific expiration date is provided without a timezone, Iambic will assume the timezone is UTC. If a timezone is provided, Iambic will use that timezone.

cat <<EOF > resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml
template_type: NOQ::GoogleWorkspace::Group
expires_at: tomorrow
properties:
  name: iambic-test-group
  description: ''
  domain: $DOMAIN
  email: iambic-test-group@$DOMAIN
  members:
    - email: $EMAIL
      role: OWNER
    - email: fakeuser@example.com
      expires_at: in 2 minutes
EOF
iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

After applying the change, notice that the expires_at date in the template was converted from a relative expiration time ("in two minutes") to an absolute date (Example: "2021-05-20T15:00:00-04:00"). This allows Iambic to know exactly when the request should be expired.

Confirm that the user was added by visiting the following URL in your browser:

echo https://groups.google.com/a/$DOMAIN/g/iambic-test-group

After a couple of minutes, the request should expire. In a production deployment, this process would be automatic. But for the purposes of testing, you can manually expire the request by re-running the apply command after two minutes have passed:

iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

6. Expire the Google Group​

In this section, we will update the Google Group we created in the previous section so the group will expire in one minute. Notice the extra line at the top-level of the YAML below, expires_at: in one minute.

Run the following command to update the group template, and then apply and view the new template.

cat <<EOF > resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml
template_type: NOQ::GoogleWorkspace::Group
expires_at: in one minute
properties:
  name: iambic-test-group
  description: ''
  domain: $DOMAIN
  email: iambic-test-group@$DOMAIN
  members:
    - email: $EMAIL
      role: OWNER
    - email: fakeuser@example.com
      expires_at: in 2 minutes
EOF

iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

cat resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

In the last line of the above commands, we printed the contents of the template to the terminal. Notice that the expires_at date has been updated from a relative time to an absolute date. This allows Iambic to know exactly when the request should be expired.

After a minute has passed, re-run the apply command to expire the request.

iambic apply resources/google_workspace/group/$DOMAIN/iambic-test-group.yaml

Conclusion​

That's it! You've now connected Google Groups to IAMbic, and are able to create and edit your groups, and expire users and groups.