An Overview of the Configuration Files

Steps required to integrate SAML SP to a web application are described in this chapter. An overview of the SAML SP configuration files created or modified during the process is shown in Listing 1 . The location of the web application is denoted with <webapp_directory> and should be replaced with the actual directory.

The application’s deployment descriptor web.xml is modified to include the SAML SP servlet and filter configuration. The provided binary libraries are copied to the WEB-INF\lib directory. SAML SP identity information is created to the WEB-INF\saml2\sp directory and the IDP metadata is copied to the WEB-INF\saml2\sp\metadata directory.

Listing 1. An overview of the SAML SP files after the integration

<webapp_directory>\WEB-INF\web.xml		   					[servlet and filter configuration] 
<webapp_directory>\WEB-INF\lib\*.jar						[SAML SP binary libraries]
<webapp_directory>\WEB-INF\saml2\sp\identity.properties		[SAML SP identity]
<webapp_directory>\WEB-INF\saml2\sp\metadata\metadata.xml	[IDP metadata]

Copying the Binary Libraries

Copy the binary libraries from ubispservlet/webapp/WEB-INF/lib to the WEB-INF/lib directory of the web application.

Listing 2. Copying the binary libraries

cd ubispservlet\webapp\WEB-INF\lib
copy *.jar <webapp_directory>\WEB-INF\lib\.

Create the SAML Service Provider identity

The SAML Service Provider identity consists of an Entity ID, an RSA private key and an HTTP endpoint address. The Entity ID and private key are used to identify and authenticate the Service Provider to the Ubisecure Identity Provider, typically Ubisecure Server. The HTTP endpoint is used by the Ubisecure IDP to submit protocol messages to the Service Provider.

The HTTP endpoint is the fully qualified URL address where ServiceProviderServlet is bound. The path of ServiceProviderServlet is /spsso.
The identity is generated into a file named identity.properties. This file is located in the /WEB-INF/saml2/sp/identity.properties path of the web application.

Listing 3. Creating the Service Provider identity

cd <webapp_directory>\WEB-INF
mkdir saml2\sp
java -jar lib\sso-ubisaml2.jar Generate https://sp.example.com/webapp/spsso -o saml2\sp

The sample command in Listing 3 assumes the application server is accessible using the hostname sp.example.com and the name of the web application is webapp. All communication with the application is encrypted using HTTPS.

NOTE: Always use the same hostname when accessing the application. The hostname should be identical with the hostname given in Listing 3 (e.g., sp.example.com) and not for example an address with the application server's IP address instead of the hostname.

Associate the SP Identity with a Ubisecure Web Agent

Use the Ubisecure Management application to associate the Service Provider identity with a Ubisecure Web Agent. You need to upload the SAML metadata of the Service Provider to the management application.

SAML metadata is an XML formatted document. The metadata represents the public information about the Service Provider identity.

Listing 4. Write the SAML metadata of the Service Provider to the c:\temp\sp.xml file

cd <webapp_directory>\WEB-INF
java -jar lib\sso-ubisaml2.jar Metadata saml2\sp -f c:\temp\sp.xml

Use the commands in Listing 4 to write the SAML metadata of the Service Provider to a file. Use your web browser to associate the SP Identity with a Ubisecure Web Agent by uploading this metadata file in the Ubisecure Management application.

Using the Ubisecure Management Application


Figure 1. Select SAML Service Provider from the drop down list and click Activate


Figure 2. Click Browse and select the file with the SP metadata, then click OK


Figure 3. The SAML Service Provider ID field now shows the Entity ID of your SP

Get the Metadata of the Identity Provider

Download the Ubisecure IDP metadata from the SAML 2.0 link on the Ubisecure Management home page. Save this file into the /WEB-INF/saml2/sp/metadata folder of your web application.


Figure 4. Click SAML 2.0 to download the IDP metadata file

During startup the Service Provider will locate and read all files in the /WEB-INF/saml2/sp/metadata folder. This folder must contain a single metadata file for a SAML Identity Provider. (It may however contain another metadata file for an Attribute Authority. See Attribute authority metadata below for more details.) The Service Provider startup will fail if an IDP metadata file is not found, or if the folder contains more than one IDP metadata file.

Attribute Authority Metadata

An Attribute Authority enables the real-time access of attributes via the backchannel. This functionality is rarely required.

If your application uses an attribute authority (AA) for attribute queries, you should copy the AA metadata to /WEB-INF/saml2/sp/metadata folder together with the IDP metadata file. The filenames must match, for example metadata.xml and metadata.href.

Key rotation

In order to use Key Rotation feature and update IDP/AA metadata automatically a ".href" file must exist. Don't be confused with the file extension since it is just a normal properties file in "key=value" format.

The file must be located at the same directory as the IDP/AA metadata file:

/WEB-INF/saml2/sp/metadata

The following properties are supported in ".href" file:

	Value type
`entityId`	string	An entity identifier. Should be taken from IDP/AA metadata: <md:EntityDescriptor entityId="https://localhost:8443/uas"...>
`type`	- IDP (Identity Provider); - AA (Attribute Authority).	An entity type.
`url`	string	A URL to fetch metadata from. The same URL where SAML 2.0 IDP/AA metadata was fetched initially. See "Get the Metadata of the Identity Provider" step.
`refreshInterval`	number	An interval in seconds to fetch the metadata.

The example:

metadata.href

entityId=https://localhost:8443/uas
type=IDP
url=https://localhost:8443/uas/saml2/metadata.xml
refreshInterval=20

Browser not supported