Skip to main content
Blackboard Help

SAML Authentication Provider Type

This article is archived and is no longer updated. Go to the latest information on the SAML Authentication Provider Type.

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 2.0 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 2.0 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 2.0 Building Block is bundled with the Q2 2016 release of Blackboard Learn 9.1 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.

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 2.0 Building Block available, proceed to step 6.

  1. Navigate to the Admin Panel.
  2. Under Building Blocks, select Building Blocks.
  3. Select Installed Tools, then select Upload Building Blocks.
    • If the SAML 2.0 Building Block is already installed, locate it in the list and set its status as available.
  4. Select Browse to locate the Building Block package on your machine. When finished, select Submit.
  5. Select Approve to make the Building Block available.
  6. On the Admin Panel, under Building Blocks, select Authentication.
  7. SAML now appears in the Create Provider list on the Authentication Provider page.

Create and Configure a SAML Authentication Provider

  1. Click the Create Provider button and select the SAML authentication provider type.
  2. Type a name and optional description for the provider.
  3. Set the Authentication Provider Availability to Active.
  4. Set the User Lookup Method to Username or Batch UID.
  5. 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.
  6. In the Link Text field, type the title for the link as you want it to appear on the Blackboard Learn login page.
  7. You can also add an icon to the login page, if desired. Select Browse to upload an icon for the login page.
  8. Click 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

  1. 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.
  2. Type a name for the Entity ID. This ID will be populated into the Service Provider Metadata.
  3. In order to set up a trusted connection, you need to share your metadata with the identity provider. Click the Generate button next to Service Provider Metadata.
  4. Share the metadata with the identity provider. After they save the metadata on their side, the trusted connection is set up.
  5. 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.

  6. 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.
  7. Select the checkbox to have the system automatically create a new account for the user if their information is not found.

Identity Provider Settings

  1. 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.

Map SAML Attributes

  1. 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.
  2. 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

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.


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 or the SAML Tracer plugin for Firefox to locate a SAML response.