AD Group Integration
This page contains information on how to leverage Active Directory groups within Cinchy.
Table of Contents
1. Group Management
This section defines how to manage Groups.
1.1 Cinchy Groups
Cinchy Groups are containers that have Users and other Groups within them as members. They are used 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 this table can only be managed by members of the Cinchy Administrators group. Each group has the following attributes:
1.2 How to Define a New AD Group
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).
Set the Group Type to "AD Group".
1.3 How to Convert an Existing Group to Sync with AD
To convert an existing group, update the Name attribute of the existing group record to match the AD Group (using the cn attribute).
Set the Group Type to "AD Group".
2. Group Membership Sync
AD Groups defined in Cinchy have their members sync-ed from AD through a batch process that leverages the Cinchy Command-line-interface (CLI).
2.1 Execution Flow
The sync operation performs the following high-level steps:
Fetches all Cinchy registered AD Groups using a Saved Query.
Retrieves the usernames of all members for each AD Group. The default attribute for username that is retrieved is "userPrincipalName", but configurable as part of the sync process.
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.
2.2 Dependencies
The Cinchy CLI Model must be installed in your instance of Cinchy.
An instance of the Cinchy CLI must be available to execute the sync.
A task scheduler is required to perform the sync on a regular basis (e.g. Autosys).
2.3 Configuration Steps
2.3.1 Create a Saved Query to retrieve AD Groups from Cinchy
Create a new query within Cinchy with the below CQL to fetch all AD Groups from the Groups table. The domain & name assigned to the query will be referenced in the subsequent step.
2.3.2 Create the Sync Config
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.
Once complete, create an entry with the config in your Data Sync Configurations table (part of the Cinchy CLI model).
If the userPrincipalName
attribute in Active Directory does not match what you expect to have as the Username in the Cinchy Users table (e.g. if the SAML token as part of your SSO integration returns a different ID), then you must replaceuserPrincipalName
in the XML config with the expected attribute.
The userPrincipalName
appears twice in the XML, once in the LDAPDataSource Columns and once in the CinchyTableTarget ColumnMappings.
2.3.3 Sync Execution & Scheduling
The below CLI command (see here for additional information on the syncdata command) should be used to execute the sync.
Update the command parameters (described in the table below) with your environment specific settings.
Execution of this command can be scheduled at your desired frequency using your scheduler of choice.
The user account credentials provided in above CLI syncdata command must have View/Edit access to Cinchy Groups table.
3. 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:
3.1 Update the Server Max Request Header Size
Follow the instructions outlined in this document.
3.2 CinchySSO App Settings
In your CinchySSO app settings, you will also need to increase the max size of the request, as follows:
Last updated