Installation Overview

• Requirements
• Preparing for installation
• Extracting HTTP Header Authentication Provider distribution package
• Creating SAML identity provider configuration
• Modifying authentication configuration
• Exporting SAML identity provider metadata
• Configuring Ubisecure Authentication Server
• Importing service provider metadata
• Deploying HTTP Header Authentication Provider

Requirements

System Requirements

• BEA Weblogic 9.2 or Apache Tomcat 6.0.x
• J2SE 1.5.x
• Ubisecure Server 4.0.2 or later

Additional Requirements

• A 3^rd party Identity Provider that send user identity information in http headers to HTTP Header Authentication Provider.
• Time synchronization is required between the UAS and HTTP Header Authentication Provider. If this is not possible for some isolated test case, this can be worked around by setting the UAS server's time slightly ahead of the Authentication Provider, but this is under no circumstances a recommended practice, especially in a production environment.
• For information about the Network Time Protocol, refer to following URLs.
  • NTP: The Network Time Protocol
    http://www.ntp.org
  • Windows Time Service Technical Reference
    https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/windows-time-service/windows-time-service

Required Files

• httpheaderap-x.x.xxxx.zip – for installation on all platforms
• The import script used to create LDAP entries when installing UAS

HTTP Header configuration Requirements

• List of HTTP headers that contain the authentication information for the user.

Preparing for Installation

Before proceeding with installation, the following configuration decisions must be made:

• Configure your 3^rd party authentication solution to send user authentication information to HTTP Header Authentication Provider in http headers.
• Decide the deployment URL for HTTP Header Authentication Provider. Later in this document, the deployment URL is referred as the base URL. Example: https://example.com/httpheaderap
• Decide which http header contains the user's subject name. This HTTP header must always be present or authentication will fail.
• Decide which HTTP headers are transmitted as attributes to Ubisecure Authentication Server in addition to the user's subject.

Extracting the Distribution Package

cd /d "C:\Program Files\Ubisecure"unzip httpheaderap-X.X.XXXX.zip

As a result, the following directory structure is created:

httpheaderap
├───ldap
├───logs
└───webapp
	└───WEB-INF
		├───classes
		├───lib
		└───uap
			└───metadata

Creating a SAML Identity Provider Configuration

Ubisecure HTTP Header Authentication Provider acts as SAML 2.0 identity provider.

Create a SAML identity provider configuration by running the following script containing base URL. Please note that the java command must be found in PATH to run this script.

cd /d "C:\Program Files\Ubisecure\httpheaderap"
java -jar webapp\WEB-INF\lib\ubisaml2.jar Generate https://example.com/httpheaderap -o webapp\WEB-INF\uap -y -disable SingleLogoutService

As a result, identity provider configuration is created in the httpheaderap/webapp/WEB-INF/uap/identity.properties file.

Configuring Log File Location

By default, the log files are generated to the following directory.

c:\Program Files\Ubisecure\httpheaderap\logs

In Unix installations, the log directory must be configured manually by modifying the log configuration file in the following location.

httpheader/webapp/WEB-INF/uap/log4j.properties

In Unix installations, the recommended location of the log files is the following directory.

/usr/local/httpheaderap/logs

Configuring HTTP Headers

The http header set by 3^rd party Identity Provider are set to context parameters in web.xml.

httpheader/webapp/WEB-INF/web.xml

Value of context parameter com.ubisecure.saml2.uap.httpheaderap.subject is the HTTP header that is used as user's subject name. This header must be present or authentication fails.

Additional attributes that will be sent with authentication if present are set to context parameter com.ubisecure.saml2.uap.httpheaderap.attributes in a comma separated list. The name of the attribute sent to UAS is the same as the name of the header. This list is a white list, meaning that no other attributes are sent than those present in this list and if header is not present, it is not sent.

    <context-param>
        <param-name>com.ubisecure.saml2.uap.httpheaderap.subject</param-name>
        <param-value>sm_user</param-value>
    </context-param>
 
    <context-param>
        <param-name>com.ubisecure.saml2.uap.httpheaderap.attributes</param-name>
        <param-value>sm_realm,sm_universalid,sm_authtype,sm_userdn</param-value>
    </context-param>

Exporting SAML Identity Provider Metadata

Export the SAML identity provider metadata by running the following script.

cd /d "C:\Program Files\Ubisecure\httpheaderap"
java -jar webapp\WEB-INF\lib\ubisaml2.jar Metadata webapp\WEB-INF\uap -idp -f metadata.xml -y

As a result, the identity provider metadata is created in the httpheaderap/metadata.xml file.

Configuring Ubisecure Authentication Server

Add the Authentication Method to the Ubisecure Directory

The authentication method is added to the Ubisecure Directory by importing LDAP LDIF script files. Replace the dn and cn attributes with the name of the authentication method instance and use the following scripts to import the LDIF to Ubisecure Directory.

cd /d "C:\Program Files\Ubisecure\httpheaderap"
c:\ubisecure\ldap\adam\import.cmd ldap\httpheaderap.ldif

cd /usr/local/httpheaderap
sh /usr/local/ubisecure/ldap/openldap/import.sh ldap/httpheaderap.ldif

#
# HTTP Header Authentication Provider
# 
dn: cn=httpheaderap.ubilogin.1,cn=Server,ou=System,cn=Ubilogin,dc=localhost
changetype: add
cn: httpheaderap.ubilogin.1
objectClass: top
objectClass: ubiloginAuthMethod
ubiloginAuthMethodType: SAML
ubiloginClassname: ubilogin.method.provider.saml2.AssertionConsumerMethod
ubiloginEnabled: FALSE
ubiloginTitle: httpheaderap.ubilogin.1

Import the HTTP Header Authentication Provider Metadata

Log into Ubisecure Server Management with System Administrator privileges. Navigate to the Server Authentication Methods view. Open the settings of the authentication method you just installed and choose the SAML view. Click Upload SAML Metadata and either upload the metadata file httpheaderap/metadata.xml created in section below (Exporting SAML identity provider metadata) or copy and paste the metadata.

Export the SAML Service Provider Metadata

Click Download SAML Metadata to download the service provider metadata and save it for the next task.

Importing Service Provider Metadata

Copy the service provider metadata created in the section Configuring Ubisecure Authentication Server to directory httpheaderap/webapp/WEB-INF/uap/metadata. Filename may be freely chosen. It is recommended to choose the name representing the specific service provider whose metadata the file contains.

Deploying HTTP Header Authentication Provider

Deploy the application with root directory httpheaderap/webapp to application server.

Verifying the HTTP Header Authentication Provider Installation

Use the context parameter from Listing 13 in the HTTP Header Authentication Provider web.xml file and redeploy HTTP Header Authentication Provider to use the test page.

<context-param>
    <param-name>com.ubisecure.saml2.uap.testpage</param-name>
    <param-value>true</param-value>
</context-param>

Now you can access the HTTP Header Authentication Provider directly using the URL https://example.com/httpheaderap/saml2/SingleSignOnService. If the HTTP headers were set and read correctly you will see the http header contents on your web browser.