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)

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. super admin/instance admin 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
  2. 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
  3. 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.

account.<account-slug>.<permission>.<access>

Permission
Possible <access> values
Default value

analyses

none/read/write

none

campaigns

none/read/write/execute

none

project

user/developer/admin

user

features

basic/beta

basic

export

none/true

none

account

user/admin

user

data

public/personal

public

project.<project-slug>.<permission>.<access>

Permission
Possible <access> values
Default value

analyses

none/read/write

none

campaigns

none/read/write/execute

none

project

user/developer/admin

user

features

basic/beta

basic

export

none/true

none

data

public/personal

public

Updated 21 days 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.