Security teams need access to relevant data and systems to investigate and respond to security threats. As attack vectors have become more diverse, it’s become increasingly common for security teams to require access to systems not owned or operated by Security. In this post, we explore how to automate common G Suite security tasks.

Connecting Tines and G Suite

Google APIs use the OAuth 2.0 protocol for authentication and authorization. To connect Tines with G Suite, we will use OAuth 2.0 with a service account.

Enable Admin SDK in Google’s API Library

The Admin SDK API allows the programmatic administration of domain resources such as users, groups and admin settings. Navigate to https://console.developers.google.com/apis/library/ and enable the Admin SDK.

Creating a service account

Detailed instructions for creating a service account are available from Google here.

1) Open the Service accounts page. If prompted, select a project.

2) Click Create service account

3) In the Create service account window, type a name for the service account, and select Furnish a new private key. Ensure that G Suite Domain-wide Delegation is enabled. Then click Create.

Your private key will be downloaded to your computer in JSON format and should look similar to the below. Keep this file safe, it contains secret information and cannot be downloaded again.

 

Authorizing the service account

In order for Tines to access user data in G Suite, a G Suite administrator needs to authorise the account we just created in the G Suite admin console, this is a process known as delegating domain-wide authority.

1) Go to your G Suite domain’s Admin console.

2) Select Security from the list of controls. If you don’t see Security listed, select More controls from the gray bar at the bottom of the page, then select Security from the list of controls. If you can’t see the controls, make sure you’re signed in as an administrator for the domain.

3) Select Show more and then Advanced settings from the list of options.

4) Select “Manage API client access” in the Authentication section.

5) In the Client Name field enter the service account’s Client ID. You can find your service account’s client ID in the Service accounts Client ID. This can be found under the “client_id” field in the private key file you downloaded and is typically a long number.

6) Under “One or More API Scopes” enter the scopes that are you require. Scopes provide a way to limit the amount of access that is granted to an access token or application. A full list of OAuth 2.0 Scopes for Google APIs is available here. Our credential uses the following scopes:

  • https://www.googleapis.com/auth/admin.directory.group,
  • https://www.googleapis.com/auth/admin.directory.user
SECURITY TIP: Only assign the scopes that are absolutely necessary for your automation story.

7) Click “Authorize”

 

Configuring Tines to work with G Suite

Now that we have an authorized client and private key, we will configure Tines to connect to G Suite.

Create a JWT credential

Like many services, G Suite uses JSON Web Tokens (JWT – pronounced “jot”) to represent and exchange information between services in a secure manner. Before Google will provide an access token which we can use to access the required APIs, we need to send a JWT confirming we are who we say we are.

1) Sign into your Tines tenant and select Credentials -> New

2) Under “Type” chose “JWT”

3) Enter a credential name

4) The only signing algorithm supported by the Google OAuth 2.0 Authorization Server is RSA using SHA-256 hashing algorithm, so, under “Algorithm” chose RSA256.

Next, we’ll define a payload for our JWT. The payload component of the JWT is the data that‘s stored inside the JWT (this data is also referred to as the “claims” of the JWT). Google expects us to provide a payload which looks like the below:

 

The required fields are described below:

Image from developers.google.com

5) For the Tines credential, we will use the following payload:

In our case, “iss” is taken from the “client_email” field in our private key file; “sub” is the email address of an admin in our domain that has access to manage users and groups; and “scope” must be the same as that defined under Step 6 of “Authorizing the service account” above.

6) By selecting the “ Auto generate ‘iat’ (Issued At) & ‘exp’ (Expiration Time) claims” checkbox. Tines will add “iat” and “exp” claims to the payload according to when the credential is used.

7) Copy and paste the private key from our private key file into the Tines credential.

8) When complete, the credential page should look similar to the below:

9) Click “Save Credential”

 

Creating the agents

We can now begin automating interaction with G Suite from Tines.

Create an agent to fetch an access token

As described previously, before we can call the Google APIs, we need an access token. We will use a HTTP Request Agent and the credential we just created to fetch the token.

The HTTP Request Agent should use the following config (replace “GSuite”) with the name of your JWT credential:

 

When you dry-run this agent, it should receive a response similar to the below:

G Suite returns an access token that is valid for one hour.

Save the agent (in this case, the agent was named “Auth to GSuite”)

 

Create an agent to retrieve all users in G Suite

We will now use another HTTP Request Agent to call the Google Directory API and list all users on our domain.

The HTTP Request Agent should receive events from the “Auth to GSuite” agent created above and be configured as follows (replace “domain” with your domain and “auth_to_gsuite” with whatever you named your authentication agent above):

 

Dry running this agent with an access token from the “Auth to GSuite” agent should return a result similar to the below:

Conclusion

From retrieving users’ login histories to automating password resets on compromised accounts, combining G Suite and Tines provides a powerful way to automate critical parts of a company’s security program. Of course, if you have questions or need help connecting G Suite and Tines, send us an email at support@tines.io.