Brightspot CMS Developer Guide

Configuring Brightspot for SAML


This section explains how to configure Brightspot for SAML.


The following sections describe the available configuration keys for deploying SAML on the Brightspot server.


The key authLinkName specifies the label for SSO login in the Brightspot login widget.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey indicating the SSO link’s label.dari/samlCredential/{id}/authLinkName
typeType of the value.java.lang.String
valueLabel appearing in the login widget.Any string. Requires that the key cmsLogin be true or absent.

The following snippet specifies the label for the SSO login is Single Sign On.

<Environment name="dari/samlCredential/default/authLinkName" override="false" type="java.lang.String" value="Single Sign On" />

Authentication link name.png

See also:


The key cmsLogin indicates if the associated SAML configuration is enabled for authenticating front-end or back-end users.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for indicating login through Brightspot or through a single sign-on server.dari/samlCredential/{id}/cmsLogin
typeType of the value.java.lang.Boolean
valueIndicates editors log in through Brightspot or SSO.true—The associated SAML configuration (identified by {id}is enabled for authenticating logins into Brightspot. Furthermore, new user accounts on the identity provider also generate new editor accounts within Brightspot.
false (default)—The associated SAML configuration is enabled for authenticating logins into front-end sites.

The following snippet indicates editors see a control for logging into SSO in the Brightspot login widget.

<Environment name="dari/samlCredential/default/cmsLogin" override="false" type="java.lang.String" value="true" />

CMS login.png
Single sign-on control

See also:


When an identity provider issues an assertion, the Brightspot server must verify the assertion’s authenticity. The key class indicates which Java class performs the authentication.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for specifying the class that processes the SSO login.dari/samlCredential/{id}/class
typeType of the value.java.lang.String
valueClass that performs the SAML authentication.Fully qualified class name.

The following snippet indicates the class for verifying a SAML assertion is com.psddev.saml.SamlX509Auth.

<Environment name="dari/samlCredential/default/class" override="false" type="java.lang.String" value="com.psddev.saml.SamlX509Auth" />

See also:


You can configure more than one set of SAML credentials, and use the key defaultSamlCredential to set one of them as a default.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameSpecifies which keys are used for the default SAML configuration.dari/defaultSamlCredential
typeType of the value.java.lang.String
valueIdentifier for the default configuration.String representing a configuration identifier.

The following snippet indicates the default configuration is localsso.

<Environment name="dari/defaultSamlCredential" override="false" type="java.lang.String" value="localsso" />

In this scenario, Brightspot uses keys containing dari/samlCredential/localsso/ for the default SAML configuration.

See also:


A user’s first SAML login through Brightspot can create a new ToolUser object. The key disableNewlyProvisionedToolUsers sets the initial value of the corresponding field SamlUser.samlDisableLogin. (This key has no impact when a user is provisioned directly on the identity provider’s server.)

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for indicating the newly provisioned users can log in.dari/samlCredential/{id}/disableNewlyProvisionedToolUsers
typeType of the value.java.lang.Boolean
valueIndicates if newly provisioned users can log in.
  • true—Newly provisioned users cannot immediately log in to Brightspot. In this scenario, the Brightspot administrator must explicitly enable their logins.
  • false (default)—Newly provisioned users can immediately log in to Brightspot.

The following snippet indicates newly provisioned users cannot immediately log in to Brightspot.

<Environment name="dari/samlCredential/default/disableNewlyProvisionedToolUsers" override="false" type="java.lang.Boolean" value="true" />

See also:


Identity providers return assertions that typically include a field containing the user’s email. The key emailAttributeField specifies the name of the email field in the assertion.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey indicating the XML attribute name corresponding to the email field in a SAML assertion.dari/samlCredential/{id}/emailAttributeField
typeType of the value.java.lang.String
valueName of the XML attribute containing the authenticated user’s email address.Value of the Name attribute in the saml.Attribute element.

The following snippet is an example of a user’s email address in a SAML assertion.

<saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> 
    <saml:AttributeValue xsi:type="xs:string">user1@example.com</saml:AttributeValue>
</saml:Attribute>
  • SAML element containing the authenticated user’s email address. The attribute Name has value mail.

Referring to the previous snippet, the value for emailAttributeField is mail.

<Environment name="dari/samlCredential/default/emailAttributeField" override="false" type="java.lang.String" value="mail" />

After receiving the assertion from the identity provider, Brightspot uses the value of the email attribute field as the editor’s username. For example, if the SAML element <saml:attribute name="mail"> contains the address user1@example.com, Brightspot uses that address as the editor’s username.

Email attribution field name.png

See also:


The key entityId specifies the identity provider’s entity ID.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for specifying the identity provider’s URI.dari/samlCredential/{id}/entityId
typeType of the value.java.lang.String
valueValue indicating the identity provider’s ID.Value provided by the identity provider.

The following snippet specifies an identity provider’s entity ID is https://samltest.id/saml/sp.

<Environment name="dari/samlCredential/default/entityId" override="false" type="java.lang.String" value="https://samltest.id/saml/sp" />

See also:


When an identity provider returns an assertion, the assertion typically includes a field containing the user’s associated groups. The key groupsAttributeField specifies the name of the field containing the groups. After receiving the assertion, Brightspot uses the value in the groups field as the editor’s role. (If more than one group is returned, Brightspot uses the first one returned.) Therefore, in an SSO environment, ensure the roles on the SSO server match the roles in Brightspot.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey indicating the name of the groups field in a SAML assertion.dari/samlCredential/{id}/groupsAttributeField
typeType of the value.java.lang.String
valueName of the field containing the authenticated user’s associated groups.Any string. If absent, Brightspot uses the default name groups.

The following snippet indicates the name of the field in a SAML assertion that contains the user’s groups is usersgroups.

<Environment name="dari/samlCredential/default/groupsAttributeField" override="false" type="java.lang.String" value="usersgroups" />

See also:


In a typical SAML configuration, the control for logging in to single sign on appears in the Brightspot login widget (see the illustration "Single sign-on control"). The key hidden hides this control. If the value of this key is true, editors can display the login control using the query parameter _saml set equal to the SAML configuration ID.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for indicating the link to the SSO server appears in the Brightspot login widget.dari/samlCredential/{id}/hidden
typeType of the value.java.lang.Boolean or java.lang.String
valueIndicates if the login link appears in the Brightspot login widget.true—The SSO login control does not appear in the Brightspot login widget.
false (default)—The SSO login control appears in the Brightspot login widget. Also requires that the key cmsLogin be set to true.

The following snippet indicates the SSO login link for the SAML configuration ID default does not appear in the Brightspot login widget.

<Environment name="dari/samlCredential/default/hidden" override="false" type="java.lang.Boolean" value="true" />

Referring to the previous snippet, the SAML configuration ID is default. Editors can override the value for hidden and display the login control for this SAML configuration by using a query parameter _saml=default.

https://editor.brightspot.com/cms/?_saml=default

See also:


The key identityProviderUrl specifies the URL of the SSO server to which Brightspot redirects login requests. Within the UI, the value of this key is the link associated with the SSO login control in the Brightspot login widget.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey indicating the identity provider’s URL.dari/samlCredential/{id}/identityProvider
typeType of the value.java.lang.String
valueURL to the identity provider’s server.Any valid URL.

The following snippet indicates Brightspot redirects login requests to http://sso.example.com/idp/SSOService.php.

<Environment name="dari/samlCredential/default/identityProviderUrl" override="false" type="java.lang.String" value="http://sso.example.com/idp/SSOService.php" />

Identity provider's URL.svg

See also:


The key issuerUrl defines the value Brightspot assigns to the element <saml:issuerurl> in a SAML authorization request.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for indicating a URI for BSP (the service provider).dari/samlCredential/{id}/issuerUrl
typeType of the value.java.lang.String
valueURl for Brightspot.Any URL. Must match what the identity provider is expecting.

The following snippet indicates Brightspot’s issuer URL is http://www.brightspot.com/saml/ourURI.

<Environment name="dari/samlCredential/default/issuerUrl" override="false" type="java.lang.String" value="http://www.brightspot.com/saml/ourURI" />

At run time, Brightspot constructs the authorization request and inserts the issuer URL, as in the following snippet.

<samlp:AuthnRequest>
   <saml:Issuer>http://www.brightspot.com/saml/ourURI</saml:Issuer>
</samlp:AuthnRequest>

If issuerUrl is not explicitly configured, Brightspot inserts the tool URL as the value for <saml:issuer>.

See also:


SAML responses may (or may not) include a <ds:keyinfo> element. By default, Brightspot does not look for this element in the response. The key keyInfoRequired requires the element to be present so that Brightspot can examine it.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for indicating the  element must be required in the SAML response.dari/samlCredential/{id}/keyInfoRequired
typeType of the value.java.lang.Boolean
valueIndicates the element must be included in the SAML response.
  • true (default)—element is required.
  • false—is not required.

The following snippet indicates the <ds:keyinfo> element must be included in SAML responses.

<Environment name="dari/samlCredential/default/keyInfoRequired" override="false" type="java.lang.Boolean" value="true" />

See also:


The key idpMetaDataPath specifies the path on the Brightspot server to the identity provider’s metadata file.

The following table describes the attributes associated with this key.

AttributeDescriptionValid values
nameKey for specifying the path to an identity provider’s metadata file.dari/samlCredential/{id}/idpMetaDataPath
typeType of the value.java.lang.String
valueAbsolute path (from the host’s file system root, not the server’s root) to the identity provider’s metadata file.Any path accessible from within the server.

The following snippet indicates the location of an identity provider’s metadata file is /servers/tomcat/conf/idp_metadata.xml.

<Environment name="dari/samlCredential/default/idpMetaDataPath" override="false" type="java.lang.String" value="/servers/tomcat/conf/idp_metadata.xml" />

See also:

Previous Topic
Image editor configuration
Next Topic
Deploying SAML
Was this topic helpful?
Thanks for your feedback.
The elements that get you up and running in a matter of days, from pre-built content types, to modules, to landing pages.

Content types
Modules
Landing pages
Everything you need to manage and administer content within Brightspot CMS, including plug-and-play integrations.

Dashboards
Authoring content
Workflows
Admin configurations
A guide for installing, supporting and administering code on the Brightspot platform, including integrations requiring developer support to use.

Field types
Content modeling
Rich-text elements
Images