Table of Contents

1. ADFS Configuration

1. On your ADFS Server, Open AD FS Management.

2. Right-click on Relying Party Trusts and select Add Relying Party Trust to launch the Add Relying Party Trust Wizard (Image 1).

3. In the ADFS Wizard, select Claims Aware > Start > Select Data Source

4. Select Enter Data About the Relying Part Manually > Next

5. Under Specify Display Name, enter a Display Name of your choice

6. Under Configure Certificates, do not choose any certificates

7. Under Configure URL, Select Enable support for the SAML 2.0 SSO Web SSO protocol.

8. Enter your Login URL in the below format:

https://<cinchy-sso-URL>/Saml2/Acs

9. Under Configure Identifiers, choose an Identifier

10. Select Next until the process finishes.

2. Claim Issuance Policy

1. To begin configuring you Claim Issuance policy, Right-click on the Relying Party Trust you just created (look for the Display Name) and click Edit Claim Issuance Policy.

2. Click on Add Rule > Claim Rule > Send LDAP Attributes as Claims.

3. Add your Claim Rule Name

4. Under Attribute Store, choose Active Directory. Map the LDAP attribute to the following outgoing claim types:

4. Click Finish.

5. Click on Edit Rule.

6. Click on View Rule Language and copy out the Claim URLs for the claims defined. This information will be needed in a later step to configure your Cinchy appsettings.json. This will look something like this:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
  => issue(store = "Active Directory",
           types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
                    "sub",
                    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
                    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
                    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
                    "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"),
           query = ";userPrincipalName,sAMAccountName,givenName,sn,mail,memberOf;{0}",
           param = c.Value);

7. Click OK to save the rule.

8. Right-click on Relying Party Trust > Properties.

9. Go to the Advanced tab and set the secure hash algorithm to SHA-256 (Image 3).

3. Cinchy Configuration

1. Open https://<your.AD.server>/FederationMetadata/2007-06/FederationMetadata.xml in a browser and save the XML file in the cinchysso folder.

2. Open IIS Manager and create an HTTPS binding on the Cinchy site (if necessary).

3. Go to sso site and bind HTTPS with it. Make sure to use the same port as the login URL above if specified.

Cinchy appsettings.json

AppSettings Section

External Identity Claim Section

You will need the Rule Language URLs you copied out from the ADFS Configuration above. Using the same example as above, we would get the following (replace with your own URLs).

{
  "AppSettings": {
    ...
    },
  "ExternalIdentityClaimSection": {
    "FirstName": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
    },
    "LastName": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    },
    "Email": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    },
    "MemberOf": {
      "ExternalClaimName": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
    }
  }
}

Web.config

Add the 3 following lines to your web.config within the appSettings section:

<appSettings>
  ...
  <add key="UseHttps" value="true" />
  <add key="StsAuthorityUri" value="https://<your.cinchy.url>" />
  <add key="StsRedirectUri" value="https://<your.cinchysso.url>/Account/LoginRedirect" />
  ...
</appSettings>

1. Overview

Cinchy supports integration with any Identity Provider that issues SAML tokens (e.g. Active Directory Federation Services) for authenticating users.

It follows an SP Initiated SSO pattern where the SP will Redirect to the IdP and the IdP must submit the SAML Response via an HTTP Post to the SP Assertion Consumer Service.

Below is a diagram outlining the flow when a non-authenticated user attempt to access a Cinchy resource (Image 1).

2. Configure SAML Authentication - IIS Deployments

Cinchy must be registered with the Identity Provider. As part of that process you'll supply the Assertion Consumer Service URL, choose a client identifier for the Cinchy application, and generate a metadata XML file.

The Assertion Consumer Service URL for Cinchy is the base URL for the CinchySSO application followed by "{AcsURLModule}/Acs"

e.g. https:///<CinchySSO URL>/Saml2/Acs

e.g. https://myCinchyServer/Saml2/Acs

To enable SAML authentication within Cinchy, follow the below steps:

1. You can find the necessary metadata XML from the applicable identity provider you're using the login against. Place the metadata file in the deployment directory of the CinchySSO web application.

2. Update the values of the below app settings in the CinchySSO appsettings.json file.

• SAMLClientEntityId - The client identifier chosen when registering with the Identity Provider

• SAMLIDPEntityId - The entityID from the Identity Provider metadata XML

• SAMLMetadataXmlPath - The full path to the metadata XML file

• AcsURLModule - This parameter is needs to be configured as per your SAML ACS URL. For example, if your ACS URL looks like this "https:///<CinchySSO URL>/Saml2/Acs", then the value of this parameter should be "/Saml2"

Once SSO is enabled, the next time a user arrives at the Cinchy login screen they will see an additional button for "Single Sign-On".

3. Configure SAML Authentication - Kubernetes Deployments

1. Retrieve your metadata.xml file from the identity provider you're using the login against.

2. Navigate to your cinchy.kubernetes\environment_kustomizations_template\instance_template\idp\kustomization.yaml file.

3. Add your metadata.xml patch into your secrets where specified below as <<metadata.xml>>

- target:
    version: v1
    kind: Secret
    name: idp-secret-appsettings
  patch: |-
    - op: replace
      path: /data/appsettings.json
      value: <<idp_appsettings_json>>
    - op: add
      path: /data/metadata.xml
      value: <<metadata.xml>>

4. Navigate to your devops.automation > deployment.json in your Cinchy instance.

5. Add the following fields into the .json and update them below using the metadata.xml.

"sso": {
    "SAMLClientEntityId": "cinchy-dev", // Cinchy instance name
    "SAMLMetadataXmlPath": "/usr/share/appsettings/metadata.xml",
    // All below values cam be taken from the metadata.xml retrieved in step 1.
    "SAMLIDPEntityId": "",
    "SAMLSSOServiceURL": "", // this value is taken from the 'Location' attribute in the metadata.xml
    "AcsURLModule": "",
    "FirstNameExternalClaimName": "",
    "LastNameExternalClaimName": "",
    "EmailExternalClaimName": "",
    "MemberOfExternalClaimName": "",
    "metadata.xml": "BASE64_ENCODED_METADATA.XML"
}

6. Navigate to your kubernetes\environment_kustomizations_template\instance_template_encoded_vars\idp_appsettings_json.

7. Update the below code with your proper AppSettings and ExternalIdentityClaimSection details.

{
    "ConfigSettings": {
        "AppSettings": {
            "SAMLClientEntityId": "<<SAMLClientEntityId>>",
            "SAMLIDPEntityId": "<<SAMLIDPEntityId>>",
            "SAMLMetadataXmlPath": "<<SAMLMetadataXmlPath>>",
            "SAMLSSOServiceURL": "<<SAMLSSOServiceURL>>",
            "AcsURLModule": "<<AcsURLModule>>",
        },
        "ExternalIdentityClaimSection": {
            "FirstName": {
                "ExternalClaimName": "<<FirstNameExternalClaimName>>"
            },
            "LastName": {
                "ExternalClaimName": "<<LastNameExternalClaimName>>"
            },
            "Email": {
                "ExternalClaimName": "<<EmailExternalClaimName>>"
            },
            "MemberOf": {
                "ExternalClaimName": "<<MemberOfExternalClaimName>>"
            }
        }
    }
}

8. Run devops automation script which will populate the updated outputs into the cinchy.kubernetes repo.

9. Commit your changes and push to your source control system.

10. Navigate to your ArgoCD dashboard and refresh the idp-app to pick up your changes. Your pods will be restarted and will pick up the latest secrets.

11. Once the pods are healthy, you can verify the changes by looking for the SSO Tab on your Cinchy login page.

4. User Management

Before a user is able to login through the SSO flow, the user must be set up in Cinchy with the appropriate authentication configuration.

Users in Cinchy are maintained within the Users table in the Cinchy domain. Each user in the system is configured with 1 of 3 Authentication Methods:

• Cinchy User Account - These are users that are created and managed directly in the Cinchy application. They log into Cinchy by entering their username and password on the login screen.

• Non Interactive - These accounts are intended for application use.

• Single Sign-On - These users authenticate through the SSO Identity Provider (configured using the steps above). They log into Cinchy by clicking the "Login with Single Sign-On" link on the login screen.

4.1 How to define a new SSO User

Create a new record within the Users table with the Authentication Method set to "Single Sign-On".

4.2 How to convert an existing user to SSO User

Change the Authentication Method of the existing user to "Single Sign-On".

4.3 Logging in with SSO

Once a user is configured for SSO, they can then click the "Login with Single Sign-On" link on the login page and that will then take them through the Identity Provider's authentication flow and bring them into Cinchy.

5. Automatic User Creation - IIS Deployments

Once SSO has been enabled on your instance of Cinchy, by default, any user that does not exist in the Cinchy Users table will not be able to login regardless if they are authenticated by the Identity Provider.

Enabling Automatic User Creation means that upon login, if the Identity Provider authorizes the user, an entry for this user will automatically be created in the Cinchy Users table if one does not already exist. This means that any SSO authenticated user is guaranteed to be able to access the platform.

In addition to creating a user record, if AD Groups are configured within Cinchy, then the authenticated user will automatically be added to any Cinchy mapped AD Groups where they are a member. See AD Group Integration for additional information on how to define AD Groups in Cinchy.

See below for details on how to enable Automatic User Creation.

5.1 Prerequisites for Automatic User Creation

The Identity Provider configuration must include the following claims in addition to the base configuration in the SAML token response:

• First Name

• Last Name

• Email

In order to enable automatic group assignment for newly created users (which is applicable if you plan on using AD Groups), then you must also include an attribute that captures the groups that this user is a member of (e.g. memberOf field in AD)

5.2 Configuration Setup

Enabling automatic user creation requires the following changes. For IIS Deployments this will be done to the appsettings.json file in the CinchySSO web application.

1. Add ExternalClaimName attribute values under "ExternalIdentityClaimSection" in appsettings.json file. Do not add the value for "MemberOf" if you don't want to enable automatic group assignment .

2. The ExternalClaimName value must be updated to create a mapping between the attribute name in the SAML response and the required field. (e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname is the name in the SAML response for the FirstName field)

"ExternalIdentityClaimSection": {
			"FirstName": {
				"ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
			},
			"LastName": {
				"ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
			},
			"Email": {
				"ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
			},
			"MemberOf": {
				"ExternalClaimName": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
			}
		}

6. Further Reading

• Configuring ADFS

• AD Group Integration

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

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

1.3 How to 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".

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:

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

2.2 Dependencies

1. The Cinchy CLI Model must be installed in your instance of Cinchy.

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

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

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

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

2.3.2 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. Once complete, 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>

2.3.3 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" 

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

1. Follow the instructions outlined in this document.

3.2 CinchySSO App Settings

1. 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
}

1. How to Enable TLS 1.2

1. Navigate to the CinchySSO Folder > appsettings.json file.

2. Find the following line:

3. Replace the above line with the following:

4. Navigate to the Cinchy Folder > web.config file.

5. Find the following line:

6. Replace the above line with the following:

7. You may need to restart the application pools in IIS for the changes to take effect.