Single Sign-On (SSO) integration

This page walks through the integration of an Identity Provider with Cinchy via SAML Authentication

Overview

Cinchy supports integration with any Identity Provider that issues SAML tokens (such as 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).

Configure SAML authentication - IIS deployments

You must register Cinchy 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 of Cinchy is the base URL of the CinchySSO application followed by "{AcsURLModule}/Acs"

https:///\<CinchySSO URL>/Saml2/Acs

https://myCinchyServer/Saml2/Acs

To enable SAML authentication within Cinchy, do the following:

You can find the necessary metadata XML from the applicable identity provider. Place the metadata file in the deployment directory of the CinchySSO web application.

If you are using Azure AD for this process, you can find your metadata XML by following these steps.

If you are using Google Workspace for this process, you can find your metadata XML by following steps 1-6 here.

If you are using ADFS for this process, you can find your metadata XML at the following link, inputting your own information for <your.ad.server>: https://<your.AD.server>/FederationMetadata/2007-06/FederationMetadata.xml

If you are using Okta for this process, you can find your metadata XML by following these steps.

If you are using Auth0 for this process, you can find your metadata XML by following these steps.

If you are using PingIdentity for this process, you can find your metadata XML by following these steps.

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

When configuring the Identity Provider, the only required claim is a user name identifier. If you plan to enable automatic user creation, then additional claims must be added to the configuration, see section 4 below for more details.

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

Configure SAML authentication - Kubernetes deployments

Retrieve your metadata.xml file from your identity provider.

If you are using Azure AD for this process, you can find your metadata XML by following these steps.

If you are using Google Workspace for this process, you can find your metadata XML by following steps 1-6 here.

If you are using Okta for this process, you can find your metadata XML by following these steps.

If you are using Auth0 for this process, you can find your metadata XML by following these steps.

If you are using PingIdentity for this process, you can find your metadata XML by following these steps.

Navigate to your cinchy.kubernetes\environment\_kustomizations\_template\instance\_template\idp\kustomization.yaml file.
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>>

Navigate to your devops.automation > deployment.json in your Cinchy instance.
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 get from metadata.xml and fill them here.
    "SAMLIDPEntityId": "",
    "SAMLSSOServiceURL": "",
    "AcsURLModule": "",
    "FirstNameExternalClaimName": "",
    "LastNameExternalClaimName": "",
    "EmailExternalClaimName": "",
    "MemberOfExternalClaimName": "",
    "metadata.xml": "BASE64_ENCODED_METADATA.XML"
}

Navigate to your kubernetes\environment_kustomizations_template\instance_template_encoded_vars\idp_appsettings_json.
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>>"
            }
        }
    }
}

Run DevOps automation script which will populate the updated outputs into the cinchy.kubernetes repository.
Commit your changes and push to your source control system.
Navigate to your ArgoCD dashboard and refresh the idp-app to pick up your changes. It will also delete your currently running pods to pick up the latest secrets.
Once the pods are healthy, you can verify the changes by looking for the SSO Tab on your Cinchy login page.

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.

Define a new SSO User

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

The password field in the Users table is mandatory. For SSO users, the value entered is ignored. You can input n/a.

Convert an existing user to SSO User

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

When a user is configured for SSO, they can select Login with Single Sign-On on the login page, which directs logins through the Identity Provider's authentication flow.

If a user successfully authenticates with the Identity Provider but hasn't been set up in the Users table, then they will see the following error message - " You aren't a registered user in Cinchy. Please contact your Cinchy administrator." To avoid the manual step to add new users, you can consider enabling automatic user creation.

Automatic user creation - IIS deployments

On SSO enabled Cinchy instances, users that don't exist in the Cinchy Users table won't be able to login, regardless if they're authenticated by the Identity Provider.

If you enable Automatic User Creation, the Identity Provider authorizes the user and automatically create a user entry in the Cinchy Users table if one doesn't already exist. This means that any SSO authenticated user is guaranteed to be able to access the platform.

If AD Groups are configured within Cinchy, then the authenticated user is also automatically be added to any Cinchy mapped AD Groups where they're 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.

Users that are automatically added won't be allowed to create or modify tables and queries. To provision this access, Can Design Tables and Can Design Queries must be checked on the User record in the Cinchy Users table.

Prerequisites for automatic user creation

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

First Name
Last Name
Email

To enable automatic group assignment for newly created users, then you must also include an attribute that captures the groups that this user is a member of. For example, the memberOf field in AD. This is applicable if you plan on using AD Groups.

Configuration setup

To enable automatic user creation, you require the following changes. For IIS Deployments this will be done to the appsettings.json file in the CinchySSO web application.

Add ExternalClaimName attribute values under "ExternalIdentityClaimSection" in appsettings.json file. Don't add the value for MemberOf if you don't want to enable automatic group assignment .
The ExternalClaimName value must be updated to create a mapping between the attribute name in the SAML response and the required field. For example, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname is the name in the SAML response for the FirstName field.

ExternalIdentityClaimSection

"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

PreviousDeployment prerequisites NextEnable TLS 1.2

Last updated 7 months ago