Configuring a self-service SAML authenticator

You can configure a SAML authenticator with any identity provider running an SSO server that supports X.509 certificates.

As a best practice, ensure users have email addresses as their usernames. You can then configure different authenticators for different email domains. For example, logins from users with an email address in the brightspot.com domain are routed to the Google Cloud Service authenticator, and logins from users with an email address in any domain outside of brightspot.com are routed to an Okta authenticator.

To configure a self-service SAML authenticator:

Obtain from the identity provider the following:
- Metadata file that Brightspot uses to verify a SAML response originated from the intended identity provider. This is an XML file starting with an EntityDescriptor element.
- Identity provider's URL to which Brightspot sends SAML requests.
- Identity provider's entity ID from the EntityDescriptor/entityID attribute.
Click menu> Admin > Sites & Settings > Sites > Global.
Click search, located to the left of more_horiz, and type Authenticators.
Under Authenticators, click add_circle_outline and select Self Service SAML Tool Authenticator.
Configure the identity provider to accept requests from Brightspot by doing the following:
1. Click View Service Provider Metadata.
  
  Displaying SAML service provider metadata
2. Use the displayed metadata to configure the identity provider as required.
Using the following table as a reference, complete the fields as needed.
Click Save.

Field	Description
Valid Domains	Enter login email domains that are routed to this authenticator. For example, if you enter `brightspot.com`, login requests from emails in the `brightspot.com` domain (such as `hello@brightspot.com`) are routed to this authenticator. Users attempting to log in using an email domain that is not specified in this or any other SAML authenticator are routed to the default authenticator (a standard username/password challenge).
Configuration	Select SAML X509.
Name	Enter a name for this SSO configuration. Brightspot uses this name in various widgets and in the `_saml` query parameter. See the `Hidden` field, below.
Auth Link Name	Enter text for the SSO label in the Brightspot login widget. If you enter `Single Sign On`, the label is `Log Into Single Sign On`. SSO login label
Identity Provider URL	Enter the identify provider's URL you obtained in step 1.
Entity ID	Enter the identity provider’s entity ID you obtained in step 1.
Idp Meta Data	Upload the identity provider’s entity metadata XML file you obtained in step 1.
Issuer URL	Enter the value Brightspot assigns to the element `<saml:issuerurl>` in a SAML authorization request.
Email Attribute Field	Enter the name of the field into which the identity provider returns a user's email. For example, if you enter `mail` in this field, the identity provider returns an XML clause similar to the following: `<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>` 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. Username from SAML email attribute
Groups Attribute Field	Enter the name of the field into which the identity provider returns a user's associated groups. Brightspot uses the value in the this 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. (For information about configuring roles, see Roles.)
Hidden	If toggled on, this SAML authenticator appears in the login widget only if the query string `_saml=PROVIDER_NAME` appears in the login URL. For example, editors typically log in to Brightspot at the URL `https://brightspot.com/cms`. If this field is toggled on, editors must log in at the URL `https://brightspot.com/cms?_saml=PROVIDER_NAME`. The value of `PROVIDER_NAME` is the value you configure for the `Name` field described above. If the `Name` field is set to `bspsso`, then editors must log in at `https://brightspot.com/cms?_saml=bspsso`.
Disable Newly Provisioned Tool Users	When a new editor successfully logs in through this SAML configuration, Brightspot creates a new account for that editor. If this field is toggled on, that new editor cannot log in to Brightspot, and an admin must manually activate the account. If this field is toggled off, the editor can log in to the new account. (This field has no impact when the editor is already provisioned on the identity provider’s server.)
Key Info Required	If this field is toggled on, Brightspot requires the identity provider to return data in a `<ds:KeyInfo>` element. If field is toggled off, the identity provider does not need to return data in a `<ds:KeyInfo>` element.
Merge Non-SAML User	This toggle determines what happens when an existing user migrates from username/password authentication to SAML authentication. If toggled on, the first time the user logs in through SAML, Brightspot ingests the identify provider's SAML settings into the user's account. For examples of those ingested SAML settings, see Reviewing a user's SAML configuration. If toggled off, the user will not be able to log in to Brightspot (even though the user passed SAML authentication).