Introduction to SAML authentication

Benjamin KAHANE
  • Updated

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between service providers and identity providers.
SAML transactions use Extensible Markup Language (XML) for standardized communications between the identity provider (IdP) and service providers (SPs). SAML allows you to log into multiple applications, using the same login credentials.

Dalet Flex has been fully tested against a number of IdPs, and details of how to configure Flex SSO using each of these is provided in the corresponding documentation sub-pages.

In addition to the above, we have also successfully performed basic validation using the following SAML IdPs for Flex.

Please contact your Dalet representative at the earliest opportunity if you intend to integrate with a different IdP.


Other IdPs may work with Flex "out-of-the-box" if they are fully compliant with the SAML standards; however, in some
cases, development work may be required.


IdP certificates

If using an IdP URL for dynamic IdP metadata retrieval, rather than providing static IdP metadata XML to Flex, then the Flex Login App must be able to verify the corresponding IdP certificate. As such, this certificate must be valid, in-date, and signed by a recognised certificate authority. If the IdP uses a self-signed certificate, please contact your Dalet Flex representative for details of how to make your own self-signed certificates available to and trusted by Flex services.


SAML Authentication Flow

The following diagram provides a high level overview of the SAML authentication flow:

 

mceclip1.png


Configuring SAML

SAML authentication must be configured from both sides: in the external IdP, and in Dalet Flex Core.

The configuration for each IdP varies, but in all cases:

  • they must use SAML 2.0, which refers to a number of standard concepts;
  • you will need to obtain certain information from Flex, with which the IdP can be configured.

 

SSO URL

A Single Sign-On URL is a url that an IdP calls back upon authentication success.
This takes a form like: https://{account}.{your-flex-deployment.com}/login/saml/SSO.

 

Audience Restriction

An audience restriction is used to identify a specific app.
Unless customised through Consul KVs, this takes the following value: urn:ooyala:flex:flex-login-app.

 

Default Relay State

For authentication initiated at the IdP (rather than on Flex) this provides the default redirect destination to which users will be routed upon successful authentication.
This could be like https://{account}.{your-flex-deployment.com} for Flex Core, or like
https://{account}.{your-flex-deployment.com}/fmp/index/ for FlexMAM.

 

User Attributes And Claims

Each IdP needs to configure below list of user attributes & claims:

Attribute Names Required or Optional?
login Optional since Flex 2022.11.x
email Required
firstName Required
lastName Required
flexAccountUuid Required
externalUniqueUserId Optional since Flex 2024.7.x


Note: By default, Flex users will be created with the email as their username. The username can optionally be overridden by passing the login attribute.

 

Obtain information from Flex

  1. Log into the Flex account to which you wish to link the IdP.
  2. Identify and take note of the UUID of this Flex account. This can be found on the corresponding Account Details page in Flex Core.
  3. Obtain Flex’s SAML metadata, from your environment’s equivalent of https://{account}.{your-flex-deployment.com}/login/saml/metadata. This will download or present an XML file that can be used to configure IdP either by either uploading SP metadata or through manual configuration.
  4. Obtain Flex’s public key certificate.
    • If running Flex 2022.9.0 or later, then visit your environment’s equivalent https://{account}.{your-flex-deployment.com}/login/saml/metadata/certificate. This will download or present a .crt file.
    • If running Flex 2022.8.0 or earlier, then you’ll need to construct the certificate file manually yourself. After performing step 3 above, look for the ds:X509Certificate node in downloaded XML file and copy the public key.
  5. Regardless of which Flex version your environment is running, the CRT file you end up with should look something like this:
    -----BEGIN CERTIFICATE-----
MIIDUjCCAjqgAwIBAgIEUOLIQTANBgkqhkiG9w0BAQUFADBrMQswCQYDVQQGEwJGSTEQMA4GA1UE
  ... <truncated> ...
bHwSoBy5hLPNALaEUoa5zPDwlixwRjFQTc5XXaRpgIjy/2gsL8+Y5QRhyXnLqgO67BlLYW/GuHE=
-----END CERTIFICATE-----


Debugging SAML login issues

If debugging SAML login issues, two extra tools will be useful:

Kibana will also contain messages for any issues. Look for messages being generated by the flex-login-app and the flex-authentication-service in Kibana for extra information on any issues.

 

Reset Password Event Handler

This depends on the Flex version. 

From Flex 2021.12 up to2025.05 the filter expression to use is

#{event.user.userType != "EXTERNAL"}

 

From Flex installation (2025.6) the filter expression in use is...

#{event.user.userType != "External"}

For more information on Spring Expressions for use in Event filters, see Spring Expressions.

 

 Legacy Flex using EL and not SpEL use the expression:

${event.mioObject.entity.authenticationProvider.displayName != "External"}


SAML in older versions of Flex

  1. Prior to version 2019.7.0, each individual Flex application managed login directly, rather than through the unified Flex Login App. There are a few differences when configuring SAML on such older versions of Flex, namely:
    - Host-based URL style is used, i.e. https://review.{your-flex-deployment.com}/review/a/{account} instead of https://{account}.{your-flex-deployment.com}/review/
    - Each individual application must be configured separately, with different SSO URLs, audience restrictions, etc.
    - For example, for the Review application, this would be: https://review.{your-flex-deployment.com}/review/saml/SSO and urn:ooyala:flex:flex-reviewer-app.
  2. Prior to version 2020.1.0, Flex could not be configured with static IdP metadata XML. On such older versions of Flex, a URL must be provided for dynamic IdP metadata retrieval.
  3. Prior to version 2021.1.0, where using dynamic IdP metadata retrieval, even IdP certificates which are signed by a recognised certificate authority need to be explicitly loaded into Flex. In such cases, please contact your Dalet Flex representative as described above. The exceptions are Okta and Auth0 IdPs, which do not require this step.

Related articles

Comments

5 comments

Date Votes

Please sign in to leave a comment.

Powered by Zendesk