--- title: "Brainspace SAML Configuration" slug: "brainspace-saml-configuration" tags: ["SAML", "os configuration", "adfs", "endpoints", "installation", "url"] updated: 2025-02-13T23:18:32Z published: 2025-02-13T23:18:32Z canonical: "docs.revealdata.com/brainspace-saml-configuration" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.revealdata.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. Configuring *SAML Authentication*** For this step, follow either the Brainspace 7 or Brainspace 6 instructions below: #### Brainspace 7 - Edit Configuration in custom.yml If using Brainspace 7, uncomment and edit the SAML configuration lines in the file: custom.yml in the following location: *~/.brainspace-configs* *BRAINS_APP_PROP___authentication__type=SAML* *BRAINS_APP_PROP___saml__brains_url=https://brainspace7.domain.com* *BRAINS_APP_PROP___saml__identifier=brainspace* *BRAINS_APP_PROP___saml__federation_metadata_xml_url=https://some.domain.com/realms/brainspace-corp/protocol/saml/descriptor* *BRAINS_APP_PROP___saml__redirect_login_url=https://some.domain.com/realms/brainspace-corp/protocol/saml* After setting up the configuration in custom.yml you will need to redeploy the Brainspace stack by running the ./install.sh script and selecting the “**Upgrade**” option. ![](https://cdn.us.document360.io/3e21d801-ca9f-4c51-93db-9cbd32741f3d/Images/Documentation/installation--upgrade-guide---brainspace-7-image-b65svn0c.png) This option can be used whenever configuration changes are made from command line and the services need to be updated to use the new configuration. Now navigate to the Brainspace UI and you should be redirected to the IDP configured in the SAML settings. #### Brainspace 6 - Set Fields in brainspace.properties If using Brainspace 6, configure SAML using the brainspace.properties file. 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: | Environment: | Brainspace Base URL | https://brainspace01.ediscovery.com/ | | --- | --- | --- | | ADFS Service Base URL | https://adfs.ediscovery.com/ | | | SAML Configuration: | SAML Identifier: | brainspace01 | | --- | --- | --- | | SAML Consumer URL | https://*brainspace01.ediscovery.com*/rest/session/saml-auth/ | | | SAML Redirect Login URL: | https://*adfs.ediscovery.com/adfs*/ls/IdpInitiatedSignon.aspx?loginToRp=brainspace01 | | | Federation Metadata URL: | https://*adfs.ediscovery.com.com*/FederationMetadata/2007-06/FederationMetadata.xml | | #### ## 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: ![](https://cdn.us.document360.io/3e21d801-ca9f-4c51-93db-9cbd32741f3d/Images/Documentation/brainspace-saml-configuration-image-ytl0b2ha.png) Relaying Trust Properties - Identifiers ![](https://cdn.us.document360.io/3e21d801-ca9f-4c51-93db-9cbd32741f3d/Images/Documentation/brainspace-saml-configuration-image-k50vhay4.png) Relaying Trust Properties - Endpoints ![](https://cdn.us.document360.io/3e21d801-ca9f-4c51-93db-9cbd32741f3d/Images/Documentation/brainspace-saml-configuration-image-oy22b4qh.png) 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 ## Related - [Installation Upgrade Guide - Brainspace 7](/installation-upgrade-guide-brainspace-7.md) - [Brainspace 6 to 7 Migration Guide](/brainspace-6-to-7-migration-guide.md) - [Changing Session Timeout Value](/changing-session-timeout-value.md)