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

Start by clicking on the link register.cymmetri.io to start the registration of your tenant on the Cymmetri Cloud 2.0 and enter your personal details with your work email. Click on Next.

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.

Supported Web Browsers

Cymmetri supports the following web browsers:

Chrome

Firefox

Edge

Safari

Version of specific browsers supported by Cymmetri are:

DESKTOP:

Browser

Version

MOBILE:

Browser

Version

Cymmetri Error Codes

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

ERROR CODE

ERROR TEXT

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.

To access this valuable documentation, you can visit https://help.cymmetri.io directly. Alternatively, you can simply click on the help icon located at the bottom left of your Cymmetri tenant screens.

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

General Configuration

In this section within Cymmetri a range of general or broad configuration settings and options are managed. These settings encompass various foundational configurations that affect the overall behavior of Cymmetri.

There are different system configurations in Cymmetri mentioned below:

On Behalf

It refers to a setting within Cymmetri that enables a user to raise an application access request on behalf of another user. An administrator can enable this feature and then the user can raise a request for any other user. The page here shows how the users get an access to the On Behalf feature and use it to raise application requests

Time Based

In the Time-Based configuration, system administrators have the capability to determine whether the system will send repeated notifications to users based on the number of days remaining, as specified in the 'Send Notifications before' field. This occurs when an application is assigned to the user as a time-based application and is about to expire.

Email Config

These settings and configurations within Cymmetri are specifically related to the management and customization of email-related functionalities. This configuration area allows administrators to set up, manage, and customize the email communications as per the organization's needs.

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.
Click on the pencil icon to edit the template.
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.

Importing Users

Users may be imported into the Cymmetri platform using the bulk Import Users feature.

Importing Users

For Importing Users in Cymmetri platform administrator need to click on Identity Hub > User menu and then click on the Bulk Import > Import Users button.

A screen pops up that lets you select the csv file you want to upload to import the users, Upload the csv file, you may also use the sample data file available and modify it to match your user details.

Click on the Upload File button and select the file you wish to import

Once the file is selected ensure that the default parameters select match your rewuirement else you may change these parameters as per your requirement and click on Next button.

Match the Column names from the CSV file with the Cymmetri User Attributes using this File Info dialog box.

Scroll down and click on the Import button. Note: A "Skip user workflow" check box is available to skip execution of any user workflow configured for creation of users, if not selected it may trigger user creation workflow and the process of importing users may slow down due to the numerous approvals that the approver might have to do.

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

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

For any user to be able to delegate their work to other users, the user should be added to the delegation users list; Check how to Add Users to the delegation list so that they can delegate their activities.

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

Logs

LIfecycle Management

Application Management

Getting Started

Provisioning How to

Reconciliation How to

Rules

Provisioning

Deprovisioning

Workflow Management

Single Sign On

My Workspace

External Identity Provider Configuration - Salesforce IDP

Note: The link below shows steps as suggested by Salesforce to configure Salesforce as an Identity Provider:

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.

Assigning Applications to End Users

Once the managed application has been added to your Cymmetri Identity platform tenant, you will be able to assign applications to your end-users.

Application Assignment

There are three ways in which applications can be assigned to users:

Admin may assign an application directly to a user.
Admin may map an application to a group; and the user is added to the group or is already part of the group.
End User may request an application and is granted access to the application.

Let us understand the flow for each of the above mentioned scenarios:

1. Admin assigns an application directly to the end user

Users with admin roles such as Organization Admin, Domain Admin, or Application Admin on the Cymmetri platform can assign managed applications to end-users .

First, we need to add the application to the Cymmetri platform
Next, we move to configure the application to assign it to an end user.
Click on the application tile to configure it.

The flow for assignment goes as follows -

Description:

Admin clicks on the application tile, and starts the configuration.
Click on the Assignments tab on the left hand side menu.
Click on the “Assign New” button on the Users menu.
Here we need to decide whether we want to provide a Lifetime Access or a Time Based Access
1. Lifetime Access: Users have access to the application without any time restrictions.
2. Time Based Access: Users have access to the application only for the specified range of time. We need to provide a Start Date & Time and an End Date & Time for Time Based Access.
Now click on Save to register a request for the application assignment. If no Workflow is configured for the said application the application is immediately assigned to the user.
If a workflow for application provisioning is configured then the workflow is been initiated.
The workflow approver will then receive a request to approve the user assignment in their inbox.
Now the approver may approve or reject the user assignment
The approver may change the start and end date, if required; refer to the dynamic form attributes passed during the application assignment.
To continue the flow click on Accept button.
Now the next level of approver will be able to see the previous levels of approval, and similar to the previous level of approval, the approver may change the start and end date, if required; refer to the dynamic form attributes passed during the application assignment.
Click “Accept” to proceed.
After the last level approver has also approved the assignment, the backend processes will run the application provisioning flow.
Once the user has been provisioned in the application, they will be able to see it in their list of applications.

2. Admin assigns an application directly to a group

Users with admin roles, such as Organization Admin, Domain Admin, or Application Admin, in a Cymmetri Identity platform deployment, will have the ability to assign entire groups of users to managed applications.

First, we need to add the application to the Cymmetri platform
Next, we move to configure the application to assign it to a group.
Click on the application tile to configure it.

The flow for assigning a group to an application goes as follows:

Description:

Click on the application tile, and start the configuration.
Click on the Assignments tab on the left hand side menu.

3. Click on the “Assign New” button in the Groups section.

4. Search for the group you wish to assign the application to and click on the assign button.

5. Checking for the users who belong to the group, we can see that the application has been assigned.

6. Viewing the application tiles, we can see if the user was directly assigned the application or received access by the virtue of being part of a group.

User requests for an application

Users on the Cymmetri platform can request access to a managed applications as a Self-Service feature.

The flow for an end-user to request for an application is as follows:

Description:

Visit the “My Workspace” menu.
Click on the “My Access” left-hand side menu.

3. Now Click on the “+ Request” button on the top-right button.

Here we need to decide whether we want to provide a Lifetime Access or a Time Based Access
1. Lifetime Access: Users have access to the application without any time restrictions.
2. Time Based Access: Users have access to the application only for the specified range of time. We need to provide a Start Date & Time and an End Date & Time for Time Based Access.
Now click on Save to register a request for the application assignment. If no Workflow is configured for the said application the application is immediately assigned to the user.
If a workflow for application provisioning is configured then the workflow is been initiated.
The workflow approver will then receive a request to approve the user assignment in their inbox.
Now the approver may approve or reject the user assignment
The approver may change the start and end date, if required; refer to the dynamic form attributes passed during the application assignment.
To continue the flow click on Accept button.
Now the next level of approver will be able to see the previous levels of approval, and similar to the previous level of approval, the approver may change the start and end date, if required; refer to the dynamic form attributes passed during the application assignment.
Click “Accept” to proceed.
After the last level approver has also approved the assignment, the backend processes will run the application provisioning flow.
Once the user has been provisioned in the application, they will be able to see it in their list of applications.

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.

Configuring Reconciliation Process

Once the applications have been configured to allow that the end-users have been provisioned into the managed application. We may now start configuring the reconciliation process for an application. The reconciliation process involves identifying the user attributes as stored in the Identity hub (Cymmetri platform) and their attributes as a user or a group account in the managed application; and the ensuring that the synchronization of the user and group accounts takes place either one-way or both ways between the managed application and the Identity hub, to ensure that there no discrepancies in the accounts stored by both the systems.

The reconciliation process may follow two strategies -

Full Reconciliation Full reconciliation is typically carried out when the managed application is first introduced into an organization’s Cymmetri platform. This involves ensuring all user accounts (and group accounts, wherever applicable) from the Cymmetri platform, are synchronized with the account information on the managed application. This type of reconciliation often takes a longer time, and is often only used as a one-time activity.
Filtered Reconciliation The Cymmetri platform and the managed application might lose synchronization due to a number of reasons, including backend changes to the user or group account information on the managed application or failure of communication between the identity platform and the managed application. In such cases, filtered reconciliation is employed on a regular, scheduled basis. This includes filters for a particular set of users, or to choose only the users that have been modified on either platforms, this is known as filtered reconciliation.

Cymmetri platform allows for both types of reconciliation phases, by allowing administrator to define an optional user filter during the reconciliation process.

The reconciliation process involves two major processes:

Pull In this mechanism, the Cymmetri platform allows for user and group account information to be pulled from the managed application.
Push In this mechanism, the Cymmetri platform pushes the user and group account information to be pushed to the managed application.

Regardless of the process employed, the configuration for the most part remains the same. Let us explore the reconciliation configurations on the Cymmetri Platform:

You may access the reconciliation menu by clicking on the application tile, and then clicking on the “Reconciliation” left-hand side menu.

Proceed to configure by clicking on the “+ Add New” button.

Name: Refers to the name of the Reconciliation process
Modes: FILTERED_RECONCILIATION (Currently the only mode supported by Cymmetri)
Sync Fields: The field from the user/group’s account information as available on the Cymmetri platform that must be used as a basis to identify the corresponding account on the managed application database.
Source Attributes: The field from the user/group’s account information as available on the managed application database that must be used as a basis to match with the “Sync fields”.
Status: Whether to run the reconciliation for Active/Inactive users.
Type: Some applications allow GROUP reconciliation, but most will have USER reconciliation only.

Filled Reconciliation basic configuration looks as above.

Synchronizing Scenarios and Their Corresponding Outcomes

Let us assume we are synchronizing the Cymmetri Platform with a cloud provider using email or mail attribute as the Sync field. As such users on both platforms having the same email address will be matched/un-matched.

Following are the scenarios managed by the Cymmetri platform -

User does not exist in Target system & exists in Cymmetri: This indicates a situation during a pull phase or a push phase, where the user account exists on the Cymmetri platform, but not in the managed application. This typically occurs when the users have been pulled into the Cymmetri platform, but the managed application is yet to be synchronized with these users.
User exists in Cymmetri & Target system: This indicates a situation during a pull phase or a push phase, where the user account exists on the Cymmetri platform and in the managed application, but they may or may not have the same attributes or the same values of the attributes.
User exists in Target system & does not exist in Cymmetri: This indicates a situation during a pull phase or a push phase, where the user account exists in the managed application database but not on the Cymmetri Identity platform. This typically occurs when the users have been pulled into the managed application through its backend and the users have not been centrally managed through the Cymmetri platform.

Conditions Explained:

User does not exist in Target system & exists in Cymmetri:
1. PROVISION: User is created in the target system with the attributes as present in their Cymmetri user profile.
2. IGNORE: User is not modified in either system.
3. UPDATE: Not relevant for this scenario.
4. DEPROVISION: User is removed from the Cymmetri platform to be consistent with the managed application user database.
5. UNASSIGN: Not relevant for this scenario.
6. ASSIGN: User is assigned access to this system in Cymmetri, this option may be used in the case of options like JIT being available to generate user profile in the managed application.
7. UNLINK: Not relevant for this scenario.
8. LINK: Not relevant for this scenario.
User exists in Cymmetri & Target system:
1. PROVISION: User is created in the target system with the attributes as present in their Cymmetri user profile.
2. IGNORE: User is not modified in either system.
3. UPDATE: User information from the Cymmetri Identity platform is updated using the account information from the managed application and vice versa.
4. DEPROVISION: Not relevant for this scenario.
5. UNASSIGN: Not relevant for this scenario.
6. ASSIGN: User is assigned the managed application on the Cymmetri platform in case they are already not assigned.
7. UNLINK: Not relevant for this scenario.
8. LINK: Not relevant for this scenario.
User exists in Target system & does not exist in Cymmetri:
1. PROVISION: User is created in the Cymmetri Identity platform deployment using the account information from the managed application.
2. IGNORE: User is not modified in either system.
3. UPDATE: Not relevant for this scenario.
4. DEPROVISION: User is removed from the managed application user database.
5. UNASSIGN: Not relevant for this scenario.
6. ASSIGN: Not relevant for this scenario.
7. UNLINK: Not relevant for this scenario.
8. LINK: Not relevant for this scenario.

Scheduling the reconciliation process:

Next Execution Date: This indicates the base date to start the execution date and time of the reconciliation process.
Cron Expression: This indicates the frequency with which the further reconciliation events will be run. There are 6 fields here - * * * * * * (e.g., 5 15 0 1 8 *) ; they refer to seconds, minutes, hours, days, months, and year after the first execution date.

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

}

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.

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.

Let us select “Exclusive” as the Canonicalization Method. Reasons may be explained here in the SAML reference document.

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:

Before starting the IDP Configuration the Multi Provider SSO Plugin needs to be enabled. Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/task/t_ActivateMultipleProviderSSO.html

Also the plugin is activated, we need to Configure Multi-Provider SSO properties, Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/task/t_ConfigureMultiProviderSSOProps.html

For successfully enable SSO properties you might have to configure an account recovery user, Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/concept/config-acr.html

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.

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>

API Based SSO

Cymmetri platform highly recommends adding support to either SAML 2.0 or OpenID Connect protocols owing to their well-accepted standards and to avoid vendor lock-in.

In the absence of the ability of the managed application to adopt either the SAML 2.0 or the OpenID Connect 1.0 standard, the Cymmetri platform provides with the ability to integrate simple REST API based mechanism to allow an end-user to perform Single SignOn from the Cymmetri Identity Portal

REST API based SSO Explained

Flow Description

User is assigned the application and clicks on the application tile.
The end user session is captured as the client IP address as received from the user’s browser.
The user session is validated and the Cymmetri platform checks if the end user is authorized to perform Single SignOn into the managed application.
In case, such a session token is created and the end-user is redirected as a query parameter to an endpoint on the managed application.
The endpoint on the managed application also captures the end-user’s client IP address, and sends the received token to its backend.
The managed application backend already holds the Application ID and Application password assigned to it when the API-based SSO is configured on the Cymmetri Identity platform.
The managed application backend now makes a POST call to the validate token API endpoint exposed by the Cymmetri Identity platform with the form parameters as follows -
1. app_id - Previously shared application ID
2. app_pass - Previously shared application password
3. user_ip - End-user’s client IP address as captured from the end-user’s browser
4. auth_token - the token sent to the endpoint of the managed application.
The Cymmetri platform responds back with a success message in case the application ID, application password, client IP address and the user session string match with the corresponding records in its backend.
In case of success, the managed application is expected to generate a user session for the prescribed user Id as shared in the success response message.
The Cymmetri platform responds back with a failure message in case of even one parameter mismatches from among - application ID, application password, client IP address or the user session string (shared token).
In case of failure, the managed application is expected to cancel the login attempt and show the error message shared by the Cymmetri Identity platform.

Configuration for REST API based SSO mechanism

For configuring the REST API based SSO mechanism, first select the application already added into your Cymmetri platform.

Then proceed to the SSO configuration using the “SignOn” link in the left-hand side menu bar.

Enable the Single SignOn by clicking the toggle button on the right-hand side of the page.

Now enter the application URL as below -

Application URL = <base url of the deployment>/apiSSO?applicationId=<applicationId>

Let us first copy the URL from the address bar -

The corresponding URL in my case is -

https://ssotester.cymmetri.io/application/6241c3b604c15417a91c7030/sign-on

We evaluate the following values from the URL -

Base URL of the deployment - https://ssotester.cymmetri.io
applicationId - 6241c3b604c15417a91c7030

Now we generate the Application URL as - https://ssotester.cymmetri.io/apiSSO?applicationId=6241c3b604c15417a91c7030

Let us enter this value in the Application URL text bar and click the “Save” button.

Let us proceed by selecting the radio button “API-based SSO”

Click on the dropdown “Advanced Settings (API)” to configure the API-based SSO and enter the information:

Configuration Parameters

Source app token param name - Refers to the key of the query parameter used to share the randomly generated token from the Cymmetri backend.
Application Secret - Refers to the parameter app_pass that must be sent back by the managed application to validate the token.
Target App Redirect URL - Refers to the endpoint exposed by the managed application to receive the token as a query parameter.
Token Validity - number of seconds for which the generated token is valid. The managed application must send back the token for validation within these many seconds.
Target app token param name - This is the field that the managed application must use to send back the token for validation.
External Application ID - Refers to the parameter app_id that must be sent back by the managed application to validate the token.

Assign the application to a user.

On clicking the application tile, the user is redirected to the URL below as per the configuration above.

http://localhost:4124/getToken?auth_token=<random token>

Once the token is received by the application, the application makes a POST call as indicated by the CURL request below -

curl --location --request POST 'https://ssotester.cymmetri.io/api-sso/api/sso/validateToken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'app_id=demoapps' \ --data-urlencode 'app_pass=Pras@4i1m$' \ --data-urlencode 'auth_token=<random token>' \ --data-urlencode 'user_ip=<client IP address>'

Mentioned below is a sample getToken method implemented in the managed application that wishes to use API SSO implementation. The url in the api call and the app_id and app_pass may vary from tenant to tenant

// Sample getToken method implementation in a Spring MVC Application
@RequestMapping("/getToken")
public String getToken(@RequestParam("auth_token") String auth_token, HttpServletRequest req) throws IOException {
	this.auth_token=auth_token;
	String ip=req.getRemoteAddr();
	Properties prop=new Properties();
	boolean allow_user=false;
	
	try (InputStream inputStream = getClass()
			.getClassLoader().getResourceAsStream("App.properties")) {
		
            	prop.load(inputStream);
            	String app_id=prop.getProperty("app_id");
    		String app_pass=prop.getProperty("app_pass");
    		String inputStr="app_id="+app_id+"&app_pass="+app_pass+"&user_session_string="+auth_token+"&user_ip="+ip;
    		String resp=apiCall("https://ssotester.cymmetri.io/api-sso/api/sso/validateToken", inputStr);
    		JSONObject respJSON = new JSONObject(resp);
    		allow_user=respJSON.getBoolean("allow_user");
	} catch (IOException e) {
		e.printStackTrace();
	}	
	
	if(allow_user)
	{
		return "Dashboard";
	}
	else
	{
		return "redirect:/Login.jsp";
	}
}
	
public String apiCall(String urlStr, String inputStr) throws IOException
{
	URL url = new URL(urlStr);

	// Open a connection(?) on the URL(??) and cast the response(???)
	HttpURLConnection connection = (HttpURLConnection) url.openConnection();

	connection.setDoOutput(true);
	connection.setRequestMethod("POST");
	connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
	// Now it's "open", we can set the request method, headers etc.
	connection.setRequestProperty("accept", "application/json");
	
	try(OutputStream os = connection.getOutputStream()) {
	    byte[] input = inputStr.getBytes("utf-8");
	    os.write(input, 0, input.length);			
	}
			
	StringBuilder response = new StringBuilder();
	try(BufferedReader br = new BufferedReader(
		  new InputStreamReader(connection.getInputStream(), "utf-8"))) {
		   
		    String responseLine = null;
		    while ((responseLine = br.readLine()) != null) {
		        response.append(responseLine.trim());
		    }
	}
	
	return response.toString();
}

Responses from the Validation

Success Response

JSON Response 
{
“status”:”Success”,
“allow_user”:”true”,
“user_id”:”abhishek.kulkarni”
}

Error Response

JSON Response
{
“status”:”User not verified”,
“allow_user”:”false”,
“user_id”:”abhishek.kulkarni”
}

In case of this error, “User not verified” message must be shown by the managed application. The user must not be allowed to login.

JSON Response
{
“status”:”Application not verified”,
“allow_user”:”false”,
“user_id”:”abhishek.kulkarni”
}

In case of this error, “Application not verified” message must be shown by the managed application. The user must not be allowed to login. The application configuration on the Cymmetri Identity platform and the managed application must be validation and cross-verified.