SAML 2.0 Configuration Guide¶

Last updated on Jul 14 2022.

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.

Important

In OVD versions prior to 3.2, the OVD Web Access must be installed to enable SAML 2.0 authentication. SAML2 is not available for use with the Inuvika Enterprise Desktop Client or the Inuvika Enterprise Mobile Clients in these previous versions.

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.

Important

OVD versions prior to 3.2 do not sign or encrypt the SAML 2.0 requests or accept encrypted responses.

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.

OVD Web Access Configuration¶

OVD versions prior to 3.2

This section only applies to OVD versions prior to 3.2.

To configure the OVD Web Access to use only SAML for authentication and to prevent other forms of authentication for browser based access to OVD, modify the OVD Web Access configuration file as follows:

^#
#	`nano /etc/ovd/web-access/config.inc.php`

Then un-comment the following line:

define('OPTION_FORCE_SAML2', true);

and save the file.

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.

OVD versions prior to 3.2

For OVD versions prior to 3.2, the url is http://<your_server_host>/ovd/auth/saml2.
The SAML Assertion Consumer Endpoint is https://<your_server_host>/ovd/client/auth/saml2/acs using a POST binding.

OVD versions prior to 3.2

For OVD versions prior to 3.2, the url is http://<your_server_host>/ovd/auth/saml2/acs.php.

The http://<your_server_host> portion of both URLs can be changed using the SAML2_REDIRECT_URI configuration described in the Assertion Consumer Service URL Configuration section.

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

OVD versions prior to 3.2

These settings are not available for OVD versions prior to 3.2.

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.

OVD versions prior to 3.2

For OVD versions prior to 3.2, if the setup is working correctly, the browser will be redirected to the Identity Provider authentication page and users will be required to authenticate themselves on that site. Upon successful authentication, the browser will be redirected back to the OVD Web Access login page. The page now displayed to the user should not display a password field and the login field should be read-only. The user may select their required session options and click on Connect to start the OVD user session.

Identity Provider SAML Assertion¶

OVD versions prior to 3.2

This section only applies to OVD versions prior to 3.2.

In the case where the system is designed so that the Identity Provider issues a SAML Assertion, the installation can be tested by pointing the web browser at the URL of the Identity Provider and entering the user credentials required to authenticate the user. Once the user has been successfully authenticated, the Identity Provider will send a SAML Assertion to OVD using an HTTP POST. The Identity Provider should be configured to post the data to

http://<your_server_host>/ovd/auth/saml2/acs.php

OVD will process the SAML Assertion and display the same login page as above for the SAML Authentication Request without a password field and the login field read-only. OVD will not process the RelayState parameter if defined. The user may select his required session options and click on Connect to start the OVD user session.

Advanced Configuration¶

Handling Multiple Authentication Methods¶

OVD versions prior to 3.2

This section only applies to OVD versions prior to 3.2.

In certain cases such as when access to OVD is integrated into a custom portal or support for different types of authentication is required, further configuration may be required. For users that will authenticate using SAML 2.0, access to OVD can be made available through the following URL:

http://<your_server_host>/ovd/auth/saml2/sp.php

and for users that do not use SAML 2.0, the standard URL can be defined.

In addition, the OVD Web Access configuration file should not be modified in this case, i.e. the following line remains commented out:

// define('OPTION_FORCE_SAML2', true);

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.

OVD versions prior to 3.2

For OVD versions prior to 3.2, this is set in the OVD Web Access configuration file as follows:

define(SAML2_REDIRECT_URI, 'https://www.example.com');

This setting can be used to enforce HTTPS and/or to use a domain name as the URL. Alternatively, it can also be configured in the Identity Provider on a Service Provider basis.

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.

OVD versions prior to 3.2

These settings are not available for OVD versions prior to 3.2.

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.

OVD versions prior to 3.2

These settings are not available for OVD versions prior to 3.2.

Custom Configuration¶

OVD versions prior to 3.2

This section only applies to OVD versions prior to 3.2.

If even further special handling is required, it is possible to create a custom redirection script that will redirect the client browser in the manner required. To achieve this, create a new php file called custom.php in the following folder:

/usr/share/ovd/web-access/auth/saml2/custom.php

In this case, you must point your SAML2 Identity Provider (IdP) to this URL using one of the options described above.

The simple example script shown below is self-sufficient and can be customized to meet your specific needs.

<?php
  define("OVD_SERVER", "https://example.com/ovd/auth/saml2/acs.php");
  ob_start();
  header("Content-Type: text/html;charset=utf-8");
  $data = $_POST['SAMLResponse'];
  setcookie('ovd-sso', 'true', 0, '/ovd/');
?>
<html>
  <script language="javascript">
    window.onload = function () { document.forms[0].submit(); }
  </script>
  <body>
    <p>Redirecting to OVD for login - If you appear to get stuck use the button below to proceed</p>
    <form method="post" action="<?php echo OVD_SERVER ?>">
      <input type="hidden" name="SAMLResponse" value="<?php echo $data ?>">
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

The principle is to display a form with a submit button and a hidden field SAMLResponse that holds the SAML2 ticket. The form is sent with a POST request to the OWA's Assertion Consumer Service that is defined by the OVD_SERVER variable. The script has some simple JavaScript code to automate posting the form and in case the web browser doesn't support JavaScript, a prompt is displayed together with the Submit button.