PhenixID

PSD1171 – Google Directory Admin Actions for Identity Provisioning

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