HelloID-Conn-Prov-Target-GoogleWorkSpace

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.

Table of contents

• HelloID-Conn-Prov-Target-GoogleWorkSpace
  • Table of contents
  • Introduction
  • Getting started
    • Prerequisites
      • Creating the Base64 Key from the PKCS #12 Certificate
    • Connection settings
    • Correlation configuration
    • Available lifecycle actions
    • Field mapping
  • Remarks
    • Uniqueness check
    • Create lifecycle action
    • Update lifecycle action
    • Enable/Disable lifecyle actions
    • Delete lifecycle action
    • Permissions - groups
      • Static permissions
      • Dynamic permissions
    • Permissions - Licenses
    • Resources - Groups
    • Resources - Organizational Units
  • Development resources
    • API documentation
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-GoogleWorkSpace is a target connector. GoogleWS provides a set of REST API's that allow you to programmatically interact with its data.

Getting started

Prerequisites

Before implementing this connector, ensure the following prerequisites are met:

• Service Account: Create a service account in Google Workspace. Visit: Google Cloud Console - Service Accounts.
• Admin Account: Have an admin account with permissions to manage users and groups within Google Workspace. Visit: Google Admin Console - Users.
• PKCS #12 Certificate: Obtain and download a PKCS #12 certificate for the service account.
• Domain-Wide Delegation: Enable domain-wide delegation to allow the service account to access Google Workspace APIs on behalf of users. The following API scopes are required:
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/admin.directory.userschema
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.orgunit
  • https://www.googleapis.com/auth/apps.licensing
• Base64 Key: Generate the base64-encoded key for the PKCS #12 certificate.

Creating the Base64 Key from the PKCS #12 Certificate

Use the following PowerShell script to create the base64-encoded key:

$p12CertificatePath = 'C:\example\example.p12'
[System.Convert]::ToBase64String((Get-Content $p12CertificatePath -AsByteStream))

Connection settings

The following settings are available:

Setting	Description	Mandatory	Example
Issuer	The client ID used to generate the token. Typically this is the service account ID used for authentication.	Yes	example-service-account@project-id.iam.gserviceaccount.com
Subject	The user or service account on whose behalf the token is issued. Typically represents the admin account that has been authorized to perform actions on behalf of users or manage the Google Workspace domain.	Yes	admin@example.com
P12CertificateBase64	The Base64 encoded version of the P12 (PKCS #12) certificate. Refer to the readme for more information.	Yes	MIIC... (truncated base64)
P12CertificatePassword	The password used to protect the private key stored within the P12 (PKCS #12) certificate.	Yes	mypassword123
InitialContainer	The Organizational Unit in which accounts should be created. When not specified, the value is determined by the fieldMapping.	No	/Users/NewAccounts
EnabledContainer	The Organizational Unit to which accounts should be moved when enabled. When not specified, the value is determined by the fieldMapping.	No	/Users/EnabledAccounts
DisabledContainer	The Organizational Unit to which accounts should be moved when disabled. When not specified, the value is determined by the fieldMapping.	No	/Users/DisabledAccounts
MoveAccountOnUpdate	Move account to a different container when the account update action is performed. The container is determined by the fieldMapping. The default value is set to false.	No	true
SetPrimaryManagerOnCreate	Set primary manager when an account is created. The default value is set to false.	No	true
DefaultDomain	The primary domain that is automatically assigned when you set up a Google Workspace environment. See: https://admin.google.com/ac/domains/manage?hl=en	No	example.com
ParentOrgUnitPath	The organizational unit path under which new organizational units will be created. Use '/' for top-level OUs or specify an existing path (e.g., '/ParentContainer').	No	/ParentContainer

Note

The configuration of the Google Workspace connector is similar to the Active Directory connector.

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within GoogleWS to a person in HelloID.

Setting	Value
Enable correlation	True
Person correlation field	PersonContext.Person.ExternalId
Account correlation field	EmployeeNumber

Tip

For more information on correlation, please refer to our correlation documentation pages.

Available lifecycle actions

The following lifecycle actions are available:

Action	Description
create.ps1	Creates a new account.
delete.ps1	Removes an existing account.
disable.ps1	Disables an account, preventing access without permanent removal.
enable.ps1	Enables an account, granting access.
update.ps1	Updates the attributes of an account.
permissions/groups/grantPermission.ps1	Grants specific groups to an account.
permissions/groups/revokePermission.ps1	Revokes specific groups from an account.
permissions/groups/permissions.ps1	Retrieves all available groups.
permissions/licenses/grantPermission.ps1	Grants specific licenses to an account.
permissions/licenses/revokePermission.ps1	Revokes specific licenses from an account.
permissions/licenses/permissions.ps1	Retrieves all available licenses.
resources/groups/resources.ps1	Creates groups.
resources/organizationalUnits/resources.ps1	Creates organizational units.
configuration.json	Contains the connection settings and general configuration for the connector.
fieldMapping.json	Defines mappings between person fields and target system person account fields.
uniquenessCheck.ps1	Validates the uniqueness of the PrimaryEmail in Google Workspace, including aliases and non-primary emails.

Field mapping

The field mapping can be imported by using the fieldMapping.json file.

Remarks

The Google Workspace connector has been developed to be functionally the same as the Active Directory target connector.

Uniqueness check

The script validates the uniqueness of the PrimaryEmail in Google Workspace, including aliases and non-primary emails.

Create lifecycle action

• Manager
  If the configuration setting SetPrimaryManagerOnCreate is enabled, the primary manager will be assigned when an account is created.

• Container
  If the configuration setting InitialContainer is assigned a value, that value will determine the container in which the user resides. If this setting is left empty, the value from actionContext.Data.Container will be used to determine the user's container.

• Password
  New accounts require a password. This password will be generated within the create lifecycle action.

Update lifecycle action

• Container
  The container is the location where the account will reside.

Important

• If the configuration setting InitialContainer is used, during the create lifecycle action, the account will be created in the organizational unit specified for this setting.
• If the configuration setting InitialContainer is empty, during the create lifecycle action, the account will be created in the organizational unit specified in actionContext.Data.Container.
• If the configuration setting MoveAccountOnUpdate is enabled, during the update lifecycle action, the account will be moved to the container specified in actionContext.Data.Container.

• Primary email address
  The connector updates the primary email address as needed but does not remove any associated aliases. In case the primairy email address will be changed, the previous value will be automatically added as an alias.

• Move Account on Update
  If the configuration setting moveAccountOnUpdate is enabled, during the update lifecycle, the account will be moved to the location specified in the field container.

Note

While the API supports alias removal, this functionality is not implemented, as it is not a desired feature within the current scope.

Important

The primaryEmail is also used in the grant lifecycle action for license assignments. Therefore, it is stored within the accountReference during the create lifecycle action. The accountReference will be updated during the update lifecycle action in case the primary email has changed.

Enable/Disable lifecyle actions

When an account is enabled or disabled, and if the configuration settings EnabledContainer or DisabledContainer are set, the account will be moved to the specified container and its status will be updated accordingly. If these settings are left empty, the account will be enabled or disabled in its current container.

Delete lifecycle action

Within the delete lifecycle action, the account will be deleted from Google Workspace.

Permissions - groups

Static permissions

Static permissions include all permissions available in Google Workspace. These can be retrieved using the /permissions/groups/permissions.ps1 script.

Dynamic permissions

Dynamic permissions are groups created either by the resource script or by groups available in Google Workspace with names corresponding to a contract property. Currently, this property is set to department.DisplayName within the /permissions/groups/subPermissions.ps1 script.

Note

Email address formatting is handled both in the resource script and within the dynamic permissions. Any changes to the formatting logic must be applied in both areas to maintain consistency.

Permissions - Licenses

• Fixed list of licenses
  

The permissions script uses a predefined list of licenses.

Warning

Please note that license assignment has not been fully tested due to their unavailability in the test environment.

Resources - Groups

• Email address generation
  Email addresses are generated from the display name. Special characters, spaces, and double underscores are sanitized or replaced during this process.

Note

The system checks whether a group already exists based on the email address.

• Default domain requirement
  A default domain is required for the resource script. This domain is also utilized during lookups, ensuring consistent email formatting and identification. For more information on domains, please refer to the configuration secttion.

• Email uniqueness
  Group email addresses must be unique across the system.

• GroupName Non-uniqueness
  Group names are not required to be unique, so additional validation or correlation logic may be necessary in certain cases.

Note

Email address formatting is handled both in the resource script and within the dynamic permissions. Any changes to the formatting logic must be applied in both areas to maintain consistency.

Resources - Organizational Units

When creating organizational units (OUs) in Google Workspace, it is essential to define their hierarchy within the directory. Organizational units are structured in a tree format, with each OU having an optional parent. This structure allows for organized management of users, settings, and policies.

To create an organizational unit, you must specify key details such as:

• name: The display name of the organizational unit.
• orgUnitPath: The unique path representing the organizational unit within the hierarchy (e.g., /Engineering/Development).
• parentOrgUnitPath: The path of the parent container under which the new organizational unit will reside. This parameter is mandatory unless the organizational unit is being created at the root level. Use / as the value for parentOrgUnitPath to place the organizational unit at the top level.

Note

The parentOrgUnitPath must be set within the configuration.

Development resources

API documentation

The API documentation can be found using the links below.

Endpoint	URL	Actions
Validate account	https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#get_user	All
Create account	https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#create_user	Create
Set manager	https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#user-relationships	Create, Update
Update account	https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#update_user	Update, Enable, Disable
Delete account	https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#delete_user	Delete
Get groups	https://developers.google.com/admin-sdk/directory/v1/guides/manage-groups#get_all_domain_groups	Permissions\Groups\SubPermissions, Resources\Groups
Update group	https://developers.google.com/admin-sdk/directory/v1/guides/manage-group-members	Permissions\Groups\Grant, Permissions\Groups\Revoke
Create group	https://developers.google.com/admin-sdk/directory/v1/guides/manage-groups	Resources\Groups
Get lisenses	https://developers.google.com/admin-sdk/licensing/v1/how-tos/products	Permissions\Licenses\Permissions
Add license	https://developers.google.com/admin-sdk/licensing/reference/rest/v1/licenseAssignments/insert	Permissions\Licenses\Grant
Remove license	https://developers.google.com/admin-sdk/licensing/reference/rest/v1/licenseAssignments/delete	Permissions\Licenses\Revoke
Get organizational unit	https://developers.google.com/admin-sdk/directory/v1/guides/manage-org-units	Resources\OrganizationalUnits
Create organizational unit	https://developers.google.com/admin-sdk/directory/v1/guides/manage-org-units	Resources\OrganizationalUnits

Getting help

Tip

For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages.

Tip

If you need help, feel free to ask questions on our forum.

HelloID docs

The official HelloID documentation can be found at: https://docs.helloid.com/