Single Sign-On (SSO)

Single Sign-on (SSO) occurs when a user logs in to one application and is then signed in to other applications automatically, regardless of the platform, technology, or domain the user is using. The user signs in only one time, hence the name of the feature (Single Sign-on). CargoDocs supports SSO through SAML 2.0.

📘

SSO using SAML 2.0

SAML 2.0 (Security Assertion Markup Language) is an open standard created to provide cross-domain single sign-on (SSO). In other words, it allows a user to authenticate in a system and gain access to another system by providing proof of their authentication.

essDOCS SSO Workflow

The setup process will work as follows.

1. Upon request from Partners, essDOCS will provide all SSO configurations as needed by the Identity Providers.
2. The consumer configures the Identity Providers and provides the .xml federated metadata file.
3. essDOCS updates the metadata file.
4. SSO testing initiates.

📘

SSO Testing Environments

Each client will be provided a seperate UAT & Production configurations.

Setting up SAMP IDP (Provided by essDOCS)

Three elemental properties must be configured per the settings provided by essDOCS.

Aspect	Background Information	Requirement/Scope/Setting
Entity ID	SSO Service provider identifier	urn:amazon:cognito:sp:eu-west-1_69KUpZjtY
Reply URL	The Reply URL is where the application expects to receive the authentication token. This is also referred to as "Assertion Consumer Service" within SML.	https://cargodocs-test.auth.eu-west-1.amazoncognito.com/saml2/idpresponse
Sign On URL	URL where the whole sign-in process starts.	https://cargodocs-test.auth.eu-west-1.amazoncognito.com/oauth2/authorize?client_id=2l132pl0b6n04p6lcunlheccbv&response_type=code&scope=email+openid+phone&redirect_uri=https://cargodocs-test/sso/saml/{company_UUID}

📘

company_UUID

The {company1_UUID} parameter in case of partner performing the SSO will be replaced by a certain companyID for which the partner is performing certain actions.

Partner Performing SSO on behalf of Customer

Partner usually operates essDOCS on behalf of a customer that falls under their contracts. The Sign On URL as indicated in the above section, requires **customerId**. In the Partners case, the partner needs to retrieve the**customerId** against which the SSO needs to be consumed.

The relevant **customerId** can be retrieved using Get Partner Customer Ids by providing a security token. Here is what the result looks like.

[
  {
    "customerId": "df192c5e-701e-4e58-9b8d-d0daf7404109",
    "customerName": "Customer 28JJh",
    "bdt": false,
    "signatures": [
      {
        "signatureId": "f4677537-e845-4c67-964a-ad1dd716d4f8",
        "signatureText": "Signed by ${signedByEmployeeName} on Behalf of  EXPORTER"
      }
    ]
  }
]

The customerId retrieved above can be used over the Sign On URL as shown below.

https://cargodocs-test.auth.eu-west-1.amazoncognito.com/oauth2/authorize?client_id=2l132pl0b6n04p6lcunlheccbv&response_type=code&scope=email+openid+phone&redirect_uri=https://cargodocs-test/sso/saml/df192c5e-701e-4e58-9b8d-d0daf7404109

Migration Plan

There are scenarios based on the implementation to migrate the users to the SSO based on a certain approach. Here are some elemental approaches to SSO Migration.

Aspect	Background Information	Requirement/Scope/Setting
Greenfields	This aspect relates to a new setup where all users will join the organization SSO for the first time.	No migration is needed as all SSO users will be new.
Big Bang	The entire user base needs to be migrated over to the SSO.	All users are migrated to SSO in a single go. This method is widely adopted for SSO migration.
Phased/Graded Rollout	Majorly used for wide-scale migration of users across the organization.	The Phased rollout approach enables the user base to shift to the SSO batch by batch for large-scale in-use systems.

essDOCS SSO Authentication

SSO Authentication involves validating user credentials, establishing the user's identity, and gaining access to the essDOCS platform.

📘

SAML

Security Access Markup Language (SAML) is an open standard that encodes text into machine language and enables the exchange of identification information. It has become one of the core standards for SSO and is used to help application providers ensure their authentication requests are appropriate. SAML 2.0 is specifically optimized for use in web applications, which enables information to be transmitted through a web browser

Aspect	Background Information	Requirement/Scope/Setting
Identity Provider & Protocol	The Identity Provider is an endpoint with which the external applications will relate. SAML, OAuth, WS-Fed ": "Aspect", "h-1": "Background, Open ID Connect, etc.	Configured with the federated metadata. XML file exported from the identity provider SAML.
NameID Value & Format	What is the person identifier to be used for user authentication (unique application ID, email address, SAM Account name, other, or if a combination of identifiers used)	NameID Value will be the user's email address and the format unspecified.
Claims/Permission Required	User information is required. - These claims must be configured exactly as mentioned, respecting capital letters and word spacing.	- Email - First Name - Last Name - Phone Number

essDOCS SSO Authorization

Against a successful authentication, Authorization is the process by which a third party is granted permission to access information or perform an action associated with another entity. essDOCS handles the authorization by providing relevant details against the logged-in user to the consumer accordingly.

Authorization Management falls under two different types of applications, as below.

Wholly Application Managed

User role details exist in the application database, where the administrator manages the entire authorization process.

AD Managed

User roles will be internally created and managed in Active Directory [AD]. These groups will be either synchronized to the application database or passed through as claims to allow access control within the application. In the case of the AD Managed approach, the application owner is responsible for requesting the local service desk to create an Active Directory Security Group and specifying the owner to approve subsequent membership of the required users. All future user creations shall go through a Service Desk request. SSO team will not be involved in this process.

Aspect	Background Information	Requirement/Scope/Setting
Authorization Management	The authorization process depends on the selected approach, i.e., Wholly Application Managed or the AD Managed.	Based on the user details collected, the SSO configurations go accordingly.

SSO Provisioning

SSO provisioning assigns permissions based on roles and event changes throughout an account’s lifecycle. Provisioning (and de-provisioning) grants, modifies, or revokes access and privileges based on triggers. User provisioning can be automated by integrating the user directory, Active Directory, and a connector tool, such as the open-standard System for Cross-domain Identity Management. Based on the requirement, four commonly used Provisioning are available.

Just-in-Time Provisioning

The application creates a user enters the instant a user logs into the system based on the information presented by Azure AD.

Automatic Provisioning

The application has a web API that supports SCIM (System for Cross-domain Identity Management) API pointing to https://tools.ietf.org/html/draft/ietf-scm-api-19. Azure AD will automatically synchronize users into it and remove the users as required.

Custom Provisioning

A script, tool, or process is created to remove them when they leave the organization.

Manual Provisioning

Administrators manually create users in the application before they log in and remove them when they leave.

Aspect	Background Information	Requirement/Scope/Setting
Provisioning	The service owner is responsible for building processes by setting up the required provisioning out of the four described above.	Based on the selected provisioning, the scope of provisioning is managed accordingly.

essDOCS SSO Implementation

• Discovery URL
• Client ID
• Client Secret

These details are incorporated into the SSO configurations. The Service Provider Sign-On URL is shared with the client, pointing to the client's authentication URL for SAML or OIDC-based SSO purposes as below.

HTTP

https://test-essdatabridge-com.auth.eu-west-1.amazoncognito.com/login?client_id=4tvd6ur1105h8lgkpl9rmfqhu1&response_type=code&scope=email+openid+phone+profile&redirect_uri=https://test.essdatabridge.com/sso/saml/a2ad8037-8242-49a7-82cb-a2e1fdea9048

OIDC Based SSO Implementation

OIDC based SSO integration requires the consume to send their Identity provider. The OIDC provider (generally called the OpenID Provider or Identity Provider or IdP) performs user authentication, user consent, and token issuance. The required parameters in IdP are:

• Discovery URL
• Client ID
• Client Secret

Based on the provided parameters by the consumer, essDOCS team will share the redirect URL as follow.

HTTP

https://test-essdatabridge-com.auth.eu-west-1.amazoncognito.com/oauth2/idpresponse