SAML 2.0 Configuration Guide¶
|1.2||2017-07-18||Updates for OVD 2.4; Reformatting|
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.
The OVD Session Manager and a valid subscription key must be installed as well as the OVD Web Access in order to enable the functionality to support SAML 2.0 authentication. SAML 2.0 authentication is available only for web browser based OVD clients, using HTML5. It is not available for use with the Inuvika Enterprise Desktop Client, nor the Inuvika Enterprise Mobile Clients.
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, and does not sign or encrypt its SAML 2.0 requests.
SAML and SINGLE SIGNON¶
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
For Example, in the following snippet from a SAML Assertion,
firstname.lastname@example.org 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">email@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¶
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
- Go to Configuration / 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 X509 Certificate or the certificate fingerprint for the Identity Provider.
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 such as: (http://certlogik.com/decoder/) may be used.
OVD Web Access Configuration¶
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:
and save the file.
Testing the Setup¶
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:
If the setup is working correctly, the browser will be redirected to the Identity Provider authentication page and the user will be required to authenticate himself 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 his required session options and click on Connect to start the OVD user session.
Identity Provider SAML Assertion¶
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
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.
Handling Multiple Authentication Methods¶
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:
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:
Assertion Consumer Service URL Configuration¶
It is possible to override the default Assertion Consumer Service (ACS) URL by defining the value in the OVD Web Access configuration file as follows:
This can for example be used to enforce https and or to use a domain name as the URL. Alternatively, this setting can also often be configured in the Identity Provider on a Service Provider basis.
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:
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.
The principle is to display a form with a submit button and a hidden
SAMLResponse that holds the SAML2 ticket. The form is sent with
a POST request to the OWA's Assertion Consumer Service that is defined
to automate posting the form and in case the web browser doesn't support