Introduction to SAML authentication

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.

• AD FS
• Auth0
• Azure AD
• Okta
• PingOne

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

• Keycloak
• PingFederate

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:

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.

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 ofhttps://{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 ofhttps://{account}.{your-flex-deployment.com}/login/saml/metadata/certificate. This will download or present a.crtfile.
   • 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 theds:X509Certificatenode 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:

• Chrome developer mode
• SAML Message Decoder

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.

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.