2017 R1

Authentication With SAMLPermanent link for this heading

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.

Shibboleth Identity ProviderPermanent link for this heading

The chosen identity provider is Shibboleth, deployed on Apache Tomcat.

The installer of Shibboleth is available for download at http://shibboleth.internet2.edu/downloads/shibboleth/idp/. Apache Tomcat is available at http://tomcat.apache.org/download-55.cgi.

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 https://spaces.internet2.edu/display/SHIB2/IdPInstall.

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.

Installation StepsPermanent link for this heading

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. CentOS and other Red Hat based Linux distributions).

After assuring that a proper JVM is available, the Shiboleth IdP can be installed by performing the following steps:

  1. Download the IdP software package (the shibbolethidentityprovider-*-bin.zip file).
  2. Unzip the downloaded archive.
  3. Prepare the servlet container (Apache Tomcat, JBoss Tomcat or Weblogic).
  4. Change into the newly created IdP distribution directory.
  5. Run ant.bat on windows or ant.sh on Linux. This script will ask for the location of the identity provider’s home directory that it will create. The user executing this script must have the permissions to create this directory. The output of the script may contain the message “JARs are never empty, they contain at least a manifest file”, but this does not indicate a problem.
  6. Deploy the IdP WAR file, located in IDP_HOME/war/, after you have properly prepared your servlet container.

The Identity Provider Directory StructurePermanent link for this heading

The installation scripts create the identity provider’s home directory which contains the following subdirectories:

  • bin/
    Contains various tools for running, testing, and deploying the IdP.
  • conf/
    Contains all the configuration files for the IdP.
  • credentials/
    This is where the IdP’s signing and encryption credentials (idp.key, and idp.crt) are stored.
  • lib/
    Contains various code libraries used by the tools in bin/.
  • logs/
    Contains the log files of the IdP.
  • metadata/
    Contains the metadata of the IdP, in a file called idp-metadata.xml. It is recommended to store any other retrieved metadata here as well.
  • war/
    Contains the web application archive (war) file that needs to be deployed into the servlet container.

Shibboleth ConfigurationPermanent link for this heading

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.

Tomcat ConfigurationPermanent link for this heading

Detailed configuration of Apache Tomcat for hosting Shibboleth can be found at https://spaces.internet2.edu/display/SHIB2/IdPApacheTomcatPrepare.

The main configuration steps are:

  • Copy the .jar files included in the identity provider’s source endorsed directory into Apache Tomcat’s $CATALINA_HOME/common/endorsed directory.
    Note: Some versions of Apache Tomcat ship with some XML related JARs in this directory. If you see JAR files related to JAXP or XML, please remove these as well as adding the aforementioned Xerces and Xalan JARs.
  • Install Shibboleth security provider
    • Copy the library shibboleth-jce-1.0.0.jar, located in the identity provider source's lib directory into JAVA_HOME/jre/lib/ext. If this directory does not exist it has to be created.
    • Edit the java.security file, located in the JRE's lib/security directory by adding the following line after the last security.provider entry: security.provider.#=edu.internet2.middleware.shibboleth.DelegateToApplicationProvider
      "#" is the number of the previous provider in the list incremented by one.
  • Configure the Apache Tomcat connector for Shibboleth:
    <Connector port="8443"













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.

Configuring Relying PartiesPermanent link for this heading

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:

<DefaultRelyingParty  provider="<idp_entity_id>"


<ProfileConfiguration xsi:type="saml:SAML2SSOProfile"






  encryptNameIds="never" />


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.

Using Principal Name for Assertion SubjectPermanent link for this heading

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.113556.1.4.656.

Note: The AttributeDefinition identifier id must be unique in the attribute configuration.





  <resolver:Dependency ref="myLDAP" />

  <!-- for including attribute urn:oid:1.2.840.113556.1.4.656 in the response -->

  <resolver:AttributeEncoder xsi:type="SAML1String"

    name="urn:mace:dir:attribute-def:userPrincipalName" />

  <resolver:AttributeEncoder xsi:type="SAML2String"  


    friendlyName="userPrincipalName" />

  <!-- for including the persistent NameID in the response -->



    nameFormat="urn:mace:shibboleth:1.0:nameIdentifier" />

  <resolver:AttributeEncoder xsi:type="SAML2StringNameID"  

    nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" />








  principal="DOMAINUSER" principalCredential="CREDENTIALS">







<AttributeFilterPolicy id="userPrincipalNameToAnyone">

  <PolicyRequirementRule xsi:type="basic:ANY" />

  <AttributeRule attributeID="userPrincipalName">

   <PermitValueRule xsi:type="basic:ANY" />



ConfigurationPermanent link for this heading

The following settings are necessary for the configuration of SAML:

  1. Open the Virtual Application Configuration, which is referenced in the Current Domain or Domain Type.
  2. Click the „Authentication” tab.

  • The following relevant properties are available:
  • Cookies
    • Cookie Valid in Session
      Set the value of this property to “Yes”, if the authentication should only be valid during a user session.
    • Authentication Expires After Minutes
      Define after how many minutes the authentication of a user expires, who is actively working with the system.
    • Authentication of an Idle Session Expires After Minutes
      Define after how many minutes the authentication of a user expires, who is not actively working with the system.
  • Activate SAML
    This property defines whether SAML is activated.
  • Identity Provider Metadata URL
    This property defines the URL, where the IdP’s metadata can be accessed. If defined, Fabasoft Folio attempts to download and update the IdP metadata on startup and ignores the Identity Provider Metadata property.
  • Identity Provider Metadata
    A file containing the metadata can be uploaded. If the Identity Provider Metadata URL is not defined, the IdP metadata is initialized based on the provided XML file. For retrieving the IdP metadata, access the IdP metadata URL (Shibboleth: https://myserver:8443/idp/shibboleth) with a browser and download the file. In case of Shibboleth, the metadata can also be retrieved from the Shibboleth metadata directory (metadata/idp-metadata.xml).
    This property is particularly useful for the initial configuration when both parties, Fabasoft Folio and the IdP, require each other’s metadata and the metadata URLs are inaccessible until the metadata is available on both sides.
  • Require Encrypted Assertions
    This property defines that only encrypted SAML assertions are accepted. For encryption, a private key must be configured.
  • Private Key Path (.p12, Assertion Encryption)
    This property defines the file system path of the PKCS #12 private key used for SAML assertion encryption.
  • Private Key Password (Assertion Encryption)
    This property defines the password of the private key used for SAML assertion encryption.
  • Name ID Format for User Identification
    Depending on the configuration of the identity provider, the name ID format can be specified here if the user identification should be contained in the NameID tag.
  • SAML Attribute Name for User Identification
    If the user identification should be done with an assertion attribute, the name of the assertion attribute has to be specified here.
  • SAML Attribute Name for Authentication Details
    If additional information provided in an assertion attribute should be logged in Account Activity in the Account portal as a result of successful authentication, the name of the assertion attribute has to be specified here. The value is stored in the property Authentication Details (COOSYSTEM@1.1:siauthdetails).
  • Alternative Base URL
    Usually the base URL can be determined through the initial request. However, in some situations this might not be possible (i.e. if a load balancer is used). Therefore the base URL can be specified in this field with the format PROTO://HOST, where PROTO is either http or https and HOST is the hostname respectively the domain name of the service provider.
  • Mappings for Authentication Methods
    By default, the authentication method recorded by the Fabasoft Folio webservice is “SAML”. The method can be changed based on the authentication method contained in the SAML assertion.
    • SAML Authentication Method
      Specifies the SAML authentication method contained in the SAML assertion (/samlp:Response/saml:Assertion/saml:AuthnStatement/saml:AuthnContext/saml:AuthnContextClassRef).
    • Authentication Method
      Specifies the Fabasoft Folio authentication method the SAML authentication method should be mapped to.
      By doing so, the Fabasoft Folio account activity contains the correct authentication method.
  • Additionally, the user’s security clearance can be extended based on the current authentication method by configuring a specific security class for a given authentication method.
    Create an entry in the Security Clearances for Authentication Methods field and edit the properties.
    • Authentication Method
      Specifies the Fabasoft Folio authentication method a security clearance is configured for.
    • Security Clearance
      Specifies an additional security class to be added to the security clearance of the authenticated user.

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:

  • Cookie Valid in Session
    Set the value of this property to “Yes“, if the authentication should only be valid during a user session.
  • Cookie Domain
    Set the value of this property to set the scope of the session cookie to a specific domain (e.g. “myserver.com”) or subdomains of a domain (e.g. “.myserver.com”).
  • Authentication Expires After Minutes
    Define after how much minutes the authentication of a user expires, who is actively working with the system.
    Note: Specify a value greater than 0. Otherwise the authentication will expire immediately.
  • Authentication of an Idle Session Expires After Minutes
    Define after how much minutes the authentication of a user expires, who is not actively working with the system.
    Note: Let this property unspecified or specify the value 0 if idle sessions should not expire. In this case the authentication will expire after the time specified in the previous property.

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.