Before you begin

Contact your Identity Provider (IdP) Administrator to obtain the XML metadata.

The SAML Gateway requires a key pair to use for encryption and signing. Obtain the key pair from your administrator or use Java Keytool to create a new one.

Our SAML SSO product uses a Services Oriented Architecture (SOA) approach.  It is deployed on a Java SE web application environment, such as Tomcat with a front end.  The SAML application and the client  application need to be able to communicate with each other over the internet.

Installation Requirements

Installing the SAML Gateway application

1. Replace the file named idp.xml in the WEB-INF/classes/metadata folder of the application with the metadata you obtained from your IdP. Depending on your provider, this information may be available in a metadata page as a file that can be downloaded or copied into an .XML file.
2. Import the encryption key pair into the provided keystore located at WEB-INF/classes/security/samlKeystore.jceks. You will need to provide the -storetype jceks option to Java Keytool when importing. The default keystore password is "mitratech".
   Alternatively, you can replace the provided keystore with your own and update saml.properties accordingly (see below).
3. Edit the saml.properties file in the WEB-INF/classes folder of the application. Refer to the table below for details on each property.

   Property	Description
   idp.UsernameIdentifier	SAML response element that will contain the Lawtrac username. Supported values are NameID and Attribute. Contact your Identity Provider for this information.
   idp.nameIDFormat	Requirement when idp.UsernameIdentifier is NameID e.g. urn:oasis:names:lt:SAML:1.1:nameid0format:unspecified. Contact your Identity Provider for this information.
   idp.attributeName	Name of the response Attribute containing the Lawtrac username. Required only when idp.UsernameIdentifier is Attribute. Contact your Identity Provider for this information.
   sp.entityID	Service Provider entity ID. This is the value used to generate service provider metadata in Step 6. If you are using an existing metadata file, enter the value of the entityID attribute from the metadata file.
   gateway.admin.username	Definition of the credentials to access the SAML gateway administration interface. Default is admin.
   gateway.admin.password	Definition of the credentials to access the SAML gateway administration interface. Default is admin.
   useSSO	Indication for whether IdP-initialized SSO should be supported. Supported values are true and false. Located in the Lawtrac .LTO file.
   application.loginUrl	Login URL for the Lawtrac application.
   application.logoutSuccessUrl=	Re-direct URL upon log-out. A Mitratech admin will provide you with the necessary war path to edit. Find the string "application.logoutSuccessUrl="and insert the desired log-out URL after the equal character (=), as shown in the example below. Note: The re-direct URL is performed through the SAML application. Warning: Do not delete the string application.logoutSuccessUrl=. Doing so will cause the SAML properties to throw an error. When removing the log-out URL, only erase the actual URL inserted after "=". When this field is blank the user is directed to the default SAML gateway after logging out. If a user is timed out of the application for security reasons, the re-direct URL set here does not run. Instead, the user is re-directed to the URL determined in Application Administration | Data Locations.
   keystore.file	Name of the Java Keystore file containing the private key for encrypting and optionally signing SAML messages. This file must be located in the WEB-INF/classes/security folder of the application. You may use the provided sample keystore (samlKeystore.jceks) or replace it with your own.
   keystore.type	Type of the keystore. Supported values are jceks and jks.
   keystore.password	Keystore password.
   keystore.privatekey.alias	Keystore alias for the private key. For security reasons, the default private key should not be used in production.
   keystore.privatekey.password	Password for the private key.

4. Deploy the SAML Gateway application.

5. In a web browser, go to <SAML gateway>/saml/web/metadata/generate.

6. Log in using the credentials defined in Step 3.

7. On the Metadata generation page, enter the Entity ID defined in Step 3. The choices for Service Provider metadata generation depend on the environment and configuration, as agreed on by the IdP and SP admins.

8. Click the Generate metadata button. The Metadata detail page is displayed.

   1. Replace the contents of the file named sp.xml in the WEB-INF/classes/metadata folder of the application with the content of the Metadata field.

   2. Edit the securityContext.xml file in the WEB-INF/classes folder of the application and update the ExtendedMetadata of <bean> with id="sp" to include the property values from the Configuration field.

9. Restart the SAML gateway application.

10. Provide service provider metadata to your IdP administrator for upload to the IdP.