Important
This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.
- HelloID-Conn-SA-Full-Mailbox-AddOrRemoveDelegate
- HelloID Environment:
- Set up your HelloID environment.
- Install the HelloID Service Automation agent (cloud or on-prem).
- Google API Credentials:
- Create a project in the Google Cloud Console.
- Enable the Admin SDK API for your project.
- Enable the Gmail API for your project.
- Create access credentials for your project:
- Create a service account for your project.
- Generate credentials (P12 key) for your service account.
- Set up domain-wide delegation for your service account with the following scopes:
https://www.googleapis.com/auth/admin.directory.userhttps://www.googleapis.com/auth/gmail.settings.sharing
- None at this time.
HelloID-Conn-SA-Full-Mailbox-AddOrRemoveDelegate is a template designed for use with HelloID Service Automation (SA) Delegated Forms. It can be imported into HelloID and customized according to your requirements.
By using this delegated form, you gain the ability to seamlessly manage Google Workspace Mailbox delegations.
Google Workspace provides a set of REST APIs that allow you to programmatically interact with its data.. The API endpoints listed in the table below are used.
| Endpoint | Description |
|---|---|
| /gmail/v1/users/{userId}/settings/delegates | Add delegate to mailbox (POST) |
| /gmail/v1/users/{userId}/settings/delegates/{delegateEmail} | Remove delegate from mailbox (DELETE) |
| /admin/directory/v1/users | List users (GET) |
The following options are available in the form:
- Search by Exact Email Address and Select Google Mailbox: Users can search for an exact email address and choose a Google mailbox.
- Search by Exact Email Address and Select Google User: Users can search for an exact email address and choose a Google user.
- Select Action to Perform: Users can choose between "Add Delegate to Mailbox" or "Remove Delegate from Mailbox."
The following actions will be performed based on user selections:
- Add Delegate to Mailbox:
- If the user selects this action, the chosen user will be added as a delegate to the selected mailbox.
- Remove Delegate from Mailbox:
- If the user selects this action, the chosen user will be removed as a delegate from the selected mailbox.
The first step to connect to the Google API and make requests is to register a new Google Cloud project. This project is required to use Google Workspace APIs.
Follow these steps:
- Go to the Google Cloud Console.
- Create a new project.
For more information, please see: Create a Google Cloud project.
Next, enable the necessary Google Workspace APIs in your Google Cloud project. For this connector, we use the Admin SDK API and the Gmail API.
Follow these steps:
- In your Google Cloud project, navigate to the “APIs & Services” > “Library” section.
- Search for “Admin SDK” and enable it.
- Search for “Gmail API” and enable it.
For more information, please see: Enable Google Workspace APIs.
There are multiple ways to authenticate to the Google API, but we use (and recommend) the service account credentials.
A service account is a special kind of account used by an application (rather than a person). You can use a service account to access data or perform actions on behalf of Google Workspace or Cloud Identity users.
Follow these steps:
- In your Google Cloud project, navigate to the “APIs & Services” > “Credentials” section.
- Create a new service account.
- Note down the service account email address.
For more information, please see: Create a service account.
To authorize service account actions within your app, you need to obtain credentials in the form of a public/private key pair. We recommend using the P12 key type.
Follow these steps:
- In the “Credentials” section, create a new key for your service account.
- Choose the P12 key type.
- Download the P12 key file and securely store it.
For more information, please see: Create credentials for a service account.
To call APIs on behalf of users in a Google Workspace organization, your service account needs to be granted domain-wide delegation of authority in the Google Workspace Admin console by a super administrator account.
The following scopes are required:
https://www.googleapis.com/auth/admin.directory.userhttps://www.googleapis.com/auth/gmail.settings.sharing
For more information, please see: Set up domain-wide delegation for a service account.
The following user-defined variables are used by the connector. Ensure that you check and set the correct values required to connect to the API.
| Setting | Description |
|---|---|
GoogleServiceAccountEmail |
The email address of your service account |
GoogleP12CertificateBase64 |
The Base64 string of the P12 certificate of your service account |
GoogleP12CertificatePassword |
The password to the P12 certificate of your service account |
GoogleAdminEmail |
The email address of an admin account with permissions to manage users |
GoogleUsersOrgUnitPath |
The full path of an organizational unit. This matches all organizational unit chains under the target. For example, orgUnitPath=/ returns all users in the organization |
GoogleSharedMailboxesOrgUnitPath |
The full path of an organizational unit. This matches all organizational unit chains under the target. For example, orgUnitPath=/ returns all users in the organization |
Note: The Base64 string of the P12 certificate file can be obtained by running the following code:
[System.Convert]::ToBase64String((Get-Content "C:\path\to\your\certificate.p12" -Encoding Byte))Tip
For more information on Delegated Forms, please refer to our documentation pages.
Tip
If you need help, feel free to ask questions on our forum.
The official HelloID documentation can be found at: https://docs.helloid.com/