SAML 2.0 Configuration Guide¶
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:
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 aPOST
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
enabledDebug 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:
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:
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.