AD Group Integration

Group management

This section defines how to manage Groups.

Cinchy Groups

Cinchy Groups are containers that have Users and other Groups within them as members. Use Groups to provision access controls throughout the platform. Cinchy Groups enable centralized administration for access controls.

Groups are defined in the Groups table within the Cinchy domain. By default, only members of the Cinchy Administrators group can manage this table Each group has the following attributes:

Define a new AD Group

1. To define a new AD Group, create a new record within the Groups Table with the same name as the AD Group (using the cn attribute).

2. Set the Group Type to AD Group.

Convert an existing Group to sync with AD

1. To convert an existing group, update the Name attribute of the existing group record to match the AD Group (using the cn attribute).

2. Set the Group Type to AD Group.

Group membership sync

AD Groups defined in Cinchy have their members synced from AD through a batch process that leverages the Cinchy Command Line Interface (CLI).

Execution flow

The sync operation performs the following high-level steps:

1. Fetches all Cinchy registered AD Groups using a Saved Query.

2. Retrieves the usernames of all members for each AD Group. The default attribute for username that's retrieved is userPrincipalName, but configurable as part of the sync process.

3. For each AD Group, it loads the users that are both a member in AD and exist in the Cinchy Users table (matched on the Username) into the "Users" attribute of the Cinchy Groups table.

Dependencies

1. You must install the Cinchy CLI Model in your instance of Cinchy. See the CLI installation page for more details.

2. An instance of the Cinchy CLI must be available to execute the sync.

3. You must have a task scheduler to perform the sync on a regular basis (For example, AutoSys).

Configuration steps

Create a saved Query to retrieve AD Groups from Cinchy

1. Create a new query within Cinchy with the below CQL to fetch all AD Groups from the Groups table. The domain and name assigned to the query will be referenced in the next step.

SELECT [Name]
FROM [Cinchy].[Cinchy].[Groups]
WHERE [Group Type] = 'AD Group'
AND [Deleted] IS NULL

Create the sync config

1. Copy the below XML into a text editor of your choice and update the attributes listed in the table below the XML to align to your environment specific settings.

2. Create an entry with the config in your Data Sync Configurations table (part of the Cinchy CLI model).

<?xml version="1.0" encoding="utf-16" ?>
<BatchDataSyncConfig name="AD_GROUP_SYNC" version="1.0.0" xmlns="http://www.cinchy.co">
  <Parameters />
  <LDAPDataSource objectCategory="group" ldapserver="LDAP:\\activedirectoryserver.domain.com" username="encryptedUsername" password="encryptedPassword" >
    <Schema>
      <Column name="cn" ordinal="1" dataType="Text" maxLength="5000" isMandatory="false" validateData="false" trimWhitespace="true" description=""/>
      <Column name="member.userPrincipalName" ordinal="2" dataType="Text" maxLength="200" isMandatory="false" validateData="false" trimWhitespace="true" description=""/>
    </Schema>
    <Filter>
      lookup('Domain Name','Query Name')
    </Filter>
  </LDAPDataSource>
  <CinchyTableTarget model="" domain="Cinchy" table="Groups" suppressDuplicateErrors="false">
    <ColumnMappings>
      <ColumnMapping sourceColumn="cn" targetColumn="name" />
      <ColumnMapping sourceColumn="member.userPrincipalName" targetColumn="Users" linkColumn="Username" />
    </ColumnMappings>
    <SyncKey>
      <SyncKeyColumnReference name="name" />
    </SyncKey>
	<ChangedRecordBehaviour type="UPDATE" />
    <DroppedRecordBehaviour type="IGNORE" />
  </CinchyTableTarget>
</BatchDataSyncConfig>

Sync execution & scheduling

1. The below CLI command (see here for additional information on the syncdata command) should be used to execute the sync.

2. Update the command parameters (described in the table below) with your environment specific settings.

3. Execution of this command can be scheduled at your desired frequency using your scheduler of choice.

dotnet Cinchy.CLI.dll syncdata -s cinchyAppServer -u username -p "encryptedPassword" -m "Model" -f "AD_GROUP_SYNC" -d "TempDirectory"

Parameters

High number of Groups in ADFS

If you are syncing someone with a lot of ADFS groups, the server may reject the request for the header being too large. If you are able to login as a user with a few groups in ADFS but run into an error with users with a lot of ADFS groups (regardless of if those ADFS groups are in Cinchy), you will need to make the following changes:

Update the server max Request Header size

1. Follow the instructions outlined in this document.

CinchySSO AppSettings

In your CinchySSO app settings, you will also need to increase the max size of the request, as follows:

"AppSettings": {
  ...
  "MaxRequestHeadersTotalSize": {max size in bytes},
  "MaxRequestRequestBufferSize": {max size in bytes, use same as above},
  "MaxRequestBodySize": -1
}