Setting up the Groups API (original) (raw)

This page explains how to set up the Cloud Identity Groups API.

Before you begin

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Installing the client libraries

To install the client libraries, run the following command:

Python

For more on setting up your Python development environment, refer to thePython Development Environment Setup Guide.

pip install --upgrade google-api-python-client google-auth \
  google-auth-oauthlib google-auth-httplib2

Authenticating with the Groups API

You can authenticate with the Groups API as an end user, as a service account group admin without domain-wide delegation, or as a service account with domain-wide delegation. The following sections describe each method.

Authenticating as an end user

If you're not an administrator, or are building an app that acts on behalf of users who aren't administrators, seeUsing OAuth 2.0 for web server applications, and then see the Instantiating a client section below.

Authenticating as a service account without domain-wide delegation

If you're using a service account and want to use it to manage groups as a group admin, complete the steps below. This authentication method should be used when you want the service account's actions to be registered in the audit logs as the service account.

Assigning an admin role to the service account

First, you should assign the Google Workspace Group Administrator Role (Group Administrator) to the service account you want to delegate to, using the Admin SDK Roles and Role Assignments API. This step gives the service account access to the groups of the domain but no other resource.

See theManaging Roles guidefor general information about managing Roles using the Admin SDK API. Follow the steps below to assign the Group Adminstrator role for your service account.

In the Google Cloud console, go to the Service Accounts page:
Go to Service Accounts
Click the name of the service account that you want to use with the Groups API.
Copy the Unique ID of the service account.
Call the Admin SDK Roles API to identify the roleId for Group Administrator. You can use theAPI Explorerin the Admin SDK documentation to do this.
Call theRole Assignments APIwith the following request body:

{  
  "assignedTo": "SERVICE_ACCOUNT_UNIQUE_ID"  
  "roleId": "ROLE_ID"  
  "scopeType": "CUSTOMER"  
  "kind": "admin#directory#roleAssignment"  
}

You now have a service account with the Group Administrator role. The second step is to complete the OAuth authentication process for the service account.

If you are developing an app on Google Cloud and the service account is an owner of the project, you can use the application default credentials instead, which can simplify the process. SeeAuthenticating as a Service Accountfor more information.
If the service account is not the owner of the project, follow the instructions below.

In either case, the applicable scope for the Cloud Identity Groups API ishttps://www.googleapis.com/auth/cloud-identity.groups.

Using the credential you just created, generate an access token.

Java

GoogleCredential credential = new GoogleCredential.Builder()  
    .setTransport(httpTransport)  
    .setJsonFactory(JSON_FACTORY)  
    .setServiceAccountId(emailAddress)  
    .setServiceAccountPrivateKeyFromP12File(new File("MyProject.p12"))  
    .setServiceAccountScopes(ImmutableList.of("https://www.googleapis.com/auth/cloud-identity.groups"))  
    .build();

Keep the access token that's generated.

Full code for generating an access token for a service account

Java

GenerateServiceAccountOauth2Token.java

package com.google.tools;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.common.collect.ImmutableList;
import java.io.FileInputStream;

/** Command line tool to generate Oauth2 token for a given service account
/** without domain wide delegation. */
public final class GenerateServiceAccountOauth2Token {

  private static final ImmutableList<String> API_SCOPES =
      ImmutableList.of(
          "https://www.googleapis.com/auth/cloud-identity.groups",
          "https://www.googleapis.com/auth/admin.directory.group",
          "https://www.googleapis.com/auth/admin.directory.group.member",
          "https://www.googleapis.com/auth/apps.groups.settings");

  public static void main(final String[] args) throws Exception {
    String accessToken = getTokenFromJsonKey();
    System.out.println("Token: " + accessToken);
  }

  private static String getTokenFromJsonKey() throws Exception {
    GoogleCredential credential =
        GoogleCredential.fromStream(
            new FileInputStream(
                "<path for json file>"),
            new NetHttpTransport(),
            GsonFactory.getDefaultInstance());
    System.out.println("ServiceAccountId=" + credential.getServiceAccountId());

    HttpTransport httpTransport = new NetHttpTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    GoogleCredential.Builder builder =
        new GoogleCredential.Builder()
            .setServiceAccountPrivateKey(credential.getServiceAccountPrivateKey())
            .setServiceAccountPrivateKeyId(credential.getServiceAccountPrivateKeyId())
            .setServiceAccountId(credential.getServiceAccountId())
            .setTransport(httpTransport)
            .setJsonFactory(jsonFactory)
            .setServiceAccountScopes(API_SCOPES)
            .setClock(credential.getClock());
    credential = builder.build();
    if (!credential.refreshToken()) {
      throw new Exception("Failed to fetch access token.");
    }
    return credential.getAccessToken();
  }
}

Build rule

java_binary(
  name = "generate_oauth2_token",
  srcs = ["GenerateServiceAccountOauth2Token.java"],
  main_class = "com.google.tools.GenerateServiceAccountOauth2Token",
  deps = [
      "//java/com/google/api/client/googleapis/auth/oauth2",
      "//java/com/google/api/client/googleapis/javanet",
      "//java/com/google/api/client/http",
      "//java/com/google/api/client/http/javanet",
      "//java/com/google/common/base",
      "//java/com/google/common/collect",
      "//third_party/java/google_http_java_client:gson",
      "//third_party/java/google_http_java_client:json",
  ],
)

Testing the service account

Try any Groups API call with the service account credentials: create a group, add users, update group settings, etc.
Check the Audit Logs in the Google Admin Console Reports section. You should see the service account as the actor for your group-related changes. SeeLog events for more information.
Alternatively, you can use APIs to access audit logs. To check using theReports API explorer, make sure to use your admin OAuth credentials.

Authenticating as a service account with domain-wide delegation

If you're an administrator managing identity groups, or if you want to provide an account with domain-wide privileges so it can manage Google Groups on behalf of admins, you should authenticate as aservice account.

For details about setting up domain-wide delegation, seeControl API access with domain-wide delegation.

To authenticate as a service account, refer toUsing OAuth 2.0 for server to server applications. When initializing the credential in your code, specify the email address on which the service account acts by calling with_subject() on the credential. For example:

Python

credentials = service_account.Credentials.from_service_account_file(
  SERVICE_ACCOUNT_FILE, scopes=SCOPES).with_subject(delegated_email)

Instantiating a client

The following example shows how to instantiate a client using service account credentials. To authenticate as an end-user instead, replace the credentialobject from the service account with the credential you obtained earlier inUsing OAuth 2.0 for web server applications.

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.groups']
SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
  delegated_credentials = credentials.with_subject('user@example.org')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service

You can now begin making calls to the Groups API.