SAML-based Authentication with Mindbreeze

Setup and Configuration

Copyright ©

Mindbreeze GmbH, A-4020 Linz , 2017.

All rights reserved. All hardware and software names used are registered trade names and/or registered trademarks of the respective manufacturers.

These documents are highly confidential. No rights to our software or our professional services, or results of our professional services, or other protected rights can be based on the handing over and presentation of these documents. Distribution, publication or duplication is not permitted.

SAML Authentication for MindbreezePermanent link for this heading

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains, namely between identity providers (producers of assertions) and service providers (assertions consumers). In the case of Mindbreeze the assertion consumers are the Mindbreeze services (client and index services). As identity provider (IdP) we have used Shibboleth, an open source product of the Internet2 Middleware Initiative. In this document we present the installation and configuration of Shibboleth and the configuration of Mindbreeze for using SAML authentication protocol and interact with the identity provider.

InstallationPermanent link for this heading

General InformationPermanent link for this heading

The identity provider chosen is the 2.1.5 version of Shibboleth, deployed on Apache Tomcat v6.0. The installer of Shibboleth v2.1.5 is available for download at http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.1.5/ and Apache Tomcat v6.0 can be downloaded from http://tomcat.apache.org/download-55.cgi. Shibboleth 2.1.5 IdP is a standard Java web application based on the Servlet 2.4 specification and it 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 Shibboleth 2.1.5 as an identity provider in the Mindbreeze SAML infrastructure, the Apache Tomcat is strongly recommended because the particular configuration tasks are discussed in the current document only for this container and web server.

Installation StepsPermanent link for this heading

Important: Shibboleth 2.1.5 cannot be installed and run by using the GNU Java compiler and VM. For installing and deploying the IdP an alternative 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 2.1.5 on operating systems that by default are using OpenJDK, for example CentOS and other Redhat-based Linux distributions.

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

  1. Download the IdP software package from Internet2 Shibboleth Download site (the shibboleth-identityprovider-*-bin.zip file).
  2. Unzip the archive you downloaded.
  3. Prepare the servlet container: Apache Tomcat, JBoss Tomcat, Weblogic.
  4. Change into the newly created IdP distribution directory.
  5. Run install.bat on Windows or install.sh on Linux, and make sure that the environment variable JAVA_HOME is set appropriate if needed.
    This script will ask for the location of the identity provider home directory that it will create. The user executing this script must have the ability to create this directory. It is normal for the script's output to contain the message "JARs are never empty, they contain at least a manifest file"; this does not indicate a problem.
    The script also asks for the full qualified host name of the installation destination.
  6. Deploy the IdP WAR file, located in IDP_HOME/war/, after you have properly prepared your servlet container.

It is possible to check the installation status by navigating to the URL http://hostname/idp/profile/Status.

If detailed message logging is needed, make sure that the logger named "PROTOCOL_MESSAGE" is configured to DEBUG in the file conf/logging.xml.

The Identity Provider directory structurePermanent link for this heading

When the installation script has completed the identity provider home directory will have been created. This directory has the following subdirectories:

  • bin/: This directory contains various tools useful in running, testing, or deploying the IdP.
  • conf/:  This directory contains all the configuration files for the IdP.
  • credentials/: This is where the IdP's signing and encryption credential, called idp.key and idp.crt, is stored. This is the default location for the IdP's keystore, where the server stores the trusted CA certificates for certificate-based authentication.
  • lib/: This directory contains various code libraries used by the tools in bin/.
  • logs/: This directory contains the log files for the IdP.
  • metadata/: This is the directory in which the IdP will store its metadata, in a file called idp-metadata.xml. It is recommended to store any other retrieved metadata here as well.
  • war/: This contains the web application archive (war) file that needs to be deployed into the servlet container.

Configuring Tomcat for Shibboleth 2.1.5Permanent link for this heading

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

The main configuration steps are:

  • Copy the .jar files included in the identity provider source endorsed directory into Tomcat's $CATALINA_HOME//endorsed directory. Some, but not all, versions of 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 you do not have an ext directory, create it.
  • Edit the file java.security 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. Here "#" is replaced with a number one more than the last provider in the list.
  • Configure the Tomcat connector for Shibboleth. A sample connector:

<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"
/>

Here the IDP_HOME is the Shibboleth home directory and PASSWORD is the password for the identity provider's keystore, which was specified during the install.

Possible Installation Issue on Windows platforms: o.s.web.context.ContextLoader - Context initialization failed at the first start. The stack trace of this error very probable contains an UnknownHostException for a host "c". This is actually the "c" from the IdP home directory path. (ex. C:\Shibboleth-2.1.5). 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 Windows) must be run again with "not new installation" option. The created idp.war needs to be redeployed.

Configuring the Identity ProviderPermanent link for this heading

The Shibboleth configuration files can be found in <Shibboleth Home>/conf folder. To configure the identity provider for using it with Mindbreeze InSpire as service provider, the relying-party.xml and the handler.xml need to be changed. The proper configuration is discussed in details in the next sections.

Configuring Relying PartiesPermanent link for this heading

For accepting identification requests from Mindbreeze InSpire services, the Mindbreeze InSpire service provider’s metadata (entity descriptor) has to be accessible for the identity provider. The entity descriptors can be grouped in so called entities descriptor xml elements. The entities descriptor of the Mindbreeze InSpire service providers can be found at the <mesmaster_url>/saml20/sp/entitiesdescriptor URL. By default <mesmaster_url> is http://servername:23000. For Shibboleth the location of the entitiesdescriptor can be specified by defining a new metadata provider. This can be achieved by adding the following lines to relying-party.xml:

<MetadataProvider id="<provider_id>" xsi:type="FileBackedHTTPMetadataProvider"
  xmlns="urn:mace:shibboleth:2.0:metadata"
  metadataURL="<mesmaster_url>/saml20/sp/entitiesdescriptor"
  backingFile="<backing_file_path>"
/>

In the example <mesmaster_url> is the current configuration URL of the Mindbreeze InSpire application and the <backing_file_path> is the path of the xml file where the service provider metadata is locally cached on the identity provider. The type attribute of the metadata provider element is FileBackedHTTPMetadataProvider and the metadataURl attribute is the URL where the entities descriptor can be found. Make sure that the <provider_id> does not contain whitespace or special characters. To load the metadata from the defined provider the identity provider must be restarted. This type of metadata source allows the identity provider to locally store the metadata and use the local copy when for example the remote source is not available. When changes occur in the Mindbreeze InSpire configuration (new services are added, service ports are changed) the identity provider must be restarted.

Additionally, locate the element named ProfileConfiguration of the type "saml:SAML2SSOProfile" inside the relying-party.xml configuration file. Set the "encryptNameIds" attribute of this element to "never", as shown in the next example:

<ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
includeAttributeStatement="true"
  assertionLifetime="300000" assertionProxyCount="0"
  signResponses="conditional" signAssertions="never"
  encryptAssertions="conditional" encryptNameIds="never" />

Disabling Shibboleth SSOPermanent link for this heading

Shibboleth single sign on works using the PreviousSession login handler defined in handler.xml this handler, when enabled activates the identity provider’s single sign on infrastructure. In this case the SAML identity is stored in the client's session.

When only using Mindbreeze InSpire with this identity provider, this option can be turned off, so the SSO management will be entirely left to Mindbreeze InSpire. In the case of certificate-based authentication the sign-off action is practically irrelevant, but the authentication should be renewed after the expiration of the SAML session, maintained by Mindbreeze InSpire. In general case removing this handler when using the identity provider with Mindbreeze InSpire can be considered a good practice. The following lines need to be deleted (commented out) from handler.xml:

<LoginHandler xsi:type="PreviousSession">
  <AuthenticationMethod>
    urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
  </AuthenticationMethod>
</LoginHandler>

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 some features of the Mindbreeze InSpire (like file system search) it is important that the principal of the user can be retrieved from the assertion. This can be accomplished by performing the following changes in the attribute-resolver.xml, respective attribute-filter.xml files.

In attribute-resolver.xml add the following lines:

<resolver:AttributeDefinition id="principal"
  xsi:type="PrincipalName" xmlns="urn:mace:shibboleth:2.0:resolver:ad">

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

</resolver:AttributeDefinition>

Modify in the attribute-fiflter.xml the "releaseTransientIdToAnyone" filter policy. The value of the attributeID of the attributeRule element needs to be changed from "transientID" to "principal". The new filter policy element should look like:

<AttributeFilterPolicy id="releaseTransientIdToAnyone">

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

  <AttributeRule attributeID="principal">
    <PermitValueRule xsi:type="basic:ANY" />
  </AttributeRule>

</AttributeFilterPolicy>

Configuring Identity Provider for HTML form-based login and Kerberos authentication Permanent link for this heading

For form-based authentication one has to be sure that the UsernamePassword handler is enabled in handler.xml.

<LoginHandler xsi:type="UsernamePassword"
  jaasConfigurationLocation="file:///C:/Shibboleth-IdP-2.1.5/conf/login.config">

    <AuthenticationMethod>
      urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
    </AuthenticationMethod>

</LoginHandler>

This handler redirects the user to a login form. The Handler also has an attribute named jaasConfigurationLocation that specifies the location of the Java Authentication and Authorization Service (JAAS) configuration file. In this configuration file a Kerberos login module needs to be added. A sample JAAS Kerberos login module:

ShibUserPassAuth {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab="true"
    keyTab="C:\Shibboleth-IdentityProvider-2.1.5\mindidpsh2.keytab";
};

The login module's name must be ShibUserPassAuth. Inside the login module, a path to a keytab file is specified. In this case "C:\Shibboleth-IDP-2.1.5\mindidpsh2.keytab". This keytab file can be created for an account from the Kerberos domain which has HOST service principal name registered for the identity provider host machine. The keytab file will be used for accessing the Domain Controller by JAAS.

Additionally the following configuration steps are required for the Tomcat 6.0 servlet container to allow using of JAAS and Kerberos based authentication in Shibboleth 2.1.5:

  • In <Tomcat_Home>/conf/catalina.properties the following lines must be added:
    java.security.krb5.realm=<REALM>
    java.security.krb5.kdc=<domain_controller>

Here <REALM> is the current Kerberos REALM and <domain_controller> the fully qualified domain name of the Kerberos domain controller (ex. dc1.mydomain.com).

HTTPS Client Side Certificate-based Authentication with ShibbolethPermanent link for this heading

The certificate-based authentication is accomplished in cooperation with the servlet container, in our case Apache Tomcat 6.0. In this case the validation of the incoming certificates is performed by Tomcat. The subject of the SAML assertion is retrieved by the identity provider using the RemoteUser login handler, from the remoteUser parameter of the servletrequest. A sample RemoteUser login handler can be found in the handler.xml configuration file (for enabling it, needs to be uncommented):

<LoginHandler xsi:type="RemoteUser">
  <AuthenticationMethod>
    urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
  </AuthenticationMethod>
</LoginHandler>

The remoteUser parameter is set to the Common Name (CN) field of the certificate sent with the request by a servlet filter. Therefore the SSLAuthFilter.jar-archive, available from the installation medium inside the Server/(CPU_ARCH)/prerequisites folder, has to be copied to the identity provider's WEB-INF/lib directory, which usually can be found in <tomcat_home>/webapps/IDP when using Tomcat for deploying. Additionally the web.xml of the identity provider needs also be modified by registering the required servlet filter to the container's filter chain. The following lines need to be added to the web.xml's proper section:

<filter>
  <filter-name>SSLAuthFilter</filter-name>
  <filter-class>
    com.mindbreeze.tomcat.filters.ClientCertificateFilter
  </filter-class>
</filter>

    

<filter-mapping>
  <filter-name>SSLAuthFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

At this point the configuration for certificate-based authentication is from the identity provider's side finished. It must be assured that the login servlet is protected and the certificate presented is validated by Tomcat. For this the Shibboleth connector in <tomcat_home>/conf/server.xml must be changed. The default connector, as we could see in the installation process should be like:

<Connector port="8443" maxHttpHeaderSize="8192" maxSpareThreads="75"
  scheme="https" secure="true" clientAuth="want"
  SSLEnabled="true" sslProtocol="TLS"
  keystoreFile="IDP_HOME/credentials/idp.jks" keystorePass="PASSWORD"
  truststoreFile="IDP_HOME/credentials/idp.jks" truststorePass="PASSWORD"
  truststoreAlgorithm="DelegateToApplication"/>

Here the clientAuth attribute value of the Connector element has to be changed from "want" to "true", so that presenting a certificate is mandatory for the clients when accessing this port. The truststoreAlgorithm attribute should be deleted so that Tomcat’s default validation algorithm will be used. The new connector should look like this:

<Connector port="8443" maxHttpHeaderSize="8192" maxSpareThreads="75"
  scheme="https" secure="true" clientAuth="true"
  SSLEnabled="true" sslProtocol="TLS"
  keystoreFile="IDP_HOME/credentials/idp.jks" keystorePass="PASSWORD"
  truststoreFile="IDP_HOME/credentials/idp.jks" truststorePass="PASSWORD"/>

Now, for the validation of client side certificates the proper CA-certificates need to be added to the truststore. In this case that is "IDP_HOME"/credentials/idp.jks". This step can be easily accomplished using for example the keytool application contained by Sun’s  JDK distribution. After these steps, the identity provider needs to be restarted.

An example of adding a trusted CA certificate to the identity provider’s keystore using the keytool utility:

keytool –importcert –alias <certificate_alias> -keystore <idp_keystore> -file <certificate file>

In the example <certificate_alias> is a name that we assign to the imported certificate. The alias must be unique. On executing the above command from Windows Command Line or Linux shell the keystore password must be typed in.

Deleting an imported certificate can be also accomplished with keytool . The command for deleting a certificate is:

keytool –delete –alias <certificate_alias> -keystore <idp_keystore>

Shibboleth 2.1.5 - Known Issue:

There is a known issue with the Shibboleth 2.1.5 identity provider: The client certificate authentication rule currently always runs indiscriminately, rather than just when it is relevant (e.g. on back-channel SOAP requests from the SP). If a client side certificate is presented by the browser via a front-channel binding during SSO for example, it will fail. This will be addressed in an upcoming release. (https://mail.internet2.edu/wws/arc/shibboleth-users/2008-03/msg00584.html)

Workaround: In the relying-party.xml, on the SecurityPolicy element with id="shibboleth.SAML2SSOSecurityPolicy", one must simply remove the Rule element for ClientCertAuth, which is this:

<security:Rule xsi:type="security:ClientCertAuth"
  trustEngineRef="shibboleth.CredentialTrustEngine" />

HTTP BASIC Authentication against LDAP using ShibbolethPermanent link for this heading

For enabling SAML-based authentication for LDAP directory users, the identity provider must be configured to authenticate the provided credentials against a LDAP server. The authentication scenario was tested with an OpenLDAP directory server installed on CentOS 5.5 operating system and a Shibboleth 2.1.5 installation.

The authentication of an LDAP user is performed by a servlet filter similar to the case of SSL certificate-based authentication described in chapter . This filter assures that basic credentials are retrieved from the clients that are then verified against an LDAP server using JAAS login. On successful authentication a SAML assertion is sent as response with the provided username as assertion subject. In the case of SSL-based authentication, the RemoteUser login handler must be enabled as described in the previous chapter.

The main configuration steps needed to set up the SAML identity providing infrastructure for LDAP users are:

  • adding and configuring the authenticator servlet filter,
  • configuring a JAAS login module for the authenticator.

Adding the Authenticator FilterPermanent link for this heading

The value of the remoteUser request attribute that is processed by the Shibboleth RemoteUser login handler is set to the username retrieved from the basic credentials of the client. This operation is done by the BasicLDAPAuthFilter servlet filter, found in the MindbreezeAuthenticationFilters.jar-archive. The web.xml of the Shibboleth identity provider must also be modified by registering the required servlet filter to the servlet container's filter chain as in the case of SSL-based authentication. The following lines must be added to the web.xml which usually can be found in <tomcat_home>/webapps/idp in a section below the root element:

<filter>
  <filter-name>BasicLDAPAuthFilter</filter-name>

  <filter-class>
    com.mindbreeze.tomcat.filters.BasicLDAPAuthFilter
  </filter-class>

  <init-param>
    <param-name>LoginConfPath</param-name>
    <param-value><JAAS configuration path></param-value>
  </init-param>

</filter>

<filter-mapping>
  <filter-name> BasicLDAPAuthFilter </filter-name>
  <url-pattern>/Authn/*</url-pattern>
</filter-mapping>

In the filter definition the path of a JAAS login configuration file must be provided as a parameter named LoginConfPath.

Configuring a JAAS Login Module for LDAP-based AuthenticationPermanent link for this heading

In the file found in the location specified by the LoginConfPath parameter a JAAS login module configuration has to be placed. The name of this module should be ShibUserPassAuth. As login module implementation for LDAP login the com.sun.security.auth.module.LdapLoginModule can be used. A sample configuration for this module is the following:

ShibUserPassAuth {
    com.sun.security.auth.module.LdapLoginModule required
    userProvider="<ldap_url>"
    useSSL="false"
    userFilter="(&(cn={USERNAME})(objectClass=person))";
};

The userProvider parameter must be set to an LDAP URL pointing to a directory entry where the user entries are located. An example:

ldap://ldapserv.mydomain.com:389/ou=people,dc=myfolder,dc=mydomain,dc=com

The userFilter parameter specifies the search filter to use to locate a user's entry in the LDAP directory. It is used to determine a user's distinguished name. The value of this parameter is an LDAP filter string (RFC 2254). If it contains the special token "{USERNAME}" then that token will be replaced with the supplied username value before the filter is used to search the directory.

The com.sun.security.auth.module.LdapLoginModule uses SSL encrypted connection by default for accessing the LDAP server. If this is not possible, then the useSSL parameter should be set to false.

Further details on this login module can be found at:

http://java.sun.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/LdapLoginModule.html.

Configuring Mindbreeze for Using SAMLPermanent link for this heading

Setting up SAML authentication on Mindbreeze InSpire has four main steps:

  1. Add an SSL Certificate that will be used for generating the service provider metadata (SAML entity descriptors of the Mindbreeze services)
  2. Configure SAML Authenticators
  3. Configuring the parameters (SAML session timeout, the service providers metadata timeout)
  4. Enabling SAML authentication mode on the selected services (clients, index services)

The necessary controls for performing these steps can be found on the Mindbreeze InSpire configuration interface's Authentication and Certificates tabs.

Uploading SSL CertificatesPermanent link for this heading

On the Certificates tab of the Mindbreeze configuration interface upload an SSL certificate.  The uploaded certificate will appear in the Available SSL Certificates list. The chosen certificate must have an empty import password.

Uploading Identity Provider MetadataPermanent link for this heading

The entity descriptor of the identity provider is generated and stored after installing Shibboleth in the <IDP_HOME>/metadata/idp-metadata.xml file. This file needs to be uploaded here for providing the identity provider metadata to the Mindbreeze InSpire services. Before uploading the file make sure that all entries of the form http(s)://hostname:port are set correctly, since the Shibboleth installer does not always set these values correctly. On upload the file is checked if it complies with SAML 2.0 standard. If it is validated then "A valid SAML identity file is installed." is displayed as SAML ID status. Use the “Choose Cert“ combo box to select the SSL certificate of the corresponding  Shibboleth server (Upload new SSL certificates in “Certificate” tab).

Setting up the SAML ParametersPermanent link for this heading

On the SAML Settings section of the user interface two parameters can be set: session timeout and metadata timeout. The value of the session timeout indicates the lifespan of the SAML session in minutes. After the session expires the assertion is renewed. The metadata timeout specifies the number of days the generated metadata of the service providers can be considered valid by the identity provider. The timeout value will be an attribute of the service provider entity descriptors. The default values are 5 min for the session timeout and 7 days for metadata timeout.

Authenticator ListPermanent link for this heading

This list shows the IDs of all available Authenticators. An Authenticator represents an available SAML identity provider service for authentication. Use the ”Certificate” combo box to configure the used SSL  certificate.

Enabling SAML Authentication for ServicesPermanent link for this heading

In the Enable/Disable SAML Authentication section of the configuration interface a list of running client and index services is displayed. For every service configure whether SAML Authentication is used and for the client service select the used Authenticator in the combo box.

Important RemarksPermanent link for this heading

  • Index services that should be contacted by a SAML enabled Client service must have SAML support enabled.
  • When updating Mindbreeze configurations with SAML from Mindbreeze InSpire 2009 Fall Release or earlier the SAML settings are retained and the default certificate is used, yet no “Authenticator” information is displayed in the configuration UI. Please re-add the IdP Metadata in order to display “Authenticator” information.
  • Environments in which a Client Service federates search requests to remote Query Services controlled by a different Mindbreeze Management Service, it is mandatory to add the SAML IdP and certificate (also known as Authenticator) of the federating Client Service to the authenticator configuration of the Query Service’s Management interface. Both parties have to share a common certificate, therefore “Default SSL Certificate” should be avoided.
  • After changing the certificate of a configured authenticator the identity provider server should be restarted in order to refresh the metadata of the Mindbreeze services.