Configuring SSO Authentication

@Since 1.11.2

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

1. Enable SAML Authentication on eSign

First we need to enable SAML authentication in eSign (this addin is used for login into Monitoring Portal, but will also become available should you wish to access eSign documents using SAML SSO).

If your eSign solution already has SAML configured you can skip this step.

From esign-home directory, open config/esign.config and add the following entries in the properties section:

Modified esign.config to enable SAML SSO provider

{
	...

	"properties": {

		...

		"authentication.saml.enabled" : true, (1)
		"extensions.saml-generic-provider.params.issuer" : "...", (2)
		"extensions.saml-generic-provider.params.idp.url" : "...", (3)
		"extensions.saml-generic-provider.params.idp.cert" : "..." (4)
	}
}

1	Enables the SAML addin
2	The unique identifier of the issuer of the IdP. This must be retrieved from your IdP portal.
3	The login url of your IdP. Endpoint to where the user is redirected to login.
4	The IdP’s certificate in BASE64, required to validate the signature of the SAML Response. This must be retrieved from your IdP portal.

In property extensions.saml-generic-provider.params.idp.cert you can add multiple IdP certificates separated by commas (,)

2. Enable SSO in Monitoring Portal

From esign-home directory, open config/esign.config and add the following entries in the properties section:

Modified esign.config to enable SSO

{
	...

	"properties": {

		...

		"monitor.sso.enabled": true (1)
	}
}

1	Enables the option to authenticate with SSO in the Monitoring Portal

3. Whitlisting Users with access to Monitoring Portal

At this point everything should be ready to log into Monitoring Portal using SSO.

However, we still need to specify which users of your domain have access to the portal (otherwise everyone in your organization would be able to access it).

If you are using eSign’s default authorization addin (enabled by default) you can whitelist the users usign esign.config.

From esign-home directory, open config/esign.config and add/edit the entry security.local.users in the properties section:

{
	...
	"properties": {
		...

		"security.local.users": [
			...

			"user1@mydomain=,monitor",
			"user2@mydomain=,monitor"
		]
	}
}

For each user you want to whitelist, add a string entry to the security.local.users property with the following format:

"[username]=,[role_to_assign]" (the comma is required after the = sign)

The username must match the username returned by the IdP authentication, which usually is username@domain.
The defaut role required to access Monitoring Portal with read/write permissions is monitor.

Instead of assigning default role monitor (which have read/write access) you can create your own eSign role with your own cherry picked permissions, for instance read-only permissions.

4. Restart eSign

After all changes are applied you must restart your eSign instance for changes to take affect.

After restarting check the container logs to make sure that no error occurred due to any misconfiguration.

After the restart, when you attempt to access the Monitoring Portal a new login option should be available called "Federated Login".

Example: Integration with AzureAD

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

{
	...

	"properties": {

		...

		"security.local.users": [

			...

			"NB18140@novabase.pt=,monitor" (1)
		],

		"monitor.sso.enabled": true, (2)
		"authentication.saml.enabled" : true, (3)
		"extensions.saml-generic-provider.params.issuer" : "[your-app-id]", (4)
		"extensions.saml-generic-provider.params.idp.url" : "https://login.microsoftonline.com/[your-tenant-id]/saml2", (5)
		"extensions.saml-generic-provider.params.idp.cert" : "MIIC/TCCAeWgAwIBAgIIUd7j..." (6)
	}
}

1	Added permissions for user `NB18140@novabase.pt` to access monitor portal (the comma is required after the = sign)
2	Enables SSO in Monitoring Portal
3	Enables SSO SAML authentication
4	Your Azure Application (client) ID
5	Your Azure Tenant ID
6	Certificate of your Azure SAML provider. Can usually be retreived from: https ://login.microsoftonline.com/[your-tenant-id]/federationmetadata/2007-06/federationmetadata.xml

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

If your federationmetadata.xml provides multiple signer certificates, you must add all of them to the extensions.saml-generic-provider.params.idp.cert property separated by commas (,).
Otherwise, the SAML response signature validation will fail (always or randomly).

Troubleshooting

Federated Login option not available

The most common reasons for the Federated Login option not being available are:

Property monitor.sso.enabled was not set to true in esign.config.
Solution: Review your esign.config file.
Property authentication.saml.enabled was not set to true in esign.config.
Solution: Review your esign.config file.
Errors occurred when eSign started, related to the configuration of the SAML provider.
Solution: Check eSign logs for exceptions during boot.

Can authenticate successfully in the IdP but get a "Session Unauthorized" message

The most common cause is that, even though the login was successful, the user does not have permissions to access Monitoring Portal.

Check if the user is correctly add to security.local.users in esign.config, as per Whitelisting configuration.

If this is the cause, eSign logs will usually show logs like these:

ERROR 2023-12-20 15:28:59.490 NB18140@novabase.pt  ad3d3b54-f6e0-4f56-85c7-a50a041940e2 novabase.connect.paperless.esign.web.services.business.errors.RestErrorHandler - Service call returned an unexpected error.
org.apache.shiro.authz.UnauthorizedException: Subject does not have permission [monitor:read:status]

Can authenticate successfully in the IdP but I am redirected to an error page with 401

The most common cause is that you did not configured in eSign the correct certificate of your IdP.

Please review your configurations to make sure that this property are properly configured for your IdP:

extensions.saml-generic-provider.params.idp.cert

If this is the cause, eSign logs will usually show logs like these:

ERROR 2023-12-20 15:55:10.085    novabase.connect.paperless.esign.saml.providers.generic.GenericSAML2Provider - Failed to validate idp response:
novabase.connect.paperless.esign.exceptions.eSignException: Failed to validate idp response:
  ...
Caused by: org.opensaml.xmlsec.signature.support.SignatureException: Signature cryptographic validation not successful

If your IdP provider provides multiple signer certificates, you must add all of them to the extensions.saml-generic-provider.params.idp.cert property separated by commas (,).

Clicking on Federated Login redirects me to an error page of the IdP

The most common cause is that you did not set valid configurations in SAML configuration.

Please review your configurations to make sure that these properties are properly configured for your IdP:

extensions.saml-generic-provider.params.issuer
extensions.saml-generic-provider.params.idp.url