Exponea Single Sign-On (SAML based SSO)

This feature is currently available in Beta version

Private/Exclusive Instance required

For large enterprises, it is difficult to manage employee access, permissions, and resources in multiple places. We provide our Exponea SSO to solve the problem by communicating with your identity provider.

When logging in, Single Sign On (SSO) removes the need to type in passwords as your identity will be provided and checked to provide access only to authorized users. The main benefit is that SSO prevents the risks created by poor password management or the risks of phishing. Moreover, it provides centralized access management which allows you to have full control of who has access to the application.

This works by propagating user groups with a SAML 2.0 message which matches the groups with permissions configured in Exponea. This ensures authenticated and authorized access to Exponea for both internal and external users. Federated Identity Management works with all identity providers that support the SAML 2.0 standard.

For SSO we use Security Assertion Markup Language (SAML) which is a general standard for logging users into the applications. SSO transfers the user’s identity from one place (the identity provider) to another (Exponea). This is done through an exchange of digitally signed XML documents.

The flow in more detail:

  1. The user is logged into a system that acts as an identity provider and wants to sign in to Exponea app
  2. Exponea app identifies the user’s origin (by application subdomain and user IP address) and redirects the user back to the identity provider, asking for authentication
  3. The user either has an existing active browser session with the identity provider or establishes one by logging into the identity provider
  4. The identity provider builds the authentication response in the form of an XML-document containing the user’s username or email address and groups and permissions, signs it using an X.509 certificate, and posts this information to Exponea
  5. Exponea retrieves the authentication response and validates it using the certificate fingerprint
  6. The identity of the user is established and the user is provided with access

As an example, James is trying to log into the Exponea Application. When he logs in he is asked to confirm his identity through an additional security layer. Once Exponea has identified James, he is granted access.

Federated Identity Management for SSO

Required configuration parameters

  • Entity ID/Issuer ID - a unique identifier of SSO connection (ie sso1).
  • Login URL - the URL path of where to redirect for login. Authentication Request Message target URL. HTTP-Redirect binding only.
  • Identity provider certificate - X.509 certificate. Used for signing/encrypting messages, assertions or metadata. Multiple certificates can be provided.
    *Metadata file or metadata endpoint to fetch the whole configuration.

Other requirements

  • Exponea requires assertions to be signed (<saml:Assertion> elements)
  • Every SAML request must include following attributes:
    • username - a unique user identifier (If not provided, a user won't be created in application)
    • email - user’s email address (If not provided, the user won't be created in application)
    • permissions_v1 (If not provided, the user will have no access)
  • The NameId parameter of the SAML request has to match the value in the username field

What Exponea provides

Exponea (service provider) provides a metadata file/endpoint. The ServiceProvider metadata endpoint/file contains:

  • entityId
  • X.509 certificates for signing/encrypting messages and assertions
  • AssertionConsumerService endpoint - “login endpoint”
  • AttributeConsumingService configuration - required attributes
  • Organization and contact person details

Formatting data in SAML

Required: username

Username might be string, number basically identifier of the user in your system.

<saml:AttributeStatement>
  <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">johnsmith</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Required: email

The email address of the user.

<saml:AttributeStatement>
  <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">[email protected]</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Required: permissions

Permissions are versioned where v{number} is the number of versions. The first version of permissions is labeled as “permissions_v1”.

You have to follow this format of permissions:

project.<project_slug>.<permission>.<access>
    - for project-level access
account.<account_slug>.<permission>.<access>
    - for account-level access

Project slug can be found in the URL, while you are logged in the application (example: https://app.exponea.com/p/exponea-demo-e-shop/home => project slug = exponea-demo-e-shop)

Account slug is not available in an interface right now.

Example:
The user has access to Exponea project with the slug “project1”:

<saml:AttributeStatement>
<saml:Attribute Name="permissions_v1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string"xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.analyses.write</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.campaigns.execute</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.export.true</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.project.admin</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>

In a case of multi-value permissions like campaigns “Read, Write, Execute” you have to specify the highest value of permissions as follows:

  • Read,Write,Execute => execute
  • Read,Write => write
  • Read => read

Optional: User attributes

User attributes are not required, but it is highly recommended to provide this information for better user experience in application.

List of attributes: first_name, last_name, phone

<saml:AttributeStatement>
  <saml:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">John</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Doe</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="phone" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">+421900123456</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

📘

All users will be created as a “regular user” type. Instance Manager user types are not supported via SSO.

Migration phase

The migration phase consists of 5 steps. The phase should offer comfortable testing of SSO configuration, and there should be no outage on the instance - existing users should not be kicked off when SSO is enabled.

  1. Username & SSO (Testing SSO configuration)
  • Users can log into APP at the same time with SSO, Username, Social login. But once you log in with SSO and User with the same username exists already in the application, this user is automatically replaced. This user from this moment can only log in only via SSO.
  • Superadmins are not automatically replaced. First of all, you need to delete the super admin and then login via SSO
  1. Disabled invitation & registrations (transition phase)
  • I can still log in with Username & SSO at the same time
  • All invitations to an Accounts/Projects are disabled.
  • All registration of user through Administration is disabled
  1. SSO only (Final phase)
  • You can log in only with SSO

Configuration

invisible_to_users - SAML2 is configured, but not visible to users (no Login with SSO button).
as_additional_method - SAML2 is available as an additional login method. The user can log in with all methods interchangeably.
enforced_once_uses - SAML2 enabled simultaneously with other login methods. Invitations still enabled. Once a user logs in via SAML2, they cannot log in with any other methods.
enforced_for_new_users - SAML2 required for new users, existing users can log in through other methods. Invitations are disabled.
enforced_for_everyone - SAML2 login only. No invitations or other login methods allowed.

Full list of possible permission settings

If a user has a permission with a default value, this does not need to be defined explicitly.

🚧

Stand-alone roles

Each user must have at least one stand-alone role to be able to access a project. The list of permissions below contains the full list of roles that can be assigned via SSO. All of them are stand-alone roles except for Personal Data Viewer which should be assigned along with another stand-alone role(s).

Account scope

Attribute value format: account.<account-slug>.<permission>.<access>

Permission [permission].[access]

Exponea role

analyses.read

Analyses Viewer

analyses.write

Analyses Editor

campaigns.read

Campaigns Viewer

campaigns.write

Campaigns Editor

campaigns.execute

Campaigns Admin

project.user

Project User (Legacy)

project.developer

Project Developer

project.admin

Project Admin

export.true

Customer Data Exporter

analyses.read AND export.true

Analyses Exporter

account.user

Account User (Legacy)

account.admin

Account Admin

data.personal

Personal Data Viewer

project.admin AND data.personal AND export.true

Exports Admin

Project scope

Attribute value format: project.<project-slug>.<permission>.<access>

Permission [permission].[access]

Exponea role

analyses.read

Analyses Viewer

analyses.write

Analyses Editor

campaigns.read

Campaigns Viewer

campaigns.write

Campaigns Editor

campaigns.execute

Campaigns Admin

project.user

Project User (Legacy)

project.developer

Project Developer

project.admin

Project Admin

export.true

Customer Data Exporter

analyses.read AND export.true

Analyses Exporter

data.personal

Personal Data Viewer

project.admin AND data.personal AND export.true

Exports Admin

📘

Instance scope permissions are not supported via SSO.

Updated 4 months ago

Exponea Single Sign-On (SAML based SSO)


This feature is currently available in Beta version

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


We rely on cookies

to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

Manage cookies
Accept & close

Cookies preferences

Accept & close
Back