Brainspace SAML Configuration

Introduction

Brainspace 6.0 supports basic SAML 2.0 authentication. When SAML authentication is enabled, all users must authenticate via SAML and local password authentication is disabled.

Brainspace SAML authentication works with the following identity providers (IDPs):

• Microsoft AD FS

• Duo Access Gateway

• Entrust GetAccess

• Optimal

• Azure AD Enterprise SSO (Brainspace Versions 6.5 and greater)

• Keycloak (Brainspace Versions 6.5.2 and greater)

• OKTA (Brainspace Versions 6.5.2 and greater)

Preparation

Required Information

The following information is required to configure SAML authentication:

SAML Identifier:

The SAML identifier configured in Brainspace must match the identifier configured on your IDP.

SAML Federation Metadata URL or File:

The SAML federation metadata must be available via an HTTPS URL or as an XML file stored locally on the Brainspace Application server. If a URL is used, the Brainspace Application server must be able to reach this URL.

SAML Redirect Login URL:

The SAML redirect login URL is the IDP endpoint where users will be redirected from Brainspace for SAML authentication. Any URL parameters required by the IDP (such as SAML identifier) must be explicitly added to this URL in the configuration (examples below).

Brainspace SAML Service URL:

The Brainspace SAML authentication endpoint where the IDP will send users after successful authentication. This is a specific path added to the normal Brainspace URL that users access.

Installation Procedure

SAML authentication is available in all Brainspace installation types, and there are no special installation steps.

1. Force Password Change

Check the Existing Users in Brainspace for "Force Password Change". Ensure that ALL existing users in Brainspace do NOT have "Force Password Change" enabled before enabling SAML.

2. Create SAML Users in Brainspace

SAML users must already exist in Brainspace before they will be able to login. Each user’s email address in Brainspace must match the email address returned by the IDP. Note that the address is CASE SENSITIVE and must match exactly.

Important

At least one user should be configured in Brainspace with system level permissions before changing the authentication type to SAML.

3. Configure the IDP (ADFS, Duo, Azure, Etc.)

The specific steps required to configure different IDPs vary – consult your IDP’s software documentation for specific instructions.

SAML Identifier

The SAML identifier configured must match on the IDP and in Brainspace.

Claim Rules - NameID Mapping

In the IDP configuration the NameID mapping must be the user’s email address, and should match the email address configured for each user in Brainspace.

SAML Consumer URL

The Brainspace SAML consumer URL where users are redirected after successful authentication is in the following format:

https://brainspace.example.com/rest/session/saml-auth/

Additional Considerations

Brainspace supports basic SAML 2.0 protocol authentication tokens.

4. Configure Brainspace

The following fields are required in /var/lib/brains/.brainspace/brainspace.properties to enable SAML authentication:

authentication.type:

Set the authentication type to SAML (default is local PASSWORD).

Example:

authentication.type=SAML

saml.identifier

A name that corresponds to SP/application identifier setting on the IDP.

Example:

saml.identifier=MyIdentifier

saml.federation_metadata_xml_url

The SAML federation metadata can be provided via HTTPS or local file.

Examples:

saml.federation_metadata_xml_url=file:///var/lib/brains/.brainspace/FederationMetadata.xml

saml.federation_metadata_xml_url=https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

saml.redirect_login_url

The URL where users will be redirected from Brainspace for SAML authentication. Any required URL

parameters must be specified here (static).

Example:

saml.redirect_login_url=https://adfs.example.com/adfs/ls/IdpInitiatedSignon.aspx?loginToRp=Brainspace

saml.userid.fieldname (optional)

The SAML Claims field name to use for the Brainspace login. Defaults to "Name ID"

Example:

saml.userid.fieldname=email

saml.brains_url (Optional, Brainspace => 6.5)

The URL where users access the Brainspace UI. This is an optional parameter used to force the redirect back to the correct Brainspace instance after login. This parameter should only be used in environments where a proxy or URL re-write is causing the Brainspace HOST header to be modified.

Example:

saml.brains_url=https://brainspace.example.com

5. Restart Brainspace Services

After making changes to the brainspace.properties file, the application service must be restarted to enable the changes:

Brainspace 6.0 to 6.1.X:

systemctl stop tomcat

systemctl start tomcat

Brainspace 6.2 and up:

systemctl stop brainspace-platform

systemctl start brainspace-platform

Example Configuration

Consider the following example scenario:

ADFS Configuration

Using the ADFS MMC Snap-in, create a Relaying Party Trust for your Brainspace instance using the steps below:

1. Add a new "Relaying Party Trust"

• Add Relaying Party Trust Wizard:

  1. Welcome: Select "Claims Aware" and Click "Start".

  2. Select Data Source: Select "Enter Data about Relaying Party Manually" and Click "Next".

  3. Specify Display Name: Enter a display name. This can be the Identifier or any naming convention that meets your ADFS standards. Click "Next".

  4. Configure Certificate: If your organization requires a certificate, add it here, otherwise leave it empty and Click "Next".

  5. Configure URL: Enable support for the SAML 2.0 WebSSO protocol and enter the Brainspace SAML Consumer URL. Click "Next".

  6. Configure Identifiers: Add the SAML Identifier for your Brainspace Instance. (example: brainspace01). Click "Next".

  7. Choose Access Control Policy: Configure as per your organization's specifications. This will determine which ADFS users will be allowed to login to Brainspace, However the user's will still need to be created in Brainspace before authentication will be successful.

  8. Ready to Add Trust: Click "Next".

  9. Finish: Enable the "Configure claims issuance policy for this application". Click "Close".

1. Edit Claims Issuance Policy for brainspace01.

   1. Click "Add Rule" Add Transform Claim Rule Wizard:

      1. Choose Rule Type: Select "Send LDAP Attributes as Claims" and Click "Next".

      2. Configure Claim Rule:

      • Claim Rule Name: NameID

      • Attribute Store: Active Directory

      • Mapping of LDAP attributes to outgoing claims:

      • LDAP Attribute: E-Mail-Address

      • Outgoing Claim Type: Name ID

      • Click "Finish".

   2. Click "Ok".

When completed, your Relaying Party Trust should look like this:

Relaying Trust Properties - Identifiers

Relaying Trust Properties - Endpoints

Claims Rules - NameID

Brainspace Configuration

Add the following to /var/lib/brains/.brainspace/brainspace.properties

authentication.type=SAML

saml.identifier=brainspace01

saml.federation_metadata_xml_url=https://adfs.ediscovery.com.com/FederationMetadata/2007-06/FederationMetadata.xml

saml.redirect_login_url=https://adfs.ediscovery.com/adfs/ls/IdpInitiatedSignon.aspx?loginToRp=brainspace01