SAML Authentication with Mindbreeze

Installation and Setup

Mindbreeze GmbH, A-4020 Linz, 2024.

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 Mindbreeze

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

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 parties

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:

Disabling Shibboleth single sign-on

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 subject

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:

Authentication with an HTML form and Kerberos

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 certificates

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:

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:

keytool –importcert –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 LDAP

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 filter

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

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 4.x

Principal attribute release for Mindbreeze

With Shibboleth 4.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:

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

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

<!--

-->

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

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

<list>

</list>

</property>

</bean>

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

Upload and configure Metadata-Provider in Shibboleth

First, follow the steps in section "Uploading IdP Metadata" and upload the Shibboleth entity descriptor (metadata/idp-metadata.xml) to your Mindbreeze InSpire appliance. After uploading the Shibboleth entity descriptor, Mindbreeze InSpire Services will restart automatically. Please wait briefly until the Entity Descriptor is generated by Mindbreeze, you can then find it at <inspire_url>:8443/saml20/sp/entitiesdescriptor. After that you can upload the entity descriptor to your Shibboleth server for example at metadata/mindbreeze.xml. Finally, the path to the Mindbreeze Entity Descriptor in conf/metadata-providers.xml has to be set accordingly:

…

…

Configuration with Microsoft Active Directory Federation Services (ADFS)

To use SAML with ADFS (Active Directory Federation Services) in Mindbreeze, follow these steps:

Add a relying party trust in your ADFS configuration. To do this, right click “Relying Party Trust” and then “Add Relying Party Trust...” Enter the settings in the wizard below to add the relying party trust.

Upload the Mindbreeze Service Provider Entities Descriptor file here. The entities descriptor of Mindbreeze InSpire Services is accessible via the Fabasoft Mindbreeze InSpire Management Center at the URL<inspire_host>:8443/saml20/sp/entitiesdescriptor when the SAML configuration on the Mindbreeze InSpire Server is finished.

Create a name for the relying party. Multi-factor authentication can also be configured if desired.

Define the permissions for the relying party as “All users” (permit all users to access this relying party).

To finish, you need to add a claim in your ADFS configuration. If the wizard below does not open automatically, select the previously created relying party trust and right-click to select it or select “Edit Claim Rules...” from the menu on the right.

Select “Transform an Incoming Claim” from the drop-down list. Enter a name for the claim. To complete the configuration, you need to specify “Name ID” for the “Outgoing claim type” and “Unspecified” for the “Outgoing name ID format.”

Configuration with Microsoft Azure Active Directory

For configuring Microsoft Azure Active Directory as SAML identity provider, for the Mindbreeze InSpire Client an Enterprise application has to be created.

Navigate to “Azure Active Directory” > “Enterprise applications” and add a new application by clicking on the “New application” button

Select “Non-gallery application” as application type, set the name of the new application and click on “Add”

Navigate to “Manage” > “Single sign-on” and then select “SAML” for setting up SAML-based single sign on for the created application.

Now download the generated federation metadata XML for the IDP in the SAML Signing Certificate section

Install the IDP metadata in Mindbreeze as described in section “Configuring SAML in Mindbreeze” and retrieve the service provider SAML metadata from the Mindbreeze InSpire appliance using the link <inspire_url>:8443/saml20/sp/entitiesdescriptor

If the entities descriptor contains the metadata file of only one Mindbreeze InSpire client service the service provider metadata file can be directly uploaded by clicking on “Upload metadata file”

Check if the settings in the “Basic SAML Configuration” section are correctly set after the metadata file upload.

If the service provider contains multiple entity descriptors for Mindbreeze InSpire Client services, then the “Entity ID” and “Assertion Consumer Service URL” has to be set manually for the client service that is assigned to this enterprise application.

Finally assign the users who can be authenticated using this application by navigating to

“Manage” > “Users and Groups” in the application menu.

The enterprise application should be ready for being used for SAML authentication with a Mindbreeze InSpire client service.

Configuring SAML in Mindbreeze

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 certificate

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 metadata

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

The IDP metadata for Shibboleth 4.x can contain multiple certificates that can be used for assertion signing or encryption. Mindbreeze supports only one certificate for signing and encryption. It is important to edit the IDP metadata (idp-metadata.xml) before uploading. Remove all KeyDescriptor entries in the IDPSSODescriptor element that are not used for the Mindbreeze Relying Party. The used certificates can be found under shibboleth-idp/credentials. Except for the certificates credentials/idp-encryption.crt (use = "encryption") and credentials/idp-signing.crt (use = "signing"), remove the remaining KeyDescriptor entries from the idp-metadata.xml before uploading to Mindbreeze.

Note for Microsoft ADFS:

The IDP metadata can be accessed at the URL <ADFS Server>/FederationMetadata/2007-06/FederationMetadata.xml. Again, the IDP metadata can contain multiple certificates. Mindbreeze can only process one certificate at a time for signing and encrypting requests. Therefore, all KeyDescriptor entries in this file must be removed except for one per use. The KeyDescriptor entries in the IDPSSODescriptor with the attributes use="signing" and use="encryption" must remain.

...

...

</IDPSSODescriptor>

Configuring the SAML parameters

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

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 services

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 notes

“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.
SAML IDPs other than those mentioned here may not be supported. If you are using a different SAML IDP, please contact us. We are very interested in what IDPs our customers are using in order to improve support for those IDPs. One reason why your IDP's SAML configuration is not working as documented may be CORS settings. See Documentation – Mindbreeze InSpire – CORS with SAML for more information on this and possible solution to the problem.

Configuration of Principals via SAML Attributes

Mindbreeze supports the configuration of Mindbreeze principals after a successful SAML login, using SAML attributes. This allows you to customize authentication to meet your individual requirements. When a user logs in to the client service, additional roles or aliases can be sent along in the attributes of the SAML XML file.

Furthermore, it is possible to override the identity of the search user. Regex rules can be used to ensure that only desired attributes and attribute values lead to successful authentication.

Preparation

It is necessary to configure the SAML IDP so that the desired roles or aliases are included in the saml:AttributeStatement block of the SAML response to the Mindbreeze Client Service.

This also supports multiple attribute values per attribute, or multiple attributes with the same name. Here you can see an excerpt from a sample XML file:

<saml:AttributeStatement>

<saml:Attribute Name="Principal"

NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">

<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"