SaaS administrators, you're in the right place!
Self- and Managed-Hosting administrators, view SAML information specific to hosted deployments.
About Security Assertion Markup Language (SAML)
Security Assertion Markup Language (SAML) is an XML-based data format that can be used to authenticate and authorize users between separate systems. SAML is frequently used as a Single Sign-On (SSO) solution, including for Blackboard Learn. When properly installed and configured, SAML allows Blackboard Learn users to log in using their username and password from another institution or application. SSO saves time for both administrators and users by providing a seamless integration for logging in.
User information is passed between systems in a SAML assertion. The identity provider is the third-party host of the user's account and your Blackboard Learn instance acts as the service provider. The identity provider sends attributes that Blackboard Learn uses to create or update an account for the user. These attributes can include information such as the username, first name, last name, and email address, and are packaged in a security token such as a SAML assertion. The identity provider sends this SAML assertion to Blackboard Learn when the user enters their login information using single sign-on. If their username doesn't match anything in the system, Blackboard Learn creates a new account with the user attributes contained in the SAML assertion.
The SAML Building Block simplifies configuration of SSO. After you activate the Building Block, a new authentication type appears in the Create Provider list on Admin Panel > Authentication, which allows you to configure the service appropriately.
The SAML Building Block is bundled with Blackboard Learn SaaS and Blackboard Learn 9.1 Q2 2016+.
The SAML Building Block establishes a single connection between Blackboard Learn and an identity provider. You can create multiple SAML authentication provider entries to connect to multiple identity providers. Additionally, SAML doesn't fully replace the Blackboard Learn login workflow. Users can log in to Blackboard Learn using their credentials as normal, if they prefer.
Activate the SAML Building Block
If you are using Blackboard Learn on a SaaS Deployment, you don't need to install the building block, as it is already present on your system.
- Navigate to the Admin Panel.
- Under Integrations, select Building Blocks.
- Select Installed Tools
- Locate Authentication Provider - SAML in the list and set its status as available.
- On the Admin Panel, under Integrations, select Authentication.
- SAML now appears in the Create Provider list on the Authentication Provider page.
Configure settings
You can configure settings to troubleshoot issues or ensure the security of your SAML connection.
- Navigate to the Admin Panel.
- Under Integrations, select Building Blocks.
- Select Installed Tools.
- Locate Authentication Provider - SAML in the list. Open the menu and select Settings. You have the following options:
- Regenerate Certificate: Select Regenerate to regenerate the SAML certificate. You may need to regenerate a certificate to keep your connection secure, or if the certificate has expired.
After you regenerate the certificate, you need to re-upload the Service Provider metadata to the Identity Provider. When you select Regenerate, the system prompts you to confirm this step.
If you generate a new certificate under the B2 settings, you need to toggle the SAML B2 to Inactive and then back to Active to force the change. After, you can return to the provider settings and generate the new metadata to import into the IDP. If you don't toggle the settings, the old certificate may still be included when you generate new metadata. The IDP won't be updated and the next time Learn restarts it will present the new certificate. SAML authentication will break because of this mismatch.
- Assertion Expiration Settings: In this section, you can adjust the Expiration time (ResponseSkew) and the SAML session age limit. You may need to edit the ResponseSkew value if your Blackboard Learn server is in a different time zone than the Identity Provider's server. The time difference can cause SAML assertions to expire before users are properly authenticated. SAML sessions expire in the time length in SAML session age limit. Select Don't limit session age if you want to allow sessions to never expire.
- Signature Algorithm Settings: Choose a signature algorithm type that meets your security needs or as required by Identity Providers. After you select the Signature Algorithm Type, restart the SAML building block to apply the new settings.
- Regenerate Certificate: Select Regenerate to regenerate the SAML certificate. You may need to regenerate a certificate to keep your connection secure, or if the certificate has expired.
- Select Submit to save your changes.
Create and configure a SAML authentication provider
- Select the Create Provider button and select the SAML authentication provider type.
- Type a name and optional description for the provider.
- Set the Authentication Provider Availability to Active.
- Set the User Lookup Method to Username or Batch UID.
- Set Restrict by hostname to Use the provider for any hostnames.
- If desired, select Restrict this provider to only the specified hostname. Type the hostname in the Restricted Hostnames field that follows.
- In the Link Text field, type the title for the link as you want it to appear on the Blackboard Learn login page.
- You can also add an icon to the login page, if desired. Select Browse to upload an icon for the login page.
- Select Save and Configure to continue.
On the SAML Authentication Settings page, you set up the service provider and identity provider settings so they establish a trusted connection. The identity provider is the third-party host of the user's account and your Blackboard Learn instance acts as the service provider.
Service provider settings
- The Assertion Consumer Service URL is shown in the ACS URL field. An identity provider may request this URL to complete configurations on their end.
- Type a name for the Entity ID. This ID will be populated into the Service Provider Metadata.
- Select the Enable automatic SSO checkbox to allow users to bypass the Blackboard Learn login screen if they've already logged in to a trusted identity provider.
- In the Single Logout Service Type section, there are three checkboxes. Select Post and Allow ADFS LogoutResponse if ADFS is the Identity Provider. When Allow ADFS LogoutResponse is selected, a user’s Identity Provider session ends when they log out of Blackboard Learn.
- In order to set up a trusted connection, you need to share your metadata with the identity provider. Select the Generate button next to Service Provider Metadata.
- Share the metadata with the identity provider. After they save the metadata on their side, the trusted connection is set up.
- Select a Data Source for this authentication provider. The data source is the source of accounts that are provisioned by this authentication provider. The default value is Internal. It is recommended that you create a specific data source for use with a SAML authentication provider.
This topic is in the Self- and Managed-Hosting section. When you're finished, use your browser's back function to return here.
- In the Compatible Data Sources list, select the data sources that this authentication provider should be compatible with. This is important when the authentication provider contains accounts that are shared with existing data sources. If the user exists and is associated with a data source that is not ticked the user will not be successfully authenticated.
- Select the checkbox to have the system automatically create a new account for the user if their information is not found.
- In the Error Message text box, you can provide a custom message for users in case SAML authentication doesn't work as expected.
Identity provider settings
- If you select Point Identity Provider, upload the identity provider's metadata file that they shared with you. You have the option to enter the identity provider's metadata URL, but it is recommended to upload the metadata file. Only one of these metadata versions is persisted in the system.
- If you select Identity Federation, a field appears where you can enter the Discovery Service URL.
After configuration, you also need to register your service provider metadata to the Federation Community, such as InCommon, UK Federation, etc.
Map SAML attributes
- Configure the SAML Attributes so they map appropriately with the identity provider's attribute definitions. If an attribute is left blank, the SAML Building Block will ignore the attribute when parsing the SAML response.
- Select Submit to save the information.
Institution roles
A user's institution role in your Blackboard Learn system is determined according to the information received from the identity provider. The roles are mapped as follows:
Primary Institution Role (SAML) | Blackboard Learn Institution Role |
---|---|
Student | Student |
Staff | Staff |
Faculty | Faculty |
Course roles
A user's role in a course is determined according to the information received from the identity provider. The roles are mapped as follows:
Course Memberships (SAML) | Blackboard Learn Course Role |
---|---|
Learner | Student |
Instructor | Instructor |
ContentDeveloper | Course Builder |
Member | Student |
Manager | Student |
Administrator | Student |
TeachingAssistant | Teaching Assistant |
Mentor | Instructor |
Multiple attribute values
If you expect the identity provider's response to include multiple values for an attribute, format your SAML response as follows.
<saml2:Attribute FriendlyName="bbuasqa3_cm" Name="urn:oid:1.3.6.1.4.1.5923.1.6.1.2" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml2:AttributeValue>Learner@batchUid:TEST_COURSE_003
</saml2:AttributeValue>
<saml2:AttributeValue>Learner@batchUid:TEST_COURSE_004
</saml2:AttributeValue>
</saml2:Attribute>
Test the connection
Test the connection to make sure it's working correctly. Log out of Learn and log back in using the SAML link. Type your account credentials for the external site to log in. You are brought back to Blackboard Learn when you successfully log in.
Log out of Blackboard Learn and a message appears to ask if you want to end all related sessions or continue. If you do nothing, the system ends all sessions in two minutes. If you want to continue your session, you’ll need to login again for your security.
Troubleshoot
If you or your users are encountering errors, refer to these troubleshooting tips.
- If an error appears before you are redirected to the identity provider's login page, the identity provider's metadata may be invalid.
- If an error appears after you log in on the identity provider's page, the reasons could be that:
- Attribute mapping between the service provider and identity provider is incorrect, or the identity provider didn't return a valid Remote User ID.
- The SAML response from the identity provider wasn't validated by the service provider. This could be caused by:
- The identity provider signs the SAML response with a certificate that is not issued by a valid certificate authority, and the service provider's keystore doesn't contain this certificate.
- The service provider's system clock is incorrect.
- To find more information on errors, open the bb-services-log.txt file or the visual log panel and search for keywords such as unsuccessfulAuthentication or BbSAMLExceptionHandleFilter
- You can use the Chrome developer console, the SAML Tracer plugin for Firefox, or the SAML Message Decoder for Firefox to locate a SAML response.