Single Sign-On (SSO) Integration
This page walks through the integration of an Identity Provider with Cinchy via SAML Authentication
Last updated
This page walks through the integration of an Identity Provider with Cinchy via SAML Authentication
Last updated
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.
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://myCinchyServer/CinchySSO/identity/AuthServices/Acs. {AcsURLModule} value needs to be defined in appsettings.json file
To enable SAML authentication within Cinchy, follow the below steps:
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.
If you are using Azure AD for this process, you can find your metadata XML by following these steps.
If you are using GSuite 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.
2. Update the value 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.
Example ACS URL: "https:///CinchySSO/identity/AuthServices/Acs"
Example parameter value: "/identity/AuthServices"
3. The following parameters pertain to signed SAML IdP requests. Within the IDPSSODescriptor tag of the metadata is the below WantAuthnRequestSigned attribute:
If the value for this attribute is set to "true" then your Identity Provider is expecting the request to be "Signed". In this case, please enter the following parameters:
SAMLSignCertificatePath - This parameter needs to be the path for the PFX file of the certificate. This must match the same certificate in your identity provider.
SAMLSignCertificatePassword - This parameter is the password for the above mentioned PFX file. You may choose to encrypt it or not.
SAMLSignCertificateMinAlgorithm - This parameter is optional and only needed for PFX files that are generated at different algorithm levels.
The possible options for this parameter are:
SHA1
SHA256
SHA384
SHA512
http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2000/09/xmldsig#rsa-sha256
http://www.w3.org/2000/09/xmldsig#rsa-sha384
http://www.w3.org/2000/09/xmldsig#rsa-sha512
4. If the Identity Provider is configured for the request to be encrypted please provide a PFX file, with a non-empty password, for the below attributes:
SAMLEncryptedCertificatePath - This parameter needs to be the path for the PFX file of the certificate. This must match the same certificate in your identity provider.
SAMLEncryptedCertificatePassword - This parameter is the password for the above mentioned PFX file.
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. Click here for more information.
Once SSO is enabled, the next time a user arrives at the Cinchy login screen they will see an additional button "Single Sign-On". Before a user is able to login through the SSO flow, the user must be set up in Cinchy with the appropriate authentication configuration. See the User Management section below for instructions on how to perform this setup.
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.
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 Single Sign-On users, the value entered is ignored. You can input "n/a".
Change the Authentication Method of the existing user to "Single Sign-On".
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.
If a user successfully authenticates with the Identity Provider but has not been set up in the Users table, then they will see the following error message - " You are not 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.
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.
Users that are automatically added will not 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.
The Identity Provider configuration must include the following claims in addition to the base configuration in the SAML token response:
First Name
Last Name
In order to enable automatic group assignment for newly created users (applicable if you plan on using AD Groups), then also include an attribute that captures the groups that this user is a member of (e.g. memberOf field in AD)
Enabling automatic user creation requires the following changes to the appsettings.json file in the CinchySSO web application.
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 .
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)
