The purpose of G Suite Sync module is to establish data synchronization with G Suite Sync. 

The main features include:

  • 2-way sync between G Suite and Passport
  • Automatic synchronization on-the-fly
  • Flexible rules and data filtering
  • Authentication against Google


Table of Contents


Configuration of connection

This section describes how to establish connection. Please check Technical Requirements and follow up instructions below.

  1. Technical requirements

    • The supported types of G Suite domains are: Educational and Business (both primary and secondary)
    • Configuration can be done only by a Global administrator
    • Data Export requires ability to assign licences for new users inside the selected G Suite domain
    • Authentication against Google won't work in case of using external IdP for selected G Suite domain
  2. Creating connection

To establish connection with G Suite - navigate to: Users > G Suite Sync, fill out Domain name and choose the desired Sync Mode:

  • Import - to import data from G Suite
  • Export - export data to G Suite
  • Import & Export - 2-way sync between G Suite and Passport

Attention: In case of choosing "Export" or "Import & Export", deleting user account in Passport will cause to account suspension in Google. But if Sync Mode is set to “Import” or "Import & Export", and a user account gets deleted in G Suite - the respective Passport account will not be deleted or suspended automatically.


To allow users authenticate against Google - activate checkbox called "Enable "Login with G Suite" for SSO Passport users". By doing this, you will activate separate button called "Login with Google" - on the login page (can be activated / deactivated on any stage of process).

To grant access to data of G Suite domain - click "Authorize", login to Google as administrator, and approve the requested access permissions.

  • Authorization is a background process that can take up from a few seconds to a minute. A warning message will appear if authorization to API is not granted. One of the common reasons for a failed authorization is a disabled permission to read G Suite data through API. Please refer to this topic for more information.

To save configuration - click "Save". To discard changes - click "Cancel". To revoke access to G Suite domain - click "Revoke". To revoke access and remove configuration of G Suite Sync - click "Delete".


Authentication

While data synchronization is not completed, authentication against Google becomes operational - after activating checkbox called "Enable "Login with G Suite" for SSO Passport users" - see section: Configuration of connection.

There are no restrictions to the type of Google account for authentication by using "Login with Google" button. The only limitation is that either username or email address of existing user in Passport should match to the selected Google account. Thus, authentication against Google can be used independent on the selected source of users data (Active Directory, CSV upload, SFTP, SIS Sync, manually created accounts, etc) - in case if usernames or email addresses of users match to Google. Both Personal and Institutional types of Google accounts are supported.


To test authentication after activating button:

  • Go back to the login page
  • Click "Login with Google"
  • Login to Google or choose Google account from the list. In case if the selected Google account corresponds to username or email address of existing user in Passport - authentication should work.


Organizational mapping

This section describes how to map Org Units from Google with organizations in Passport. This view contains the table with 3 columns:

  • G Suite Org Units – the list of Org Units in G Suite.
  • Import / Export – icons that indicate synchronization mode.
  • SSO Passport Organization – organization in SSO Passport that can be linked with Org Unit.


The steps are:

  • Navigate to Users > G Suite Sync > Org Units.
  • Click + beside the Org Unit, which needs to be linked and then choose the desired Organization or "New" - for creating organization in Passport automatically.
  • To save save changes - click “Save”.

To import users who are members of sub OUs under the selected Org Unit - every Org Unit needs to be linked. Otherwise users won't be imported.


Data filtering and Mapping of attributes

This section describes how to filter data and map users attributes in both Passport and G Suite. Navigate to Users > G Suite Sync > Users > Filter Rules

  1. Data filtering

    Filter rules allow to exclude user accounts with specific attributes from synchronization process. Every organization, that is mapped in Org Units tab, has a default filter rule that enables import of user accounts from specific Org Unit. This filter can not be edited or deleted. To change priority drag & drop the filter rule up or down to change the order. All filter rules are evaluated according to priority. First item in the list has highest priority. Filtering user accounts feature applies only to “Import” and “Import & Export” mode.

     

    To create a new Rule - click “Add Filter” button, fill out data and click “Save” button.

     

    Every filter consists of 4 elements:

    • G Suite attribute name - type of the element inside G Suite. The supported values:
      • groupsMembership – to filter based on G Suite group membership
      • orgUnitPath – to filter based on G Suite organization membership
    • Condition - defines the rule for matching FQDN of the Org Unit or Group
      • IS - value fully match
      • IS_NOT - value does not match
      • CONTAINS - name of OU/Group contains value
      • DOESNT_CONTAIN - name of OU/Group does not contain value
      • STARTS_WITH - FQDN of OU/Group starts from value
      • ANT_PATH - http://ant.apache.org/manual/dirtasks.html#patterns
    • Match expression - A value or a pattern for comparison
    • Status - Defines whether the rule allows or blocks synchronization
  2. Mapping of Attributes

Attribute mappings is used to assign SSO Passport user accounts with additional attributes (role, user type, student's grade) based on their G Suite Group or OU membership. Every organization, mapped in Org Units tab, has a default attribute mapping that assigns SSO Passport’s organization, default role and default user type. This attribute mapping can not be edited or deleted.

 

To create a new Attribute Mapping - Navigate to Users > G Suite Sync > Users > Attribute Mappings and click “Add Mapping Set” button, fill out data and click “Save”.


Every attribute mapping consists of 4 elements, that are related to Passport:

  • SSO Passport Organization: Defines Organziation
  • SSO Passport Role: Defines Role
  • User Type: Defines type of a user. There are 3 options:
    • STAFF (for Teachers and other employees)
    • STUDE (for students)
    • PARENT (parents, guardians)
  • Grade: Allows to set grade level for users


In the meantime, there 4 additional elements, that are related to G Suite and described in Data filtering.


Every attribute mapping can have one or many associated filter rules. Rules are managed in the same way as was described in Data filtering.



Please note: Changes to Filter Rules & Attributes Mappings will be applied for subsequent synchronizations as though synchronization happens for the first time. Thus, changes to Filter Rules & Attributes Mappings will not result in deletion of previously synchronized organizations, groups and user accounts.


 


Synchronization

This section describes how to initialize data synchronization process. To do that - navigate to Users > G Suite Sync > Sync and click "Sync Users". System will show a message: "G Suite Sync process successfully has been scheduled", and new record in "Synchronziation History" will be created. To view the details of data synchronization - click "view".

Once the data synchronization process gets initialized - it should work automatically in the future. It does mean that new users will be created automatically (with the lag in 1-5 minutes). To start synchronization manually - click “Sync Users”.


Troubleshooting

If synchronization mode is set to "Import":

The system will try to import all users from the selected Org Unit or Group. Import from sub OUs is not implemented.

In case of deleting user accounts in Google - the respective user accounts in Passport will be deleted as well.


If synchronization mode is set to "Export":

In this case data synchronization affects only on those users, whose email addresses correspond to selected Google domain.

In case of deleting users accounts in Passport - the respective Google accounts will be suspended.


Authentication won't work:

In case of 2 or more email addresses in the selected Organization (in Passport) correspond to selected Google account.


Data synchronization won't work:

if no mappings have been created.