Add an Identity Provider
-
Visit your organization’s Identity Provider tool or website and create a new application.
-
In Brightspace, from Admin Tools select SAML Administration.
-
Click Add Identity Provider.
-
From the Add New Identity Provider page, collect the Brightspace Metadata URL by clicking Copy.
Note: The Brightspace Metadata URL is typically all the information that is required, however, if your application requires the contents of the Metadata URL, click See detailed metadata and collect Entity ID / Issuer, Assertion Consumer Service (ACS) / Reply URL, or All Brightspace Metadata (full XML metadata).
-
Add this information to your new application on your Identity Provider’s site.
-
In Brightspace, set the Display Name to easily identity the purpose of the registered Identity Provider. Example names include Learner Log in, Faculty Log in, or Primary Log in, although any name can be used.
-
Click Import from your Identity Provider to display the Identity Provider Application Metadata URL (optional) input, and the Import from URL button.
-
If you have a publicly accessible metadata URL available from your Identity Provider, click Import from URL. This pre-populates the following fields:
-
Entity ID / Issuer
-
Single Sign-On Service (HTTP-Redirect) URL
-
X.509 Signing Certificates
-
If you do not have a publicly accessible metadata URL available from your Identity Provider, populate the following fields manually with information from your Identity Provider:
-
Entity ID/ Issuer
-
Single Sign-on Service (HTTP-Redirect) URL
-
X.509 Signing Certificate
-
Set the User / Name ID Mapping option.
Note: The User / Name ID Mapping field is used to create a mapping between the end user’s identity provider user account and their Brightspace user account. The options include: Username, Org Defined Id, Email Address, Username or Org Defined Id. Depending on what option is chosen you must set use the appropriate format. Username and/or Org Defined Id require the unspecified Subject NameId format be used. Email Address requires the emailAddress Subject NameId format to be used.
-
Populate the optional field for Logout Redirect URL (optional). This URL is used to redirect the end user when logging out of Brightspace. D2L recommends using the URL of your organization's homepage.
-
Populate the optional field for Failed Log in Redirect URL (optional). This URL is used to redirect the end user when an SSO log in attempt fails. This overrides the standard D2L failed login error page.
-
Click Save.
Validate Identity Provider
Once an Identity Provider has been registered, the Registration Complete page displays. This page includes an overview of the Identity Provider which was created during the Add Identity Provider steps. Ensure that all of the information is accurate. If necessary, click Edit Configuration to make any required changes.
Test an Identity Provider
-
From the Registration Complete page, click Test your new Identity Provider.
-
Copy the Log in URL and attempt to load the page from your browser.
-
Confirm that you are being successfully logged in to the correct page.
If it is necessary to make changes to an existing registered Identity Provider, on the SAML Administration page, click on the name of the identity provider you need to edit. Common update tasks include updating the Log out Redirect or Failed Log in Redirect URL, or manually adding a new X.509 Signing Certificate.
The Manage Identity Provider page displays an overview of the registered identity provider along with options to Edit Configuration, Add New Certificate, and Delete Identity Provider.
Selecting Edit Configuration, allows you to perform the following tasks:
-
Edit the Display Name
-
Edit the Single Sign-On Service (HTTP-Redirect) URL
-
Change the selected User / Name ID Mapping
-
Add, Edit, Remove the Log out Redirect URL
-
Add, Edit, Remove the Failed Log in Redirect URL
Ensure you save all changes when updates are complete.
Note: If a publicly accessible metadata URL was provided to initially register the Identity Provider, it cannot be updated or removed. This is intentional.
Note: If a mistake was made when manually entering the Entity ID / Issuer, this cannot be changed. The Entity ID is the unique identifier of the client’s Identity Provider, therefore the appropriate action is to delete the registered Identity Provider and start the registration process over again with the correct Entity ID.
Selecting Add Certificate, allows you to add a new X.509 Signing Certificate. For any Identity Provider that has been manually registered (not pre-populated leveraging a publicly accessible metadata URL), periodic certificate renewals are required to maintain SAML SSO functionality. Registering a new X.509 Signing Certificate for an existing registered Identity Provider can be performed from the Manage Identity Provider page as well.
Adding a new X.509 Signing Certificate can be performed by either clicking Add new Certificate on the Manage Identity Provider page, or by clicking the Add new Certificate button under the Manage Certificates subheading.
-
On the Add New Certificate page, paste your certificate information in the X.509 Signing Certificate field.
-
Ensure the Valid From dates and all other information is correct and click Save.
For any Identity Provider that has been manually registered (not pre-populated leveraging a publicly accessible metadata URL), periodic clean-up of expired certificates is a recommended best practice.
Note: If the Identity Provider was registered using a publicly accessible metadata URL, any expired certificates are deleted by the nightly recurring task.
-
On the Manage Identity Provider page, click on the certificate to access the View Certificate page.
-
Click Delete Certificate and confirm the deletion by clicking Proceed.
If your organization is switching from one Identity Provider to another (for example, ADFS to Azure), or if you incorrectly registered the Identity Provider (for example, an incorrect Entity ID) during the initial registration it may be necessary to delete an existing Identity Provider.
-
On the Manage Identity Provider page, click Delete Identity Provider.
-
A confirmation displays, click Delete to complete the deletion of the Identity Provider and any registered X.509 Signing Certificates associated to it.
Note: Once deleted, an identity provider cannot be restored.
Troubleshooting
At the bottom of the Registration Complete page is the Common Troubleshooting Issues area, which contains the detailed requirements necessary for SSO to function based on the selected User / Name ID Mapping.
If issues arise when testing a registered Identity Provider, on the SAML Administration main page there is a Troubleshoot Issues by Enabling SAML Logging card. Clicking Enable Logs captures additional debug, information, and warning log messages related to SAML SSO, and are viewable in the System Log.
The default amount of time specified is 24 hours, but this can be overridden or disabled.