configuration-example.yaml

# Example of Google directory sync configuration.

# Synchronisation configuration
sync:
  # A regular expression which is used to match the organization unit path for
  # Google users who should be excluded from the list returned by Google. Those
  # users do not exist for the purposes of the rest of the sync and so if they
  # appear in the list of managed users this script will attempt to re-add them
  # and fail in the process. Use this setting for users who are managed
  # completely outside of this script.
  ignore_google_org_unit_path_regex: '^/Service Accounts$'

  # The organization unit path in which new accounts are placed
  new_user_org_unit_path: '/'

  # Suffix appended to the names of groups created in Google. The Google group
  # name will be "{groupName}{group_name_suffix}", where {groupName} is the
  # Lookup group name.
  group_name_suffix: ' from lookup.cam.ac.uk'

  # Settings to be applied to groups in Google. These settings are applied to both
  # new and existing groups imported from Lookup.
  # See https://developers.google.com/admin-sdk/groups-settings/v1/reference/groups#json
  group_settings:
    whoCanJoin: INVITED_CAN_JOIN
    whoCanViewMembership: ALL_IN_DOMAIN_CAN_VIEW
    whoCanViewGroup: ALL_MEMBERS_CAN_VIEW
    whoCanPostMessage: ALL_IN_DOMAIN_CAN_POST
    allowWebPosting: 'false'
    messageModerationLevel: MODERATE_ALL_MESSAGES
    includeInGlobalAddressList: 'true'
    whoCanLeaveGroup: NONE_CAN_LEAVE
    whoCanContactOwner: ALL_MANAGERS_CAN_CONTACT
    whoCanModerateMembers: OWNERS_ONLY
    whoCanDiscoverGroup: ALL_IN_DOMAIN_CAN_DISCOVER

  # Inter-batch delay in seconds. This is useful to avoid hitting Google rate
  # limits. Default: 5.
  inter_batch_delay: 5

  # Batch size for Google API calls. Google supports batching requests together
  # into one API call. This can be no greater than 1000 but in practice this
  # should be less to avoid hitting other Google rate limits. Default: 50.
  batch_size: 50

  # Number of times to retry HTTP requests if a 503 "Service Unavailable" received
  http_retries: 2

  # Delay in seconds between HTTP 503 response retries
  http_retry_delay: 5

# Configure limits defining maximum scope of changes.
limits:
  # The abort_... settings below are safety limits and will abort the run if the
  # limits are violated. They are there to define the "sane limits" for an
  # update.

  # Refuse to perform sync if we are to "touch" more than this percentage of
  # users. The percentage of users "touched" is calculated as
  #
  #   (new google users + modified google users) / max(1, total google users)
  #
  # where "modified" includes metadata changes and suspension/restoration. As
  # such this calculated percentage can be greater than 100. Set to null to
  # have no limit. Default: null.
  abort_user_change_percentage: 2 # percent

  # Refuse to perform sync if we are to "touch" more than this percentage of
  # groups. The percentage of groups "touched" is calculated as
  #
  #   (new google groups + modified google groups) / max(1, total google groups)
  #
  # where "modified" includes metadata changes and deletion. As such this
  # calculated percentage can be greater than 100. Set to null to have no limit.
  # Default: null.
  abort_group_change_percentage: 2 # percent

  # Refuse to perform sync if we are to "touch" more than this percentage of
  # overall group memberships. The percentage of group memberships "touched" is
  # calculated as
  #
  #   (new memberships + deleted memberships) / max(1, total google group memberships)
  #
  # As such this calculated percentage can be greater than 100. Set to null to
  # have no limit. Default: null.
  abort_member_change_percentage: 2 # percent

  # The max_... settings below will not abort the run if the number of items
  # affected is greater than the specified number. Instead the number of items
  # affected is capped to that number. The selection of which items are included
  # in the capped number is arbitrary.

  # Limit the number of new user creations per run. This is an absolute number.
  # Set to null to have no limit. Default: null.
  max_new_users: 100

  # Limit the number of new group creations per run. This is an absolute number.
  # Set to null to have no limit. Default: null.
  max_new_groups: 100

  # Limit the number of user suspensions per run. This is an absolute number.
  # Set to null to have no limit. Default: null.
  max_suspended_users: 100

  # Limit the number of group deletions per run. This is an absolute number.
  # Set to null to have no limit. Default: null.
  max_deleted_groups: 100

  # Limit the number of user un-suspensions (reactivations) per run. This is an
  # absolute number. Set to null to have no limit. Default: null.
  max_reactivated_users: 100

  # Limit the number of user metadata changes per run. This is an absolute
  # number. Set to null to have no limit. Default: null
  max_updated_users: 100

  # Limit the number of group metadata changes per run. This is an absolute
  # number. Set to null to have no limit. Default: null
  max_updated_groups: 100

  # Limit the total number of group members to insert per run. This is an
  # absolute number. Set to null to have no limit. Default: null
  max_inserted_members: 100

  # Limit the total number of group members to delete per run. This is an
  # absolute number. Set to null to have no limit. Default: null
  max_deleted_members: 100

# Google API configuration
google_api:
  # Authentication
  auth:
    # Path to on-disk JSON credentials used when accessing the API.
    credentials: "./credentials.json"

    # Path to on-disk JSON credentials used when accessing the API in
    # "read-only" mode. Use this if you want to have a separate "safe" service
    # account which can only read data. If null, use the same credentials for
    # reading and writing. Default: null.
    read_only_credentials: null

# Details about the LDAP server
ldap:
  # Scheme and hostname of the LDAP server.
  host: 'ldaps://ldap.example.com'

  # LDAP search base for users. Person filters are always relative to this.
  user_search_base: 'ou=people,o=example-corps,dc=example,dc=com'

  # LDAP search base for groups. Group filters are always relative to this.
  group_search_base: 'ou=groups,o=example-corps,dc=example,dc=com'

  # LDAP search base for institutions. Institution filters are always relative to this.
  inst_search_base: 'ou=insts,o=example-corps,dc=example,dc=com'

  # Filter to use to determine the "eligible" list of users. If a non-admin user
  # is found on Google who isn't in this list, their account will be suspended.
  eligible_user_filter: '(uid=*)'

  # Filter to use to determine the "eligible" list of groups. If a group is
  # found on Google that isn't in this list, it will be deleted.
  eligible_group_filter: '(groupID=*)'

  # Filter to use to determine the "eligible" list of institutions. If an
  # institution is found on Google that isn't in this list, it will be deleted.
  eligible_inst_filter: '(instID=*)'

  # Filter to use to determine the "managed" list of users. If a user appears in
  # this list who isn't in Google their account is created. If the user metadata
  # for a user in this list changes, the change is propagated to Google. If
  # null, the value of "eligible_user_filter" is used. Default: null.
  managed_user_filter: null

  # Filter to use to determine the "managed" list of groups. If a group appears
  # in this list that isn't in Google it is created. If the group metadata or
  # list of members for a group in this list changes, the change is propagated
  # to Google. If null, the value of "eligible_group_filter" is used.
  # Default: null.
  managed_group_filter: null

  # Filter to use to determine the "managed" list of institutions. If an
  # institution appears in this list that isn't in Google it is created. If the
  # institution metadata or list of members for an institution in this list
  # changes, the change is propagated to Google. If null, the value of
  # "eligible_inst_filter" is used. Default: null.
  managed_inst_filter: null

# Details about the Google Domain we're managing.
google_domain:
  # Name of the domain.
  name: 'example.com'

  # If using a service account with Domain-Wide Delegation, set to the username
  # within the GSuite for the user which has administration rights.
  # Should be an e-mail style name. E.g. "super-admin@example.com". The service
  # account credentials specified in the google_api.auth section are used to
  # perform admin actions as this user.
  # If not using Domain-Wide Delegation (i.e. the service account executing this
  # script has been made a member of an Admin Role), use null or comment out.
  # Default: null
  admin_user: 'super-admin@example.com'

  # Secondary domain or domain alias for groups. If null, the value of "name"
  # is used. Default: null
  groups_domain: null

  # Secondary domain or domain alias for institutions. If null, the value of
  # "name" is used. Default: null
  insts_domain: null