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.
| 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" />
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.
| 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" />
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.
| 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" />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.
| 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.
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.
| 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. |
|
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.
| 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">
<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.
See also:
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" />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.
| 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 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.
| 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
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.
| Attribute | Description | Valid values |
| name | Key indicating the identity provider’s URL. | dari/samlCredential/{id}/identityProvider |
| 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" />
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.
| 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>.
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.
| Attribute | Description | Valid values |
| name | Key for indicating the element must be required in the SAML response. | dari/samlCredential/{id}/keyInfoRequired |
| type | Type of the value. | java.lang.Boolean |
| value | Indicates the element must be included in the SAML response. |
|
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.
| 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" />See also: