Configuring SSO Authentication

eSign Portal login can be configured to integrate with a SAML2.0 IdP.

The entire configuration of this integration can be managed with environment variables in your deployment.

Enable/Disable SSO Authentication

SSO Authentication can be easily toggled on and off with the configuration below:

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_SAML_ENABLED

false

Determines if SSO login is enabled

false
If you enable SSO SAML Authentication, the section below MUST be configured.

Integration with SAML IdP

SSO Authentication can be easily toggled on and off with the configuration below:

Minimum mandatory configurations

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_SAML_ISSUER

true

The unique identifier of the issuer of the IdP.
This must be retrieved from your IdP portal

<null>

ESIGN_SSO_SAML_IDP_URL

true

The login url of your IdP.
(endpoint to where the user is redirected to login)

<null>

ESIGN_SSO_SAML_IDP_CERTIFICATE

true

The IdP’s certificate in BASE64, required to validate the signature of the SAML Response.
@Since 1.1.1, You can add multiple IdP certificates separated by commas (,)
This must be retrieved from your IdP portal

<null>

ESIGN_SSO_SAML_RESPONSEISSUER

true

The response issuer. Must match the value present in the "Issuer" element of the SAML Response.

<null>
If your IdP provider provides multiple signer certificates, you must add all of them in ESIGN_SSO_SAML_IDP_CERTIFICATE separated by commas (,).
Otherwise the authentication will randomly fail when the IdP rotates the certificate.

Additional configurations

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_SAML_IDP_KEY

false

The IdP key in BASE64 needed to decrypt the assertions (should the IdP be configured to return encrypted assertions)

<null>

ESIGN_SSO_SAML_SP_CERTIFICATE

false

Your own certificate key in BASE64.
This is used when SAML IdP is configured to return the assertions of the response encrypted. Sets the certificate to be used when signing and encrypting the message and its assertions.

<null>

ESIGN_SSO_SAML_SP_KEY

false

Your own private key in BASE64.
This is used when SAML IdP is configured to only accept signed SAML Requests. It also requires that your own matching certificate is configured in the SAML IdP.

<null>

ESIGN_SSO_SAML_ATTR_USERNAME

false

Name of the attribute of the SAML response containing the username

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

ESIGN_SSO_SAML_ATTR_FIRSTNAME

false

Name of the attribute of the SAML response containing the user first name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

ESIGN_SSO_SAML_ATTR_LASTNAME

false

Name of the attribute of the SAML response containing the user last name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

ESIGN_SSO_SAML_ATTR_EMAIL

false

Name of the attribute of the SAML response containing the user email

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

ESIGN_SSO_SAML_ATTR_ROLES

false

Name of the attribute of the SAML response containing the user roles (ex: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups)

<null>

Advanced Configurations

Auto-Create Users

When SSO login is enabled, by default all users of your organization will have access to eSign Portal.

By default new users are automatically created and assign the default permission to view the analytics dashboard.

To change this behavior use the following configurations:

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_CREATE_USER_ENABLED

false

Automatically create a user entry in eSign Portal UAM DB when a new user successfully logs in with SSO.
(if disabled users will first need to be explicitly added in eSign Portal)

true

ESIGN_SSO_CREATE_USER_ROLES

false

Assigns new users login in with SSO the on or more default roles (comma separated)

Operator

Whitelisting Users & Roles

It is possible to add criteria to prevent anyone with an SSO login to access eSign Portal.

For this purpose, it is possible to configure a whitelist of either usernames or roles.

Whitelisting Users

Set a configuration with a list of the usernames that are authorized to access eSign Portal.
The username must match the username retrieved from the SSO response.

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_WHITELIST_USERS

false

Whitelist of users authorized to access eSign Portal (comma separated)
(leaving this empty or null means any user can log in)

<null>

Whitelisting Users

Set a configuration with a list of the roles that are authorized to access eSign Portal.

Pre-requirements:

  • The IdP must be configured to retrieve list of roles of the user in the response

  • The configuration ESIGN_SSO_SAML_ATTR_ROLES listed in Additional Configurations must be set to match the attribute of the SAML Response where the roles will be listed.

Env Variable Name Mandatory Description Default Value

ESIGN_SSO_WHITELIST_ROLES

false

Whitelist of roles the user logging-in must have to access eSign Portal (comma separated)
The names must match the values returned as roles in the SAML Response
(leaving this empty or null means any user can log in)

<null>

Example: Integration with AzureAD

Below is an example of a heml chart override (overrides.yaml) configured to use AzureAD SAML.

conf:
env:
  custom:
    - name: ESIGN_SERVER_URL
      value: https://my-esign.com
    - name: ESIGN_SERVER_USERNAME
      value: admin
    - name: ESIGN_SERVER_PASSWORD
      value: my_admin_pass
    - name: ESIGN_SSO_SAML_ENABLED
      value: true (1)
  customFromCredentialSecret:
    - name: ESIGN_SSO_SAML_ISSUER
      key: ssoSamlIssuer
      value: [your-app-id] (2)
    - name: ESIGN_SSO_SAML_IDP_URL
      key: ssoSamlIdpUrl
      value: https://login.microsoftonline.com/[your-tenant-id]/saml2 (3)
    - name: ESIGN_SSO_SAML_IDP_CERTIFICATE
      key: ssoSamlIdpCert
      value: MIIDBTCCAe2gAwIBAgIQGQ6YG6NleJxJGDRAwAd... (4)
    - name: ESIGN_SSO_SAML_RESPONSEISSUER
      key: ssoSamlRespIssuer
      value: https://sts.windows.net/[your-tenant-id]/ (5)
1 Enables SSO SAML authentication
2 Your Azure Application (client) ID
3 Your Azure Tenant ID
4 Certificate of your Azure SAML provider. Can usually be retreived from:
https ://login.microsoftonline.com/[your-tenant-id]/federationmetadata/2007-06/federationmetadata.xml
saml azuread cert

You can check your Tenant ID and Application ID in Azure Portal

saml azuread