Activate the SSO service in Paradigm

Single Sign-On (SSO) is a feature that allows users to connect to multiple applications using the same credentials, without having to re-enter their Paradigm username and password.

In this article, we'll explain how to enable SSO functionality in Paradigm for a global and per-company instance via Paradigm admin.

There are 4 steps to setting up SSO:

1. Activate the SSO service for the entire Paradigm instance
2. Retrieving information from the Identity Provider (IdP)
3. SSO configuration on the Paradigm Service Provider (SP) side
4. SSO configuration on identity provider side

Step 1: Enable SSO for the full Paradigm instance

To activate SSO, you must go to the page Config Key from the administration and configure the following two fields:

1. is_sso_on: True
   For SSO to be active, the value of this field must be equal to True (pay attention to case). If this value is False, SSO is disabled for the entire instance.
2. default_sso_permissions_for_company_admins: This field allows you to define whether by default "Company admin" type users can configure their company's SSO or not. If the value is True (pay attention to case), then by default the "company admin" can configure SSO. If this box is False, then by default "company admin" cannot configure their company's SSO.

Step 2: Retrieve Identity Provider Information

To continue, the following information from your identity provider is required:

• Entity ID: The ID used to identify your identity provider.

You can then either retrieve:

• SSO URL: The URL of your identity provider to which Paradigm should send its SAML requests.
• Certificate: The certificate allowing a secure exchange of information between the SP and the IdP.

Or:

• Metadata URL: url redirecting to the configuration of your Identity Provider including the SSO URL and the Certificate.

Step 3: Paradigm Service Provider Side SSO Configuration

For each company, the implementation of SSO requires the creation of a Social Application.

To create a new SSO configuration, go to Paradigm administration > Authentication > Social Applications.

Finally click on add and fill in the fields with the following information:

• Provider : SAML
• Provider ID : You should enter the Entity ID of your Identity Provider retrieved in step 2.
  (ex: https://accounts.google.com/o/saml2?idpid=F482izkcy)
• Name : Name that will appear in the admin. 
  (ex: My SAML Configuration)
• Client ID: Unique identifier of the SAML configuration across Paradigm.
  This field is automatically populated with a UUID.
  Cannot be modified by company admins.
  (ex: 3fde0dd3-6457-489a-88e3-cdf413c48a62)
• Settings : Additional information in json format.
  Accepted structures are shown below.
• Company : Allows you to define which company you wish to link this SSO configuration to.

Social application settings - With SSO URL and Certificate

{
  "sp": {
    "entity_id": "paradigm-mycompany-saml-config"
  }, 
  "idp": {
    "entity_id": "<idp_entity_id>",
    "sso_url": "<idp_sso_url>", 
    "x509cert": "<idp_certificate>"
  }
}

• the Entity ID of the desired service provider for the Paradigm instance (ex: paradigm-mycompany-saml-config)
• the SSO URL of your identity provider retrieved in step 2,
• the Entity ID of the identity provider retrieved in step 2,
• the identity provider certificate retrieved in step 2.

Social application settings - With Metadata URL

{
  "sp": {
    "entity_id": "paradigm-mycompany-saml-config"
  }, 
  "idp": {
    "entity_id": "<idp_entity_id>",
    "metadata_url": "<idp_metadata_url>"
  }
}

• the Entity ID of the desired service provider for the Paradigm instance (ex: paradigm-mycompany-saml-config)
• the Entity ID of the identity provider retrieved in step 2,
• the Metadata URL retrieved in step 2.

Step 4: Configure SSO on the identity provider side

To configure SSO for Paradigm on the side of your identity provider, 2 ways are possible:

• Par un fichier XML de métadonnées
• Par une configuration manuelle

Configuration via metadata XML file

If your identity provider requires a metadata XML file to be configured, you can retrieve this file at the following URL:

https://<domain_name>/auth/saml/<client_id>/metadata/

with:

• <domain_name> the domain name of the Paradigm instance you are using.
  For our SaaS offer, this field will therefore be paradigm.lighton.ai.
• <client_id> the ID defined in Paradigm and allowing you to know which SAML configuration to use (because there can be one SAML configuration per company)
  

A metadata example could be: https://paradigm.lighton.ai/auth/saml/3fde0dd3-6457-489a-88e3-cdf413c48a62/metadata/ 

Manual configuration

If your Identity Provider requires manual configuration, you can user the following information:

• ACS URL: https://<nom_de_domaine>/auth/saml/<id_client>/acs/
  ACS URL example: https://paradigm.lighton.ai/auth/saml/3fde0dd3-6457-489a-88e3-cdf413c48a62/acs/
• Entity ID: Entity ID of the service provider defined in the SAML configuration settings
  (ex: paradigm-mycompany-saml-config)
• Name ID: Set this field to "Primary Email"

Attribute matching

The email address of your users must be included in the attributes of your SAML responses.

The following application attributes are supported by default in Paradigm to map the user email:

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

• urn:oid:0.9.2342.19200300.100.1.3

If those default keys do not fit your Identity Provider configuration, you can enter whatever key fits your needs and specify it in the Social Application settings as shown below:

{
  "sp": {
    ...
  }, 
  "idp": {
    ...
  },
  "attribute_mapping": {
    "email": "<your_email_key>"
  }
}

The value of <your_email_key> in your SAML responses will then be mapped to the Paradigm users email.

User access

You can then assign this SAML configuration to the user group of your choice.

User journey to log in via SSO

1. The user must go to the authentication page https://paradigm.lighton.ai/login.
2. The user must enter their email address and click on "Connect" and follow the route of their supplier (if the user wants to switch to login/password mode, they can click on the dedicated button).

Help setting up your SSO from your provider

As an example, here are different guides for configuring your SSO:

• Google
• Microsoft

Debugging advice

If you were to face any issue with your SSO configuration, we advice to use a debugging tool such as SAML-tracer which can give you information about the SAML requests and responses between Paradigm and your Identity Provider.

SAML-tracer extension links:

• Chrome extension
• Firefox extension

1. First, make sure your SAML requests are sent to your Identity Provider
2. Then, you can verify that the SAML response includes a NameID in the Subject
3. Finally, check that the user email is correctly included in the SAML response with an expected attribute name (either the default ones or the one you defined in the "attribute_mapping" setting)

We hope this article helped you understand how to enable SSO functionality in Paradigm. If you have any questions or problems, do not hesitate to contact us.