INUVIKA OPEN VIRTUAL DESKTOP ENTERPRISE SAML 2.0 CONFIGURATION GUIDE Roy Heaton David Pham-Van Version 1.1 Published March 23, 2015 This document describes how to configure OVD to use SAML 2.0 for user authentication. www.inuvika.com
TABLE OF CONTENTS 1. INTRODUCTION... 3 2. PRE-REQUISITES... 3 3. OVD SAML FUNCTIONALITY... 3 3.1 SAML and Single Signon... 3 4. SETUP & CONFIGURATION... 4 4.1 OVD Session Manager Configuration... 4 4.2 OVD Web Access Configuration... 5 4.3 Testing the Setup... 5 4.3.1 SAML Authentication Request... 5 4.3.2 Identity Provider SAML Assertion... 6 5. ADVANCED CONFIGURATION... 6 5.1 Handling Multiple Authentication Methods... 6 5.2 Web Access Cookies... 7 5.3 Assertion Consumer Service URL Configuration... 7 5.4 Custom Configuration... 7 Page 2
1. 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. 2. PRE-REQUISITES The OVD Session Manager and an Inuvika OVD Enterprise subscription must be installed as well as the OVD Web Access in order to have the functionality to support SAML 2.0 authentication. SAML 2.0 authentication is available only for web browser based OVD clients, using either HTML5 or Java. It is not available for use with the Inuvika Enterprise Desktop Client, nor the Inuvika Enterprise Mobile Clients. 3. 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. 3.1 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 Page 3
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> 4. SETUP & CONFIGURATION 4.1 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) Go to Configuration -> Authentication Settings In the AuthMethod section : o Un-check all options o Check the SAML2 box In the SAML2 section : o Enter the Identity Provider URL that identifies the location that will receive and process a SAML 2.0 Authentication Request o Enter either the X509 Certificate or the certificate fingerprint for the Identity Provider. Page 4
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. 4.2 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: define('option_force_saml2', true); and save the file. 4.3 TESTING THE SETUP 4.3.1 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: http://<your_ server_ host>/ovd/ 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 Page 5
should be read-only. The user may select his required session options and click on Connect to start the OVD user session. 4.3.2 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 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. 5. ADVANCED CONFIGURATION 5.1 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: 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); Page 6
5.2 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 YouName01 to the unique cookie name for the server: define('session_cookie_name', 'YourName01'); 5.3 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: define(saml2_redirect_uri, 'https://www.example.com'); 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. 5.4 CUSTOM CONFIGURATION 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. Page 7
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. Page 8