SAML Authentication with Mindbreeze

Installation and Setup

Copyright ©

Mindbreeze GmbH, A-4020 Linz, 2018.

All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.

These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.

For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.

SAML authentication with MindbreezePermanent link for this heading

SAML (Security Markup Language) is an XML-based standard for authentication and authorization between identity providers (IdP, manufacturers of assertions) and service providers (assertion consumers) in a security domain. Fabasoft Mindbreeze Enterprise services, such as index and client service, are service providers. Mindbreeze uses the open source product Shibboleth, the Internet-2-Middleware Initiative, as the identity provider. The following is a description with instructions for installing and configuring Shibboleth and the SAML configuration in Fabasoft Mindbreeze Enterprise.

Identity provider configuration for Shibboleth 2.xPermanent link for this heading

The Shibboleth configuration files are located in the installation directory under conf. To use Shibboleth with Fabasoft Mindbreeze InSpire, you need to change the files relying-party.xml and handler.xml. The next two sections explain the necessary steps.

Configuring the relying partiesPermanent link for this heading

In order for the IdP to accept authentication requests from Fabasoft Mindbreeze Enterprise services, the metadata for the services (entity descriptor) needs to be accessible for the IdP. The metadata is defined in an XML document. The entity descriptor of Fabasoft Mindbreeze Enterprise services can be accessed via the Fabasoft Mindbreeze Inspire Management Center, using the URL <inspire_url>:8443/saml20/sp/entitiesdescriptor. This URL has to be entered as follows in the file relying-party.xml of the Shibboleth configuration:

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

<mesmaster_url> must be replaced by the URL of Fabasoft Mindbreeze Enterprise master, and <backing_file_path> specifies the path where the metadata is cached for faster access. Please note that in <provider_id>, no spaces or other special characters are allowed. The server must be restarted after configuration. You also have to restart Shibboleth if the entity descriptor on the Fabasoft Mindbreeze Enterprise master changes.

In addition, the SAML2SSOProfile in the file relying-party.xml must have the encryptNameIds attribute set to “never” as shown in the following example:

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

Disabling Shibboleth single sign-onPermanent link for this heading

Shibboleth uses HTML cookies for single sign-on. If only Fabasoft Mindbreeze Enterprise is operated with this identity provider, this option can be disabled. This ensures that the validity of a session is determined solely by the Mindbreeze Client Service session duration. To do this, the following lines in handler.xml must be commented out or deleted:

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

    </
AuthenticationMethod>
</
LoginHandler>

Using the name of the logon user as the assertion subjectPermanent link for this heading

By default, Shibboleth uses a generated ID as the assertion subject. Since some functions in Fabasoft Mindbreeze Enterprise (e.g. searching the file system) require the name of the logon user, Shibboleth is configured so that that name is transmitted as the assertion subject. To do this, the following changes must be made to attribute-resolver.xml and attribute-filter.xml:

  • Add the following lines to attribute-resolver.xml:

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

  • Change the "releaseTransientIdToAnyone" filter policy in attribute-filter.xml. The value of the attributeId attribute must be changed from “transientId” to “principal.” After the change has been made, the filter policy should look like this:

    <AttributeFilterPolicy id="releaseTransientIdToAnyone">
      <
PolicyRequirementRule xsi:type="basic:ANY" />
      <
AttributeRule attributeID="principal">
        <
PermitValueRule xsi:type="basic:ANY" />
      </
AttributeRule>
    </
AttributeFilterPolicy>

Authentication with an HTML form and KerberosPermanent link for this heading

To enable forms-based authentication, the username/password handler must be configured in handler.xml.

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

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

    </
AuthenticationMethod>
</
LoginHandler>

The handler allows users to log on using the logon form. The attribute jaasConfigurationLocation specifies the configuration file of Java Authentication and Authorization (JAAS). In this configuration file (C:/Shibboleth-idp/conf/login.config), the Kerberos login module must be entered as shown in the following example:

ShibUserPassAuth {

    com.sun.security.auth.module.Krb5LoginModule required

    useKeyTab="true"

    keyTab="C:\Shibboleth-IDP-2.1.5\mindidpsh2.keytab";

};

The name of the login module must be “ShibUserPassAuth.” The keytab file contains the credentials of the Shibboleth service user.

Additionally, if you are using Tomcat, the following lines must be added to the configuration file <TOMCAT_HOME>/conf/catalina.properties:

java.security.krb5.realm=<REALM>

java.security.krb5.kdc=<domain_controller>

<REALM> should be replaced by Kerberos REALM and <domain_controller> should be replaced by the fully qualified domain name of the Kerberos domain controller (e.g. dc1.mydomain.com).

Authentication with HTTPS client certificatesPermanent link for this heading

The client certificates are validated using the servlet container. To retrieve the assertion subject, Shibboleth uses the RemoteUser login handler. This is configured in handler.xml; for example:  

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

  </
AuthenticationMethod>
</
LoginHandler>

The common name (CN) field of the certificate is used as the user name. In addition, the SSLAuthFilter must be installed and configured in the servlet container. To do this, copy the SSLAuthFilter.jar archive available on the installation media under Server/(CPU_ARCH)/prerequisites into the WEB-INF/lib directory of the Shibboleth web application and enter the following lines in the appropriate section of web.xml:

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

In addition, the standard Tomcat connector has to be reconfigured. The clientAuth attribute must be changed from “want” to “true” and the truststoreAlgorithm attribute has to be deleted. After the changes, the 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"/>

The CA certificates used for validation must be imported into the TrustStore. For example, you can use the program keytool, which is installed with Java:

keytoolimportcert –alias <certificate_alias> -keystore <idp_keystore> -file <certificate file>

<certificate_alias> is assigned to the imported certificate as a unique name. When the command is executed, the KeyStore password is required.

To remove a certificate from the KeyStore, execute the following command:

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

After that, the identity provider needs to be restarted.

Authentication using HTTP BASIC against LDAPPermanent link for this heading

To enable SAML-based authentication for users from an LDAP directory, the identity provider must be configured so that it checks the user name/password pair against the LDAP server.

To authenticate an LDAP user, a special servlet filter is required (similar to the scenario with SSL client side certificates in chapter ). This filter sends an HTTP BASIC challenge to the client and checks the entered data against an LDAP server using JAAS login. If this login is successful, a reply is sent to the client with the entered username as the “assertion subject.” The RemoteUser login handler has to be enabled just like in the previous scenario.

For further configuration of the identity provider, you will need to follow these steps:

  • Adding and configuring the servlet filter
  • Configuring the JAAS login module for the authenticator

Adding the servlet filterPermanent link for this heading

The value for the “RemoteUser” attribute required by the Shibboleth RemoteUser login handler is taken directly from the username of the HTTP Basic challenge. This is done by a servlet filter called BasicLDAPAuthFilter, which is included in the MindbreezeAuthenticationFilters.jar package. The Shibboleth servlet configuration file web.xml must be adapted accordingly so that the abovementioned filter is added to the normal filter chain. The following lines are required in the <tomcat_home>/webapps/idp/web.xml file:

<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 addition, the path to a JAAS login configuration file must be set in the LoginConfPath parameter.

Configuring a JAAS login module for LDAP authenticationPermanent link for this heading

In the JAAS login configuration file (as described above), a JAAS login module is configured for the identity provider. The module must be named ShibUserPassAuth; com.sun.security.auth.module.LdapLoginModule can be used as the class for LDAP login. A sample configuration looks like this:

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

An LDAP URL that refers to the user objects that are administered in the LDAP must be entered here as the userProvider. Here’s an example:

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

The userFilter parameter specifies a search filter to find the user entry in the LDAP directory and is used to isolate the user’s DN. The syntax is similar to LDAP filter strings (RFC 2254). The substring {USERNAME} is thereby replaced by the user name entered in the Basic dialog before the filter is applied.

The login class com.sun.security.auth.module.LdapLoginModule uses SSL-encrypted connections by default to log in to the LDAP server. If an SSL connection is not possible, you can disable it with the useSSL parameter.

For more information on configuration, see:

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

Identity provider configuration for Shibboleth 3.xPermanent link for this heading

Principal attribute release for MindbreezePermanent link for this heading

With Shibboleth 3.x it is important that the attribute that is used as the SAML NameID is released for the Mindbreeze InSpire relying party. To do this, add the following lines to the <idp_home>/conf/attribute-filter.xml configuration file:

<AttributeFilterPolicy id="mesuid">

        <PolicyRequirementRule xsi:type="Requester" value="<mes_relying_party_id>" />

        <AttributeRule attributeID="uid">

            <PermitValueRule xsi:type="ANY" />

        </AttributeRule>

   </AttributeFilterPolicy>

Replace the “<mes_relying_party_id>” with the SAML entity ID of the Mindbreeze InSpire client services. In this example, the “uid” attribute is used as the SAML principal.

Configuring the SAML Subject NameID generatorPermanent link for this heading

A NameID generator must be defined for the “uid” attribute that has been released. In the <idp_home>/conf/saml-nameid.xml configuration file you will find the "<util:list id="shibboleth.SAML2NameIDGenerators">" element. Add

“shibboleth.SAML2AttributeSourcedGenerator” to the list with the following settings:

<util:list id="shibboleth.SAML2NameIDGenerators">

        <ref bean="shibboleth.SAML2TransientGenerator" />

        <!-- Uncommenting this bean requires configuration in saml-nameid.properties. -->

        <!--

        <ref bean="shibboleth.SAML2PersistentGenerator" />

        -->

        <bean parent="shibboleth.SAML2AttributeSourcedGenerator"

            p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"

            p:attributeSourceIds="#{ {'uid'} }" />

    </util:list>

The previously released “uid” attribute is used as the source here.

Setting the SAML NameID format for Mindbreeze InSpirePermanent link for this heading

Add the following element to the “shibboleth.RelyingPartyOverrides” list in <idp_home>/conf/relying-party.xml:

    <bean parent="RelyingPartyByName" c:relyingPartyIds="<mes_relying_party_id>">

            <property name="profileConfigurations">

                <list>

                    <bean parent="SAML2.SSO" p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />

                </list>

            </property>

     </bean>

Replace the “<mes_relying_party_id>” with the SAML entity ID of the Mindbreeze InSpire client services.

Configuring SAML in MindbreezePermanent link for this heading

Configuring SAML in Mindbreeze is a four-step process:

  • Adding an SSL certificate that is used to generate the service provider metadata
  • Configuring the SAML authenticator
  • Configuring the parameters (“session timeout” and “metadata timeout”)
  • Activating SAML for individual services

The configuration is performed in the “Authentication” tab.

Adding an SSL certificatePermanent link for this heading

You can add SSL certificates in the Certificates tab. The certificate to be added must have an empty “import password” and is displayed in the list of Available SSL Certificates after it is added.

Uploading IdP metadataPermanent link for this heading

After installing Shibboleth, the IdP entity descriptor is located in the installation directory under metadata/idp-metadata.xml. This allows Fabasoft Mindbreeze Enterprise services to access the IdP. Check the http(s)://host:port entries before uploading, since they are not always correctly adjusted during the installation of Shibboleth. During the upload, the system checks whether the document complies with the SAML 2.0 standard. After a successful check, you will see the message “A valid SAML identity file is installed” by the “SAML ID status.” Use the “Choose Cert” selection box to select the SSL certificate of the corresponding Sibboleth server (you can import new SSL certificates in the Certificates tab).

Note for Shibboleth 3.x:

The IDP metadata for Shibboleth 3.x can contain multiple certificates that can be used for assertion signing or encryption. It is important that the IDP metadata is edited before uploading and that the KeyDescriptor entries that are not used for the Mindbreeze relying party are removed from the IDPSSODescriptor element.

Configuring the SAML parametersPermanent link for this heading

The parameters “session timeout” and “metadata timeout” can be set in the “SAML Settings” section. “Session timeout” specifies the duration of a SAML session in minutes. At the end of this time, the assertion is renewed. “Metadata timeout” is used to determine the number of days that the metadata of the service provider is valid for the identity provider. The default configuration is five minutes for “session timeout” and seven days for “metadata timeout.”

“Authenticator” listPermanent link for this heading

This list shows all available “Authenticator” IDs. An authenticator corresponds to an identity provider service that is available for authentication. Use the “Certificate” selection box to select the certificate used.

Activating SAML for individual servicesPermanent link for this heading

For index services and client services, you can enable the use of SAML using checkboxes in the “Enable/Disable SAML Authentication” section. Select the appropriate authenticator for each enabled client service in the selection box.

If SAML authentication is enabled for a client service, the “External URL” parameter must be set to the external URL of the client service in the client service configuration. The external URL parameter determines the base URL for the SAML service provider endpoints.

Important notesPermanent link for this heading

  • “Use SAML Authentication” must be enabled for the indexes that are to be contacted by a client service configured with SAML.
  • For 2009 Fall Release updates of Fabasoft Mindbreeze Enterprise or earlier in which SAML authentication was used, the existing IDP metadata and default values for the certificates are used. However, no authenticator is displayed in the configuration. This can be changed by reloading the metadata.
  • In environments in which a client service refers to query services of a remote Mindbreeze installation, the client service’s SAML IdP and certificate (jointly referred to as the authenticator) must also be set up in the remote station’s configuration. The query service accepts all configured SAML IdPs, which means that no further configuration is required here. Please note that both endpoints must use the same IdP and identical certificates, therefore the “Default SSL Certificate” should not be used.
  • If an SSL certificate is added and changed on an authenticator, the identity provider should be restarted so that the changed metadata is reloaded.