Fact

PhenixID Identity Provisioning 6.1.0 or later

System Requirements

Account in Google G Suite
Service Account, see PSD1195 – Google Apps Service Account Configuration for setup
- Important: the linked document is written for the old Google actions, so some tweaks are necessary (and Google have slightly altered their user interface – when in doubt, consult Google’s documentation)
- For keys: Use JSON, not p12
- For OAuth2 scopes: Please see Google’s documentation (as of writing, it can be found here). Without correct scopes setup, the service account won’t have access to certain APIs
- Delegation: The service account must be allowed to act on behalf on the admin-user you specify. See the part about “Domain-wide Delegation”

Situation

Use PhenixID Identity Provisioning to setup automatic user provisioning to Google.

Solution

This document will show the steps that are necessary to configure PhenixID Identity Provisioning to automatically provision (list/create/update/delete) information for Google Apps users, groups, organizational units and roles.

Download and install the action package

Google Directory Admin action package with dependencies

For instruction of how to install the action package, read PSD1149.

Upgrading

If an older version of Google Actions have been used, do a backup of the folder /ext before installing the new version.

Add all new files from /ext folder in the downloaded zip-file.
Look for all duplicates in the /ext folder and remove the older ones.

PIP does not support the older Google actions ends after the upgrade.

Older versions of actions in /actionPackages/customer will stop working when implementing the included new files in /ext.
The deprecated actions will still exist in Configurator until you remove the GoogleAdminDirectoryAPI.jar or any older Google_Apps.jar that might exist in your environment.
So it’s possible to copy/paste information from an older version of the action to a new.
Running the old actions will not be possible after upgrading and good practice is to remove them from UI.

Common Action Parameters

Multiple actions are included in the package, but they all have some parameters in common.

Parameter	Description	Example
Google Domain	[Optional] The Google domain. Example: mycompany.com. Supports SESSION() and GLOBAL(). This parameter is set to optional, but if the parameter is blank there must be a valid value in the global parameter GoogleDomain.	mycompany.com
Google Administrator Username	[Optional] The Google administrator username. Example: admin@mycompany.com. Supports GLOBAL(). This parameter is set to optional, but if the parameter is blank there must be a valid value in the global parameter GoogleAdminID.	admin@mycompany.com
Google Credentials File Path	[Optional] The File Path to the Google Private Key. Example: C:\MySecretFiles\credentials.json. Supports GLOBAL(). This parameter is set to optional, but if the parameter is blank there must be a valid value in the global parameter GoogleCredentials.	C:\MySecretFiles\credentials.json
Error Message Attribute	The name of the session attribute that will contain the error message, no default value. This attribute will be set if any error occurs for the specific session object.	errorMessage

Actions for handling Users

Create User

Create a new user in Google.

Parameter	Description	Example
Attribute with User ID	[Optional] The session attribute that contains the Google username. Default: googleID	googleID
Attributes to set on user object	[Mandatory] Comma separated list of the attributes to set on user in Google. Use \| to map the session attribute name with the Google attribute name, e.g. googleAttribute\|myAttributeName. See * Supported attributes Mandatory attributes: familyname, givenname, password.	password, familyname\|sn, givenname
Password Hash Method	[Optional] Use SHA-1 or MD5. Supports GLOBAL(). Default is the value in global parameter GooglePasswordHashMethod, otherwise clear text.
Change Password at Next Login	[Optional] If the user has to change the password at next login. Default is the value in global parameter GoogleChangePasswordAtLogin, otherwise false.	true
Custom Attribute Categories	[Optional] Comma-separated list of Custom Categories to update. Syntax: google_schema_name\|google_attr_name\|session_attr_name. Default is blank (no Custom Categories).
No of Simultaneous Calls	[Optional] The action can create multiple threads to create multiple calls to Google asynchronously. Enter the number of threads to create. Maximum is 100. Default: 1.	5

Update User

Update an existing user in Google.

Parameter	Description	Example
Attribute with Username	[Optional] The session attribute that contains the Google username. Default: googleID	googleID
Attributes to update	[Mandatory] Comma separated list of the attributes to set on user in Google. Use \| to map the session attribute name with the Google attribute name, e.g. googleAttribute\|myAttributeName. See * Supported attributes	password, familyname\|sn, givenname
Password Hash Method	[Optional] Use SHA-1 or MD5. Supports GLOBAL(). Default is the value in global parameter GooglePasswordHashMethod, otherwise clear text.
Change Password at Next Login	[Optional] If the user has to change the password at next login. Default is the value in global parameter GoogleChangePasswordAtLogin, otherwise false.	true
Custom Attribute Categories	[Optional] Comma-separated list of Custom Categories to update. Syntax: google_schema_name\|google_attr_name\|session_attr_name. Default is blank (no Custom Categories).
No of Simultaneous Calls	[Optional] The action can create multiple threads to create multiple calls to Google asynchronously. Enter the number of threads to create. Maximum is 100. Default: 1.	5

Delete User

Delete an existing user in Google.

Parameter	Description	Example
Attribute with Username	[Optional] The session attribute that contains the Google username. Default: googleID	googleID
Delete Filter Criteria	[Optional] Remove the object if the filter matches, usage: session attribute=value, Supports (!(attrib=value)). Supports GLOBAL(). Default is the value in global parameter GoogleDeleteFilter.

Enable User

Enable an existing user in Google.

Parameter	Description	Example
Attribute with Username	[Optional] The session attribute that contains the Google username. Default: googleID	googleID
Enable Filter Criteria	[Optional] Enable the user if the filter matches, usage: session attribute=value, Supports (!(attrib=value)). Supports GLOBAL(). Default is the value in global parameter GoogleEnableFilter.

Disable User

Disable an existing user in Google.

Parameter	Description	Example
Attribute with Username	[Optional] The session attribute that contains the Google username. Default: googleID	googleID
Disable Filter Criteria	[Optional] Disable the user if the filter matches, usage: session attribute=value, Supports (!(attrib=value)). Supports GLOBAL(). Default is the value in global parameter GoogleDisableFilter.

Undelete User

Undelete a previously deleted user in Google.
(User account possible to undelete up till 20 days after deletion)

Parameter

Description

Example

Attribute with User ID

[Mandatory] The session attribute that contains the GoogleID. Default: googleID

Note: It has to be the 21 digit GoogleID previously exported from Google.

googleID

Attribute With Organization Unit Path

[Mandatory] The attribute that contains the Organization Unit Path to restore the account. Default: orgUnitPath.

orgUnitPath

Get All Users

Get all existing users in Google.

Parameter	Description	Example
Attributes to fetch	[Mandatory] Comma separated list of the attributes to fetch from Google. To rename the attributes, use \| to map the attribute name, e.g. googleAttribute\|myAttributeName. See * Supported attributes Default: givenname,familyname,primaryemail.	familyname\|sn, givenname, phone.value\|mobile
Attribute to store the Google User ID	[Optional] The attribute to store the Google username. Default: googleUserID.	googleUserID
Custom Attribute Categories	[Optional] Comma-separated list of Custom Categories (Schemas) to fetch attribute values from. Syntax: google_schema_name,google_schema_name. Default is blank (no Custom Categories).

* Supported attributes

(All attributes are of String type except where stated)

givenname
familyname
fullname
password
changepasswordatnextlogin
orgunitpath
primaryemail
emails (JSON)
suspended
isadmin
lastlogin
aliases
phones (JSON)
phone.value
phone.type
addresses (JSON)
address.formatted
address.streetaddress
address.country
address.countrycode
address.locality
address.pobox
address.postalcode
address.region
address.type
organizations (JSON)
organization.name
organization.description
organization.title
organization.domain
organization.location
organization.symbol
organization.costcenter
organization.department
organization.type
relations (JSON)

Actions for handling User Photos (thumbnails)

Insert/Update User Photo

Create a new photo or update existing in Google.

Parameter	Description	Example
Attribute with User ID	[Mandatory] The session attribute that contains the Google username. Default: googleID	googleID
Photo attribute	[Mandatory] The attribute that contains the base64 encoded photo data. Default is the value in parameter ‘GooglePhoto’.

Get User Photo

Get a photo in base64 format from Google.

Parameter	Description	Example
Attribute with User ID	[Mandatory] The session attribute that contains the Google username. Default: googleID	googleID

Delete User Photo

Delete a user photo in Google.

Parameter	Description	Example
Attribute with User ID	[Mandatory] The session attribute that contains the Google username. Default: googleID	googleID

Actions for handling Groups

Create Group

Create a new group in Google.

Parameter	Description	Example
Group Mail Attribute	[Mandatory] The attribute that contains the Google Group Mail (or the value before the @ character). No default value.
Group Name Attribute	[Mandatory] The attribute that contains the Google Group Name. Default value: googleGroupname.
Group Description Attribute	[Optional] The attribute that contains the Google Group Description (Info). No default value
Group Member(s) Attribute	[Optional] The multivalue attribute that contains the Google Group Members email adresses. Default value: googleGroupMembers.
No of Simultaneous Calls	[Optional] The action can create multiple threads to create multiple calls to Google asynchronously. Enter the number of threads to create. Maximum is 100. Default: 1.	5

Update Group

Update an existing group in Google.

Parameter	Description	Example
Current Group Mail Attribute	[Mandatory] The attribute that contains the Current Google Group Mail (or the value before the @ character). Used to retrieve the Google Apps Group Id. No default value.
New Group Mail Attribute	[Optional] The attribute that contains the New Google Group Mail (or the value before the @ character). No default value
Group Name Attribute	[Optional] The attribute that contains the Google Group Name. No default value.
Group Description Attribute	[Optional] The attribute that contains the Google Group Description (Info). No default value.

Delete Group

Delete an existing group in Google.

Parameter	Description	Example
Group Mail Attribute	[Mandatory] The attribute that contains the Google Group Mail (or the value before the @ character). No default value.
Delete Filter Criteria	[Mandatory] Delete the object if the filter matches. Usage: session attribute=value.

Sync Group Members

Sync group members in Google Apps. Adds (and removes) group members from local group (or other session attribute data).

Parameter	Description	Example
Group Id Attribute	[Optional] The session attribute that contains the Google Group Id. Default: googleGroupId
Group Mail Attribute	[Optional] The attribute that contains the Google Group Mail (or the value before the @ character). Used to lookup Google Group Id, if not configured or present. No default value.
Group Member Attribute Name	[Optional] The name of the session attribute that will contain the username for the members. Default: googleGroupMembers.
Remove Google Users not in Member Attribute (true/false)	[Optional] If users who exists in Google groups but not in the member attribute should be removed. (true/false) Default value: true.	true
No of Simultaneous Calls	[Optional] The action can create multiple threads to create multiple calls to Google asynchronously. Enter the number of threads to create. Maximum is 100. Default: 1.	5

Get Group Members

Get all group members from Google.

Parameter	Description	Example
Group Id Attribute	[Optional] The session attribute that contains the Google Apps Group Id. Default: googleGroupId
Group Mail Attribute	[Optional] The attribute that contains the Google Group Mail (Prefix). Used to lookup Google Apps Group Id, if not configured or present. No default value.
Group Member Attribute Name	[Optional] The name of the session attribute that will contain the username for the members. Default: googleGroupMembers.
No of Simultaneous Calls	[Optional] The action can create multiple threads to create multiple calls to Google asynchronously. Enter the number of threads to create. Maximum is 100. Default: 1.	5

Get All Groups

Get all groups from Google. Groups are created as session objects.

Parameter	Description	Example
Group Name Attribute Name	[Optional] The name of the session attribute that will contain the group name. Default: googleGroupName
Group Id Attribute Name	[Optional] The name of the session attribute that will contain the group id. Default: googleGroupId

Actions for handling Org Units

Create Org Units

Create a new organizational unit in Google.

Parameter	Description	Example
Attribute with OrgUnitPath	[Optional] The attribute that contains the unique OrgUnitPath for the orgunit. Used to see if there is an existing org unit with this path. No default.
Attribute with Name	[Mandatory] The attribute that contains the name of the orgunit. No default.
Attribute with Description	[Optional] The attribute that contains the description of the orgunit. No default.
Attribute with ParentOrgUnitPath	[Mandatory] The attribute that contains the path for the parent orgunit. Example /parentOrgUnit/subOrgUnit. To place the orgunit in the top organization, use / as parentOrgUnitPath. Defaults to /

Update Org Units

Update an existing organizational unit in Google.

Parameter	Description	Example
Attribute with OrgUnitPath	[Optional] The attribute that contains the unique OrgUnitPath for the orgunit. Used to see if there is an existing org unit with this path. No default.
Attribute with Name	[Mandatory] The attribute that contains the name of the orgunit. No default.
Attribute with Description	[Optional] The attribute that contains the description of the orgunit. No default.
Attribute with ParentOrgUnitPath	[Mandatory] The attribute that contains the path for the parent orgunit. Example /parentOrgUnit/subOrgUnit. To place the orgunit in the top organization, use / as parentOrgUnitPath. No default.

Delete Org Units

Delete an existing organizational unit in Google.

Parameter	Description	Example
Attribute with OrgUnitPath	[Optional] The attribute that contains the unique OrgUnitPath for the orgunit. No default.
Delete Filter Criteria	[Optional] Remove the object if the filter matches, usage: session attribute=value, Supports (!(attrib=value)). Default is blank (filter criteria is matched).

Get All Org Units

Get all organizational units from Google.

The organizational units are stored as separate Session Objects with the following Session Attribute names: name, description, orgUnitPath, parentOrgUnitPath.

Actions for handling Roles

Add Role To Users

Add a role to users in Google.

Parameter	Description	Example
Role Name Attribute	[Optional] The session attribute that contains the Google Role Name. Default: googleRoleName
User Attribute Name	[Optional] The name of the session attribute that contains the username for the users. Default: googleUsers

Remove Role From Users

Remove a role from users in Google.

Parameter	Description	Example
Role Name Attribute	[Optional] The session attribute that contains the Google Role Name. Default: googleRoleName
User Attribute Name	[Optional] The name of the session attribute that contains the username for the users. Default: googleUsers

Get Role Assignees

Get all assignees (users) that has the configured role in Google.

Parameter	Description	Example
Role Name Attribute	[Optional] The session attribute that contains the Google Role Name. Default: googleRoleName
User Attribute Name	[Optional] The name of the session attribute that will contain the username for the users. Default: googleUsers

DISCLAIMER

Information provided in this document is for your information only. PhenixID makes no explicit or implied claims to the validity of this information. Any trademarks referenced in this document are the property of their respective owners.

The origin of this information may be internal or external to PhenixID. PhenixID makes all reasonable efforts to verify this information.

PhenixID - support.phenixid.se