SAML 2.0 Configuration Guide¶

Last updated on Aug 27 2024.

Introduction¶

This document describes the functionality and configuration of the Security Assertion Markup Language 2.0 (SAML 2.0) Authentication in Inuvika OVD.

SAML 2.0 is a version of the SAML standard used in the exchange of authentication and authorization data between security domains. It is a protocol that is XML-based and uses security tokens containing assertions to pass information about a principal (usually an end user). The information is passed between a SAML authority (an Identity Provider) and a SAML consumer (a Service Provider). SAML 2.0 enables web-based authentication and authorization scenarios. SAML 2.0 can be used for cross-domain single sign-on (SSO) to help reduce the administrative overhead involved in distributing multiple authentication tokens to the user.

Prerequisites¶

The OVD Session Manager and a valid subscription key must be installed in order to enable the functionality to support SAML 2.0 authentication.

OVD SAML Functionality¶

OVD acts as a Service Provider as described in the SAML 2.0 specification. OVD supports both Identity Provider originated SAML Authentication Assertions and Service Provider originated SAML Authentication Requests.

OVD does not provide support for a SAML Logout.

SAML and SINGLE SIGN-ON¶

OVD provides support for the SSO scenario described in the SAML 2.0 Specification. As with standard users, users authenticated using SAML must still be created within OVD or a directory such as LDAP that is integrated with OVD. In this case the user password is not relevant since the Identity Provider is responsible for authentication, so a random password may be used. Users must also be assigned to User Groups in the normal way so that OVD can manage application publications for that user. The Identity Provider must be configured to provide the identity of the OVD user in the NameID element within the Subject element of the SAML Assertion. OVD will use this value to identify the corresponding OVD User and create an OVD session using the user profile configuration parameters. For Example, in the following snippet from a SAML Assertion, foobar@example.com is the username of the user defined in OVD:

<saml:Subject>
  <saml:NameID
    SPNameQualifier=""
    Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">foobar@example.com</saml:NameID>
  <saml:SubjectConfirmation
    Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
  <saml:SubjectConfirmationData
    NotOnOrAfter="2014-06-07T22:15:22Z"
    Recipient="https://mydomain.ovd.com/ovd"/>
  </saml:SubjectConfirmation>
</saml:Subject>

Setup & Configuration¶

Note

<your_server_host> used in URLs must be replaced with the IP/FQDN of the corresponding OVD service, as seen by the end user (Session Manager by default). If, for example, the Enterprise Secure Gateway (ESG) is used, the IP/FQDN of the ESG would be used.

OVD Session Manager Configuration¶

Once the standard installation and configuration of the Inuvika OVD Enterprise has been completed, the OVD Session Manager can be configured to manage user authentication using SAML 2.0. This section applies to SAML Authentication Assertions originating from an Identity Provider and SAML Authentication Requests originating from OVD.

To do this, first enable SAML 2.0 Authentication as the method to be used for authenticating users by performing the following steps:

Open the OVD Administration Console http://<your_server_host>/ovd/admin

Note

When using the Administration Console for the first time, Service Provider Entity ID and Assertion Consumer Service URL are automatically set, based on the URL currently used to access the OVD Administration Console.
Go to "Users / Authentication Settings".
In the "AuthMethod" section :
- Un-check all options
- Check the "SAML2" box
In the "SAML2" section :
- Enter the Identity Provider URL that identifies the location that will receive and process a SAML 2.0 Authentication Request
- Enter either the X.509 Certificate or the certificate sha1 fingerprint for the Identity Provider.

Note

The fingerprint for the Identity Provider certificate can be created using openssl as follows:

^#
openssl x509 -noout -fingerprint -in "certificate.crt"

Alternatively, an online service can also be used to create the fingerprint (ex: https://certlogik.com/decoder/).

Warning

Use of the fingerprint method in production is not recommended as it can be exploited by a collision attack. Using sha1 is discouraged as this is a deprecated algorithm and should not be used.

Identity Provider Configuration¶

The Identity Provider (IdP) settings can be found in different places depending on the specific IdP, but generally the names are kept the same.

The Service Provider Entity ID, or Relaying Party Identifier, is https://<your_server_host>/ovd/client/auth/saml2.
The SAML Assertion Consumer Endpoint is https://<your_server_host>/ovd/client/auth/saml2/acs using a POST binding.

OVD has no SAML2 logout feature, meaning users will have no way to end their SAML2 sessions from within OVD. For this reason, we recommend configuring the IdP to always ask for the user’s credentials for the OVD Entity ID. This can be achieved by setting the timeout to a short value, such as one minute, or using a specific setting depending on the IdP capabilities.

Testing the Setup¶

When testing the setup, it is recommended to enable the Debug Mode setting. During the authentication process, additional information about communication between Identity and Service Provider will be displayed in the browser.

For testing purposes, the setting "Strict SAML2 response validation" can be disabled to ease the Assertion validation and allow testing without a valid SSL certificate.

Both options can help find configuration issues, but should be returned to their default values once validated for production use:

Strict SAML2 response validation enabled
Debug Mode disabled

SAML Authentication Request¶

In the case where the system is designed so that OVD issues a SAML Authentication Request to the Identity Provider, the installation can be tested by pointing the web browser at the OVD Web Access URL in your environment:

https://<your_server_host>/ovd/

If the setup is working correctly, the login page will show a new "Authenticate with SAML2" button which users can click to be redirected to the Identity Provider authentication page where users will be required to authenticate themselves on that site. Upon successful authentication, the browser will be redirected back to the OVD Web Access and the OVD user session will start automatically.

Advanced Configuration¶

Web Access Cookies¶

Unique cookie names can be defined for different Web Access servers. This caters to the need to have more than one OVD Web Access server accessible with the same IP address or domain but with different TCP ports. Uniquely named cookies make each Web Access server identifiable to those services that need to route traffic. For example, if you use a load balancer or a proxy that manages authentication, then assign unique cookie names to each server so that the browser can handle traffic correctly. To do this, update the OVD Web Access configuration files for each server with a different cookie name by uncommenting the line shown below and setting YourName01 to the unique cookie name for the server:

define('SESSION_COOKIE_NAME', 'YourName01');

Assertion Consumer Service URL Configuration¶

It is possible to override the default Assertion Consumer Service (ACS) URL by defining the value in the corresponding Administration Console setting.

Assertion and Request encryption¶

If the Identity Provider supports Encrypted Assertions, the Service Provider Private Key can be specified in the Administration Console.

The corresponding public key must be installed on the Identity Provider.

Entity ID¶

For custom setups and improved validation, the Identity Provider Entity ID can be configured, as well as the Service Provider Entity ID, if they are not detected correctly.