Authentication With SAML

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 Provider

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/: new window. Apache Tomcat is available at http://tomcat.apache.org/download-55.cgi: new window.

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

Installation Steps

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:

Download the IdP software package (the shibbolethidentityprovider-*-bin.zip file).
Unzip the downloaded archive.
Prepare the servlet container (Apache Tomcat, JBoss Tomcat or Weblogic).
Change into the newly created IdP distribution directory.
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.
Deploy the IdP WAR file, located in IDP_HOME/war/, after you have properly prepared your servlet container.

The Identity Provider Directory Structure

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 Configuration

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 Configuration

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

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"
maxHttpHeaderSize="8192"
maxSpareThreads="75"
scheme="https"
secure="true"
clientAuth="want"
SSLEnabled="true"
sslProtocol="TLS"
keystoreFile="IDP_HOME/credentials/IdentityProvider.jks"
keystorePass="PASSWORD"
truststoreFile="IDP_HOME/credentials/IdentityProvider.jks"
truststorePass="PASSWORD"
truststoreAlgorithm="DelegateToApplication"
/>

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 Parties

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:

<MetadataProvider
  id="<id>"
  xsi:type="FileBackedHTTPMetadataProvider"
  xmlns="urn:mace:shibboleth:2.0:metadata"
  metadataURL="<folio_url>/saml2/metadata"
  backingFile="<backing_file_path>"
/>

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>"
  defaultSigningCredentialRef="IdPCredential"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport">
…
<ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
  includeAttributeStatement="true"
  assertionLifetime="300000"
  assertionProxyCount="0"
  signResponses="conditional"
  signAssertions="never"
  encryptAssertions="never"
  encryptNameIds="never" />
…
</DefaultRelyingParty>

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 Subject

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:AttributeDefinition
  id="userPrincipalName"
  xsi:type="PrincipalName"
  xmlns="urn:mace:shibboleth:2.0:resolver:ad"
  sourceAttributeID="userPrincipalName">
  <resolver:Dependency ref="myLDAP" />

  <resolver:AttributeEncoder xsi:type="SAML1String"
    xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
    name="urn:mace:dir:attribute-def:userPrincipalName" />

  <resolver:AttributeEncoder xsi:type="SAML2String"
    xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
    name="urn:oid:1.2.840.113556.1.4.656"
    friendlyName="userPrincipalName" />

  <resolver:AttributeEncoder
    xsi:type="SAML1StringNameIdentifier"
    xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
    nameFormat="urn:mace:shibboleth:1.0:nameIdentifier" />

  <resolver:AttributeEncoder xsi:type="SAML2StringNameID"
    xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
    nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" />

</resolver:AttributeDefinition>

<resolver:DataConnector
  id="myLDAP"
  xsi:type="LDAPDirectory"
  xmlns="urn:mace:shibboleth:2.0:resolver:dc"
  ldapURL="ldap://sqd1.sq.fabasoft.com"
  baseDN="ou=Setup-Test
  Accounts,ou=SQ,dc=sq,dc=fabasoft,dc=com"
  principal="DOMAINUSER" principalCredential="CREDENTIALS">
  <FilterTemplate>
    <![CDATA[
      (userPrincipalName=${requestContext.principalName})
      ]]>
  </FilterTemplate>
</resolver:DataConnector>

Configuration

The following settings are necessary for the configuration of SAML:

Open the Virtual Application Configuration, which is referenced in the Current Domain or Domain Type.
Click the „Authentication” tab.
The following relevant properties are available:
Proxy Settings
If a proxy is used, the configuration can be defined in this section.
- Proxy Host
  The host on which the proxy is running.
- Proxy User
  The user to be used for the proxy.
- Proxy Password
  The proxy user password.
Cookies
Note: To sign the cookie, the path to a file containing the PKCS #12 credentials must be configured. This can be done via the Private Key Path field in the SAML section. If the key is password protected, the password also has to be defined.
- 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”).
- Session Cookie
  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.
  Note: Specify a value greater than 0. Otherwise the authentication will expire immediately.
- 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.
  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.
SAML
- Activate SAML
  This property defines whether SAML is activated.
- Enable Single Logout
  This property defines whether the single logout feature is enabled.
  To use this feature, a private key must be configured.
- Require Encrypted Assertions
  This property defines that only encrypted SAML assertions are accepted.
  To use this feature, a private key must be configured.
- Sign AuthnRequests
  This property defines whether AuthnRequests are signed.
  To use this feature, a private key must be configured.
- Signature Algorithm
  This property defines the algorithm use to sign AuthnRequests and Single Logout SOAP calls.
  If not configured RSA-SHA1 is used.
- Disable ForceAuthn for Permanent Login Pairing Requests
  This property defines whether the ForceAuthn attribute is set on SAML requests for permanent login pairing requests. If the ForceAuthn attribute is disabled, the IdP should use other means to ensure these requests need user interaction for the authentication to prevent XSS attack vectors targeting the permanent login.
  This property should only be set if required for compatibility with an IdP that does not support ForceAuthn.
- 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.
- 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.
  Example: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- 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).
    Example: urn:left:rfc:1510
  - 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.
    Example: Kerberos (SPNEGO)

Optional: Configure Security Clearances for Authentication Methods

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.

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.