Single Sign-On Authentication using SAML

Tidal Automation (TA) supports single sign-on (SSO) to the TA Client Manager using Security Assertion Markup Language (SAML). SAML is an XML-based markup language for exchanging authentication and authorization between an identity provider (IDP) and a service provider (SP). TA supports the identity providers like Active Directory Federation Service (ADFS) and Okta (cloud based).

SAML based Authentication Overview

When accessing the TA Client Manager, users are redirected to a web page (ADFS or Okta - Identity provider) where they are prompted to enter their username and password (if active session does not exists).

On using SAML, a user is automatically verified with the identity provider when they sign in. The user is then allowed to access the TA Client Manager without being prompted to enter separate login credentials.

Configuration Changes for ADFS Service Provider

The ADFS service provider is configured in each TA Client Manager for sending the SAML requests to the ADFS Service Provider and processing the SAML responses.

Mapping user information such as name, email, groups is also configured in the Service Provider. These steps are followed for integrating the Client Manager with ADFS Service Provider:

Adding the Relying Party Trust

You must be ready to set up the ADFS connection with TA Client Manager. The connection between ADFS and TA Client Manager is defined using a Relying Party Trust (RPT).

Click Server Manager > ADFS Management.

Choose the Relying Party Trusts folder from ADFS Management.

To add a Relying Party Trust:

Right-click the Relying Party Trusts folder and click Add Relying Party Trust. The Add Relying Party Trust wizard appears. This wizard helps to add a new relying party trust to the AD FS configuration database.

Click Claims aware and click Start. The Select Data Source page appears.

Click Enter data about the relying party manually to obtain the data about the relying party.

Click Next. The Specify Display Name page appears.

Specify the display name of the relying party in the Display Name field to recognize the name in the future.

Enter any comments in the Notes field.

Click Next. The Configure Certificate page appears.

Configuring URL

To configure the Certificate Page:

Leave the certificate settings at their defaults on the Configure Certificate page and click Next. The Configure URL page appears.

Check the Enable support for the SAML 2.0 Web SSO protocol checkbox and provide the Client Manager URL.

Click Next. The Configure Identifiers page appears.

Configuring Identifiers

Enter the Client Manager URL and click Add. The Choose Access Control Policy page appears.

Choose an access control policy and click Next. The Ready to Add Trust page appears. The relying party trust is ready to be configured.
Review the settings, and click Next to add the relying party trust to the ADFS configuration database.

Click Finish. The relying party trust is configured now.

Click Close. You can then configure the claims issuance policy for the application.

Creating Claim Rules

Once the relying party trust is created, you can create the claim rules. By default, you can configure the claim issuance policy for the application.

To create the claim rule:

Click the trust, right-click, and choose Edit Claim Issuance Policy.

Click Add Rule on the Edit Claim Issuance Policy window. The Select Rule Template page appears.

Click Choose Rule Type.

Choose Send LDAP Attributes as Claims rule.

Click Next.

To configure a Claim Rule:

Choose Active Directory as the attribute store.

Map the required LDAP attributes to outgoing claim types as provided in the table.

LDAP Attribute	Outgoing Claim Type
SAM-Account-Name	E-Mail Address
Is-Member-Of-Group	Group
Token-Groups-Unqualified Names	Group

Click Finish to save the new rule.

To transform an Incoming Claim rule:
- Create another new rule by clicking Add Rule on the Select Rule Template page.
- Choose Transform an Incoming Claim as the template.
- Click Next. The Configure Rule page appears to map an incoming claim to an outgoing claim type.

Perform these steps on the Configure Rule page:
- Enter the name of the claim rule in the Claim rule name field.
- Choose E-mail Address as the Incoming claim type.
- Choose Name ID as the Outgoing Claim Type.
- Choose Email as the Outgoing Name ID Format.
- Leave the rule to the default of Pass through all claim values.

Click Finish to save the rule.

To create Pass Through or Filter an Incoming Claim rule:
- Create another new rule by clicking Add Rule on the Select Rule Template page.
- Click Pass Through or Filter an Incoming Claim as the template.
- Click Next. The Edit Rule window appears.

In the Edit Rule page, perform these steps:

Enter the name of the claim rule on the Claim rule name field.
Choose Windows account name as the Incoming claim type.
Leave the rule to the default of Pass through all claim values.

Use View Rule Language to get the raw code for the rule.
Click OK to create the claim rule.
Click OK again to finish creating the rules.

Adjusting the Trust Settings

You need to adjust some settings on the relying party trust.

To adjust the Trust Settings:

Click the trust, right-click and choose Properties. The TA ADFS Properties window appears.

Click the Endpoints tab.

Choose and double-click the SAML Assertion Consumer Endpoints. The Edit Endpoint window appears.

Choose any one of these values in the Binding field:
- POST (default value)
- Redirect
- Artifact
  
  Note: If you change the default value (POST) in the Binding field, the same value must be updated in the Client Manager by editing or adding the property SAML.Binding in clientmgr.props located under <ClientManager_HOME>/config.
  
  Also, note that if you choose the binding type as Artifact, you must edit the bindings.

Click Sites > Default Web Site on the APPBOX (SAML) administration.

Click Edit Bindings. The Site Bindings window appears.

Click https. The Edit Site Binding window appears.

Choose the same SSL certificate as used for ADFS and click OK.

To add Logout Endpoint:

Click Add SAML on the TA ADFS Properties window to add a new endpoint. The Add an Endpoint window appears.

Choose the Endpoint type as SAML Logout.

Choose the binding value as POST or Redirect.

Note: If you change the default value (POST) in the Binding field, the same value must be updated in the Client Manager by editing or adding the property SAML.Binding in clientmgr.props located under <ClientManager_HOME>/config.

Enter the trusted URL in the Trusted URL field:

https://ClientMangerHostName:8433/client/logoutReq

Enter the response URL in the Response URL field:
```
https://ClientMangerHostName:8433/client/logout
```
Click OK.

To add the Signature Verification Certificate:

Click the Signatures tab on the TA ADFS Properties window.

Click Add.

Get the certificate created for the Client Manager host which was referred in <Client Manager_HOME>/config/webserver.xml.

Click Apply and click OK. The signature verification certificate is added.

Configuring SAML Authentication with Microsoft Entra ID

Note: Azure Active Directory (Azure AD) has been renamed to Microsoft Entra ID.

Before starting, ensure you have created the MS Entra ID Enterprise application and installed the necessary connector.

Note: If your Tidal instance does not have a direct public IP address or is hosted in a private network, you must additionally configure the connector to ensure access from Microsoft Entra ID.

To configure Tidal Automation SAML authentication using Microsoft Entra ID Enterprise application:

Open your Enterprise application, navigate to the Single sign-on section, and enable SSO. Refer to Enable single sign-on for details.
Click Edit in the Basic SAML Configuration section and set these values:
- Identifier (Entity ID): The unique application identifier (your application's base URL).
- Reply URL(Assertion Consumer Service URL): The URL where the application expects to receive the authentication token.
  
  Example: ${Identifier (Entity ID)}/client
- Logout URL: The URL for the SAML logout response.
  
  Example: ${Identifier (Entity ID)}/?appproxy=logout
Go to Single sign-on > SAML Certificates and download the Federation Metadata XML file.
Navigate to the Users and groups section and add the corporate user accounts or groups that will be enabled for TA login.

Tidal Automation Configuration

Ensure Tidal Automation is configured to run via HTTPS.
Put the downloaded Federation Metadata XML file into the CM config folder.
Stop the Client Manager and add these properties to the clientmgr.props file:

SAML.Enable=Y

SAML.Binding=POST

SAML.SAML_ADFS_OnPrem=N

SAML.LogoutBinding=POST

SAML.KeyStoreAliases=saml

SAML.MetadataFileName=saml-app-federation-metadata.xml

SAML.DomainAttribute=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

SAML.CMHostNameOrIPAcessibleToIDP=saml-ta.mycompany.com
- SAML.MetadataFileName: The path to the federation metadata xml file you downloaded from MS Entra ID.
- SAML.CMHostNameOrIPAcessibleToIDP: The DNS name or IP address of the VM running TA. This value must exactly match the base URL used for the Reply URL in the MS Entra ID application.
Start the Client Manager.
Navigate to https://saml-hostname:port/client/ and you should be redirected to MS SSO login page.
Log in with your corporate credentials. You should be successfully redirected to Tidal Automation.

Configuration Changes for Okta Service Provider

The Okta service provider provides secure identity management and single sign-on to the TA applications in cloud environment.

Follow these steps for integrating the Client Manager with Okta Service Provider:

Login to Okta using https://<xyz>.okta.com/app/UserHome, where <xyz> is Unique ID. The Okta dashboard appears.
Click Applications. The Applications window appears displaying the list of added applications.
Click Add Application to add an application. The Add Application window appears.
Click Create New App to create a new application. The Create a New Application Integration window appears.
- Choose Web in the Platform field.
- Click SAML 2.0 in the Sign on Method field.
- Click Create.
  
  The new application is created. The Create SAML Integration window appears.
To create SAML integration
- Click General Settings.
- Enter the application name in the App name field.
- Click Next.

Enter this Single sign on address on the Configure SAML page:

Example: https://ClientMangerHostName:8433/client

Enter the Audience URI:

Example: https://ClientMangerHostName:8433/client

Choose the Name ID Format as EmailAddress.

Choose the Application username as Okta username.
Click Show Advanced Settings. The settings window appears.
Set these attributes:
- Check the Allow Application on the Enable Single Logout filed to initiate Single Logout checkbox.
- Enter the Single Logout URL:
  
  Example: https://ClientMangerHostName:8433/client/logout
- Enter the SP issuer:
  
  Example: https://ClientMangerHostName:8433/client
- Click Browse and choose the certificate from the Client Manager and upload the certificate in the Signature Certificate field.

To set the attributes statements:
- Enter the name:
  
  Example: http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname.
  
  Note: Alternative user can enter the name as ‘domain’ or enter any alphanumeric value. Edit the property SAML.DomainAttribute in clientmgr.props located under <clientmanager_home>/config.
  
  Example: SAML.DomainAttribute = domain
- Enter User.Email in the Value field.

To set the group attribute statements:
- Enter the name:
  
  Example: http://schemas.xmlsoap.org/claims/Group.
  
  Note: Alternative user can enter the name as ‘group’ or enter any alphanumeric value. Edit the property SAML.GroupAttribute in clientmgr.props located under <clientmanager_home>/config.
  
  Example: SAML.GroupAttribute = group

Choose the filter value as Regex in the Filter field and enter the filter value: .*.*

Click Next. The Feedback page appears. Okta support asks you whether you are a customer or partner. You can choose that you are a software vendor and would like to integrate your application with Okta.
Click Finish.
Click the Applications > Client Manager (integrated application) on Okta.
Click the Sign On tab. The Sign On Methods Settings window appears.
Click View Setup Instructions.
Click Optional – Provide the IDP metadata to your SP provider. The IDP metadata displays.
Copy the metadata and paste the data in a file called FederationMetadata.xml and place the data under
```
<ClientManager_HOME>/config location.
```
Assign the users and group to the application.

Configuring Changes for Client Manager to Enable SAML

Before making the configuration changes in the Client Manager, some prerequisites are required from the Service Providers.

Prerequisites for ADFS Service Provider

Get the certificate from the ADFS box and import the certificate into the same Keystore file referred by the Client Manager.
Download the metadata file from ADFS using https://<ADFS_HOSTNAME>/federationmetadata/2007-06/federationmetadata.xml
Place the metadata file under <ClientManger_Home>/config.

These properties are added in the clientmgr.props for the SAML configuration.

Property Name	Default Value	Supported Values	Mandatory	Description
SAML.Enable	N	Y or N	No	Enables SAML
SAML.KeyStoreAliases	Client Manager certificate Alias	Alphanumeric	Yes	Sends the Client Manager certificate information to IDP
SAML.MetadataFileName	FederationMetadata.xml	Alphanumeric	No	To use an alternative file name
SAML.Binding	POST	POST Redirect Artifact	No	Depends on the binding configured in ADFS
SAML.LogoutBinding	Redirect	POST Redirect	No	Depends on the logout binding configured in ADFS
SAML.GroupAttribute	http://schemas.xmlsoap. org/claims/Group	Alphanumeric	No	Used for custom claim rule
SAML.DomainAttribute	http://schemas.microsoft. com/ws/2008/06/identity/cla ims/windowsaccountname	Alphanumeric	No	Used for custom claim rule
SAML.CMHostNameOrIPAces sibleToIDP	Host name of CM	Alphanumeric	No	Custom Client Manager Host name
SAML.SAML_ADFS_OnPrem	Y	Y or N	No	Used for AZURE AFDS
SAML.DomainName	N/A	Alphanumeric	No	Name of the domain used to authenticate users

Prerequisites for Okta Service Provider

In Okta, you can click the Applications > Client Manager (integrated application). Click the Sign On tab and click View Setup Instructions. You can then click Optional – Provide the IDP metadata to your SP provider. The IDP metadata displays. You can copy the metadata and paste the data in a file called FederationMetadata.xml and place the data under <ClientManager_HOME>/config location.

These properties are added in the clientmgr.props for the SAML configuration for Okta Service Provider.

Property Name	Default Value	Supported Values	Mandatory	Description
SAML.Enable	N	Y or N	No	Enables SAML
SAML.KeyStoreAliases	Client Manager certificate Alias	Alphanumeric	Yes	Sends the Client Manager certificate information to IDP
SAML.MetadataFileName	FederationMetadata.xml	Alphanumeric	No	To use an alternative file name
SAML.Binding	POST	POST Redirect	No	Depends on the binding configured in Okta
SAML.LogoutBinding	Redirect	POST Redirect	No	Depends on the logout binding configured in Okta
SAML.GroupAttribute	http://schemas.xmlsoap.or g/claims/Group	Alphanumeric	No	Name in GROUP ATTRIBUTE STATEMENTS in Okta
SAML.DomainAttribute	http://schemas.microsoft.c om/ws/2008/06/identity/ claims/windowsaccountna me	Alphanumeric	No	Name in ATTRIBUTE STATEMENTS in Okta
SAML.CMHostNameOrIPAc essibleToIDP	Host name of CM	Alphanumeric	No	Custom Client Manager Host name

Enabling HTTP Basic Authentication

Starting with TA 6.5.7, the Web Client uses login page-based authentication method.

If required, the Client Manager can be configured to use HTTP Basic authentication using these configuration parameters in the clientmgr.props file:

Auth.BASIC

When Auth.BASIC is set as OFF, the Web Client uses login page-based authentication and the Client Manager API requires token-based authentication.

Set Auth.BASIC as ON to set the Web Client logon mode as well as Client Manager API authentication to HTTP Basic.

Note: For more information, see the Tidal Automation REST API Reference Guide.

Auth.API.CompatMode

When Auth.BASIC is set as OFF, set Auth.API.CompatMode as Y to enable authentication of API requests using HTTP Basic authentication.