SAML Authentication

Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IDP) to pass authorization credentials to a service provider (SP). SAML is the link between the authentication of users' identities and the authorization to use a service from the provider.  ExtraView relies on the use of a third party IDP.

SAML is used in conjunction with SSO and often with LDAP.  With an operational ExtraView installation, the configuration of SAML requires these three steps:

  1. The configuration of a working SSO external to ExtraView, in the ExtraView behavior settings and Configuration.properties file
  2. The configuration of the third party Identity Provider (IDP)
  3. The configuration of ExtraView SAML behavior settings and the storage of the certificate used by the IDP

LDAP Configuration

See the previous pages on External Authentication - LDAP, SSO and SAML.

SSO Configuration

See the previous page on LDAP Connections with SSO.

Identity Provider (IDP) Configuration

The components of the IDP configuration depend on the provider itself, but it is expected that the most relevant points are:

  • The specification of the URL to which authentication responses are directed
  • The assertion key-value mapping for SSO keys; the SSO_PRIMARY_KEY must have an assertion in the authentication message to identify the ExtraView user.

ExtraView Configuration

The following behavior settings should be configured as appropriate for your installation.  You should determine the parameter values for all the settings below to be used in the authentication response before starting the configuration.

ExtraView Setting Explanation
SSO_STATE This behavior setting must be set to SAML
SAML_ASSERTION_CONSUMER_URL This behavior setting is the URL of the consumer service that receives the authentication response from the SAML IDP. This is the URL that invokes the Consumer Servlet when the behavior setting SSO_STATE has a value of SAML.  Typically this will have a value that looks similar to https://myserver.mydomain.com/Consumer.  This is the application URL registered with the IDP.
SAML_SSO_SERVICE This behavior setting provides the URL of the SSO service to which the SAML SP sends an authentication request. This URL points to a target in the IDP
SAML_SSO_SP_ENTITY_ID The SP Entity ID behavior setting is a URL or other identifier given by the Service Provider (SP) that uniquely identifies it to the IDP.  This is derived from the metadata for the SP.  A typical value is an XML fragment and will look similar to:

<md:entitydescriptor entityid=
    "http://www.okta.com/exki3aihaifAHCbex0h7"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
</md:entitydescriptor>
SSO_DO_UPSERT This is set within the Configuration.properties file if it the values from the authentication are to be updated within the ExtraView database with each authentication
SSO_PRIMARYKEY This is the mapping for the user name that is set within the Configuration.properties file.  This parameter must include the expected ExtraView User ID
SSO_SURNAME This is the mapping for the user's last name that is set within the Configuration.properties file
SSO_GIVENNAME This is the mapping for the user's given name that is set within the Configuration.properties file
SSO_EMAIL This is the mapping for the user's email address that is set within the Configuration.properties file

The IDP will typically require a valid security certificate to validate the encrypted signature in the authentication response from the IDP.  This certificate is stored securely within ExtraView within the Key Manager administation utility.  This is located at Admin --> Advanced --> Encryption Key Management   The format for the certificate is known as PEM (Privacy Enhanced Mail).  The name is somewhat of a misnomer as the certificates for SAML have no connection with email.  The format is a Base 64 encoded striing of characters which is pasted into the Enter certificate PEM field within the Encryption Key Manager.  If there is no entry in this field, the new entry you create for the key is added as a secret key only and is not used for SAML authentication.

The entry in the key manager should look like this:

  • Name for the key - this must be SPKey
  • Key password - this must be password
  • Certificate PEM - this is the field where you paste the contents of the certificate

The action to save a certificate in this field builds the appropriate credentials for the SAML certificate.

SAML Logging Configuration

When first establishing a connection to an IDP to perform SAML authentication it can be useful to add additional logging to view the precise details of the transactions.  This configuration is achieved within the ExtraView WEB-INF/configuration/Configuration.properties file.

Any property name within the Configuration.properties file that begins with LOGBACK is treated as a replaceable variable for the logback.template file.  The logback.template file is part of the third-party SAML installation.
 
The replaceable variable modifies the logback.template file that creates the logback.xml configuration file that is then passed to the loggers for SAML.
 
For example, LOGBACK_FILE_PATH_NAME_ABSOLUTE is a replaceable variable that may have the value /tmp/logs.
 
The Configuration.properties file will contain the line:
 
LOGBACK_FILE_PATH_NAME_ABSOLUTE=/tmp/logs
 
The logback.xml will contain the line:
 
<file>__LOGBACK_FILE_PATH_NAME_ABSOLUTE__/SAML.log</file>
 
This will result in a log file named /tmp/logs/SAML.log.
 
There are two configurable files:
  1. Configuration.properties, which defines the LOGBACK... properties
  2. logback.template, which has replaceable variables surrounded by "__".
 
The following are the replaceable variables and the values specified in the delivered Configuration.properties:
 
LOGBACK_FILE_PATH_NAME_ABSOLUTE=
LOGBACK_MAX_FILE_SIZE=10mb
LOGBACK_LOG_LEVEL=INFO
 
The value of the LOGBACK_LOG_LEVEL attribute may be one of the case-insensitive string values TRACE, DEBUG, INFO, WARN, ERROR, ALL or OFF.

Bypassing SAML Authentication

There are some circumstances where you might want to bypass the SAML authentication, for example if the IDP service is not operable, or you need to access the ExtraView ADMIN account directly.  To achieve this, include the parameter EV_BYPASS_SSO=YES on the URL, following the ExtraView address.  This will produce the standard built-in ExtraView login screen for authorization.  For example, your address might look like:

http://myserver.mycompany.com/evj/ExtraView?EV_BYPASS_SSO=YES

SAML Authentication Via the CLI

CLI calls, by their very nature, cannot support SAML authentication, so the EV_BYPASS_SSO option is used to overcome this limitation.  A -B true option on the CLI command line allows the user to enter a valid user ID and password for authentication.

SAML Certificate

If there is a SAML certificate, place the name of the certificate in the behavior setting named KEY_ENTRY_ID and place the certificate in the key store.  The default certificate name is SPKey.