Self- and Managed-Hosting administrators, you're in the right place!
SaaS administrators, view SAML information specific to SaaS 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 9.1 Q2 2016+ and Blackboard Learn SaaS.
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. After you make the SAML Building Block available, proceed to step 6.
- Navigate to the Admin Panel.
- Under Integrations, select Building Blocks.
- Select Installed Tools, then select Upload Building Blocks.
- If the Authentication Provider - SAML Building Block is already installed, locate it in the list and set its status as available.
- Select Browse to locate the Building Block package on your machine. When finished, select Submit.
- Select Approve to make the Building Block available.
- On the Admin Panel, under Integrations, select Authentication.
- SAML now appears in the Create Provider list on the Authentication Provider page.
Configure building block settings
You can configure settings in the SAML Building Block to troubleshoot issues or ensure the security of your 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 .
- 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.
Learn more about Data Sources.
- 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 Enable JIT Provisioning 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.
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.
Generate and store private keys
If you want to add another layer of security, you can create a private key for identity providers to use when they establish a connection with your system. You share the key and password with the identity provider in the same way you share the service provider metadata. Keys are used to digitally sign SAML assertions and encrypt their content.
In the following commands, replace some-alias and changeit with the name and password for the key you want to create or import.
You can generate your own self-signed key using the Java utility keytool:
keytool -genkeypair -alias some-alias -keypass changeit -keystore samlKeystore.jks
The keystore will now contain an additional PrivateKeyEntry, with alias mykey, which can be imported to the keyManager in your securityContext.xml. Keys signed by certification authorities are typically provided in .p12/.pfx format or can be converted to such using OpenSSL.
Import keys signed by certification authorities to the Java keystore using:
keytool -importkeystore -srckeystore key.p12 -srcstoretype PKCS12 -srcstorepass password \
-alias some-alias -destkeystore samlKeystore.jks -destalias some-alias \
-destkeypass changeit
Use this command to determine the available aliases in the p12 file: keytool -list -keystore key.p12 -storetype pkcs12
Import public keys
If the metadata URL is provided by HTTPS protocol, don't forget to add this identity provider's certificate to "samlKeystore.jks"
The system stores cryptographic material to decrypt incoming data and verify trust signatures in SAML messages and metadata. This information is stored in the metadata of the remote entities or in the keyManager. Run the following command to import additional trusted keys to the keystore:
keytool -importcert -alias some-alias -file key.cer -keystore samlKeystore.jks