Component diagram

The below diagram shows a high level overview of Cinchy's Infrastructure components when deploying on IIS.

Component overview

Overview

This section will guide you through the considerations and the prerequisites before deploying version 5 of the Cinchy platform.

The pages in this section include:

• Deployment Architecture Overview: This page explores your two high-level options for deploying Cinchy, on Kubernetes or on VM, and why Cinchy recommends a Kubernetes deployment. It also walks you through selecting a database to run your deployment on and some sizing considerations.

  • Kubernetes Deployment Architecture: This page provides Infrastructure (for both Azure and AWS), Cluster, and Platform component overviews for Kubernetes deployments. It also guides you through considerations about your cluster configuration.

  • IIS Deployment Architecture: This page provides Infrastructure and Platform component overviews for IIS (VM) deployments.

• Deployment Prerequisites: This page details important prerequisites for deploying Cinchy v5.

Deployment planning checklist

Use the following checklist when planning for your Cinchy v5 deployment. Each item links to the appropriate documentation page.

• Will you run on Kubernetes or a VM?

The main differences between a Kubernetes based deployment and an IIS deployment are:

• Kubernetes offers the ability to elastically scale.

• IIS limits certain components to running single instances.

• As all caching is in memory in an IIS deployment, if multiple instances are online for redundancy there is point to point communication between them (HTTP requests on the server IPs) required to maintain the cache.

• Performance is better on Kubernetes because of Kafka/Redis

• Prometheus/Grafana and OpenSearch aren't available in an IIS deployment

• The Maintenance CLI runs as a CronJob in Kubernetes while this needs to be orchestrated using a scheduler for an IIS deployment.

• Upgrades are simpler with the container images on Kubernetes.

Kubernetes checklist

If you will be running on Kubernetes, please review the following checklist:

• Which database will you use?

• Define your sizing.

• Define your cluster configuration.

• How many clusters will you need?

  • Will you be sharing from an existing cluster?

  • Will you be running multiple environments on a single cluster?

  • Will you be using Cinchy's recommended cluster components or your own?

• Define your object storage requirements.

  • Create an S3 compatible bucket.

• Create your SSL Certs (With the option to use Self-Signed).

• Define your Secrets Management, if desired.

• Define whether you will use Cinchy's Docker Images or your own.

  • If using Cinchy’s, pull the images.

• Access the deployment repositories and copy them into your own repository (GitHub or similar).

IIS checklist

If you will be running on IIS, please review the following checklist:

• Ensure that you have an instance of SQL Server 2017+

• Ensure that you have a Windows Server 2012+ machine with IIS 7.5+ installed

• Install .net core Hosting bundle Version 6.0

  • Specifically, install: ASP.NET Core/.NET Core Runtime & Hosting Bundle

• Ensure that you review the minimum web server hardware recommendations

• Ensure that you review the minimum database server hardware recommendations

• Define your application storage requirements.

• Ensure you have access to the release binary.

Infrastructure configuration (on cluster)

The diagram below shows a high level overview of a possible Infrastructure diagram with components on the cluster, but your specific configuration may vary (Image 1).

AWS infrastructure configuration (outside cluster)

When deploying Cinchy version 5 on Kubernetes, you may deploy via Amazon Web Services (AWS). The diagram below shows a high level overview of a possible AWS Infrastructure with components outside the cluster, but your specific configuration may vary (Image 2).

Infrastructure component overview

Azure infrastructure configuration (outside cluster)

When deploying Cinchy v5 on Kubernetes, you may deploy via Microsoft Azure. The diagram below shows a high level overview of possible Azure Infrastructure with components outside the cluster, but your specific configuration may vary (Image 3).

Infrastructure component overview

Cluster level component overview

The following highlighted area provides a high-level overview of cluster level components used when deploying Cinchy on Kubernetes and what versions they're running.

These are created once per cluster. Clients may choose to run these components outside of the cluster or replace with their own comparable components. This diagram shows them in the cluster (Image 4).

Cluster level components

These are created once per cluster. Clients may choose to run these components outside of the cluster or replace with their own comparable components.

• Service Mesh - Istio: Istio handles and routes all inbound traffic to your Cinchy instance, keeping it secure and managed.

• Monitoring/Alerting - Prometheus & Grafana: Prometheus consumes metrics from the running components in your environment, which you can visualize into user friendly graphs and dashboards by Grafana. Prometheus can also connect to third party services to provide alerting capabilities. Both Prometheus and Grafana use persistent storage.

• Logging - OpenSearch and Fluent Bit: OpenSearch captures and indexes all logs in a single, accessible location. These logs can be queried, searched, and filtered, and Correlation IDs mean that they can also be traced across various components. These logging components take advantage of persistent storage.

• Caching - Redis: Redis facilitates a distributed lock using RedLock, which guarantees lock synchronizations across Cinchy instances. It's also a storage location for the execution output when running batch data syncs.

• Event Processing - Kafka: This acts as the middleware for messaging between components through a queuing mechanism. Kafka features persistent storage.

Cluster configuration

Before you deploy Cinchy on Kubernetes, consider the following about your cluster configuration :

• How many clusters will you need?

• Will you be sharing from an existing cluster?

• Will you be running multiple environments on a single cluster?

Instance component overview

Each Cinchy instance uses the following components to either provide an experience to users/applications or connect data in/out of Cinchy. You can deploy multiple Cinchy instances per cluster, so these components will repeat for each environment.

The following highlighted area provides a high-level overview of instance level components used when running Cinchy on Kubernetes (Image 5).

• Meta Experiences: Cinchy offers pre-packaged experiences that you can import into your Cinchy environment and use on your data network. This includes experiences like Meta-Forms and Meta-Reports.

• Connections: Use the Cinchy Connections experience to create data syncs in/out of the platform. It features persistent storage.

• Data Browser: Cinchy’s data collaboration platform features a Universal Data Browser that allows users to view, change, analyze, and otherwise interact with all data on the network. The Data Browser even enables non-technical business users to manage and update data, build models, and set controls, all through an easy and intuitive UI.

• Identity Provider: An Identity Provider (IdP) creates and manages user credentials and associated identity attributes. Cinchy uses IdPs authentication services to authenticate end-users.

• Event Listener: The Event Listener picks up events from connected sources during a data sync. Review the Data Sync page for further information on the Event Listener. The Event Listener uses persistent storage.

• Event Stream Worker: The Event Stream Worker processes data picked up by the Event Listener during data syncs. Review the Data Sync page for further information on the Event Stream Worker. The Event Worker uses persistent storage.

• Maintenance (Batch Jobs): Cinchy performs maintenance tasks through the CLI. This includes the data erasure and data compression deletions.

GitOps

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes that simplifies the application deployment and lifecycle management. ArgoCD is highly recommended for deploying Cinchy, but you can also use another tool.

Once you set up the configurations, ArgoCD automates the deployment of the desired application states into your specified target environments. Implemented as a Kubernetes controller, it continuously monitors running applications and compares the current, live state against the desired target state (as specified in your repositories).

Certainly, presenting the information in a table can help make it easier to understand. Here's how you can structure it:

Before You Begin

Before starting with the ADFS configuration, make sure to have following information:

Having these details readily available will streamline the ADFS configuration process.

Configuration Steps in ADFS

1. Navigate to AD FS Management on your ADFS server.

2. Right-click on Relying Party Trusts and choose Add Relying Party Trust to open the Add Relying Party Trust Wizard.

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

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

5. Fill in a Display Name under Specify Display Name.

6. Skip certificate configuration in Configure Certificates.

7. In Configure URL, select Enable support for the SAML 2.0 SSO Web SSO protocol.

8. Input your login URL as follows:

   Copy

   https://{your.cinchysso.url}/Saml2/Acs

9. Under Configure Identifiers, add an Identifier and press Next to complete the setup.

Set up Claim Issuance Policy

1. Right-click on the newly created Relying Party Trust (located by its Display Name) and select Edit Claim Issuance Policy.

2. Select Add Rule > Claim Rule > Send LDAP Attributes as Claims.

3. Input a Claim Rule Name.

4. In the Attribute Store, select Active Directory. Map the LDAP attributes to the corresponding outgoing claim types as shown in the table below:

1. Select Finish.

2. Select Edit Rule > View Rule Language. Copy the Claim URLs for later use in configuring your Cinchy appsettings.json. It should look like the following:

   Copy

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

3. Press OK to confirm and save.

Configuration for Cinchy

Initial setup

1. Retrieve and save the Federation Metadata XML file from the following location: https://{your.ADFS.server}/FederationMetadata/2007-06/FederationMetadata.xml.

2. If needed, use IIS Manager to establish an HTTPS connection for the Cinchy website.

3. Also establish an HTTPS connection for the SSO site. Make sure the port number aligns with the one specified in the login URL.

Configuration for appsettings.json

App Settings Section

External identity claim section

You will need to refer to the Rule Language URLs you copied from the ADFS Configuration. Replace the placeholders below with your own URLs:

{
  "AppSettings": {
    // Replace placeholders below with URLS
  },
  "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"
    }
  }
}

Edit web.config

Insert the following lines within the <appSettings> section of your web.config file. Make sure to replace the {your.cinchy.url} and {your.cinchysso.url} with your Cinchy and Cinchy SSO values.

<appSettings>
  <!-- Replace placeholders below with URLS -->
  <add key="UseHttps" value="true" />
  <add key="StsAuthorityUri" value="https://{your.cinchy.url}" />
  <add key="StsRedirectUri" value="https://{your.cinchysso.url}/Account/LoginRedirect" />
  <!--  -->
</appSettings>

Group management

This section defines how to manage Groups.

Cinchy Groups

Cinchy Groups are containers that have Users and other Groups within them as members. Use Groups 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, only members of the Cinchy Administrators group can manage this table Each group has the following attributes:

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.

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.

Group membership sync

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's 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.

Dependencies

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

3. You must have a task scheduler to perform the sync on a regular basis (For example, AutoSys).

Configuration steps

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 and name assigned to the query will be referenced in the next step.

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. Create an entry with the config in your Data Sync Configurations table (part of the Cinchy CLI model).

Sync execution & scheduling

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.

Parameters

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:

Update the server max Request Header size

CinchySSO AppSettings

In your CinchySSO app settings, you will also need to increase the max size of the request, as follows:

Kubernetes vs IIS

When choosing to deploy Cinchy version 5, you must decide whether to deploy via Kubernetes or on a VM (IIS).

is an open-source system that manages and automates the full lifecycle of container-based applications. You now have the ability to deploy Cinchy v5 on Kubernetes, which helps to simplify your deployment and enhance your scaling. Kubernetes can maximize your container capacity and scale up/down with your current operations.

• Grafana, OpenSearch, OpenSearch Dashboard: Working together, these three applications provide a visual logging dashboard for all the information coming in from your database pods. This streamlines your search for information by putting the control into your hands and compiling your logs in one easy to access place — you can now write a query against all your logs, in all your environments. You will have access to a default configuration out of the box, but you can also customize your dashboards as well.

• Prometheus: With the Kubernetes addition, you now have access to Prometheus for your metrics dashboard. Prometheus records real-time metrics in a time series database used for event monitoring and alerting. You can then create custom dashboards to display your data in an easy to use visual that makes reporting on your metrics easy, and even set up push alerts based on your custom needs.

You also have the option to run Cinchy on , which was the traditional deployment method before Cinchy v5. Internet Information Services (IIS) for Windows Server is a flexible, secure and manageable Web server for hosting anything on the Web.

Choose a database

Before deploying Cinchy v5, you must select which database you want to use.

The following list outlines the supported databases for Kubernetes Deployments.

For IIS Deployments

Microsoft SQL Server

• Microsoft SQL Server is a relational database management system. As a database server, it's a software product with the primary function of storing and retrieving data as requested by other software applications—which may run either on the same computer or on another computer across a network.

• Microsoft Azure SQL Database is a managed cloud database provided as part of Microsoft Azure. It runs on a cloud computing platform, and access to it's provided as a service. Managed database services take care of scalability, backup, and high availability of the database.

• SQL Managed Instance is a managed, cloud-based, always up-to-date SQL instance that combines broad SQL Server engine compatibility with the benefits of a fully managed PaaS.

Amazon Aurora

• Amazon Aurora (Aurora) is a fully managed relational database engine that's compatible with MySQL and PostgreSQL. It combines the speed and reliability of high-end commercial databases with the simplicity and cost-effectiveness of open-source databases. Aurora is part of the managed database service Amazon Relational Database Service (Amazon RDS). Amazon RDS is a cloud web service that makes it easier to set up, operate, and scale a relational database.

PostgreSQL

• PostgreSQL is a free and open-source relational database management system emphasizing extensibility and SQL compliance. PostgreSQL comes with features aimed to help developers build applications, administrators to protect data integrity and build fault-tolerant environments, and help you manage your data no matter how big or small the dataset.

• Amazon RDS makes it easy to set up, operate, and scale cloud-based PostgreSQL deployments. With Amazon RDS, you can deploy scalable PostgreSQL deployments with cost-efficient and resizable hardware capacity. Amazon RDS manages complex and time-consuming administrative tasks such as PostgreSQL software installation and upgrades; storage management; replication for high availability and read throughput; and backups for disaster recovery. Amazon RDS for PostgreSQL gives you access to the capabilities of the familiar PostgreSQL database engine.

• This is a fully managed and intelligent Azure Database for PostgreSQL. Enjoy high availability with a service-level agreement (SLA) up to 99.99 percent, AI-powered performance optimization, and advanced security. A fully managed database that automates maintenance, patching, and updates. Provision in minutes and independently scale compute or storage in seconds.

Sizing considerations and requirements

Before deploying Cinchy v5, you need to define your sizing requirements.

Sizing

Kubernetes sizing

Cluster sizing recommendations vary and are dependant on a number of deployment factors. We've provided the following general sizing recommendations, but encourage you to explore more personalized options.

CPU: 8 Cores

Memory: 32GB Ram

Number of Servers: 3

AWS: m5.2xlarge

Azure: D8 v3

IIS sizing

Application storage requirements

If you are choosing to deploy Cinchy v5 on IIS, then you need to ensure that your VM disks have enough application storage to run your clusters.

Object storage requirements

If you are using Terraform for your Kubernetes deployment, you will need to set up a new S3 compatible bucket to manually to store your state file. You will also need a bucket for Connections, to store error files created during data syncs.

Example Terraform Bucket: cinchy-terraform-state

Example Connection Bucket: cinchy-connections-cinchy-nonprod

S3 provides unlimited scalability and it charges only for what you use/how much you store on it, so there are no sizing definitions.

General Kubernetes deployment prerequisites

Before deploying Cinchy v5 on Kubernetes, you must follow the steps listed below.

Download your tools

Install the following tools on the machine where the deployment will run:

• (v1.23.0+)

• (You can also use on Windows)

Create your domains

All your Cinchy environments will need a domain for each of the following:

• ArgoCD

• OpenSearch

• Grafana

Do this through your specific domain registrar. For example, GoDaddy or Google Domains.

SSL certs

You must have valid SSL Certs ready when you deploy Cinchy v5. Cinchy recommends using a wildcard certificate if ArgoCD will be exposed via a subdomain. Without the wildcard certificate, you must create a port forward using kubectl on demand to access ArgoCD's portal.

Secrets management

Although optional, Cinchy strongly recommends secret management for storing and accessing secrets that you use in the deployment process. Cinchy currently supports:

Single sign-on

Docker images

You can use Cinchy Docker images or your own. If you would like to use Cinchy images, please follow the section below to access them.

Access Cinchy Docker images

You will pull Docker images from Cinchy's AWS Elastic Container Registry (ECR).

Create your repositories

• cinchy.terraform: Contains all Terraform configurations.

• cinchy.argocd: Contains all ArgoCD configurations.

• cinchy.kubernetes: Contains cluster and application component deployment manifests.

• cinchy.devops.automations: Contains the single configuration file and binary utility that maintains the contents of the above three repositories.

Access to Cinchy artifacts

You will need to access and download the Cinchy artifacts before deployment.

To access the Kubernetes artifacts:

2. Navigate to the release you wish to deploy.

3. Download the .zip file(s) listed under the Kubernetes Artifacts column.

Kubernetes Azure requirements

If you are deploying Cinchy v5 on Azure, you require the following:

Terraform requirements

• A resource group that will contain the Azure Blob Storage with the terraform state.

• A storage account and container (Azure Blob Storage) for persisting terraform state.

The deployment template has two options available:

• Use an existing resource group.

• Creating a new one.

Existing resource group

If you prefer an existing resource group, you must provision the following before the deployment:

• The resource group.

• A VNet within the resource group.

• A single subnet. It's important that the address range be enough for all executing processes within the cluster, such as a CIDR ending with /22 to provide a range of 1024 IPs.

New resource group

• If you prefer a new resource group, all resources will be automatically provisioned.

• The quota limit of the Total Regional vCPUs and the Standard DSv3 Family vCPUs (or equivalent) must offer enough availability for the required number of vCPUs (minimum of 24).

• An AAD user account to connect to Azure, which has the necessary privileges to create resources in any existing resource groups and the ability to create a resource group (if required).

Kubernetes AWS requirements

If you are deploying Cinchy v5 on AWS, you require the following:

Terraform requirements:

The template has two options available:

• Use an existing VPC.

• Create a new one.

Existing VPC

• If you prefer an existing VPC, you must provision the following before the deployment:

  • The VPC. It's important that the address range be enough for all executing processes within the cluster, such as a CIDR ending with /21 to provide a range of 2048 IPs.

  • 3 Subnets (one per AZ). It's important that the address range be enough for all executing processes within the cluster, such as a CIDR ending with /23 to provide a range of 512 IPs.

  • If the subnets are private, a NAT Gateway is required to enable node group registration with the EKS cluster.

New VPC

• If you prefer a new VPC, all resources will be automatically provisioned.

• The limit of the Running On-Demand All Standard vCPUs must offer enough availability for the required number of vCPUs (minimum of 24).

• An IAM user account to connect to AWS which has the necessary privileges to create resources in any existing VPC and the ability to create a VPC (if required).

• You must import the SSL certificate into AWS Certificate Manager (or a new certificate can be requested via AWS Certificate Manager).

IIS deployment prerequisites

Before deploying Cinchy v5 on IIS, you require the following:

Access the artifacts

You need to access and download the Cinchy binary before deployment:

• Navigate to the release you wish to deploy

• Download the files listed under the Component Artifacts column. This should include zip files for:

  • Cinchy Platform

General requirements

1. An instance of SQL Server 2017+

2. A Windows Server 2012+ machine with IIS 7.5+ installed

3. • Specifically, install: ASP.NET Core/.NET Core Runtime & Hosting Bundle

System requirements

Minimum web server hardware recommendations

• 2 × 2 GHz Processor

• 8 GB RAM

• 4 GB Hard Disk storage available

Minimum database server hardware recommendations

• 4 × 2 GHz Processor

• 12 GB RAM

• Hard disk storage dependent upon use case. Note that Cinchy maintains historical versions of data and performs soft deletes which will add to the storage requirements.

Clustering

Clustering considerations are applicable to both the Web and Database tiers in the Cinchy deployment architecture.

The web tier can be clustered by introducing a load balancer and scaling web server instances horizontally. Each node within Cinchy uses an in-memory cache of metadata information, and expiration of cached elements is triggered upon data changes that would impact that metadata. Data changes processed by one node wouldn't be known to other nodes without establishing connectivity between them. The nodes must be able to communicate over either HTTP or HTTPS through an IP based binding on the IIS server that allows the broadcast of cache expiration messages. The port used for this communication is different from the standard port that's used by the application when a domain name is involved. Often for customers this means that a firewall port must be opened on these servers.

The database tier relies on standard MS SQL Server failover clustering capabilities.

Scaling Cconsiderations

The web application oversees all interactions with Cinchy be it through the UI or connectivity from an application. It interprets/routes incoming requests, handles serialization/deserialization of data, data validation, enforcement of access controls, and the query engine to transform Cinchy queries into the physical representation for the database. The memory footprint for the application is low, as caching is limited to metadata, but CPU use grows with request volume and complexity(For example, insert/update operations are more complex than select operations). As the user population grows or request volume increases, there may be a need to add nodes.

The database tier relies on a persistence platform that scales vertically. As the user population grows and request volume increases, the system may require additional CPU / Memory. Cinchy recommends you start off in an environment that allows flexibility (such as a VM) until you can profile the real-world load and establish a configuration. On the storage side, Cinchy maintains historical versions of records when changes are made and performs soft deletes of data which will add to the storage requirements. The volume of updates occurring to records should be considered when estimating the storage size.

Backups

Outside of log files there is no other data generated & stored on the web servers by the application, which means backups are centered around the database. Since the underlying persistence platform is a MS SQL Server, this relies on standard procedures for this platform.

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:

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

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

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

1. Retrieve your metadata.xml file from your identity provider.

1. Navigate to your cinchy.kubernetes\environment\_kustomizations\_template\instance\_template\idp\kustomization.yaml file.

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

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

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

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

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

1. Run DevOps automation script which will populate the updated outputs into the cinchy.kubernetes repository.

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

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

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

Convert an existing user to SSO User

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

Login with SSO

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.

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.

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

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.

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

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

## 6. Further Reading

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

2. Find the following line:

1. Replace the above line with the following:

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

2. Find the following line:

1. Replace the above line with the following:

1. Restart the application pools in IIS for the changes to take effect.