Support and Documentation

SAML configuration keys

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

Authentication link name

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

The following table describes the attributes associated with this key.

Attribute

Description

Valid values

name

Key indicating the SSO link's label.

dari/samlCredential/{id}/authLinkName

type

Type of the value.

java.lang.String

value

Label 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" />
saml-cms-login.png
CMS login

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.

Attribute

Description

Valid values

name

Key for indicating login through Brightspot or through a single sign-on server.

dari/samlCredential/{id}/cmsLogin

type

Type of the value.

java.lang.Boolean

value

Indicates 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" />
Single sign-on control
Figure 154. Single sign-on control


Credential class

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.

Attribute

Description

Valid values

name

Key for specifying the class that processes the SSO login.

dari/samlCredential/{id}/class

type

Type of the value.

java.lang.String

value

Class 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" />
Default SAML configuration

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.

Attribute

Description

Valid values

name

Specifies which keys are used for the default SAML configuration.

dari/defaultSamlCredential

type

Type of the value.

java.lang.String

value

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

Disable newly provisioned users

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.

Attribute

Description

Valid values

name

Key for indicating the newly provisioned users can log in.

dari/samlCredential/{id}/disableNewlyProvisionedToolUsers

type

Type of the value.

java.lang.Boolean

value

Indicates 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 as described in Enabling or disabling SSO 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" />
Email attribute field name

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.

Attribute

Description

Valid values

name

Key indicating the XML attribute name corresponding to the email field in a SAML assertion.

dari/samlCredential/{id}/emailAttributeField

type

Type of the value.

java.lang.String

value

Name 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"> 1
    <saml:AttributeValue xsi:type="xs:string">user1@example.com</saml:AttributeValue>
</saml:Attribute>

1

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.

saml-email-assertion-field.png
Entity ID

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

The following table describes the attributes associated with this key.

Attribute

Description

Valid values

name

Key for specifying the identity provider's URI.

dari/samlCredential/{id}/entityId

type

Type of the value.

java.lang.String

value

Value 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" />
Group attribute field name

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.

Attribute

Description

Valid values

name

Key indicating the name of the groups field in a SAML assertion.

dari/samlCredential/{id}/groupsAttributeField

type

Type of the value.

java.lang.String

value

Name of the field containing the authenticated user's associated groups.

Any string. If absent, Brightspot uses the default field 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" />
Hidden login control

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.

Attribute

Description

Valid values

name

Key for indicating the link to the SSO server appears in the Brightspot login widget.

dari/samlCredential/{id}/hidden

type

Type of the value.

java.lang.Boolean or java.lang.String

value

Indicates 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

Identity provider's URL

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.

Attribute

Description

Valid values

name

Key indicating the identity provider's URL.

dari/samlCredential/{id}/identityProviderUrl

type

Type of the value.

java.lang.String

value

URL 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-url.svg
Issuer URL

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.

Attribute

Description

Valid values

name

Key for indicating a URI for BSP (the service provider).

dari/samlCredential/{id}/issuerUrl

type

Type of the value.

java.lang.String

value

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

Key information required

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.

Attribute

Description

Valid values

name

Key for indicating the <ds:KeyInfo> element must be required in the SAML response.

dari/samlCredential/{id}/keyInfoRequired

type

Type of the value.

java.lang.Boolean

value

Indicates the <ds:KeyInfo> element must be included in the SAML response.

  • true (default)—<ds:KeyInfo> element is required.

  • false<ds:KeyInfo> 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" />
Path to identity provider's metadata

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.

Attribute

Description

Valid values

name

Key for specifying the path to an identity provider's metadata file.

dari/samlCredential/{id}/idpMetaDataPath

type

Type of the value.

java.lang.String

value

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