Moving to SAML B2 for Authentication

Discussion created by david.cartwright on Jul 18, 2017
Latest reply on Jul 3, 2018 by ve0070998

Hi all.


We're just finalising our move to the new(ish) SAML B2 for auth here.  We went round in circles for a little while due to lack of Shibboleth knowledge on the Blackboard team and a lack of documentation online.  I thought I'd provide my write up of how we went about configuring things in case it was of any use to people.  I've removed any identifying data so hopefully it all still makes sense.


Props to Christin Deville for the very useful ADFS proof of concept work and Garry Harper at Blackboard for his extensive help with SAML/Shibboleth and ensuring that deep linking worked correctly after we moved.


Write up:


Bb Auth Providers, SAML and Custom Login Page

Types of Auth Provider

Blackboard supports several providers types and these options can be further extended or modified by installing additional B2s.  It is possible to have multiple provider types active at any one time and UoM we have historically had internal, ldap and Shibboleth (legacy) all enabled together. 


At UoM the default provider used on login is set through a parameter in the custom login page file (see Custom Login Page section for further info).  This default option can be bypassed by visiting the “bypass login URL” (see “Bypass Login URL” section for more info on this.  Disabling the custom login page essentially pushes all users to the bypass login URL and allows them to select which authentication provider to login against.


This is the default out-of-box authentication provider.  Usernames and passwords are both stored in the internal Blackboard database.  Additional users can be added through the Blackboard System Admin GUI users area.  Blackboard support has several accounts that authenticate against this auth provider.  It is recommended that Student Systems users have a backup system administrator account that runs against the internal authentication to be used in the event of a failure of the University’s CAS/Shibboleth systems.

Future Development

It is possible for UoM to modify our integration feeds to push (encrypted) user passwords to the Blackboard database.  Doing this would allow us to switch to Blackboard’s internal authentication provider as required to allow users to still access Blackboard in the event that a failure of the University’s CAS/Shibboleth systems.  This would reduce risk of loss of Blackboard access during key periods - e.g. the online exams.


This authentication provider authenticates against regular or secure LDAP (we currently use secure/LDAP over SSL at UoM).  Despite the name, “secure” LDAP is not regarded as particularly secure and the recommendation is that we move away from using it for authentication.  Assuming that no issues are encountered, LDAP authentication will be disabled as part of the 30/07/17 Blackboard Service Pack upgrade.  LDAP authentication also does not support 2FA which the University plans to move to before the end of the 2017/18 academic year.


Accounts must be created either via the System Admin GUI or through a SIS feed in order to authenticate against LDAP.

Legacy Shibboleth

Legacy Shibboleth has until recently been the preferred option for authentication at UoM.  Much like LDAP, user accounts must first be created via the System Admin GUI or a SIS feed.  Unlike LDAP, which only authenticates against the username and password, UoM Shibboleth requires that the user be redirected to CAS for username/password authentication, before being returned to Blackboard with a ticket that contains Shibboleth “attributes” which are then matched against the Blackboard user record - in the case of the UoM Blackboard set up, only the “uid” attribute is used - which contains the user’s SPOT ID.


Legacy Shibboleth requires that an additional Apache instance be set up on one of the Blackboard nodes.  Changes to this configuration must be completed by Managed Hosting and require a restart of the Apache application running on the node.  Additionally, this setup is NOT supported by the SaaS Blackboard service.


The SAML B2 is a recent development that aims to both modernise and simplify the authentication provider configuration in Blackboard.  It offers several options for auth provider types, including Shibboleth, CAS and ADFS.  At UoM we currently only utilise Shibboleth (CAS is used for authentication but that then hooks into Shibboleth, so as far as Blackboard is concerned, it is a Shibboleth auth provider type) but in the future we may move to ADFS.

SAML - Shibboleth

The SAML implementation of Shibboleth essentially offers the same functionality as the Legacy Shibboleth but with the following improvements:

  • A separate Apache instance is no longer required as the functionality is now “Blackboard native”.  This is required for Shibboleth support within Blackboard SaaS.
  • All configuration can now be performed in the Blackboard System Admin GUI without requiring any intervention by Blackboard support.
  • Added support for SAML 2.0 bindings.
  • “Just in time” user creation (provisioning) is supported.  This is not used at UoM as all user provisioning is performed by our SIS integration.


With full understanding of the SAML Shibboleth implementation steps, migrating to ADFS should be relatively simple.  This will need to be investigated in more detail once the ADFS project is further along.  See the “External Documentation” section for some more details on this.

SAML Implementation

As part of the 30/07/17 Service Pack upgrade and in order to prepare for migration to Blackboard SaaS UoM moved from Legacy Shibboleth to SAML Shibboleth. 

Configuration Process Overview for UoM

Configuring a new authentication provider requires working closely with the directories team (specifically, ************) and undertaking the following steps:

  1. Establish the signature algorithm type used by our Shibboleth server.  At UoM this is current SHA-1.  The corresponding setting then needs modifying in the Building Block settings area for the B2 “Authentication Provider - SAML”.  Whenever this setting is changed the B2 must be restarted (Set Inactive followed by Set Available).
  2. A new provider must be created and configured (see below).
  3. Service Provider Metadata must be generated by a Blackboard System Administrator and this file must be provided to the Directories team along with details of the configured Entity ID.
  4. The Directories team will configure Shibboleth to work with Blackboard:
    1. Adding the metadata to the Shibboleth configuration.
    2. Configuring Shibboleth to release the correct SAML attributes to Blackboard.
    3. Restarting Shibboleth
  5. At this point, users should be able to login to Blackboard with the new auth provider.

Configuring a New Auth Provider

  1. Browse to System Admin > Authentication and select Create Provider > SAML.
  2. Enter an easily identifiable Name and Link Text (recommended to have these match) and select Active, Username and Use this provider for any hostnames from the options available.
  3. You will be returned to the Authentication page.  Now click the dropdown on the provider you just created and select SAML Settings.
  4. Choose a unique entity ID.  For UoM the format is as below (e.g. *********-********):


     Be aware that each Entity ID on a particular environment must be unique.  For example, if configuring the environment for beta Shib and prod Shib (with separate auth providers) each auth provider must have a different Entity ID.

  1. Ensure Enable automatic SSO and Single Logout Service Type (Post and Redirect) are all ticked.
  2. Click Generate to generate the service provider metadata that will need to be sent to the Directories team in order for them to configure Shibboleth successfully.
  3. For Data Source, choose the appropriate DSK for standard users.  At UoM this is sis_grouped_users.  We also tick SYSTEM from the Compatible Data Sources list to allow local accounts to authenticate against this auth provider for testing purposes.
  4. Ensure that Enable Just in Time Provisioning is NOT ticked unless you wish to allow users to be created on the fly (at UoM we do not).
  5. For Identity Provider Settings at UoM we use:
    1. Identity Provider Type: Point identify provider
    2. Metadata Type: Metadata URL
    3. Metadata URL:
      1. https://beta.*********-********.ac.uk/shibboleth-idp/profile/Metadata/SAML (pre-prod)
      2. https://*********-********.ac.uk/shibboleth-idp/profile/Metadata/SAML(prod)
  1. Be sure to click Validate as otherwise you will be unable to save the SAML settings.
  1. Set the Remote User ID as a Custom SAML Attribute with the value:
    1. urn:oid:*.*.****.**********.***.*.*

It is always worth confirming that the above attribute is correct and will return the “uid” of the user.  The Directories team will have this information.

  1. Click Submit.


Once the above is complete and the Directories team have configured Shibboleth it should be possible to successfully log in with a central username and password.  This should be tested by accessing the bypass login URL and selecting the new authentication provider you created via the dropdown.

Common Problems

Unfortunately, error messages presented to users are often not very informative.  The vast majority of issues seem to be caused by either the Authentication Provider - SAML B2 not being configured to utilise the correct certificate signing algorithm or Shibboleth not being correctly set up to release the uid attribute to Blackboard. 

There are some further examples of common errors in the External Documentation section.

External Documentation

Blackboard’s SAML B2 documentation: https://help.blackboard.com/Learn/Administrator/SaaS/Authentication/Implement_Authentication/SAML_Authentication_Provider_Type

Blackboard’s Common Issues documentation: https://help.blackboard.com/Learn/Administrator/SaaS/Authentication/Implement_Authentication/SAML_Authentication_Provider_Type/Common_Issues_with_SAML_Authentication

ADFS proof of concept work by Christin Deville on the Blackboard community site: https://community.blackboard.com/thread/1768-connecting-blackboard-to-adfs-30-saml-sso

Custom Login Page


By default Blackboard presents users with a vanilla login page which authenticates against the Blackboard Internal auth provider type and LDAP (if configured).  Additionally, users are presented with a drop-down box which allows them to select other auth provider types such as Shibboleth.

When utilising a Central Authentication Service (CAS) of any kind it is possible to force users to log in via this auth provider type rather than presenting them with the vanilla Blackboard login page.  This is achieved at UoM through the use of a Custom Login Page.  It is also possible to achieve a similar result through the use of Gateway options and forcing login via particular auth providers when accessing via specific URLs/domains but there are issues around redirection and deep links with this approach and as such it has not been adopted at UoM.

The Custom Login Page works by reading the incoming URL when attempting to access any part of the Blackboard application, extracting information from the URI components and then either sending the user to the Shibboleth server for authentication (with an encoded “return URL” to redirect them back to the correct page once they are authenticated) or simply sending the user to the correct page if they are already authenticated.  This is done via a small piece of javascript within the Custom Login Page file.  Within this file there is also configuration for the auth provider ID which controls exactly which Shibboleth server the user is authenticated against.

Deep Linking to Courses and Content Areas

As above, the Custom Login Page javascript code allows users to deep-link to specific content items and courses.  Without it, users will always be redirected back to the Blackboard “homepage” upon successful login.

Configuring and Uploading the Custom Login Page

The Custom Login Page file requires only minimal configuration before uploading to Blackboard.  Download a sample file from the link below.  Then, open the file with Notepad++ or Sublime Text and change the following variable values:

var server = "https://*********-********.blackboard.com";

  • This should be set ot the full URL for the Blackboard environment.


var serverEnc = "https%3A%2F%2F*********-********.blackboard.com";

  • This should be the same as the server var but with any special characters encoded as per the JS function encodeURIComponent.


var authProviderID = '_3228_1';


Once this configuration is complete the newly modified Custom Login Page can be uploaded by navigating to System Admin > Brands and Themes > Customise Login Page.  If you are replacing a previous Custom Login Page it is recommended that you download and back up the old version first.

Common Problems

Redirect Loops

These may occur if you have set the auth provider ID wrong in the Custom Login Page file.  Use the Bypass Login URL to get in to Blackboard and check.

Deep Linking Not Working for Some Pages

This is a known issue with some parts of the Blackboard application.  This cannot be fixed through modifying the Custom Login Page code and instead when found should be reported to Blackboard as a bug.

Contacts at Blackboard

*********** is Blackboard’s Shibboleth and SAML expert.

Sample Custom Login Page Files


Process - Changing Default Authentication Provider

Follow the steps already provided for configuring a Custom Login Page but replace the authProviderID in the .jsp file with your newly chosen auth provider ID.

Process - Raising a Splash Page for an Upgrade

Replace the Custom Login Page .jsp file content with your chosen splash page html.  An example of the standard splash page can be obtained from Blackboard Managed Hosting.


Process - Bypass Login URL

When attempting to test a new auth provider type or when experiencing issues logging in via normal means, the Bypass Login URL can be used to access the system.  This URL is also provided to FEAT during UAT in order to allow them access whilst normal users are locked out.


The page presents users with a vanilla login page which authenticates against the Blackboard Internal auth provider type and LDAP (if configured).  Additionally, users are presented with a drop-down box which allows them to select other auth provider types such as Shibboleth.


URL structure is: https://server-name/webapps/login/login.jsp


E.g. https://*********-********.blackboard.com/webapps/login/login.jsp