AD Group Integration

This page contains information on how to leverage Active Directory groups within Cinchy.

Group Management

Cinchy Groups

Cinchy Groups are containers that contain Users and other Groups within them as members, and 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:

Name - Group name, this must be unique across all groups within the system
Users - Users which are members of the group
User Groups - Groups which are members of the group
Owners - Users which are able to administer the membership of this group. By default Owners are also members of the group (i.e. they do not need to also be added into Users).
Owner Groups - Groups whose members are able to administer the membership of this group. By default, members of Owner Groups are also members of the group (i.e. they do not need to also be added into Users or User Groups).
Group Type - Either "Cinchy Group" or "AD Group". If this is a "Cinchy Group", this means that membership is maintained directly in Cinchy. If this is an "AD Group", then a sync process will be leveraged to maintain the membership and overwrite the Users.

How to define a new AD Group

Create a new record within the Groups Table with the same name as the AD Group (use the cn attribute).
Set the Group Type = "AD Group".

How to convert an existing group to sync with AD

Update the Name attribute of the existing group record to match the AD Group (use the cn attribute).
Set the Group Type to "AD Group".

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).

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, 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

Cinchy CLI Model must be installed in your instance of Cinchy, steps are mentioned here
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)

Configuration Steps

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.

SavedQuery

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

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).

ConfigXML

<?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>

XML Tag

Attribute

Content

LDAPDataSource

ldapserver

The LDAP server url

(e.g. LDAP:\\activedirectoryserver.domain.com)

LDAPDataSource

username

The encrypted username to authenticate with the AD server

(generated using the CLI's encrypt command -

dotnet Cinchy.CLI.dll encrypt -t "Domain/username").

LDAPDataSource

password

The encrypted password to authenticate with the AD server

(generated using the CLI's encrypt command -

dotnet Cinchy.CLI.dll encrypt -t "password").

LDAPDataSource -> Filter

Domain Name

The domain of the Saved Query that retrieves AD Groups

LDAPDataSource -> Filter

Query Name

The name of the Saved Query that retrieves AD Groups

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 replaceuserPrincipalNamein 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.

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.

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

Options

Description

-s, --server

Required. The full path to the Cinchy server without the protocol

(e.g. cinchy.co/Cinchy).

-u, --userid

Required. The user id to login to Cinchy.

This account must have access to edit the Groups table

-p, --password

Required. The encrypted password of the specified user

(generated using the CLI's encrypt command -

dotnet Cinchy.CLI.dll encrypt -t "password").

-m, --model

Required. The Cinchy model to use for retrieval of batch configuration information and persistence of the execution log.

-d, --tempdirectory

Required. The path to a directory that the CLI can use for storing temporary files to support the sync (e.g. partitioned data).

The user account credentials provided in above CLI syncdata command must have View/Edit access to Cinchy Groups table.

References

PreviousConfiguring ADFS NextHigh Number of Groups in ADFS

Last updated 3 years ago