1 of 100

2.7.13 Getting Started

What is Cymmetri?

Cymmetri is a Converged Identity & Access Management Platform and a well-trusted platform acting as an advisor and an end-to-end partner for Security-aware teams looking to deploy Identity and Access Management Solutions across their organization.

We offer an industry-standard product backed by a strong team that always aims to innovate our solutions to cater to a wide variety of enterprise needs.

Starting your Cymmetri Trial

Enter your country, phone number (mandatory to receive OTP), and enter a domain name for your tenant. In case the domain available message is not shown, choose a different domain name. Click on Start Trial button.

You will receive an OTP on your mobile number from the previous step. Enter the OTP here and wait for a few seconds for your tenant to be created.

You will be redirected to your domain to create the first Organization Admin user. Ensure that your password matches the password policy.

You will receive a message to show that your tenant has been created.

Click on the Login button for proceeding with the onboarding process
Enter your username and press Next

Enter your password and proceed with the setup of your tenant by clicking on the Login button

Choose applications from the application catalogue, click on the application icon for all the applications you wish to add. Then click on the Next button.

Enter details to create a second administrator account. Click on Send Invite button to create an administrator. Click on Next button to proceed.

(Optional) Add users if you wish to. Then click on Finish.

You will be redirected to the Dashboard to proceed with the system.

Admin Dashboard

Cymmetri dashboard provides administrators with a centralized and visual representation of key information and controls related to identity management, access governance, and administration.

The dashboard serves as a command center for overseeing and managing the identity lifecycle, compliance, and other aspects of identity and access governance within an organization.

Upon Logging in the admin is landed on the dashboard where he can see the following:

Shortcut to configure recently added application - Configuration the application means adding roles, defining provisioning, reconciliation, SSO and so on
Users Activity - Total Successful user logins in Cymmetri
Accounts Locked - User account locked event
Users Onboarded - New users being onboarded in the system
Password reset - Password reset activity in the system
Authentication stats - Number of successful and failed login attempt in a timeframe
App Identity - It displays the application reconciliation activity with respect to the users.

Cymmetri also displays some important system KPIs to the admin as shown below

Application - The count of applications integrated into the Cymmetri system.

Active Users - The total number of users currently active within the system.

Total Users - The overall number of users registered and onboarded into Cymmetri.

Roles - The total count of roles created for applications within the Cymmetri platform.

Workflows - The total number of approval workflows established in the Cymmetri system.

Password policy - The total count of password policies configured for user authentication in Cymmetri.

Rules - The cumulative count of rules implemented in the system, covering provisioning, Multi-Factor Authentication (MFA), approval workflows, etc.

Users unlogged - The number of users who have not initiated a login session in Cymmetri since their registration.

Additionally, there are some useful system shortcuts placed on the right side of the page to make faster business decisions.

Accessing Cymmetri

To access Cymmetri, users must use a web browser, such as Google Chrome or Safari, and enter the appropriate address in the address bar as shown below:

URL: https://<companyname>.cymmetri.com/login

Example: https://helpdocs.cymmetri.com/login

Once the address is entered it opens a page as shown below, where the users may enter their username and password to access Cymmetri.

Cymmetri Error Codes

A comprehensive list of all known Cymmetri error codes and their summary understanding:

Help

The Cymmetri Help Page serves as a vital resource, offering users a comprehensive documentation hub that breaks down all the features and provides step-by-step configurations for various functionalities.

Key Features of the Help Page:

Comprehensive Feature Explanation: The Cymmetri Help Page covers all the features of the platform in a straightforward manner. Whether you are a beginner or an experienced user, you can find detailed explanations of each feature, ensuring you have a clear understanding of its purpose and functionality.
Step-by-Step Configurations: One of the highlights of the Help Page is its provision of step-by-step configurations for various features. This means you can follow a simple, structured guide to set up and customize different aspects of Cymmetri according to your specific needs.
User-Friendly Language: The documentation is crafted in a manner that balances technical precision with user-friendly language. You won't find unnecessary jargon, making it accessible for users with varying levels of technical expertise.

Personalization

Admins

Cymmetri platform has six different admin roles with various levels of access to the various menus and resources on the administration portal of the Cymmetri.

In addition to these six admin roles, Cymmetri also supports three different privileged user roles that grant varying levels of access (read, write, report) to privileged users within Cymmetri.

Administrators

The various admin roles on the Cymmetri Identity Platform may be described as follows:

Organization Administrator

This is the so-called 'super admin' administrator role in the Cymmetri platform. Administrators with this role have the authorization to modify any settings or make changes to the tenant.

Domain Administrator

This is a slightly less privileged administrator. Most tenant-wide system settings, such as the configuration of SMS and email providers (when configured by the tenant), are restricted for domain administrators. All other configurations can be viewed and edited by administrators with the Domain Administrator role.

Application Administrator

An administrator with the role of Application Administrator has access to Identity Hub configurations, including Application, User, and Group configurations. The Application Administrator can map users and groups to applications and has the ability to edit all configurations related to Application Management.

Report Administrator

An administrator with the role of Report Administrator has access to the Reports menu, which includes the ability to view, modify, and add new reports.

Help Desk Administrator

Helpdesk administrator has access to a very limited set of administrative functionalities, such as, reset password of end-user, remove configured Multifactor authentication options, and other such common use-case

Read Only Administrator

All administrative users have editing access to the various administrative sections of the Cymmetri platform. However, administrators with the "Read Only Administrator" role do not have editing access to any of the settings or configurations; they only have "Read Only" access to the administrative section.

PAM Write Access

PAM Write Access in Cymmetri grants users the privilege to connect to servers via RDP or SSH and perform write or modification actions on those servers. Users with PAM Write Access have the ability to make changes, update configurations, and perform tasks that involve altering data or settings on the connected servers. This access level is typically assigned to administrators and IT personnel responsible for making configuration changes or updates on various servers within the Cymmetri environment.

PAM Read Access

PAM Read Access provides users with the ability to connect to servers using RDP or SSH and view the content and configurations on those servers. However, users with PAM Read Access do not have the authority to make modifications or changes to the server settings or data. This level of access is suitable for individuals who need to monitor server activities, check logs, or retrieve information from servers without the need to alter any server configurations.

PAM Report Access

PAM Report Access is designed for users who require access to PAM-related reports without the need to connect to servers via RDP or SSH directly. Users with PAM Report Access can generate and access reports that provide insights into server activities, access logs, or other relevant data within the Cymmetri. Such users can also configure schedulers to send timely reports to various other users. This level of access is beneficial for auditors, compliance teams, or individuals focused on analyzing server-related information for reporting and auditing purposes.

Adding a New Admin

Follow the steps mentioned below to promote a user as an admin in Cymmetri platform.

Click on the Configuration menu on the right-hand side

Now click on the Admins sub menu within the Configuration menu

Click on the "+Add New" new button to add a new administrator

To assign an administrator role to a user, search for the user and then click the 'Assign' button.

Select the chosen administration role and click on Save

Administrator has been assigned the role as “Report Administrator”.

Masters in Cymmetri

Masters are key-value pairs that can be defined for the entire tenant. The key(name) in this context refers to the label to be shown on the Cymmetri User Interface, and the value is the backend identifier used to reference this field in various processes, rules, and policies defined in the Cymmetri platform.

Cymmetri platform allows for configuring a number of masters in the system, the major classification among which is Global masters (which allow for creating master key-value pairs that may be used for various situations, such as creating a new department, designation, and other custom attributes for users in the system) and Zone masters (which are network configurations that may be used to whitelist or blacklist user access onto the platform as well as act as a source for adaptive Multi-factor authentication).

Global Masters

These are system-wide key value pairs primarily used to setup key value pairs referring to various masters as given below:

Types of Global Masters:

Adding a new Master

Follow the steps below to Add a New Master:

Click on the "+Add New" button to add a new master of any category mentioned above.

Enter the Name and Value for the new Master, then select the type of master you wish to create and enable the active toggle button to make the master active. Once all values are entered click on Save button

A new Global Master is successfully created in the selected category

Zone Masters

Zone masters indicate the network zones that may be used for blacklisting or whitelisting access to the Cymmetri Identity platform deployment. It may also be used for detecting users from certain zone and assign relevant multi-factor authentication policies.

Zone Name: Used to refer to a zone in other configurations on the Cymmetri platform.

Inactive/Active: Toggle button to check whether the zone is active (configurable as a condition for other rules on the Cymmetri platform.)

Gateway IP: Refers to the Gateway IP address for the network zone.

Proxy IPs: Proxy Server IP addresses that may be used to be directed to this network or the IP addresses outside of the zone that would indicate a connection from this zone.

For adding a new Zone Master or for editing an existing one, Fill all the mandatory details in the screen as shown above, click on the enable toggle button and finally click a “Save” button.

Personalize Notification Templates

Notifications are triggered from the Cymmetri platform for various actions occuring on the platform either through direct action by the end-user or by the virtue of some backend action (such as running of a scheduler for a campaign). Cymmetri platform ships with default notification templates that may be modified by the administrator using the following process:

Access the notification templates menu by clicking on the configuration menu on the left-hand side menu bar and then clicking on the Notification templates pop-up menu.
Click on the eye icon to preview the corresponding template
Values in <> anchor tags and ${} reflect macros.
We may treat this template as an email, and edit the subject of the mail.
By default, the email notification will be sent to the corresponding affected end-user, but selecting the toggle option for “Send notification to Reporting Manager” will also copy the mail to the Reporting manager of the affected end-user, allowing for offline followup for the notification.
The administrator may edit the HTML using the provided HTML editor to add/change any template button/text/background. The macros required for the particular template are already provided in the sample default notification template.
Click on the Save button to save the notification template.

Tenant Branding

Tenant branding in Cymmetri allows you to personalize and enhance the visual identity of your environment. With tenant branding, you can customize the appearance of your platform, including logos, color schemes, and even tailored messages, aligning it with your organization's branding guidelines.

This not only creates a cohesive and professional user experience but also reinforces your brand's presence throughout the Cymmetri environment. It's a powerful tool for organizations looking to maintain a consistent and recognizable image while utilizing Cymmetri's identity and management capabilities.

The Cymmetri platform allows a certain level of customization to your tenant from the administration panel. This includes the ability to modify the default Cymmetri branding scheme to your own Organization’s branding scheme.

Your Organization Name and Tagline
Your Organization Logo
Your Organization Branding Colors (Primary, Secondary, Accent Colors)

Configuring your tenant branding

To access the branding menu, first click on the Configuration menu on the left-hand side and then proceed by clicking on the Branding menu item.
Start the configuration by entering your Organization Name and Tag Line
Proceed by adding your URL to the Website text box and click on “Fetch Brand”.
If your organization’s branding is available, the logo and the corresponding color scheme will be displayed in the menu below.
If your branding is not available, you may configure it yourself by uploading your logo and editing your primary color, secondary color, and accent color.
Click on Save and Sync Server button to make the branding configuration apply to the entire website.
The configuration will be applied in a few seconds to reflect your branding.

Custom Attributes

Custom Attributes may be added for all user entities in your Cymmetri Platform. This allows organizations to add custom user attributes, that are used across the applications in the organization.

For example, your organization has a custom attribute that captures and uses the local language of your employees and vendors for the purpose of providing local services. This attribute may be stored in your Active Directory, and may need to be synchronized to your organization’s other applications during the course of an employee or vendor’s employment.

Cymmetri platform allows the administrator to define custom attributes on a tenant-wide level.

Custom attributes can be used at various places like when creating a user, as a filter when searching for users, and is visible in the others section of user info

Configuring Custom Attributes

To start configuring custom attributes, click on the Configurations menu on the left-hand side and then click on the Custom Attributes menu.

Click on the Add New button to start adding a custom attribute
Fields to be updated:
1. Name/ Key: refers to the label assigned to the custom attribute.
2. Description: allows you to provide additional details or notes about the custom attribute for reference and clarity.
3. Status: Allows to activate the custom attribute. Only if it is set to active, is the attribute available to use in the User Object.
Note: A custom attribute once created can only be set to inactive, it cannot be deleted.

Identity Hub

Managing Users and Groups

Create Users

While users may be imported and sychronized from other Identity providers, sometimes users may need to be added manually by the administrator.

Steps to Create Users:

First navigate to the User configuration page, by clicking on the Identity Hub > User menu on the left-hand side panel.
Click on the “+Add New” button.
Enter the required information and scroll down to add further information
Click on the Save button to move to the next configuration page, and copy the automatically generated password.
Optionally a group can be assigned to the user.
And also applications can be assigned to the user.

Once all the above steps are completed successfully the user is created with the assigned groups and assigned applications.

Create Groups

Administrator tasks pertaining to bulk users may be eased by creating groups of users.

Creating User Groups

Access the group configuration page by clicking the Identity Hub >Groups menu on the left-hand side.

Click on the “+Add New” button to start creating a new group

Group Name: Indicates name of the group.

Group Type: For environments not using Active Directory, either Local or Remote Group may be chosen, in case Active Directory is being used for synchronization in the tenant, the appropriate type according to the group policy object must be chosen.

Parent Group: If a parent group is chosen, all the policies and rules applicable to the parent group will be assigned to this new group, in addition to the policies and rules specifically applied to this new group.

Group Description: Optionally, a description may be provided to the group.

Once all the details have been entered click on Save button and a new group is created.

Assigning Users to Groups

Assigning Users to a Group

Users once created in the Cymmetri platform can be assigned to a group. Assigning users to a group helps ease the administrative efforts to apply the same policies and assigning applications to multiple users.

When assigning users to groups there can be various approaches which can be used:

Adding User to Group (from the Group Page)
Assigning a Group to a User (from the User's Page)
Bulk Assigning Users to a Group (Using Group Assignment on Group Page)

Adding User to Group

First the administrator needs to click on the group name and enter the configuration for the group.

Now Go to the Users Page and click on +Add button to get a list of users to add to the group

3. Now click on the assign button next to the user you wish to add to the group.

Once assigned the user can be seen on the Users page of the Group as shown below:

Assigning a Group to a User

For this approach the Administrator needs to go to Identity Hub > User page and then select the user from the list to whom the group needs to be assigned

Go to the user's page and select the Groups menu and click on "+Assign New" button

This opens a pop up window where a list of all groups is visible

Click on the assign button and the group is assigned to the user or you may say the user becomes a part of the group

Bulk Assigning Users to a Group

For this approach the Administrator needs to go to Identity Hub > Group page and then click on the Group Assignment button

A screen pops up that lets you select the csv file you want to upload to import the users that needs to be assigned to the group. This csv file needs to have one column that contains login id of users; Upload the csv file, you may also use the sample data file available and modify it to match your user's login id.

Once the file is selected and uploaded next you need to select the group to which you want to assign the users.

After selecting the group the column in the csv file needs to be mapped with the Cymmetri login column.

Once mapped click on the import button and the users would be mapped to the assigned group provided the login id is correct

Results of successfully Imported Users, Duplicate Users or any error that occurred during import can be see in Logs > Import History page

Delegation

Setting up Delegation

Delegation as a process in the Cymmetri platform refers to the ability of any end-user to delegate their responsibilities to any other end-user on the platform. As such, delegation provides the ability to the delegatee to perform various actions, including Single Sign On, Application Requests, managing workflows by providing approvals, performing Cymmetri administrative actions (if the delegator has the required permissions on the platform), among other actions. However, the login flow for the delegatee stays the same.

Configuring the delegation on your tenant

Access the Delegation administration panel, by clicking on the Configuration left-hand side menu item and then click on the Delegations menu item.

For any user to be able to delegate their work to other users, the user should be added to the delegation users list; To Add Users who can delegate their activities, click on the Assign New button and select one or more users to add to this list

The User and Assignee Consent sections allow organizations to align task delegation practices with their unique policies. This customizable feature empowers administrators to define specific consent texts, ensuring that both the user delegating a task and the assignee receiving it acknowledge and agree to these terms.

The user consent will be displayed whenever the delegator (user) will go to their settings in their Workspace and assign a delegation to an end-user (assignee).This consent will be recorded in the Cymmetri backend for audit logging purpose.

Similarly, the assignee consent will be recorded when the end-user (delegate/assignee) logs into the account for their manager (delegator/user).

Here's how it works:

Administrator Configuration: Administrators can craft consent texts tailored to their organization's requirements. These texts typically outline the responsibilities, expectations, and any legal or compliance aspects associated with task delegation.
User Perspective: When a user decides to delegate a task to someone else, they will be presented with the customized consent text. The user must carefully review and accept the terms before proceeding with the delegation process. This step ensures that the user is aware of the implications of task delegation and is willing to proceed.
Assignee Perspective: On the other side, the assignee who is about to receive the delegated task will also be presented with relevant consent text. They must thoroughly read and accept these terms before taking on the responsibility. This step helps establish clarity and accountability for the assignee.

Delegating Work to Delegatee

Delegate Work to Delegatee

Following are the steps to delegate work to an delegatee:

The logged in user needs to go to their Settings Page by clicking on the user's username on top right

Once on the Settings Page user needs click on My Delegations menu

Toggle Status: Enable the Toggle Status to Active

Start Date: The date from which the user is delegate the work

End Date: The date upto which the access is delegated

Delegated To: The user (delegatee) to whom the work is delegated. This dropdown populates the list of all users to whom the task can be assigned

Excluded Applications: List of applications whose access is not provided to the delegatee

Once all the details are filled the user is expected to accept the consent to be able to configure the delegation. The consent looks something similar to as show below:

Once confirmed the user needs to click on the I agree check box and save the delegation

Once save the delegatee can see and accept the delegation in their My Delegation Page under Settings.

Accepting Delegation

Upon receiving a delegation request, the user is notified via email and within the platform.

To view the delegated task the delegatee can go to Settings->Delegation to Me to see details about the delegated tasks and the user who has assigned the task

The user needs to click on the Accept button to accept the delegation. On click the Accept button an Assignee(delegatee) Consent is shown which the users needs to read and confirm. The Consent also shows details of the delegator and the duration of the delegation.

Once the user accepts the delegation the user sees a login button, to login into cymmetri as the delegator

On clicking the login button the delegatee is redirected to the delegator's My Workspace Dashboard.

The delegatee can access and perform actions on all the applications assigned to them and if any application is excluded during delegation they are not visible to the delegatee.

Authentication

Identity Provider

Internal IDP

Internal Identity Provider Configuration: Cymmetri

To access Internal Identity Providers navigate to Authentication-> Identity Provider->Internal IDP

Since Cymmetri is a default Internal IDP no configuration is needed for it. An administrator may still have an option to disable Cymmetri Authentication which can be done by editing the Cymmetri Authentication Internal IDP mechanism

An administrator may also change the Display Name and/ or Description as shown in the screen above.

Internal Identity Provider Configuration: Active Directory

Active Directory (AD) serves as a robust Identity Provider (IDP) in enterprise environments. It authenticates and authorizes users, facilitating seamless access to resources. AD centralizes user management, streamlining security protocols and ensuring efficient user provisioning.

Active Directory can be utilized in Cymmetri as an Identity Provider (IDP), leveraging existing AD user accounts to access Cymmetri, as the platform supports the LDAP protocol.

For configuring AD as an Identity Provider on the primary service needed is the Adapter Service.

The Adapter Service

The Adapter Service or Auth Adapter Service is exposed as a rest service which runs on https acts as an adapter to facilitate authentication using the LDAP protocol which is often employed for authentication purposes in various systems and every adapter service instance is called by the secret generated while installation/configuration of adapter service.

The rest endpoints are called by cymmetri-cloud AuthenticationService to connect to On-Prem AD/Ldap or cloud AD/Ldap. The AdaptorService is used to test connection, authenticate, change, reset password of an user.

Configuration

For configuring Active Directory as an internal IDP navigate to Authentication -> Identity Provider -> Internal IDP. Here you may either configure the already created AD Authentication instance or +Add New

In either cases a screen opens where you need to provide the below mentioned details

Name: AD Authentication
IDP Type: Active Directory
Description: A general description about the IDP type
Status: Active
Adapter Service Domain: Location (IP) of the server on which the Adapter Service is deployed
Adapter Service Secret: The secret generated while installation/configuration of adapter service
Base DN: Active Directory root domain name
Search Scope: A search scope for locating users in Active Directory

Once all the details are entered Save the changes and Test the Connection using Test Connection button.

Once the rule is configured, whenever a user matches the rule conditions, their credentials are verified against those stored in Active Directory. Upon successful verification, the user is granted access to log in to Cymmetri.

Internal Identity Provider Configuration: LDAP

Lightweight Directory Access Protocol (LDAP) serves as a important Identity Provider (IDP) in enterprise environments. It authenticates and authorizes users, facilitating seamless access to resources. LDAP is commonly used as a directory service for managing user identities and authentication information within an organization.

LDAP can be utilized in Cymmetri as an Identity Provider (IDP), leveraging existing user accounts to access Cymmetri, as the platform supports the LDAP protocol.

For configuring LDAP as an Identity Provider one of the primary service needed is the Adapter Service.

The Adapter Service

Configuration

For configuring Active Directory as an internal IDP navigate to Authentication -> Identity Provider -> Internal IDP. Here you may either configure the already created LDAP Authentication instance or +Add New

In either cases a screen opens where you need to provide the below mentioned details

Name: LDAP Authentication
IDP Type: Open LDAP
Description: A general description about the IDP type
Status: Active
Adapter Service Domain: Location (IP) of the server on which the Adapter Service is deployed
Adapter Service Secret: The secret generated while installation/configuration of adapter service
Base DN: LDAP root domain name
Search Scope: A search scope for locating users in LDAP

Once all the details are entered Save the changes and Test the Connection using Test Connection button.

Once the rule is configured, whenever a user matches the rule conditions, their credentials are verified against those stored in LDAP. Upon successful verification, the user is granted access to log in to Cymmetri.

External IDP

External Identity Providers (IdPs) in Cymmetri refers to third-party services or systems that handle the authentication of users. Instead of managing user identities internally, an IAM solution can leverage external IdPs to authenticate users and provide access to applications and resources. This externalization of identity management can enhance security, user experience, and streamline the onboarding process.

Introduction

Cymmetri's External Identity Provider (IdP) feature allows you to authenticate user identities using different IdPs for various user types. This flexible configuration enables you to streamline access for both internal employees and external users, such as consultants, vendors, and their employees. In this documentation, we will guide you through the process of configuring an External IdP within Cymmetri's identity and access management system.

For internal employees, you can configure Cymmetri's Internal IdP mechanisms like Active Directory or LDAP. This allows seamless authentication for your organization's employees.

Whereas external users, such as consultants, vendors, and their employees, can be verified using popular External IdPs like Google, Azure, Salesforce, or any other supported IdP. This approach simplifies access for external parties while maintaining security and control.

Configuring External Identity Providers

To configure an External IdP in Cymmetri, administrator needs to provide the following information:

Name: A descriptive name for the External IdP configuration.
IDP Type: The type or provider of the IdP (e.g., Google, Azure, Salesforce).
Entity ID: The unique identifier for the IdP entity.
SSO Service URL: The URL where Single Sign-On (SSO) requests should be sent.
Destination: The location where authentication responses should be directed.
Protocol Binding: The protocol used for communication with the IdP (e.g., HTTP Post, HTTP Redirect).
Name ID Policy and Value: This policy defines the format and content of the identifier that represents the authenticated user. For example:
- Policy: email
- Value: email
Certificate: The certificate used for secure communication between Cymmetri and the External IdP.

In the upcoming sections we will learn step by step implemenatation of the various External IDP mechanisms:

Google:

Google serves as a robust external Identity Provider (IDP) through its Identity Platform. Leveraging various authentication mechanisms, it facilitates secure user authentication for Cymmetri. This allows users to sign in with their Google credentials, ensuring a seamless and familiar login experience. Google's IDP mechanism is adopted for its reliability and user-friendly authentication processes, thus making it a preferred choice for integration into Cymmetri as and External IDP.

Azure Active Directory (Azure AD):

Azure AD serves as a robust external IDP, facilitating secure access into Cymmetri. Employing industry standards like OAuth 2.0 and SAML, it enables Single Sign-On (SSO) and multi-factor authentication. Azure AD seamlessly integrates with Cymmetri providing easy identity management and ensuring compliance with modern security standards.

Salesforce:

Salesforce as an external Identity Provider (IDP) offers robust authentication and access control solutions. Utilizing industry-standard protocols like SAML and OAuth, Salesforce IDP ensures secure Single Sign-On (SSO) experiences.

Configuring External Identity Providers in Cymmetri gives you the flexibility to authenticate user identities using different IdPs tailored to specific user types. Whether it's for internal employees or external collaborators, Cymmetri's External IdP feature ensures secure and convenient access to your organization's resources.

External Identity Provider Configuration - Google IDP

Google Configuration:

Once in the admin section click on Apps > Overview

In the overview page click on Web and mobile apps tile to add a new custom app

On the Web and mobile apps page click on the Add app dropdown and then select Add custom SAML app to add the Cymmetri tenant as a custom app

Provide a relevant App Name, Optionally a description for the application can be provided. An App Icon can also be attached if required. Once entered click on Continue button

Once the IDP metadata and certificate is obtained the Service Provider(i.e. Cymmetri) details need to be provided. We need to provide the ACS URL and the Entity ID these details can be obtained from Cymmetri as shown here. No change need to be done for Name ID format and Name ID it can be kept to UNSPECIFIED and Basic Information > Primary email. Once done click on Continue

Attributes can be added on this creen which could then be sent as a SAML response to Cymmetri. These values can be used to create a user in Cymmetri if JIT provisioning is enabled on Cymmetri's side

Group membership information can also be sent by cinfiguring groups here and if the user belonged to the configured group. Once attributes and groups are configured click on FINISH.

Once you click on the FINISH button the below screen appears that shows the configuration details. It also shows various shortcuts to Test SAML Login, Download Metadata, Edit Details and Delete App

Download IDP Certificate

If the administrator does not download the certificate while configuring the custom application, it can be later downloaded. For the same the administrator needs to go to Security>Authentication>SSO with SAML applications. This will open the Security Settings page from where either the IDP details like SSO URL and Entity ID can be copied and IDP Certificate can be downloaded. These details can be used to configure the IDP in Cymmetri.

Cymmetri Configuration

Once Google IDP is configured, the administrator must proceed with the configuration on the Cymmetri side. To achieve this, the administrator needs to set up Cymmetri as a Service Provider and also incorporate Google as an external IDP.

Once the Service Provider is configured next we need to configure Google as an external IDP.

Administrator needs to go to Authentication->Identity Provider->External IDP. Here you may either configure the already created google-idp instance or +Add New

In either cases a screen opens where you need to provide the below mentioned details

Name: Google IdP
IDP Type: Google
Entity ID: https://accounts.google.com/o/saml2?idpid=xxxxxxxxxxxx
SSO Service URL: https://accounts.google.com/o/saml2/idp?idpid=xxxxxxxxxxxx
Destination: https://<hostname>/spsamlsrvc/samlSP/SingleSignOn
Protocol Binding: HTTP Post (can also be set to HTTP Redirect if it is set so in Google IDP)
Name ID Policy:
- Policy: Email (This may change based on what is configured in Google IDP)
- Value: Email (This may change based on what is configured in Google IDP)
Certificate: Certificate downloaded from Google IDP
Logout Request URL: Need to mention the SingleLogoutService url from the metadata file if SLO (Single Logout) is configured in Google.
Logout Protocol Binding:HTTP Post (can also be set to HTTP Redirect if it is set so in Google IDP)
Service Provider Id: cymmetri (Need to the select the configured Service Provider as shown above)

Once all the details are entered Save the changes.

Once the rule is configured whenever a user matches with the rule conditions the user is redirected to Google screen and the user needs to provide his/her Google credentials to be able to login into Cymmetri.

Authentication Rules

Within Cymmetri, the authentication process is highly customizable through the definition of authentication rules. While the platform provides a default authentication rule, administrators have the ability to define custom authentication rules that align with the specific business needs and the variety of identity providers at their disposal.

For instance, let's consider a scenario where an organization has distinct user types, such as regular employees, contractors, and administrators. The administrators might require to authenticate employees with Active Directory as the identity provider and use Cymmetri's own authentication engine to verify the identity of vendors and contractors. With Cymmetri's flexibility, administrators can create authentication rules that cater to these varying requirements, ensuring a tailored and secure authentication experience based on user roles and organizational needs.

Admins can find authentication rules in Authentication tab in Cymmetri.

To create a new authentication rule, admin must simply click on the "Add New" button on the top right corner of the page.

The admin must fill in the following details

The name of the rule
Identity provider radio button ( Enable for External IDP or Disable for Internal IDP)
Identity provider
Description of the rule
Active Radio Button

Conditions

The administrator has the capability to establish rules based on conditions like: Department, designation, User Type, country, and Login Pattern.

Subsequently, the administrator defines regular expressions for conditions, specifying whether they should be equal to, not equal to, and assigns corresponding values.

Cymmetri facilitates the creation of multiple conditions for an authentication rule and provides the option to group these conditions using AND or OR logic.

In the image presented above, an exemplar authentication rule is showcased. This rule is structured to authenticate a user in Cymmetri through Active Directory if two conditions are met: the user's department must be equal to "Compliance," and the user type should be "Employee."

Similarly If you wish to set the Identity provider for users having email address ending with "@cymmetri.com" then you may select condition as LoginPattern > Regular Expression and its value as (.)*(@cymmetri.com)+$; and save the details.

This demonstrates how authentication rules can be precisely configured to suit specific criteria and streamline the authentication process based on defined conditions.

Global Auth Policy

The Global Auth Policy allows to configure various user login parameters as shown below:

Auth Failed Count: The Auth Failed Count parameter signifies after how many failed login attempts will the user account be locked.

Unlock after Minutes: The Unlock after Minutes parameter signifies after how many minutes will a locked account be automatically unlocked.

Token Expiry Minutes: The Token Expiry Minutes parameter signifies after how many minutes will the session token expire.

Refresh Token Expiry Minutes: The Refresh Token Expiry Minutes parameter signifies after how many minutes will the refresh token expire.

Logs

LIfecycle Management

Application Management

Getting Started

Provisioning How to

Reconciliation How to

Rules

Provisioning

Deprovisioning

Workflow Management

Single Sign On

My Workspace

OpenID Connect Based SSO

To use this mechanism ensure that the managed application supports authentication using OpenID Connect 1.0 protocol.

OpenID Connect 1.0 is a simple authentication layer protocol built on top of OAuth 2.0 protocol. It acts as a Single Sign On mechanism and authentication mechanism for not only the Web based applications, as SAML 2.0 does, but also for applications requiring access to APIs protected by this protocol as an authorization mechanism, and for mobile-native or Single page Applications (SPA) to verify user’s identity.

For understanding the core concepts of the OpenID Connect 1.0 protocol, it is important to grab the basics of the underlying OAuth 2.0 protocol.

Glossary of terms used in OAuth 2.0 and OpenID Connect 1.0 protocols

Client (RP): Client refers to the managed application to which the end-user wishes to perform Single SignOn into. The client in the context of the OAuth 2.0 and OpenID Connect 1.0, is also referred to as the Relying Party (RP), since it relies on the Authorization Server
1. Client ID: Client ID is the unique identifier assigned to each managed application while configuring the application for OpenID Connect 1.0 or OAuth 2.0 flow.
2. Client Secret: This is a secret value that is shared between the relying party and the Authorization server, so that they may communicate and be always assured that the communication shared was actually sent by the other node in the communication.
Cymmetri Platform: Cymmetri platform in the context of OpenID Connect 1.0 Single SignOn mechanism acts as two components in the OAuth 2.0 and OpenID Connect 1.0 flows. These component roles are explained below.
1. OpenID module (Authorization Server): Since Cymmetri platform acts as an Identity platform, it holds the capability to ensure that user session is valid, the user is authorized to access the managed application, among other authorization decisions, it plays the role of Authorization server in the OpenID Connect 1.0 process.
2. User Management Module (Resource server): Since the Cymmetri platform acts as a User Identity Hub, it holds the capability to store and provide user information to a managed application for the purpose of authentication and Single Sign On, it plays the role of Resource Server (Resource, being the user information) in the OpenID Connect 1.0 process.
User (Resource Owner) - The user information to be shared for a successful authentication is the resource in the OpenID Connect 1.0 flow, therefore, in the OAuth 2.0 terms, the user information is the resource, and the end-user is the resource owner.
OpenID Authorisation Endpoint - Authorization endpoint is used for accepting authentication/authorization requests in the form of redirected requests with the OpenID request query parameters added to it.
OpenID Token Endpoint - Token endpoint is used for generating Access and ID tokens by using the authorisation code received by the managed application (Relying Party).
User Information Endpoint - User information endpoint may be invoked by using the token shared to the managed application from the Cymmetri Identity platform, it will provide a list of all the user information that the user has consented to share with the end-application.
Token Introspection Endpoint - Token introspection endpoint is used when the relying party is an API client that requires access to the APIs protected by the OpenID Connect deployment. It will verify whether the access token is still valid and well-formed.
Redirect URIs - These are callback resources on the managed application, that can receive the messages sent from the Authorisation provider (Cymmetri Identity platform).
Scope - These are parameters used to indicate what information related to the user can be shared to the managed application.
State - This is a random string generated by the Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn.
Nonce - This is a random string generated by Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn and to prevent replay attacks.
Access Token - Access token is generated by the Cymmetri Identity platform for the purpose of authorising a client (whether an end-user OR an application using OpenID Connect). This may be verified for the purpose of ensuring the validity of the access token by the client requesting the token.
ID Token - The ID token is generated by the Cymmetri Identity platform for the purpose of authenticating an end-user using OpenID Connect protocol. Typically, the subject name and the email Address are shared as a part of this ID token along with any nonces or states used in the protocol are shared. This ID token may be used to get more information using the User Information Endpoint.
Authorisation Code - This is a string generated by the Cymmetri Identity platform for the purpose of server-to-server communication between the Relying party (managed application) and the Authorisation provider (Cymmetri Identity Platform). It may be exchanged by the relying party for the purpose of obtaining access and ID tokens.

Understanding OpenID Connect Flows

Common Use Cases for OpenID Connect 1.0

For performing Single SignOn with managed applications that have a backend (Typical Web Application SSO)
For performing Single SignOn with managed applications that do not have a backend (Single Page Applications and mobile-native applications)
For authorising access to REST APIs by verifying that the client making the calls has the requisite access.

Commonly Used OpenID Connect 1.0 flows

1. Authorisation Code Grant Type Flow

Typically used in the same scenario as the SAML 2.0 flow, it is used when the Identity provider and the Managed application are both capable of having a separate frontend and backend. These backends can have back-channel communication that is secure and cannot be modified or viewed in transit. This is therefore typically used when full-blown web applications are available.

2. Implicit Grant Type Flow

Typically used when the managed application is a simple Single Page application or a mobile native application that may not be able to use back-channel secure communication and a shared secret may not be used for authenticating the managed application to the Identity provider.

3. Client Credentials Type Flow

Typically used when a user is not involved and there is no need for ID tokens. The managed application handles its own authentication or is operating as a backend service only and needs to access a resource protected by the Identity provider.

Configuring and Managing OpenID Connect flow for Authorisation Code Grant Type

Understanding the Authorisation Code Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the authorization code, state, and the nonce will be sent as query parameters.
The managed application will verify the state and the nonce shared in step 2.
The managed application will then make a POST API request to the Token API of the Cymmetri OpenID service to exchange the authorization_code with the ID token and the Access token.
If this authorization_code is validated by the OpenID service, the managed application will receive the ID token and the Access token.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Authorisation Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

The ‘openid’ scope is mandatory for this flow.

The ‘offline_access’ scope is not currently used by the Cymmetri Identity platform deployment.

Other profiles are optional.

Providing ‘profile’ scope overrides the settings for the ‘email', ‘address’ and ‘phone’ scopes.

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.
Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the authorization code, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

This indicates the manner in which the response (access token or ID token) is shared back by the Cymmetri Identity platform to the managed application.

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Implicit Grant Type

Understanding the Implicit Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the access token, ID token, state, and the nonce will be sent as query parameters.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Implicit Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Implicit refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the ID token directly along with access token, we may choose “id_token” or “id_token token” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen 'id_token token' as our return type, we could choose any other response type that also includes both of these return types.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Client Credentials Grant Type

Understanding the Client Credentials Grant Type

Flow Diagram

Flow Explained

Generating Access Token for the Managed Application

OpenID service shares client ID, client secret, and audience to the managed application during the configuration phase.
The managed application makes a POST request to the token API of the OpenID service with the previously shared clientID, client secret, the audience string, and the grant_type as “client_credentials”.
The OpenID service validates the combination of (client_id, client_secret, and audience) and generates an access token to be shared to the managed application with an expiry time (in seconds).
The managed application should then verify the access token received by calling the token introspection endpoint.

Using the Access token to access protected API resource

The managed application should first request an access token as discussed above.
The managed application may then attempt to access the protected resource by sharing the client_id and authenticate the request using Bearer token as the access_token.
The protected resource may then validate the access token shared by calling the token introspection and validate that the client_id shared by the managed application in step 2 matches the client_id for which the access_token was generated, and that the token has not expired.
If the validation in step 3 is successful, the protected resource will be shared to the managed application.

Configuring the Client Credentials Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty for this flow, since the user does not need to be involved with this flow.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.
Audience - This audience needs to be shared by the managed application, and the Cymmetri Identity platform will validate it for providing access token.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the access token, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow has API exchange of tokens and validations. So we choose to use “Client Secret over HTTP POST” as the response type setting for this flow.

Configuring Webhooks

Webhooks are a way for external systems to receive events from the Cymmetri Identity Platform.

Requires the tenant organization to run a web server that is exposed to the Internet or at least accessible from the Cymmetri Cloud 2.0 deployment on the cloud

Events may be received for the following events -

Testing Webhook - Generates a POST request to the /test endpoint of the web server hosted by the tenant. It provides an authorization token that can be used for making any API calls to the Cymmetri Cloud 2.0 APIs. Is generated after this configuration. Go to the Configuration Menu and Select the webhooks menu -
Click on the save & test button.
Pre Create User - Generates a POST request, before the user is created, to the /preCreateUser endpoint of the web server hosted by the tenant.
Pre Update User - Generates a POST request, before the user is updated, to the /preUpdateUser endpoint of the web server hosted by the tenant.
Post Update User - Generates a POST request, after the user is updated, to the /postUpdateUser endpoint of the web server hosted by the tenant.
Validate User - Generates a POST request, before the user is created and validation is to be run, to the /validateUser endpoint of the web server hosted by the tenant.
Validate Update User - Generates a POST request, before the user is created and validation is to be run, to the /validateUpdateUser endpoint of the web server hosted by the tenant.
Change password - Generates a POST request, upon the change of password for a user, to the /changePassword endpoint of the web server hosted by the tenant.
Pre Provision - Generates a POST request, before the provisioning of the user to an application, to the /preProvision endpoint of the web server hosted by the tenant.
Post Provision - Generates a POST request, after the provisioning of the user to an application, to the /postProvision endpoint of the web server hosted by the tenant.
Policy Map - Generates a POST request, while assigning the application to a user, to the /policyMap endpoint of the web server hosted by the tenant.
Deprovision Run - Generates a POST request, upon the update of a user to deprovision a user, to the /runDeprovision endpoint of the web server hosted by the tenant.

While other webhooks operate on a principle of fire-and-forget, the validateUser and the validateUpdateUser expect the response from the tenant as the same or modified body as sent to it for validation.

API body for the endpoints

Test web hook

Purpose : This api is used to test web hook api.

Input Needed: NA

Curl Request:

--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImRlbGVnYXRlZSI6bnVsbCwiZGVsZWdhdGVlSWQiOm51bGwsImZpcnN0TG9naW4iOmZhbHNlLCJyb2xlcyI6WyJPUkdfQURNSU4iLCJVU0VSIl0sInRlbmFudElkIjoiYXMxMDAiLCJleHAiOjE2NDYzOTYzMDgsInVzZXJJZCI6IjYyMTRkYjdiZDY2MWE1NzM4NmE3MWYxMCIsImlhdCI6MTY0NjM5MDMwOH0.bdKZ3UBCedT91bJAWLCo2AOahIs5ClFMAhnj36f_ecQ' \

--header 'Content-Type: application/json' \

--data-raw '{

Response:

{ "response": {} }

Pre Create User

Purpose : This web hook api is used to do some events before creating a user in the target system.

Input needed :

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response: {

"response": {

"data": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Post create User

Purpose : This web hook is used to do some events after creating a user in the target system.

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response : NA

Restful API - Pre update user

Purpose : This web hook is used to do some events before updating a user in the target system.

Input needed:

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response

{

"response": {

"data": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Post update user

Purpose : This web hook is used to do some events after updating a user in the target system.

Input needed :

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response: NA

Validate User

Purpose : This web hook is used to validate users before creating a user in the target system.

Input Needed :

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response: {

"response": {

"error": true,

"message": "MobileAlreadyExist"

}

Validate update user

Purpose : This web hook is used to validate users before updating a user in the target system.

Input needed:

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response:

{

"response": {

"error": true,

"message": "EmailAlreadyExist"

}

Change password

Purpose : This web hook is used to do some events on password change.

Input Needed :

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

"passwordText" : "Welcome@123"

}

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

"passwordText" : "Welcome@123"

}

Response: NA

Pre provision

Purpose : This web hook is used to do some events before assigning applications to a user.

Input Needed :

{

"request": {

"policyMap" : "email",

"form" : "",

"applicationId" : "620231fee789224ec1cec3dd",

"roleList" : [],

"action" : "Application Create",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl Request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"policyMap" : "email",

"form" : "",

"applicationId" : "620231fee789224ec1cec3dd",

"roleList" : [],

"action" : "Application Create",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response : NA

Post provision

Purpose : This web hook is used to do some events after assigning applications to a user.

Input Needed :

{

"request": {

"policyMap" : "email",

"form" : "",

"applicationId" : "620231fee789224ec1cec3dd",

"roleList" : [],

"action" : "Application Create",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

"isSuccess" : true,

"uid" : "5f36283bc193991db0990d3e"

}

Curl response :

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"policyMap" : "email",

"form" : "",

"applicationId" : "620231fee789224ec1cec3dd",

"roleList" : [],

"action" : "Application Create",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

"isSuccess" : true,

"uid" : "5f36283bc193991db0990d3e"

}

Response : NA

Policy map

Purpose : This web hook is used to do some events on policy map while assigning the application to a user.

Input needed :

"request": {

"targetAttribute" : "email",

"cymmetrifield" : "email",

"formVeriable" : "",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request :

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"targetAttribute" : "email",

"cymmetrifield" : "email",

"formVeriable" : "",

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response :

{

"response": {

"mappedValue": "valid"

}

Run deprovisioning

Purpose : This web hook is used for deprovisioning applications when users get updated .

Input needed :

{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Curl request:

--header 'Content-Type: application/json' \

--data-raw '{

"request": {

"user": {

"assignedGroups": [],

"provisionedApps": {},

"securityQuestion": {},

"country": "India",

"firstName": "Shreyash2",

"lastName": "Pande2",

"login": "shreyash2",

"userType": "Employee"

}

Response:

{

"response": {

"data": true

}

SAML 2.0 Based SSO

Note: To use this mechanism, please ensure that your managed application supports authentication using SAML 2.0 protocol acting as the Service Provider (SP).

SAML 2.0 is a primarily web-based Single Sign On mechanism that uses XML based messages exchanged between the authenticating party, referred to as the Identity Provider (IdP) in the SAML 2.0 terms, and the relying party, referred to as the Service Provider (SP) in the SAML 2.0 terms.

In the context of Cymmetri SAML 2.0 implementation, your Cymmetri platform acts as the Identity Provider (IdP) and the managed application that the end-user wishes to access through Single Sign On acts as the Service Provider (SP).

SAML 2.0 bindings

The mechanisms within the SAML 2.0 protocol used for sharing Single Sign On messages are referred to as the SAML 2.0 bindings.

While the SAML 2.0 and its predecessor SAML 1.1 support various bindings, the Cymmetri platform supports the two most commonly used bindings for web applications - viz., HTTP POST Binding and HTTP Redirect Binding. These reflect the manner in which the requests and responses are shared between the Identity provider (Cymmetri platform) and the Service Provider (managed application).

HTTP Redirect Binding: The SAML assertion messages (request and response XML messages) are shared as GET query parameters.

HTTP POST Binding: The SAML assertion messages (request and response XML messages) are shared as POST body messages.

SAML 2.0 Request-Response Cycle

Additionally, there are two flows in which SAML 2.0 Request-Response cycle may be accomplished.

Service Provider initiated flow (SP initiated flow)
Identity Provider initiated flow (IdP initiated flow)

To start the configuration of the managed application for SAML 2.0 based SignOn mechanism, we must identify the flow supported by the managed application.

Let us explore what both these flows mean and how to configure your managed application to use them.

Service Provider Initiated Flow (SP Initiated Flow)

The SAML 2.0 Service Provider Initiated flow indicates that the Service Provider (in our case, the managed application which the end-user wishes to access via Single Sign On) has started the SAML 2.0 Single Sign On process by sending a SAML 2.0 request XML to the Cymmetri platform. This is achieved by the user landing on the Single Sign On URL of the managed application.

In practice, however, since the user is typically on the Cymmetri platform, we have enabled mechanisms to redirect the user to the Single SignOn URL of the managed application, when the user clicks on the application tile.

Flow Description

User lands on the SSO URL page of the managed application. This may be either through clicking on the application tile on the Cymmetri platform or by the user actually entering the SSO URL of the managed application in the browser address bar.
Managed application generates the SAML 2.0 request XML which holds the following important parameters - Request Id, Assertion Consumer Service URL (ACS), the expected Protocol Binding, and the Issuer of the Request.
A redirect is made to the page handling Single Sign On requests on the Cymmetri platform (<baseurl-of-cymmetri-tenant/samlsrvc/SingleSignOnService>) with the request in base64 format as a query parameter.
This page sends the SAML request body to the backend services of the Cymmetri platform to validate the request and to verify whether a session exists for a Cymmetri user in the current browser instance.
If a session does not exist for any user, the user is asked to login into the Cymmetri Identity platform.
If a session exists for the user, then the backend validates whether the user is authorized to access the application for which the SSO request has been initiated. (by checking whether the user is assigned the application.)
The backend services of the Cymmetri platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding in the SAML request is HTTP POST binding) to the Assertion Consumer Service URL mentioned in the SAML Request body, with the SAML Response audience as the Issuer mentioned in the SAML request body, and a field “InResponseTo” as the Request ID from the SAML request body.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
If the SAML response body is a valid SAML response, then the SAML assertion is extracted to obtain the user information sent by the Cymmetri platform.
If the user information is not valid, for any reason, then the corresponding error is displayed to the user by redirecting the user to the managed application’s error page.
If all the user information is valid, the managed application initiates the user’s session in the managed application web portal, and corresponding session cookies are generated.
Finally, the user is redirected from the application’s Assertion Consumer Service URL to the landing page of the managed application.

Note: In case of any validation errors, please refer to the section explaining the error scenarios below and change the configuration in either the managed application or the Cymmetri Application Sign On configuration page.

Service Provider(SP) Initiated Flow Configuration

The configuration parameters mentioned below are required to configure an application for Single Sign On using the Service Provider Initiated flow in the Cymmetri platform.

Prerequisites from the Managed Application

Entity ID/ Request Issuer - This is the request issuer that would have been sent by the managed application in case this were a Service Provider Initiated flow.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri platform.
Expected NameID Policy - This indicates whether the managed application expects the user subject name to be sent as the email address, username, or some other unspecified value.
Expected Signature Algorithm - The expected algorithm to be used for signing the responses and assertions.

Let us see an example demonstrating SP Initiated flow. We will be using a Service Now Instance for this example.

First we create an application in Cymmetri platform as discussed in previous articles. Let us use this application example below. We have already enabled SignOn as discussed and selected the SAML 2.0 option.

Let us now click on the dropdown for “Advanced Settings (SAML 2.0)”.

Click on the “Download Metadata” button, it is to be used in future steps.

Now go back to Service Now instance and Navigate to Multi-Provider SSO > Identity Providers. Choose any existing IdP and click the Generate Metadata button. The integration automatically generates the instance's SP metadata from the system property settings.

Let us come back to the SAML 2.0 settings for our managed application in Cymmetri platform and start entering the fields one by one.

SAML Type - We select the “SP_INITIATED” from the dropdown.

Since the metadata downloaded from ServiceNow does not indicate the use of a particular signature algorithm, let us simply use “RSA_SHA256”.

Further, we need to select NameID Format. Referring to the highlighted portion in the metadata downloaded from the sample application, we find only 1 supported NameID format

emailAddress: This indicates to the managed application, that the Identity Provider (Cymmetri Platform) will be sending the end-user’s email address, and that the managed application must handle it accordingly.

We see four other NameID formats in the dropdown, let us understand them one-by-one.

NameID Formats:

unspecified: This is a generic and default selection of NameID format, typically this would mean that the Cymmetri platform may send any user attribute, which can be selected further. The managed application must handle it accordingly. This will be used whenever some custom or unusual user attribute is to be passed to the managed application.
transient: This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is in fact not permanent, but may change for the period of the end-user’s identity lifecycle.
persistent: This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is permanent, and will remain the same for the period of the end-user’s identity lifecycle.
username: This is used as a NameID format when we wish to indicate to the managed application, that we will be sharing the end-user’s username from Cymmetri Identity Provider to the managed application during the SAML 2.0 process.

Let us select email as the NameID format.

Let us now discuss NameID Values

There are two scenarios here -

Choosing NameID format as “username” and “email” - The value of the NameID Value will not matter, the end-user’s username or email address will be shared to the managed application.
Choosing NameID format as “unspecified”, “transient”, and “persistent” - The value of the NameID value will allow for a particular value of the User object to be shared to the managed application.

Possible Values of NameID Value are - email, mobile, firstName, lastName, displayName, loginId.

Let us select email as a NameID value, however, it will not affect the configuration.

For configuring the “Request Issuer”, let us refer back to the downloaded metadata.xml from the Service Now application.

We use the entityID from the downloaded metadata as the Entity ID

Please note that the Entity ID field is how the Cymmetri platform identifies the managed application from the SAML Request sent by the managed application. Please ensure that the Entity ID is unique across the deployment.

For the Assertion Consumer Service URL, we once again refer to the downloaded XML,

Let us enter the Assertion Consumer URL as "https://dev165684.service-now.com/navpage.do"

Finally, we refer to the downloaded XML one last time, for deciding upon the toggle buttons:

Here we see the managed application, requires only the Assertions to be signed and not the Authentication requests, we define the toggle switches accordingly.

Let us return back to Service Now application for completing the configuration on the Service rovider side.

Note:

Once the above 3 steps are successfully completed we can create a new IDP

Create a new IDP

Click on the New button to create a new IDP

Then select SAML

Then upload the metadata from the file downloaded in a previous step. and Hit Import button to store the Identity provider metadata in the application.

Once imported provide the Signing/ Encryption Key Alias and Signing/ Encryption Key Password as saml2sp and in the Advanced Tab tick the CreateAuthnContextClass checkbox. The Signing/ Encryption Key Alias and Signing/ Encryption Key Password are used for encryption of data and the CreateAuthnContextClass is used to tell the IDP that Service Now requires that they present a specific login mechanism such as form, Kerberos etc.

Note: Also make sure both the logout urls present here are removed temporarily for testing purposes, else you would logout completely from ServiceNow

Then enter the instance url in the SignOn configuration of the managed application on the Cymmetri portal.

Click the “Save” button.

Next Create a New User in Service Now. Go to Organization->Users->New and provide the credentials of the user logged into Cymmetri as show below and Submit:

Testing the Service Provider initiated flow

Now that both sides are configured, let us test the flow by assigning the application to the current user.

Then to activate the externa IDP in Service Now we need to test the connection on the Service Now side by clicking on the Test Connection button.

Once successfully tested you should see the below screen with successful test results. Click on the Activate button to activate the IDP.

Once activated Click on the Set as Auto Redirect IdP link to automatically redirect to IDP when using a SP Initiated process

Once it is enabled we can come to the currently logged in user's My Workspace-> My Access page and click on the Service Now application tile

We will now be redirected to the ServiceNow home page using the logged in users crendentials as shown below:

Identity Provider Initiated Flow (IdP Initiated Flow)

The SAML 2.0 Identity Provider Initiated flow indicates that the Identity Provider (in our case, the Cymmetri platform) has started the SAML 2.0 Single SignOn process by sending an unsolicited SAML 2.0 response XML to the Cymmetri Identity platform. This is achieved by the user clicking on the managed application tile in their workspace.

Flow Description

The user clicks on the application tile, which sends a request to the Cymmetri platform backend to initiate the SAML 2.0 SignOn process.
The backend validates whether the user is authorised to access the application for which the SSO request has been initiated. (by checking whether the user is assigned the application.)
The backend services of the Cymmetri platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding expected in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding expected in the SAML request is HTTP POST binding) to the Assertion Consumer Service URL mentioned in the SAML Request body, with the SAML Response audience as the Issuer mentioned in the SAML request body, and a field “InResponseTo” as the Request ID from the SAML request body.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
If the SAML response body is a valid SAML response, then the SAML assertion is extracted to obtain the user information sent by the Cymmetri platform.
If the user information is not valid, for any reason, then the corresponding error is displayed to the user by redirecting the user to the managed application’s error page.
If all the user information is valid, the managed application initiates the user’s session in the managed application web portal, and corresponding session cookies are generated.
Finally, the user is redirected from the application’s Assertion Consumer Service URL to the landing page of the managed application.

Identity Provider(IdP) Initiated Flow Configuration

The configuration parameters mentioned in the information panel below are required to configure an application for Single SignOn using the Identity provider initiated flow in the Cymmetri Identity portal.

Prerequisites from the managed Application

Entity ID/ Request Issuer: This is the entity id/ request issuer that would have been sent by the managed application in case this were a Service Provider initiated flow.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.
Expected NameID Policy - This indicates whether the managed application expects the user subject name to be sent as the email address, username, or some other unspecified value.
Expected Signature Algorithm - The expected algorithm to be used for signing the responses and assertions.

Note: Identity Provider initiated flow is a subset of the Service Provider initiated flow. Some steps are similar if you have already configured the Service Provider initiated flow.

First we create an application in the Cymmetri platform as discussed in previous article. Let us use Service Now application as an example below. We have already enabled SignOn and enabled SAML 2.0 option.

Let us now click on the dropdown for “Advanced Settings (SAML 2.0)”.

Let us start entering the fields one by one.

SAML Type - We select the “IDP_INITIATED” from the dropdown.

All the remaining steps for configuring IdP Initiated SAML 2.0 flow are same as shown above in the SP Initiated flow.

Testing the Identity Provider Initiated Flow

Now that both sides are configured, let us test the flow by assigning the application to the current user.

Click on the currently logged in user's My Workspace-> My Access page and click on the Service Now application tile

We will now be redirected to the ServiceNow home page using the logged in users crendentials as shown below:

Identity Provider Initiated Flow (IdP Initiated Flow)

Possible Error Scenarios in Validation

Scenario 1: SAML request body does not meet the validation requirements for the SAML request.

Cause: Incorrect implementation of the SAML protocol by the managed application.

Fix: Verify that the SAML protocol is accurately implemented by the managed application.

Scenario 2: SAML request body does not have the same issuer as the configuration in the Cymmetri platform.

Cause: Incorrect configuration of SignOn on the Cymmetri platform for the managed application.

Fix: Change the request Issuer in the managed application configuration on the Cymmetri platform according to the Issuer field in the SAML request.

Scenario 3: SAML response body does not meet the validation requirements for the SAML response.

Cause: Incompatible expectations of the SAML 2.0 response body between the managed application and the Cymmetri Identity platform.

Fix: Connect with the Cymmetri Identity platform support team.

Scenario 4: SAML Response assertion has the incorrect audience.

Cause: Incorrect configuration of the entity id/request issuer field in the Cymmetri Identity platform for the managed application.

Fix: Verify and change the entity id/ request issuer field in the managed application configuration on the Cymmetri platform according to the Issuer field in the SAML request.

Scenario 5a: User from the SAML Assertion is not valid.

Cause: Incorrect name ID format.

Fix: Verify and change the NameID format as expected by the managed application.

Scenario 5b: User from the SAML Assertion is not valid.

Cause: Incorrect user field in the assertion.

Fix: Verify that the right user field is selected as the “NameID Value” in the managed application configuration and Verify that the user information has the correct information as expected by the managed application in the field selected as the “NameID Value” in the managed application configuration on the Cymmetri platform.

Scenario 5c: User from the SAML Assertion is not valid.

Cause: User information is as expected but scenario 5b is not the cause.

Fix: Verify that the user information is present in the user database of the managed application. In case the managed application has JIT feature, ensure that the SAML attributes are correctly configured.

SAML Attribute Mapper

A SAML Attribute Mapper is a component or feature in a Single Sign-On (SSO) or identity federation system that helps map user attributes between different identity providers (IdPs) and service providers (SPs) during the SAML (Security Assertion Markup Language) authentication process.

Here's how it works:

Authentication: When a user tries to access a service or application that requires authentication, they are redirected to an identity provider (IdP) for authentication. The IdP verifies the user's identity and generates a SAML assertion containing information about the user.
SAML Assertion: The SAML assertion typically contains various attributes about the user, such as their username, email address, roles, or other user-related information. These attributes are represented as name-value pairs.
Attribute Mapping: Before the SAML assertion is sent to the service provider (SP), which is the application or service the user is trying to access, there may be a need to map or transform these attributes. This is where the SAML Attribute Mapper comes into play.
- Attribute Transformation: Sometimes, the IdP may use different attribute names or formats than what the SP expects. The SAML Attribute Mapper can transform the attributes in the SAML assertion to match the expectations of the SP.
- Filtering: The mapper can also be used to filter or select specific attributes from the SAML assertion. For example, if the IdP provides a wide range of attributes, but the SP only needs a subset of them, the mapper can be configured to include only the required attributes in the assertion sent to the SP.
- Value Mapping: It can map attribute values as well. For instance, if the IdP uses "userType=employee" and the SP expects "role=employee," the mapper can perform this value mapping.
Forwarding to SP: Once the attributes in the SAML assertion are mapped or transformed as necessary, the SAML assertion is forwarded to the service provider. The SP can then use these attributes for authorization and access control decisions.

Configure SAML attributes

In case of default attributes, the user object already has the attributes, we just need to ensure that the right values are assigned to these attributes. In case of custom attributes, custom attributes must be added to your Cymmetri Identity platform deployment.

Cymmetri Attribute

Default / Custom

user.eduPersonPrincipalName

Custom

user.eduPersonTargetedID

Custom

user.displayName

Default

user.cn

Custom

user.givenName

Custom

user.sn

Custom

user.mail

Default

user.schacHomeOrganization

Custom

user.schacHomeOrganizationType

Custom

user.schacPersonalUniqueCode

Custom

user.eduPersonAffiliation

Custom

user.eduPersonScopedAffiliation

Custom

user.eduPersonEntitlement

Custom

user.eduPersonOrcid

Custom

user.isMemberOf

Custom

user.preferredLanguage

Custom

user.eckid

Custom

user.surfCrmId

Custom

user.uid

Default

user.login

Default

user.firstName

Default

user.lastName

Default

user.country

Default

user.countryCode

Default

user.city

Default

user.mobile

Default

user.address1

Default

user.address2

Default

user.managerId

Default

user.userType

Default

user.orgUnitId

Default

user.employeeId

Default

user.department

Default

user.designation

Default

user.status

Default

user.associatedPartner

Default

user.dateOfBirth

Default

user.landline

Default

Let us click on the “configure SAML attributes” link in the configuration page

On clicking the following should pop up

Let us add an attribute mapper as per the table defined above

We have added the First Name of the user from the Cymmetri Identity Platform to the managed Application as the key “First Name”.

Click on the save icon next to the delete icon (trash can icon).

Click on the “X” icon to close the attribute mapper.

Now once again go back to the “My Access” page and click the application tile.

Service Now can use this data for auto provisioning of users via jit provisioning provided Auto Provisioning User is enabled under the User Provisioning tab in the Identity Provider Configuration page.

Samples

SAML 2.0 Sample Request

SAML 2.0 Sample Response

<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
                 Destination="https://dev165684.service-now.com/navpage.do"
                 ID="_6db464f3-b783-4834-98ea-6ed1681dd2cd"
                 IssueInstant="2023-09-26T10:19:01.472Z"
                 Version="2.0"
                 >
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">ccaa</saml2:Issuer>
    <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                     xmlns:xs="http://www.w3.org/2001/XMLSchema"
                     ID="_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87"
                     IssueInstant="2023-09-26T10:19:01.472Z"
                     Version="2.0"
                     >
        <saml2:Issuer>ccaa</saml2:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
                <ds:Reference URI="#_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
                                                    PrefixList="xs"
                                                    />
                        </ds:Transform>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue>4BaEkbuyzytz0XkXo19cBeLjGnYrTOvPhxfv3NWyidc=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>vRw1lhio5G38L/inuAp9l9yjekbCCM4BduLykL7vg4wijlHmbrSMiNJNuqOu8vO79Aqruj6GBafGRD6Slqrco5vScsWbfH5LiHz5UejAh2sGsqbQHapYFPlZJ6ErauwFxbzGN7od5CYlZUgDPUdO1dF2jiwoYeqhs+aQOISsyoq9pcQ2yl35wmaUy6C388a+m54OzygQhwsQdxEeA1OqLDtAw3ulTxbKsjRw1hAa7zv4JKKO10HirrWwWXDe3dSsh2Z3um0sF6TxWjV5wKXKflXz1alNPcNBONTjTWOfwKD/a+agZITQ8jGJAo6vZXfF3bI7N0uo3dWF3ogK2jzpjg==</ds:SignatureValue>
        </ds:Signature>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">Ak@mail.com</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData NotOnOrAfter="2023-09-26T18:19:01.472Z"
                                               Recipient="https://dev165684.service-now.com/navpage.do"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2023-09-26T10:16:01.472Z"
                          NotOnOrAfter="2023-09-26T10:22:01.472Z"
                          >
            <saml2:AudienceRestriction>
                <saml2:Audience>https://dev165684.service-now.com</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2023-09-26T10:19:01.472Z"
                              SessionIndex="_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87"
                              >
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="User Name"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Ak@123</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="email"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Ak@mail.com</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="firstName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Akash</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="lastName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Patil</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

External Identity Provider Configuration - Salesforce IDP

Here below the same steps are demostrated to use Salesforce as and Identity Provider and Cymmetri as a Service Provider.

Configuring Salesforce

For configuring Salesforce to be used as an IDP the Salesforce Administrator needs to login in Salesforce as shown below:

Once logged in the administrator needs to click on Setup on top right and then in the search bar on the right side search for Identity Providers. Once found click on Security Controls -> Identity Provider menu

When the Identity Provider page opens click on Enable Identity Provider button to enable Salesforce as and Identity Provider so that it can be used for authentication in Cymmetri.

When the Enable Identity Provider button is clicked it opens a page that asks you to choose a certificate. Select the default certificate here and click Save.

When saved it shows a warning message as below just click OK button and continue.

Once confirmed the screen as show below appears you may download the certificate and the metadata file here using the Download Certificate and Download Metadata buttons. These files can be downloaded later during the end the process which can be seen later in the documentation below.

The metadata file appears as below, this data is used later to configure the External IDP in Cymmetri.

The certificate file appears as below this is also needed when configuring the External IDP in Cymmetri.

Once the files are downloaded next to add the Service Provider the salesforce administrator needs to click on Service Providers are now created via Connected Apps. Click here link. The mentioned link allows to create a Connected App for Cymmetri which acts as a service provider in Salesforce.

The link above leads to the page below where a new connected app can be added. Following details need to mentioned to add a connected app:

Connected App Name: App Name (Cymmetri in this case)
API Name: Auto-populated based on Connected App Name field, can be changed
Contact Email: a valid contact email

Note: Other fields shown in the image below are optional and hence can be skipped.

Next on the same page there is a section called Web App Settings here click on Enable SAML to enable the SAML settings. Once enabled all the below mentioned details need to be provided.

Entity Id: A unique identifier for a SAML entity, such as a Service Provider (SP) or Identity Provider (IDP), within a federated authentication environment.
ACS URL (Assertion Consumer Service URL): The endpoint where a service provider expects to receive SAML assertions from an identity provider, facilitating single sign-on (SSO) in a federated system.
Enable Single Logout: A configuration option indicating whether the system supports single logout functionality, allowing users to log out of all connected services in a federated environment with one action.
Single Logout URL: The endpoint to which a SAML entity sends logout requests as part of the single logout process when a user logs out of the federated system.
Single Logout Binding: The protocol or method used to transmit single logout requests and responses between SAML entities, often specified as either HTTP Redirect or HTTP POST.
Subject Type: Specifies the type of subject identifier used in SAML assertions, such as transient, persistent, or bearer, indicating how the identity of the user is communicated between the identity provider and the service provider.
Name ID Format: Defines the format of the NameID element in SAML assertions, determining how the user's identity is represented, such as email address, X.509 certificate, or unspecified.
Issuer: Identifies the entity that issues a SAML assertion, typically the identity provider, and is included in the SAML assertion to establish trust between the entities in a federated system.
IDP Certificate: The public key certificate associated with the identity provider, used by the service provider to verify the authenticity and integrity of SAML assertions and messages.
Signing Algorithm for SAML Messages: Specifies the cryptographic algorithm used to sign SAML messages, ensuring the integrity and authenticity of the information exchanged between identity providers and service providers in a federated

Once all details are successfully added and saved the screen as below appears which shows the configuration details.

Administrator can click on Manage button (as shown above) to view SAML Service Provider Settings and SAML Login Information. Administator can also download metadata file here.

The downladed metadata file appears as below. The details mentioned in the metadata file are used to configure an External IDP in Cymmetri.

Based on the diverse profiles of users in Salesforce, the administrator needs to enable Connected App Access for these profiles. Here in this example access has been enabled for the System Administrator; similarly, it should be enabled for all profiles of various users who are intended to access Cymmetri.

For enabling the connected app administrator needs to go to Setup->Manage Users-> Profiles, then select the profile for which the connected app needs to be enabled

Once the profile is selected click on Edit button and look for Connected App Access section.

In the Connected App Access section look for the custom app you created(Cymmetri in this case) and click the checkbox to enable the access.

Once all the configurations on Salesforce end are done, the administrator must proceed with the configuration on the Cymmetri side. To achieve this, the administrator needs to go to Authentication->Identity Provider->External IDP. Here you may either configure the already created salesforce-idp instance or +Add New

In either cases a screen opens where you need to provide the below mentioned details

Name: salesforce-idp
IDP Type: Salesforce
Entity ID: Need to mention the EntityID from the metadata file downloaded from Salesforce
SSO Service URL: Need to mention the SingleSignonService url from the metadata file downloaded from Salesforce
Destination: https://<hostname>/spsamlsrvc/samlSP/SingleSignOn
Protocol Binding: HTTP Post (can also be set to HTTP Redirect if it is set so in Salesforce)
Name ID Policy:
- Policy: Unspecified(This may change based on what is configured in Salesforce)
- Value: Login(This may change based on what is configured in Salesforce)
Certificate: Certificate downloaded from Salesforce
Logout Request URL: Need to mention the SingleLogoutService url from the metadata file downloaded from Salesforce
Logout Protocol Binding:HTTP Post (can also be set to HTTP Redirect if it is set so in Salesforce)
Service Provider Id: cymmetri (Need to the select the configured Service Provider as shown above)

Now the user can login into Cymmetri using Salesforce. The user needs to provide his/her username and click on Next.

The user is then redirected to Salesforce login page where the user needs to enter their Salesforce credentials and click on Log in

Once the salesforce credentials are successfully validated the user is redirected to Cymmetri home page.

Configuring Connector Server

Connectors can be deployed in two ways:

Local connectors are deployed to a Cymmetri instance. This is the usual way how connectors are used. The connector is executed inside a Cymmetri instance, has the same lifecycle (start/stop), etc. Cymmetri can detect local connectors automatically and overall the connector management is easier.
Remote connectors are executed in a different process or on a different node than Cymmetri instance. Remote connectors are deployed to a connector server. There may be need to use a remote connector e.g. to access a file on a remote system (e.g. in case of CSV connector) or because of platform incompatibilities (e.g. .NET connectors)

Connector is not developed as local or remote. The placement of the connector is a deployment-time decision. There is just one connector package that can be deployed locally or remotely.

A connector server is required when a connector bundle is not directly executed within your application. By using one or more connector servers, the connector architecture thus permits your application to communicate with externally deployed bundles.

Connector servers are available for both Java and .NET.

A Java connector server is useful when you do not wish to execute a Java connector bundle in the same VM as your application. It may be beneficial to run a Java connector on a different host for performance improvements if the bundle works faster when deployed on the same host as the native managed resource. Additionally, one may wish to use a Java connector server under a Java remote connector server in order to eliminate the possibility of an application VM crash due to a fault in a JNI-based connector.

The use of .NET connector server is especially useful when an application is written in Java, but a connector bundle is written using C#. Since a Java application (e.g. J2EE application) cannot load C# classes, it is necessary to instead deploy the C# bundles under a .NET connector server. The Java application can communicate with the C# connector server over the network, and the C# connector server serves as a proxy to provide to any authenticated application access to the C# bundles deployed within the C# connector server.

Java Connector Server

Installing a Java Connector Server

Minimum Requirements:

Java 1.6 or later for 1.4.X.Y / Java 1.8 for 1.5.X.Y
Refer to your Java connectors to determine if there are any additional requirements

Create your execution environment

Download the Connector Server package
Unzip it in a directory of your choice (e.g. /usr/jconnserv) on the host where you wish to run the Java connector server

Test your execution environment

From the directory created above, run the Java connector server with no arguments to see the list of command-line options:

Linux / MacOS: ./bin/ConnectorServer.sh
Windows: \bin\ConnectorServer.bat

You should see the following output:

Usage: 
  Main -run -properties 
  Main -setKey -key  -properties 
  Main -setDefaults -properties

Configure your Java connector server

Run the connector server with the setkey option as described below to set your desired key into your properties file
- Linux/ MacOS: ./bin/ConnectorServer.sh -setkey <key> -properties conf/ConnectorServer.properties
- Windows: bin\ConnectorServer.bat /setkey <key> /properties conf\ConnectorServer.properties
For all other properties (e.g. port), edit the conf/connectorserver.properties manually. The available properties are described in the connectorserver.properties file.

Running your Java connector server

Run the server by launching with the -run option:

Linux / MacOS: ./bin/ConnectorServer.sh -run -properties conf/ConnectorServer.properties
Windows: bin\ConnectorServer.bat /run -properties conf\ConnectorServer.properties

Installing Connectors on a Java Connector Server

To deploy a Java connector:

Copy the Java connector bundle jar file into the bundles directory in your Java connector server directory
If necessary, add to the classpath any 3rd party jars required by any Java connector
Restart the Java connector server

Using SSL to communicate with connector servers

The following steps are necessary to successfully communicate with a connector server using SSL:

Deploy an SSL certificate to the connector server's system.
Configure your connector server to provide SSL sockets.
Configure your application to communicate with the communicate with the connector server via SSL.

Configure your application to use SSL

Refer to your application manual for specific notes on how to configure connections to connector servers. You will need to indicate to your application that an SSL connection is required when establishing a connection for each SSL-enabled connector server.

Additionally, if any of the SSL certificates used by your connector servers is issued by a non-standard certificate authority, your application must be configured to respect the additional authorities. Refer to your application manual for notes regarding certificate authorities.

Java applications may solve the non-standard certificate authority issue by expecting that the following Java system properties are passed when launching the application:

javax.net.ssl.trustStorePassword For example, -Djavax.net.ssl.trustStorePassword=changeit
javax.net.ssl.trustStore For example, -Djavax.net.ssl.trustStore=/usr/myApp_cacerts

Or, instead, the non-standard certificate authorities may be imported to the standard ${JAVA_HOME}/lib/security/cacerts.

.NET Connector Server

Installing a .NET Connector Server

Minimum Requirements:

Windows Server 2003 or 2008
.NET Framework 3.5 or higher
Refer to your .NET connector to determine if there are any additional requirements

Execute ServiceInstall.msi. Just follow the wizard. It will walk you through the whole process step by step. Upon completion, the Connector Server will be installed as a windows service.

Configuring the .NET Connector Server

Start the Microsoft Services Console. Check to see if the Connector Server is currently running. If so, stop it. From a command prompt, set the key for the connector Server. This is done by changing to the directory where the connector server was installed (by default: \Program Files\Identity Connectors\Connector Server) and executing the following command:

ConnectorServer /setkey <newkey>

where <newkey> is the value for the new key. This key is required by any client that connects to this Connector Server.

Look through the configuration file and inspect all settings. The most common things to change would be the port, trace, and ssl settings.

Additional Notes about configuration

The port, address, and SSL settings are in the tag called AppSettings, and look like this:

<add key="connectorserver.port" value="8759" />
<add key="connectorserver.usessl" value="false" />

<add key="connectorserver.certificatestorename" value="ConnectorServerSSLCertificate" />
<add key="connectorserver.ifaddress" value="0.0.0.0" />

The port can be set by changing the value of connectorserver.port. The listening socket can be bound to a particular address, or can be left as 0.0.0.0. To setup to use SSL, you must set the value of connectorserver.usessl to true, and then set the value ofconnectorserver.certifacatestorename to your the certificate store name.

You will need to record for use later the following information regarding your connector server installation:

Host name or IP address
Connector server port
Connector server key
Whether SSL is enabled

Changing Trace Settings

Trace settings are in the configuration file. The settings look like this:

<system.diagnostics>
  <trace autoflush="true" indentsize="4">
     <listeners>
       <remove name="Default" />
       <add name="myListener" type="System.Diagnostics.TextWriterTraceListener"
  initializeData="c:\connectorserver2.log" traceOutputOptions="DateTime">        
         <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information" />
       </add>
    </listeners>
  </trace>
</system.diagnostics>

The Connector Server uses the the standard .NET trace mechanism. For more information about the tracing options, see Microsoft's .NET documentation for System.Diagnostics.

The default settings are a good starting point, but for less tracing, you can change the EventTypeFilter's initializeData to "Warning" or "Error". For very verbose logging you can set the value to "Verbose" or "All". The amount of logging performed has a direct effect on the performance of the Connector Servers, so be careful of the setting.

Any configuration changes will require the connector server to be stopped and restarted.

Running the .NET Connector Server

The best way to run the Connector Server is as a Windows service. When installing, the Connector Server is installed as a Windows service. This should be fine for most installations.

If for some reason, this is not adequate, the connector server may be installed or uninstalled as a Windows service by using the /install or /uninstall arguments on the command line. To run the Connector Server interactively, issue the command:

ConnectorServer /run

Installing Connectors on a .NET Connector Server

To install new connectors, change to the directory where the Connector Server was installed, and unzip the zip file containing the connector there. Restart the Connector Server.

Running Multiple Connector Servers on the Same Machine

To install additional Connector Servers on the same machine, download the Connector Server zip file from the downloads section. Create a directory to install to, and unzip the file there. Edit the configuration file as described above ensuring that you have a unique port. You may also want to make sure that the trace file is different as well. You can then run the additional Connector Server interactively or as a service.