Custom login pages in Saas - third-party account

Blog Post created by smachaje on Oct 7, 2019

guardLogin pages are important.  There are many UX principles and security regulations that apply to them.  Among many good ideas, we want login pages to be aesthetically appealing and guard the main doors to the system.  It is best when users type in credentials to the same login page across the organization (such as in Shibboleth technology) instead of retyping the same credentials on multiple login pages (such as LDAP and others).  This moves many organizations to use SAML/Shibboleth as web authentication technology.  In Blackboard Learn this is called third-party account.


The problem:

If an administrator configured SAML/Shibboleth for Blackboard Learn, an authentication URL is created automatically on the default login page (sample default page URL:  However, the Username and Password prompts remain.  On a custom login page such prompts can be removed and direct link can be used (sample direct link URL:  Since Shibboleth requires web interfaces, the Blackboard mobile app must be forced to the web with "Web Login".  Unfortunately, after password is accepted users are forwarded to the main Institutional Page location.  In iOS the mobile app doesn't recognize it as a successful login and integrations, such as Panopto SSO, are not correctly redirected to their destination.



As long as you provide the default login page in the Blackboard mobile services B2 "change mobile login url", students will be able to use the default prompts or use the drop-down selection to Shibboleth on the default page with this design:


default prompts



So what's the problem with the workaround?

We would like the custom page to work for the mobile apps and third-party integrations without default login prompt.  This keeps the institutional branding consistent.  Also, if the organization uses only Shibboleth the default black (above picture) Username and Password prompts will not work.  It is necessary to use the link in the bottom drop-down.  The prompts will work with LDAP or internal database authentication, but these may be disabled.  As a security principle, we don't want users to put username or password into any other prompts but the main organizational Shibboleth prompts.  We would also like to understand the root problem. 


As a side note, the name Shibboleth has an interesting story:

Shibboleth - Wikipedia 


Let's get started.  The customization of the Blackboard login page provides important benefits to student engagement and system adaption.  Much can be communicated and advertised. Nathan Cobb wrote up a great piece on how to create a custom login page to Blackboard Learn: Show us your ... Learn Ultra Login Page .   


The basic design is to use the a starter file with about 100 lines of code that begin like this:


<!-- This login.jsp file is tagged with comments identifying sections for easy editing -->

<!-- This section below calls various servlets from the Learn environment and other things you don't want to touch. Do not delete anything in this section -->
<%@ include file="/webapis/ui/doctype.jspf" %>
<%@ page import="blackboard.servlet.util.CourseCatalogUtil" %>



You can download the full starter file here: 


This is  a great start, but it includes design elements, such as credential prompts, which are not wanted in Shibboleth-only approach.  What if you don't want to display the Username and Password prompts that require either local database authentication or LDAP?  Again, if we're using Shibboleth, the internal prompts will break our login process.


So, out of necessity, some administrators created a custom login page with a simple link to the third-party authentication URL.  This link can be extracted from the default login page drop-down.  Here is a simplified code of a custom page that works and uses Shibboleth only:


<a id="loginurl"

Sign In</a>



The code above is a minimalistic approach, but will work perfectly for logging into Blackboard Learn in a browser.  It will process Shibboleth prompts, and redirect back into /ultra home.


However, at this point the mobile app, which has to be switched to forced web login for Shibolleth prompts, will not work.  Support sometimes applied this known issue to tickets reporting the behavior:

MOBI-9602 - iOS 4.4 Doesn't Poll to Native View after External Authentication Until a User Action - Persisting Behavior of MOBI-9247

Article #000050914 - iOS Doesn't Establish Native Session View after External Authentication Until a User Action  


The problem is not with iOS or the mobile app.  The problem also persists in any external single signon application such as Panopto.  So, the functional workaround is to force the mobile app to the default login page and enable at least LDAP to get the prompts workings.


The root cause of this behavior is the redirectUrl and new_loc URL parameters.  If you trace the clicks, the login page from the mobile app or Panopto includes a return URL to successfully receive the authenticated session.  Ok, so there is a JS that can be added to the login page to capture new_loc and forward properly.  After writing that code, it became obvious that there is a better way, more maintainable and sustainable across future upgrades.


The successful trick is to display the Blackboard generated login prompts with the custom drop-down, then hide them, then assign back in HTML the properly formatted custom login URL.


This is how it works:


/* onLoad event on body tag let's us wait for all HTML elements
to be loaded before we detect the custom authentication URL */
<body onLoad="setLogin()">

/* include any HTML/CSS/JS code you have for your custom page.
The only important element below is id="loginurl",
which will let you replace the href dynamically.
The link can be anywhere on your custom login page. */
<a id="loginurl"
href="" >

Sign In</a>

/* this section will build the hidden login prompts with
correctly structured third-party URL.
We are going to pull the first row from the drop-down,
so the first URL in case you have multiple. */

<%@ taglib uri="/bbNG" prefix="bbNG" %>
<%@ taglib uri="/loginUI" prefix="loginUI" %>

<div id="login-form" class="login-form"style="display: none">
<loginUI:loginForm />

<script lang="JavaScript">
function setLogin() {
var a = document.getElementById("loginRedirectProviderList");
var b = a.getElementsByTagName('a');





This approach will fix the login process to the mobile app, SSO to Panopto, and ensure that Shibboleth authentication prompts are presented at the login page and all integrations entry points.


This article applies to Blackboard Learn clients who are not using LDAP, local database authentication, but instead try using SAML/Shibboleth by itself.