SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). Whereas Fabasoft Folio is the service provider and Shibboleth - an open source SAML implementation - is used as identity provider. The following chapters describe how to install and configure the Shibboleth IdP and how to configure Fabasoft Folio to use single sign-on authentication with SAML.
The chosen identity provider is Shibboleth, deployed on Apache Tomcat.
The Shibboleth IdP is a standard Java web application based on the Servlet 2.4 specification and can be deployed on several servlet containers. For Apache Tomcat, JBoss Tomcat, or Weblogic, detailed documentation about installing and deploying Shibboleth on them is available at : new window.
However, for using the Shibboleth IdP as an identity provider for Fabasoft Folio, Apache Tomcat is recommended. The installation tasks for the Shibboleth IdP described in this document are referred to Apache Tomcat as web server.
Shibboleth cannot be installed and run by using the GNU Java compiler and VM. For using the IdP another Java virtual machine and compiler must be installed. The recommended JVM is the Sun HotSpot. This fact must be kept in perspective for deploying Shibboleth on operating systems that are using OpenJDK by default (e.g. Red Hat based Linux distributions).
After assuring that a proper JVM is available, the Shibboleth IdP can be installed by performing the following steps:
The installation scripts create the identity provider’s home directory which contains the following subdirectories:
The Shibboleth configuration files are located in the folder <Shibboleth Home>/conf. For using the Shibboleth IDP with Fabasoft Folio, the default configuration files relying-party.xml, attributefilter.xml, attribute-resolver.xml and metadata.xml have to be adapted. The necessary modifications are described in the next chapters.
Detailed configuration of Apache Tomcat for hosting Shibboleth can be found at : new window.
The main configuration steps are:
IDP_HOME is the Shibboleth home directory and PASSWORD is the password for the identity provider’s keystore, which was specified during the installation process.
Possible installation issue on Microsoft Windows platforms:
o.s.web.context.ContextLoader – Context initialization failed at the first start.
The stack trace of this error probably contains an UnknownHostException for a host “c”. This is actually the “c” from the IdP home directory path (e.g. C:\Shibboleth-2.1). The error is caused by wrong path expressions in SHIBSRC\identityprovider\resources\WEB-INF\web.xml. Replace every occurrence of “file://$IDP_HOME$" to "file:///$IDP_HOME” in the path expressions. Then the installer (ant.bat on Microsoft Windows) has to be run again with "not new installation" option. The created idp.war has to be deployed again.
For interaction of the identity provider with Fabasoft Folio, the service provider must provide the standardized metadata.xml document. This file contains so called entity descriptors, which can be grouped in entity descriptor XML elements. The location of an entity descriptor can be defined by specifying a new metadata provider in the file relying-party.xml:
In the example above, the type attribute of the <MetadataProvider> element is FileBackedHTTPMetadataProvider, which specifies that the entity descriptor can be downloaded via HTTP and the service provider’s metadata gets locally cached in the identity provider’s file system.
For each MetadataProvider, <id> is a unique string. The attribute metadataURL is the URL where the metadata can be downloaded whereas <folio_url> is the base URL of the Fabasoft Folio service. The attribute backingFile specifies the file system location where the metadata gets cached. To reload the specified metadata, the identity provider has to be restarted.
Also some attributes of the XML element DefaultRelyingParty have to be adjusted to set some default values for the IDP like shown in the following:
The attribute provider is set to <idp_entity_id> which is the entity-id of the used IdP. To enable password authentication, the attribute defaultAuthenticationMethod must be set to urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport. Because assertions should not be encrypted, it is also mandatory to set encryptAssertions to never.
By default the subject of the assertions generated by the identity provider is the transient id of the authenticated user. For single sign-on with Fabasoft Folio it is necessary that the principal of the user is contained in the assertion. This can be accomplished by performing changes in the attribute-resolver.xml, respectively attributefilter.xml file. In the following, an example configuration is given where LDAP is used as authentication backend and the user principal name gets embedded in the NameID tag of the assertion. This example includes attribute encoders which entails that the name identification gets sent the NameID tag of the response and additionally in an attribute with the name urn:oid:1.2.840.1135184.108.40.2066.
Note: The AttributeDefinition identifier id must be unique in the attribute configuration.
<resolver:Dependency ref="myLDAP" />
<!-- for including attribute urn:oid:1.2.840.1135220.127.116.116 in the response -->
<!-- for including the persistent NameID in the response -->
<PolicyRequirementRule xsi:type="basic:ANY" />
<PermitValueRule xsi:type="basic:ANY" />
The following settings are necessary for the configuration of SAML:
Providing credentials for cookie signing
For signing the cookie, the path to a file containing the pkcs12 credentials must be configured. This also can be done on the “Authentication” tab via the Private Key Path field. If the key is password protected, also the password has to be defined.
Furthermore the following properties can be specified:
Configuring proxy settings
If a proxy is used, the configuration can be defined in this section.
Optional: Setting the environment variable FSCVEXT_ALTAUTHMETH
If LDAP authentication should be used as the alternative authentication method while using SAML as the primary one, the environment variable FSCVEXT_ALTAUTHMETH has to be set. This alternative authentication method will only be used if the username and password are already attached to the HTTP request header. However the web service will not send a challenge response if the HTTP request headers does not exist.
Additionally a regular expression can be defined in the environment variable FSCVEXT_ALTAUTHUSERAGENT which will be applied to the HTTP header variable User-Agent. If the regular expression matches and the HTTP request does not contain the username and password in the request header, a challenge response will be sent to the client. So it is possible to use LDAP authentication for defined user agents.