Common Issues with SAML Authentication

This guide provides a general overview of the Security Assertion Markup Language (SAML) 2.0 Building Block along with common Single Sign-On (SSO) issues and troubleshooting techniques for the SAML authentication provider.

If for any reason an updated/new IdP metadata XML file is uploaded in the Blackboard Learn GUI on the SAML Authentication Settings page in the Identity Provider Settings section for a SAML authentication provider, the SAML B2 and that SAML authentication provider should also be toggled Inactive/Available, while having the SAML authentication provider in 'Active' status, to ensure any cached IdP metadata is cleared out and the updated IdP metadata is fully utilized.

Key terms

The following terms and abbreviations are used throughout this guide:

• SAML: Security Assertion Markup Language
• IdP: Identity Provider
• SP: Service Provider
• ADFS: Active Directory Federation Services
• GUI: Graphical User Interface. In the context of Blackboard Learn, this means working within the software.

Edit SAML configuration settings

To help troubleshoot SAML authentication issues, the SAML Building Block was updated in Q2 2017 to include these configuration settings and options:

• Define the SAML session age limit
• Choose a signature algorithm type
• Regenerate certificates
• Change the ResponseSkew value

More on how to configure settings in the SAML Building Block

Errors and exceptions

SAML related errors/exceptions are captured in the following logs:

• /usr/local/blackboard/logs/bb-services-log.txt
• /usr/local/blackboard/logs/tomcat/stdout-stderr-<date>.log
• /usr/local/blackboard/logs/tomcat/catalina-log.txt

These logs should always be searched when investigating a reported SAML authentication issue.

SAML Tracer

With SAML 2.0 authentication troubleshooting iterations, at some point it may be necessary to confirm/view the attributes that are actually being released from the IdP and sent to Learn during the authentication process. If the attributes from the IdP are NOT encrypted in the SAML response, the Firefox browser SAML tracer Add-on or Chrome SAML Message Decoder can be used to view the attributes.

Attribute not properly mapped

If the attribute containing the userName is not properly mapped as specified in the Remote User ID field in the Map SAML Attributes section on the SAML Authentication Settings page in the Blackboard Learn GUI, the following event will be logged in the bb-services log when attempting to login to Blackboard Learn via SAML authentication:

2016-06-28 12:48:12 -0400 - userName is null or empty

A similar Sign On Error! message displayed in the browser: Blackboard Learn is currently unable to log into your account using single-sign on. Contact your administrator for assistance.

An Authentication Failure entry appears in the bb-services log:

2016-06-28 12:48:12 -0400 - BbSAMLExceptionHandleFilter - javax.servlet.ServletException: Authentication Failure
 at blackboard.auth.provider.saml.customization.handler.BbAuthenticationSuccessHandler.checkAuthenticationResult(BbAuthenticationSuccessHandler.java:81)
 at blackboard.auth.provider.saml.customization.handler.BbAuthenticationSuccessHandler.onAuthenticationSuccess(BbAuthenticationSuccessHandler.java:57)
 at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.successfulAuthentication(AbstractAuthenticationProcessingFilter.java:331)
 at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:245)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
 at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
 at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
 at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
 at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
 at java.lang.reflect.Method.invoke(Method.java:497)
 [SNIP]

Resolution

You have two options to resolve the issue. First, select the Create accounts if they don't exist in the system option on the SAML Authentication Settings page in the Blackboard Learn GUI. Alternatively, you can attempt to view the value of the attributes released by the IdP via SAML tracer or Debug Logging if the attributes are NOT encrypted:

<saml2:Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:type="xs:anyType"
                          >[email protected]</saml2:AttributeValue>
</saml2:Attribute>

and map the Attribute Name that has the desired AttributeValue to the Remote User ID on the SAML Authentication Settings page in the Blackboard Learn GUI.

Compatible data source not selected

Users won't be able to login to Blackboard Learn via SAML authentication if the Data Source for the users is not selected in the Services Provider Settings > Compatible Data Sources section on the SAML Authentication Settings page in the Blackboard Learn GUI. The following event will be logged in the bb-services log when attempting to log in to Blackboard Learn via SAML authentication:

2016-09-23 12:33:13 -0500 - userName is null or empty

The Sign On Error! message appears in the browser, as well as the Authentication Failure in the bb-services log:

2016-09-23 12:33:13 -0500 - BbSAMLExceptionHandleFilter - javax.servlet.ServletException: Authentication Failure
        at blackboard.auth.provider.saml.customization.handler.BbAuthenticationSuccessHandler.checkAuthenticationResult(BbAuthenticationSuccessHandler.java:82)
        at blackboard.auth.provider.saml.customization.handler.BbAuthenticationSuccessHandler.onAuthenticationSuccess(BbAuthenticationSuccessHandler.java:58)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.successfulAuthentication(AbstractAuthenticationProcessingFilter.java:331)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:245)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor3399.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        [SNIP]

Resolution

1. Obtain the username of a user that is unable to login.
2. In the Blackboard Learn GUI, navigate to System Admin > Users and search for the user.
3. Copy the Data Source Key of the user.
4. Navigate to System Admin > Authentication > "Provider Name" > SAML Settings > Compatible Data Sources.
5. Place a check mark next to that Data Source in the Name column and select Submit.

"Given URL is not well formed" error message

If OneLogin is configured as the IdP for the SAML authentication provider in Blackboard Learn, a Given URL is not well formed error may be displayed on the page after entering the OneLogin credentials when attempting login to Blackboard Learn.

With the following displayed in the bb-services-log:

2016-09-16 09:43:40 -0400 - Given URL is not well formed<P><span class="captionText">For reference, the Error ID is 17500f44-7809-4b9f-a272-3bed1d1af131.</span> - java.lang.IllegalArgumentException: Given URL is not well formed
        at org.opensaml.util.URLBuilder.<init>(URLBuilder.java:120)
        at org.opensaml.util.SimpleURLCanonicalizer.canonicalize(SimpleURLCanonicalizer.java:87)
        at org.opensaml.common.binding.decoding.BasicURLComparator.compare(BasicURLComparator.java:57)
        at org.opensaml.common.binding.decoding.BaseSAMLMessageDecoder.compareEndpointURIs(BaseSAMLMessageDecoder.java:173)
        at org.opensaml.common.binding.decoding.BaseSAMLMessageDecoder.checkEndpointURI(BaseSAMLMessageDecoder.java:213)
        at org.opensaml.saml2.binding.decoding.BaseSAML2MessageDecoder.decode(BaseSAML2MessageDecoder.java:72)
        at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:105)
        at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:172)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:80)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
    [SNIP]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: java.net.MalformedURLException: no protocol: {recipient}
        at java.net.URL.<init>(URL.java:593)
        at java.net.URL.<init>(URL.java:490)
        at java.net.URL.<init>(URL.java:439)
        at org.opensaml.util.URLBuilder.<init>(URLBuilder.java:77)
        ... 203 more

Resolution

1. Turn on the Firefox browser SAML tracer and replicate the login issue.
2. Review the beginning of the SAML POST event:

   <samlp:Response Destination="{recipient}"
           ID="R8afbfbfee7292613f98ad4ec4115de7c6b385be6"
           InResponseTo="a3g2424154bb0gjh3737ii66dadbff4"
           IssueInstant="2016-09-16T18:49:09Z"
           Version="2.0"
           xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
           xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
           >
       <saml:Issuer>https://app.onelogin.com/saml/metadata/123456</saml:Issuer>
       [SNIP]

3. For line 1 with the Response, observe that the Destination= is only set to recipient.
4. Have the client access the Configuration section of their OneLogin IdP.
5. Confirm if the Recipient field is blank.
6. Copy the value of the ACS (Consumer) URL, paste it into the Recipient field and select Save.

IdP/SP Problem Scenarios

1. If an error appears before you are redirected to the IdP's login page, the IdP's metadata may be invalid.
2. If an error appears after you log in on the IdP's page, the reasons could be that:
   1. Attribute mapping between the SP and IdP is incorrect, or the IdP didn't return a valid Remote User ID.
   2. The SAML response from the IdP wasn't validated by the SP. This could be caused by:
      • The IdP signs the SAML response with a certificate that is not issued by a valid certificate authority, and the SP's keystore doesn't contain this certificate.
      • The SP's system clock is incorrect.

Active Directory Federation Services (ADFS)

The attribute names are case sensitive in the Map SAML Attributes section on the SAML Authentication Settings page in the Blackboard Learn GUI. So if the Remote User ID has sAMAccountName for the Attribute Name on the settings page and the actual SAML POST from the IdP has this for the Attribute Name in the AttributeStatement:

<AttributeStatement>
    <Attribute Name="SamAccountName>
        <AttributeValue>Test-User</AttributeValue>
    </Attribute>
</AttributeStatement>

The user will not be able to login. The Remote User ID attribute name value on the SAML Authentication Settings page would need to be changed from sAMAccountName to SamAccountName.

"Resource not found" or "Sign on error!" warning

This section contains some of the common problems that may prevent a user from logging into Learn via SAML authentication with ADFS when The specified resource was not found, or you do not have permission to access it or Sign On Error! message is displayed in the Blackboard Learn GUI.

Problem #1

After entering the login credentials on the ADFS login page, an error may be displayed after being redirected to the Blackboard Learn GUI: The specified resource was not found, or you do not have permission to access it.

With a corresponding message in the stdout-stderr log:

INFO | jvm 1 | 2016/06/22 06:08:33 | - No mapping found for HTTP request with URI [/auth-saml/saml/SSO] in DispatcherServlet with name 'saml'

The problem occurs because the noHandlerFound() method is used in the DispatcherServlet.java code and is unable to locate/map the HTTP SSO request.

/**
 * No handler found -> set appropriate HTTP response status.
 * @param request current HTTP request
 * @param response current HTTP response
 * @throws Exception if preparing the response failed
 */
protected void noHandlerFound(HttpServletRequest request, HttpServletResponse response) throws Exception {
 if (pageNotFoundLogger.isWarnEnabled()) {
  pageNotFoundLogger.warn("No mapping found for HTTP request with URI [" + getRequestUri(request) +
    "] in DispatcherServlet with name '" + getServletName() + "'");
 }
 if (this.throwExceptionIfNoHandlerFound) {
  throw new NoHandlerFoundException(request.getMethod(), getRequestUri(request),
    new ServletServerHttpRequest(request).getHeaders());
 }
 else {
  response.sendError(HttpServletResponse.SC_NOT_FOUND);
 }
}

Resolution

This typically occurs because the Entity ID for the SP configured in the Blackboard Learn GUI is incorrect. This can be resolved by navigating to System Admin > Authentication > SAML Authentication Settings > Service Provider Settings and updating the Entity ID. For ADFS, the default configuration for the Entity ID would be https://[Learn Server Hostname]/auth-saml/saml/SSO.

If a school changes their URL from the default https://school.blackboard.com to https://their.school.edu, the Entity ID in the Blackboard Learn GUI on the SAML Authentication Settings page should be updated to https://their.school.edu/auth-saml/saml/SSO.

Problem #2

After entering the login credentials on the ADFS login page, an error may be displayed after being redirected to the Blackboard Learn GUI: The specified resource was not found, or you do not have permission to access it.

With this corresponding message in the stdout-stderr log:

INFO  | jvm 1  | 2016/06/22 06:08:33 | - No mapping found for HTTP request with URI [/auth-saml/saml/SSO] in DispatcherServlet with name 'saml'

And this message in the catalina log:

ERROR 2016-06-27 10:47:03,664 connector-6: userId=_2_1, sessionId=62536416FB80462298C92064A7022E50 org.opensaml.xml.encryption.Decrypter - Error decrypting the encrypted data element
org.apache.xml.security.encryption.XMLEncryptionException: Illegal key size
Original Exception was java.security.InvalidKeyException: Illegal key size
        at org.apache.xml.security.encryption.XMLCipher.decryptToByteArray(XMLCipher.java:1822)
        at org.opensaml.xml.encryption.Decrypter.decryptDataToDOM(Decrypter.java:596)
        at org.opensaml.xml.encryption.Decrypter.decryptUsingResolvedEncryptedKey(Decrypter.java:795)
        at org.opensaml.xml.encryption.Decrypter.decryptDataToDOM(Decrypter.java:535)
        at org.opensaml.xml.encryption.Decrypter.decryptDataToList(Decrypter.java:453)
        at org.opensaml.xml.encryption.Decrypter.decryptData(Decrypter.java:414)
        at org.opensaml.saml2.encryption.Decrypter.decryptData(Decrypter.java:141)
        at org.opensaml.saml2.encryption.Decrypter.decrypt(Decrypter.java:69)
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:199)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:82)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        [SNIP]
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: java.security.InvalidKeyException: Illegal key size
        at javax.crypto.Cipher.checkCryptoPerm(Cipher.java:1039)
        at javax.crypto.Cipher.init(Cipher.java:1393)
        at javax.crypto.Cipher.init(Cipher.java:1327)
        at org.apache.xml.security.encryption.XMLCipher.decryptToByteArray(XMLCipher.java:1820)
        ... 205 more

And this message displayed in the bb-services log:

2016-06-27 10:47:03 -0400 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor3422.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:277)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:274)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
        at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:309)
        at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:249)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:237)
        at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:55)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:191)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:187)
        at java.security.AccessController.doPrivileged(Native Method)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:186)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at sun.reflect.GeneratedMethodAccessor3421.invoke(Unknown Source)
        [SNIP]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: Response doesn't have any valid assertion which would pass subject validation
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:229)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
        ... 229 more

The problem occurs because by default ADFS encrypts the attributes it sends using AES-256 and the Java runtime used by Blackboard Learn doesn't support AES-256 out of the box.

Resolution

A universal resolution option is to open a PowerShell on the ADFS server and set the relying party created for Blackboard Learn to send the attributes as unencrypted. As the whole communication is over SSL, this will not reduce the security of the authentication. It also makes debugging of any issues easier as the attributes can be viewed using debugging tools such as the Firefox browser SAML tracer Add-on and a restart of the Blackboard Learn system is not required. To set the relying party created for Blackboard Learn to send the attributes as unencrypted, open a PowerShell and execute the following command, replacing TargetName with the name of the Relying Party Trust that is in the ADFS Management Console under Trust Relationships > Relying Party Trusts.

set-ADFSRelyingPartyTrust –TargetName "yourlearnserver.blackboard.com" –EncryptClaims $False

After this change the ADFS service will need to be restarted with the command: Restart-Service ADFSSRV

Problem #3

After entering the login credentials on the ADFS login page, an error may be displayed after being redirected to the Blackboard Learn GUI: The specified resource was not found, or you do not have permission to access it or Sign On Error!

With either, these similar corresponding SAML related events appear in the stdout-stderr log:

INFO   | jvm 1    | 2016/09/06 20:33:04 | - /saml/login?apId=_107_1&redirectUrl=https%3A%2F%2Fbb.fraser.misd.net%2Fwebapps%2Fportal%2Fexecute%2FdefaultTab at position 1 of 10 in additional filter chain; firing Filter: 'SecurityContextPersistenceFilter'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - No HttpSession currently exists
INFO   | jvm 1    | 2016/09/06 20:33:04 | - No SecurityContext was available from the HttpSession: null. A new one will be created.
INFO   | jvm 1    | 2016/09/06 20:33:04 | - /saml/login?apId=_107_1&redirectUrl=https%3A%2F%2Fbb.fraser.misd.net%2Fwebapps%2Fportal%2Fexecute%2FdefaultTab at position 2 of 10 in additional filter chain; firing Filter: 'WebAsyncManagerIntegrationFilter'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - /saml/login?apId=_107_1&redirectUrl=https%3A%2F%2Fbb.fraser.misd.net%2Fwebapps%2Fportal%2Fexecute%2FdefaultTab at position 3 of 10 in additional filter chain; firing Filter: 'HeaderWriterFilter'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - /saml/login?apId=_107_1&redirectUrl=https%3A%2F%2Fbb.fraser.misd.net%2Fwebapps%2Fportal%2Fexecute%2FdefaultTab at position 4 of 10 in additional filter chain; firing Filter: 'FilterChainProxy'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - Checking match of request : '/saml/login'; against '/saml/login/**'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - /saml/login?apId=_107_1&redirectUrl=https%3A%2F%2Fbb.fraser.misd.net%2Fwebapps%2Fportal%2Fexecute%2FdefaultTab at position 1 of 1 in additional filter chain; firing Filter: 'SAMLEntryPoint'
INFO   | jvm 1    | 2016/09/06 20:33:04 | - Request for URI http://www.w3.org/2000/09/xmldsig#rsa-sha1
INFO   | jvm 1    | 2016/09/06 20:33:04 | - Request for URI http://www.w3.org/2000/09/xmldsig#rsa-sha1
INFO   | jvm 1    | 2016/09/06 20:33:04 | - SecurityContext is empty or contents are anonymous - context will not be stored in HttpSession.
INFO   | jvm 1    | 2016/09/06 20:33:04 | - SecurityContextHolder now cleared, as request processing completed
INFO   | jvm 1    | 2016/09/06 20:33:07 | - /saml/SSO at position 1 of 10 in additional filter chain; firing Filter: 'SecurityContextPersistenceFilter'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - HttpSession returned null object for SPRING_SECURITY_CONTEXT
INFO   | jvm 1    | 2016/09/06 20:33:07 | - No SecurityContext was available from the HttpSession: org.apache.catalina.session.StandardSessionFacade@6708a718. A new one will be created.
INFO   | jvm 1    | 2016/09/06 20:33:07 | - /saml/SSO at position 2 of 10 in additional filter chain; firing Filter: 'WebAsyncManagerIntegrationFilter'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - /saml/SSO at position 3 of 10 in additional filter chain; firing Filter: 'HeaderWriterFilter'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - /saml/SSO at position 4 of 10 in additional filter chain; firing Filter: 'FilterChainProxy'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Checking match of request : '/saml/sso'; against '/saml/login/**'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Checking match of request : '/saml/sso'; against '/saml/logout/**'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Checking match of request : '/saml/sso'; against '/saml/bbsamllogout/**'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Checking match of request : '/saml/sso'; against '/saml/sso/**'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - /saml/SSO at position 1 of 1 in additional filter chain; firing Filter: 'SAMLProcessingFilter'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Authentication attempt using org.springframework.security.saml.SAMLAuthenticationProvider
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Forwarding to /
INFO   | jvm 1    | 2016/09/06 20:33:07 | - DispatcherServlet with name 'saml' processing POST request for [/auth-saml/saml/SSO]
INFO   | jvm 1    | 2016/09/06 20:33:07 | - No mapping found for HTTP request with URI [/auth-saml/saml/SSO] in DispatcherServlet with name 'saml'
INFO   | jvm 1    | 2016/09/06 20:33:07 | - SecurityContext is empty or contents are anonymous - context will not be stored in HttpSession.
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Successfully completed request
INFO   | jvm 1    | 2016/09/06 20:33:07 | - Skip invoking on
INFO   | jvm 1    | 2016/09/06 20:33:07 | - SecurityContextHolder now cleared, as request processing completed

Or these similar SAML exceptions in the bb-services log:

2016-11-29 09:04:24 -0500 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor853.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
        at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
        at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
        at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
        at java.security.AccessController.doPrivileged(Native Method)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at sun.reflect.GeneratedMethodAccessor853.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        [SNIP]
        at org.apache.catalina.valves.RemoteIpValve.invoke(RemoteIpValve.java:677)
        at blackboard.tomcat.valves.LoggingRemoteIpValve.invoke(LoggingRemoteIpValve.java:44)
        at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:87)
        at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:349)
        at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:1110)
        at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:66)
        at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:785)
        at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1425)
        at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: Response issue time is either too old or with date in the future, skew 60, time 2016-11-29T14:03:16.634Z
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:126)
        at blackboard.auth.provider.saml.customization.consumer.BbSAMLWebSSOProfileConsumerImpl.processAuthenticationResponse(BbSAMLWebSSOProfileConsumerImpl.java:40)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
        ... 230 more

The problem occurs when the ADFS server and the Blackboard Learn application server have a time drift close to or beyond the default of 60 seconds.

Resolution

There are two options to resolve the issue:

1. Manually syncing the clocks of the Blackboard Learn application servers and the ADFS server. For Blackboard Learn, the current time and time zone of the server can be viewed in a web browser by adding /webapps/blackboard/amiup.jsp to the end of a Blackboard Learn URL.

   Example: https://mhtest1.blackboard.com/webap...oard/amiup.jsp

   Yes database : Thu Dec 08 17:13:32 EST 2016 : HOSTNAME=fgprd-523885-sf160752-app001

   An institution may use one of the above URLs to compare the Blackboard Learn system time zone and clock with that of their ADFS server and then adjust those items as necessary on the ADFS server so that they are in-sync with the Blackboard Learn site.

2. The skew can be adjusted in the securityContext.xml to workaround the issue:
   1. Make a backup copy of the file:

      /usr/local/blackboard/content/vi/BBLEARN/plugins/bb-auth-provider-saml/webapp/WEB-INF/config/saml/securityContext.xml

   2. Change:

      <!-- SAML 2.0 WebSSO Assertion Consumer -->
      <bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl"/>

      to:

      <!-- SAML 2.0 WebSSO Assertion Consumer -->
      <bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
      <property name="responseSkew"value="60000"/><!-- 100 hours -->
      </bean>

Problem #4

After entering the login credentials on the ADFS login page, an error may be displayed after being redirected to the Blackboard Learn GUI: The specified resource was not found, or you do not have permission to access it or Sign On Error!

With the following exceptions in the bb-services log:

2016-11-01 12:47:19 -0500 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor929.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
        at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
        at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
        at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
        at java.security.AccessController.doPrivileged(Native Method)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
 [SNIP]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: Response has invalid status code urn:oasis:names:tc:SAML:2.0:status:Responder, status message is null
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:113)
        at blackboard.auth.provider.saml.customization.consumer.BbSAMLWebSSOProfileConsumerImpl.processAuthenticationResponse(BbSAMLWebSSOProfileConsumerImpl.java:40)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
        ... 230 more
 2016-11-01 12:47:19 -0500 - BbSAMLExceptionHandleFilter - javax.servlet.ServletException: Unsuccessful Authentication
         at blackboard.auth.provider.saml.customization.filter.BbSAMLProcessingFilter.unsuccessfulAuthentication(BbSAMLProcessingFilter.java:31)
         at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:235)
         at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
         at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
         at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
         at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
         at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
         at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
         at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
         at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
         at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
         at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
         at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
         at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
         at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
         at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
         at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
         at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
         at sun.reflect.GeneratedMethodAccessor929.invoke(Unknown Source)
         at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
         at java.lang.reflect.Method.invoke(Method.java:498)
         at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
         at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
         at java.security.AccessController.doPrivileged(Native Method)
         at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
         at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
         at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
         at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
         at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
         at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
         at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
         at java.security.AccessController.doPrivileged(Native Method)
         at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
         at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
 [SNIP]

Resolution

In Blackboard Learn 9.1 Q2 2017 and later, this option can be configured in the user interface.

1. Navigate to the Admin Panel.
2. Under Building Blocks, select Building Blocks.
3. Select Installed Tools.
4. Locate Authentication Provider - SAML in the list. Open the menu and select Settings.
5. Under Signature Algorithm Settings, choose SHA-256 in the list. After you select the Signature Algorithm Type, restart the SAML building block to apply the new settings.
6. Select Submit to save your changes.

For Blackboard Learn 9.1 Q4 2016 and earlier, you can adjust the SHA option as follows.

The authentication requests are encrypted between Blackboard Learn and ADFS using the SHA-256 algorithm, which is used by default for MS ADFS as its base encryption.

1. In the ADFS management console, right-click the Relying Party Trust.
2. Select Properties.
3. Select the Advanced Tab.
4. Change the Security hash algorithm from SHA-256 (ADFS Default) to SHA-1.
5. Select OK.

Problem #5

After entering the login credentials on the ADFS login page, an error may be displayed after being redirected to the Blackboard Learn GUI: The specified resource was not found, or you do not have permission to access it or Sign On Error!

With the following exceptions in the bb-services log:

2017-01-04 22:52:58 -0700 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor935.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
        at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
        at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
        at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
        at java.security.AccessController.doPrivileged(Native Method)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
    [SNIP]
        at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: NameID element must be present as part of the Subject in the Response message, please enable it in the IDP configuration
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:252)
        at blackboard.auth.provider.saml.customization.consumer.BbSAMLWebSSOProfileConsumerImpl.processAuthenticationResponse(BbSAMLWebSSOProfileConsumerImpl.java:40)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
        ... 214 more

As stated in the above SAML exception, the NameID element is missing from the Subject in the Response message. The problem typically occurs when the NameID is not setup as an Outgoing Claim Type in a Claims Rule for the Relying Party Trust on the institution's ADFS IdP or the Claims Rule for the NameID is not in the proper order for the Relying Party Trust on the institution's ADFS IdP, which in turn causes the missing NameID element in the Subject in the Response message.

Example: NameID element is missing

<Subject>
    <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="a22ai8iig0f75ae22hd28748b12da50"
                                 NotOnOrAfter="2017-01-03T05:57:58.234Z"
                                 Recipient="https://yourschool.blackboard.com/auth-saml/saml/SSO"
                                 />
    </SubjectConfirmation>
</Subject>

Example: NameID element is present

<Subject>
    <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">testadfs</NameID>
    <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="a5903d39if463ea87ieiab5135j9ji"
                                 NotOnOrAfter="2017-01-05T04:33:12.715Z"
                                 Recipient="https://yourschool.blackboard.com/auth-saml/saml/SSO"
                                 />
    </SubjectConfirmation>
</Subject>

You can use the Firefox SAML tracer Add-on to view the Subject in the Response message.

Resolution

There are three methods to resolving this issue.

1. Confirm the steps from the SAML B2 Setup Guide for ADFS were properly followed and make changes as needed to transform an incoming claim for the Relying Party Trust for their ADFS IdP:
   1. Select Edit Claims Rule.
   2. Select Add Rule.
   3. On the Select Rule Template page, select Transform an Incoming Claim for the Claim rule template and then select Next.
   4. On the Configure Rule page, in the Claim rule name field, type Transform Email to Name ID.
   5. Incoming claim type should be SamAccountName (it must match the Outgoing Claim Type created initially in the Transform Username to NameID rule).
   6. The Outgoing claim type is Name ID.
   7. The Outgoing name ID format is Email.
   8. Confirm Pass through all claim values is selected and select Finish.
   9. Select OK to save the rule and OK again to complete the attribute mappings.
2. Ensure for the order of the Claims Rules used for their ADFS IdP that the rule which has the NameID element does not have any optional rules occurring before it.
3. If using a custom attribute, ensure the NameID element is in the Relying Party Trust since Learn still expects that their ADFS IdP release a NameID value.

Problem #6

When logged into Blackboard Learn via SAML authentication, the user attempts to log out by clicking on the Sign Out button on the left side of the page and then clicks the End SSO Session button, a Sign On Error! is immediately displayed.

Sign On Error!
Blackboard Learn is currently unable to log into your account using single sign-on. Contact your administrator for assistance.
For reference, the Error ID is [error ID].

With the following exception in the bb-services log:

2017-05-08 15:10:46 -0400 - BbSAMLExceptionHandleFilter Error Id: f3299757-8d4e-4fab-98cf-49cd99f4891e - javax.servlet.ServletException: Incoming SAML message failed security validation
    at org.springframework.security.saml.SAMLLogoutProcessingFilter.processLogout(SAMLLogoutProcessingFilter.java:145)
    at org.springframework.security.saml.SAMLLogoutProcessingFilter.doFilter(SAMLLogoutProcessingFilter.java:104)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
    at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
    at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
    at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
    [SNIP]
    at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
    at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.ws.security.SecurityPolicyException: Validation of request simple signature failed for context issuer
    at org.opensaml.common.binding.security.BaseSAMLSimpleSignatureSecurityPolicyRule.doEvaluate(BaseSAMLSimpleSignatureSecurityPolicyRule.java:139)
    at org.opensaml.common.binding.security.BaseSAMLSimpleSignatureSecurityPolicyRule.evaluate(BaseSAMLSimpleSignatureSecurityPolicyRule.java:103)
    at org.opensaml.ws.security.provider.BasicSecurityPolicy.evaluate(BasicSecurityPolicy.java:51)
    at org.opensaml.ws.message.decoder.BaseMessageDecoder.processSecurityPolicy(BaseMessageDecoder.java:132)
    at org.opensaml.ws.message.decoder.BaseMessageDecoder.decode(BaseMessageDecoder.java:83)
    at org.opensaml.saml2.binding.decoding.BaseSAML2MessageDecoder.decode(BaseSAML2MessageDecoder.java:70)
    at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:105)
    at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:172)
    at org.springframework.security.saml.SAMLLogoutProcessingFilter.processLogout(SAMLLogoutProcessingFilter.java:131)
    ... 244 more

The error occurs because of the Single Logout Service Type setting on the SAML Settings page.

Resolution

The setting needs to be configured in Blackboard Learn and on the ADFS server.

For ADFS as the IdP, select the Post setting only and remove the Redirect endpoint for the Learn instance's Relying Party Trust on the ADFS server.

1. In Learn, navigate to Admin > Authentication > (Provider Name) > SAML Settings > Single Logout Service Type.
2. Select Post and clear the Redirect checkbox.
3. In the ADFS Server, go into the Relying Party Trust for your Learn Instance.
4. Select Properties > Endpoints. Two SAML logout endpoints are listed.
5. Remove the Redirect endpoint. Select Remove Endpoint to remove it, then Apply and OK.

After making the above changes in Learn and the ADFS server, the End SSO Session logout button will work to properly sign out the user.

Problem #7

After entering the login credentials on the ADFS login page, a Sign On Error! message is displayed when redirected to Learn.

With the following SAML exception in the bb-services log:

2017-05-26 07:39:30 -0400 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
        at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
        at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLProcessingFilter.attemptAuthentication(BbSAMLProcessingFilter.java:46)
        at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor380.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
        at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
        at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
        at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
        at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
        at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
        at java.security.AccessController.doPrivileged(Native Method)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
        at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:37)
    [SNIP]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: Response has invalid status code urn:oasis:names:tc:SAML:2.0:status:Responder, status message is null
        at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:113)
        at blackboard.auth.provider.saml.customization.consumer.BbSAMLWebSSOProfileConsumerImpl.processAuthenticationResponse(BbSAMLWebSSOProfileConsumerImpl.java:56)
        at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
        ... 247 more

Resolution

Beginning in Learn Q2 2017, there is now an option to regenerate the SAML encryption certificate by navigating to System Admin > Building Blocks > Authentication Provider - SAML > Settings > Regenerate Certificate. The Sign On Error! problem may occur if the Regenerate certificate button is selected after the SP metadata is already uploaded to the Relying Party Trust for the Learn site on the ADFS server. To resolve the issue:

1. Navigate to System Admin > Authentication > [SAML Provider Name] > SAML Settings.
2. Select Generate next to Service Provider Metadata to save the new metadata file.
3. Access your ADFS server and upload the new SP metadata to the Relying Party Trust for your Learn site.

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.

Federation Metadata

With Active Directory Federation Services (ADFS), since the metadata for an ADFS federation typically located in https://[ADFS Server Hostname]/FederationMetadata/2007-06/FederationMetadata.xml includes an element that is incompatible with SAML 2.0, the metadata needs to be edited to delete the incompatible element before it is uploaded to the Identity Provider Settings section on the SAML Authentication Settings page in the Blackboard Learn GUI. If the metadata with the incompatible element is uploaded, an error will occur when selecting the SAML login link on the Blackboard Learn login page: Metadata for entity and role wasn't found. For reference, the Error ID is [error ID].

And the corresponding Java stack trace for the Error ID in the bb-services log has the following:

2016-06-21 11:42:51 -0700 - Metadata for entity https://<Learn Server Hostname>/adfs/ls/ and role {urn:oasis:names:tc:SAML:2.0:metadata}SPSSODescriptor wasn&#39;t found<P><span class="captionText">For reference, the Error ID is c99511ae-1162-4941-b823-3dda19fea157.</span> - org.opensaml.saml2.metadata.provider.MetadataProviderException: Metadata for entity https://ulvsso.laverne.edu/adfs/ls/ and role {urn:oasis:names:tc:SAML:2.0:metadata}SPSSODescriptor wasn't found
        at org.springframework.security.saml.context.SAMLContextProviderImpl.populateLocalEntity(SAMLContextProviderImpl.java:319)
        at org.springframework.security.saml.context.SAMLContextProviderImpl.populateLocalContext(SAMLContextProviderImpl.java:216)
        at org.springframework.security.saml.context.SAMLContextProviderImpl.getLocalAndPeerEntity(SAMLContextProviderImpl.java:126)
        at org.springframework.security.saml.SAMLEntryPoint.commence(SAMLEntryPoint.java:146)
        at org.springframework.security.saml.SAMLEntryPoint.doFilter(SAMLEntryPoint.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor1652.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        [SNIP]

Resolution

Since the default metadata location for an ADFS federation is https://[ADFS server hostname]/FederationMetadata/2007-06/FederationMetadata.xml:

1. Download this file and open it in a text editor. Carefully delete the section starting <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> ... </X509Data></KeyInfo> and ending </ds:Signature>
   <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

   <ds:SignedInfo>
     <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
     <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
     <ds:Reference URI="#_43879f32-9a91-4862-bc87-e98b85b51158">
      <ds:Transforms>
       <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
       <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      </ds:Transforms>
      <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <ds:DigestValue>z1H1[SNIP]jaYM=</ds:DigestValue>
     </ds:Reference>
     </ds:SignedInfo>
     <ds:SignatureValue> FVj[SNIP]edrfNKWvsvk5A==
     </ds:SignatureValue>
     <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <X509Data>
       <X509Certificate>
       FDdd[SNIP]qTNKdk5F/vf1AocDaX
       </X509Certificate>
      </X509Data>
     </KeyInfo>
   </ds:Signature>

2. Upload the updated metadata XML file in the Blackboard Learn GUI on the SAML Authentication Settings page in the Identity Provider Settings section.
3. Toggle the SAML authentication provider and SAML B2 Inactive/Available, while having the SAML authentication provider in 'Active' status.

If an institution is testing SAML authentication on a Blackboard Learn site and has multiple SAML authentication providers that share the same underlying ADFS IdP metadata XML file on the Blackboard Learn site, even if the other SAML authentication providers are set to Inactive, they will also need to have the updated metadata XML file uploaded in the Blackboard Learn GUI on the SAML Authentication Settings page in the Identity Provider Settings section. The SAML B2 should then be toggled Inactive/Available, while having the SAML authentication provider in 'Active' status, to ensure the updated metadata XML file is recognized system-wide.

Incorrect user lookup method

After entering the login credentials on the ADFS login page, the user is redirected to the Blackboard Learn GUI, but not logged into Blackboard Learn.

The ONLY SAML authentication related event in the bb-services log is:

2016-10-18 13:03:28 -0600 - userName is null or empty

Resolution

1. Login to Blackboard Learn as administrator using the default Blackboard Learn Internal authentication.
2. Navigate to System Admin > "SAML Authentication Provider Name" > Edit.
3. Change the User Lookup Method from Batch Uid to Username.

Extra End SSO Session logout button

ADFS tries to add an extra End SSO Session logout button on the End all sessions? page that is displayed after first selecting the logout button at the top right in the Blackboard Learn GUI.

This is done by adding an extra SingleLogoutService to the IdP Metadata file:

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://your.server.name/adfs/ls/"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://your.server.name/adfs/ls/"/>

Since that is an optional SAML B2 IdP configuration and the signature being provided in the Redirect Endpoint is not correct, an error will occur when selecting the extra End SSO Session button on the End all sessions? page: Incoming SAML message failed security validation. Validation of request simple signature failed for context issuer. For reference, the Error ID is [error ID].

The corresponding Java stack trace for the Error ID in the bb-services log has:

2016-10-17 16:57:44 -0400 - Incoming SAML message failed security validation Validation of request simple signature failed for context issuer<P><span class="captionText">For reference, the Error ID is 930c7767-8710-475e-8415-2077152280e0.</span> - org.opensaml.ws.security.SecurityPolicyException: Validation of request simple signature failed for context issuer
        at org.opensaml.common.binding.security.BaseSAMLSimpleSignatureSecurityPolicyRule.doEvaluate(BaseSAMLSimpleSignatureSecurityPolicyRule.java:139)
        at org.opensaml.common.binding.security.BaseSAMLSimpleSignatureSecurityPolicyRule.evaluate(BaseSAMLSimpleSignatureSecurityPolicyRule.java:103)
        at org.opensaml.ws.security.provider.BasicSecurityPolicy.evaluate(BasicSecurityPolicy.java:51)
        at org.opensaml.ws.message.decoder.BaseMessageDecoder.processSecurityPolicy(BaseMessageDecoder.java:132)
        at org.opensaml.ws.message.decoder.BaseMessageDecoder.decode(BaseMessageDecoder.java:83)
        at org.opensaml.saml2.binding.decoding.BaseSAML2MessageDecoder.decode(BaseSAML2MessageDecoder.java:70)
        at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:105)
        at org.springframework.security.saml.processor.SAMLProcessorImpl.retrieveMessage(SAMLProcessorImpl.java:172)
        at org.springframework.security.saml.SAMLLogoutProcessingFilter.processLogout(SAMLLogoutProcessingFilter.java:131)
        at org.springframework.security.saml.SAMLLogoutProcessingFilter.doFilter(SAMLLogoutProcessingFilter.java:104)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
        at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
        at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
        at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
        at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
        at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
        at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
        at sun.reflect.GeneratedMethodAccessor1652.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:498)
        [SNIP]

Resolution

1. Access the ADFS Server and go into the Relying Party Trust for the Blackboard Learn Instance.
2. Select Properties > Endpoints tab.
3. In the Endpoints tab there will be 2 SAML Logout Endpoints.
4. Remove the Redirect endpoint.
5. Select Remove Endpoint to remove it, then Apply and OK.

After removing the Redirect endpoint, the End SSO Session button will work properly signing out the user.

Viewing application logs with event viewer

When troubleshooting an ADFS SAML authentication issue, it may be necessary to also have an institution review the ADFS application logs in the Event Viewer on their ADFS server for further insight. This is particularly necessary when the SAML response from the ADFS server has a Request Denied status as seen below:

<samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:RequestDenied" />
    </samlp:StatusCode>
</samlp:Status>

The SAML response can be viewed by using the Firefox browser SAML tracer Add-on.

The Request Denied status in a response typically indicates a problem occurred when the IdP (ADFS) attempted to understand the response and process the result the SP (Blackboard Learn) provided.

To view the ADFS application logs with the Event Viewer:

1. Open the Event Viewer on the ADFS server.
2. On the View menu, select Show Analytic and Debug Logs.
3. In the console tree, navigate to Application and Service Logs > AD FS Tracing > Debug.

Azure Active Directory

Azure AD is Microsoft's (MS) cloud based directory and identity management service.

Send first part of email

If an institution is using Azure AD as their IdP and wishes to only have the first part of the Azure AD email username used for the Blackboard Learn username, they can configure their Azure AD IdP to use the special ExtractMailPrefix() function to remove the domain suffix from either the email or the user principal name resulting in only the first part of the username being passed through (e.g. "joesmith" instead of [email protected]).

If the Blackboard Learn Remote User ID is urn:oid:1.3.6.1.4.1.5923.1.1.1.6, the Attribute setting for the Azure IdP would look like this:

Attribute Name:        urn:oid:1.3.6.1.4.1.5923.1.1.1.6
Attribute Value:    ExtractMailPrefix()
Mail:            user.userprincipalname

So with the example [email protected] email username, it would be passed like this in the SAML assertion from the Azure IdP to Blackboard Learn:

<Attribute Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6">
    <AttributeValue>joesmith</AttributeValue>

Additional info about using the ExtractMailPrefix() function is available on the MS Azure documentation page.

Azure AD IdP updating certificate

After entering the login credentials on the MS Azure AD login page, a Sign On Error! may be displayed after being redirected to the Blackboard Learn GUI.

With the following exception in the bb-services log:

2016-10-13 12:03:23 +0800 - unsuccessfulAuthentication - org.springframework.security.authentication.AuthenticationServiceException: Error validating SAML message
 at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:100)
 at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
 at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
 at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
 at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
 at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
 at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
 at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
 at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
 at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
 at sun.reflect.GeneratedMethodAccessor854.invoke(Unknown Source)
 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
 at java.lang.reflect.Method.invoke(Method.java:498)
 at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:282)
 at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:279)
 at java.security.AccessController.doPrivileged(Native Method)
 at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
 at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:314)
 at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:253)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:190)
 at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:46)
 at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:148)
 at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:144)
 at java.security.AccessController.doPrivileged(Native Method)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:143)
 at blackboard.auth.provider.saml.customization.filter.BbSAMLExceptionHandleFilter.doFilterInternal(BbSAMLExceptionHandleFilter.java:30)
 [SNIP]
 at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
 at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
 at java.lang.Thread.run(Thread.java:745)
Caused by: org.opensaml.common.SAMLException: Response doesn't have any valid assertion which would pass subject validation
 at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:229)
 at blackboard.auth.provider.saml.customization.consumer.BbSAMLWebSSOProfileConsumerImpl.processAuthenticationResponse(BbSAMLWebSSOProfileConsumerImpl.java:40)
 at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:87)
 ... 230 more
Caused by: org.opensaml.xml.validation.ValidationException: Signature is not trusted or invalid
 at org.springframework.security.saml.websso.AbstractProfileBase.verifySignature(AbstractProfileBase.java:272)
 at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.verifyAssertionSignature(WebSSOProfileConsumerImpl.java:419)
 at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.verifyAssertion(WebSSOProfileConsumerImpl.java:292)
 at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:214)
 ... 232 more

This is caused by the MS Azure AD IdP updating the certificate, but the metadata XML used by the Blackboard Learn SP not being adjusted to reflect the new certificate.

Resolution

• The new metadata XML file with the new certificate will need to be updated on the SAML Settings page in the Blackboard Learn GUI for the authentication provider.
• The SAML B2 and the authentication provider will then need to be toggled Inactive/Available, while having the SAML authentication provider in 'Active' status, to have the updated metadata with the new certificate applied.
• If a Blackboard Learn site has multiple authentication providers that share the same underlying certificate for the same underlying IdP Entity ID, ALL those authentication providers will need to be updated.

Microsoft has indicated that that they will be updating certificates every 6 weeks from now on, and that such updates will be unannounced.

IdP-initiated single sign on

If a user first logs into their user portal and then selects the app for their Blackboard Learn site, a new browser tab opens to display a message: The specified resource was not found, or you do not have permission to access it.

With the corresponding SAML related events in the stdout-stderr.log:

INFO   | jvm 1    | 2016/08/16 10:49:22 | - /saml/SSO at position 1 of 10 in additional filter chain; firing Filter: 'SecurityContextPersistenceFilter'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - HttpSession returned null object for SPRING_SECURITY_CONTEXT
INFO   | jvm 1    | 2016/08/16 10:49:22 | - No SecurityContext was available from the HttpSession: org.apache.catalina.session.StandardSessionFacade@58c53845. A new one will be created.
INFO   | jvm 1    | 2016/08/16 10:49:22 | - /saml/SSO at position 2 of 10 in additional filter chain; firing Filter: 'WebAsyncManagerIntegrationFilter'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - /saml/SSO at position 3 of 10 in additional filter chain; firing Filter: 'HeaderWriterFilter'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - /saml/SSO at position 4 of 10 in additional filter chain; firing Filter: 'FilterChainProxy'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Checking match of request : '/saml/sso'; against '/saml/login/**'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Checking match of request : '/saml/sso'; against '/saml/logout/**'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Checking match of request : '/saml/sso'; against '/saml/bbsamllogout/**'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Checking match of request : '/saml/sso'; against '/saml/sso/**'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - /saml/SSO at position 1 of 1 in additional filter chain; firing Filter: 'SAMLProcessingFilter'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Forwarding to /
INFO   | jvm 1    | 2016/08/16 10:49:22 | - DispatcherServlet with name 'saml' processing POST request for [/auth-saml/saml/SSO]
INFO   | jvm 1    | 2016/08/16 10:49:22 | - No mapping found for HTTP request with URI [/auth-saml/saml/SSO] in DispatcherServlet with name 'saml'
INFO   | jvm 1    | 2016/08/16 10:49:22 | - SecurityContext is empty or contents are anonymous - context will not be stored in HttpSession.
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Successfully completed request
INFO   | jvm 1    | 2016/08/16 10:49:22 | - Skip invoking on
INFO   | jvm 1    | 2016/08/16 10:49:22 | - SecurityContextHolder now cleared, as request processing completed

The Service Provider Settings section of the SAML Authentication Settings page has changed and the Enable automatic SSO option should be checked to allow a user to access Blackboard Learn from their portal. If it is enabled, the ACS URL will also be changed to include an alias.

Wrong document error

After entering the login credentials on the SAML authentication provider login page, a Sign On Error! may be displayed after being redirected to the Blackboard Learn GUI.

With the following DOMException and WRONG_DOCUMENT_ERR in the bb-services log:

2016-11-18 12:27:31 -0600 - WRONG_DOCUMENT_ERR: A node is used in a different document than the one that created it.<P><span class="captionText">For reference, the Error ID is 86ebb81d-d3a3-4da5-95ab-1c94505f4281.</span> - org.w3c.dom.DOMException: WRONG_DOCUMENT_ERR: A node is used in a different document than the one that created it.
    at org.apache.xerces.dom.ParentNode.internalInsertBefore(Unknown Source)
    at org.apache.xerces.dom.ParentNode.insertBefore(Unknown Source)
    at org.apache.xerces.dom.NodeImpl.appendChild(Unknown Source)
    at org.opensaml.xml.encryption.Decrypter.parseInputStream(Decrypter.java:832)
    at org.opensaml.xml.encryption.Decrypter.decryptDataToDOM(Decrypter.java:610)
    at org.opensaml.xml.encryption.Decrypter.decryptUsingResolvedEncryptedKey(Decrypter.java:795)
    at org.opensaml.xml.encryption.Decrypter.decryptDataToDOM(Decrypter.java:535)
    at org.opensaml.xml.encryption.Decrypter.decryptDataToList(Decrypter.java:453)
    at org.opensaml.xml.encryption.Decrypter.decryptData(Decrypter.java:414)
    at org.opensaml.saml2.encryption.Decrypter.decryptData(Decrypter.java:141)
    at org.opensaml.saml2.encryption.Decrypter.decrypt(Decrypter.java:69)
    at org.springframework.security.saml.websso.WebSSOProfileConsumerImpl.processAuthenticationResponse(WebSSOProfileConsumerImpl.java:199)
    at org.springframework.security.saml.SAMLAuthenticationProvider.authenticate(SAMLAuthenticationProvider.java:82)
    at org.springframework.security.authentication.ProviderManager.authenticate(ProviderManager.java:167)
    at org.springframework.security.saml.SAMLProcessingFilter.attemptAuthentication(SAMLProcessingFilter.java:87)
    at org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter.doFilter(AbstractAuthenticationProcessingFilter.java:217)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
    at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:184)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:64)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:53)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:91)
    at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:330)
    at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:213)
    at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:176)
    at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:346)
    at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:262)
    at sun.reflect.GeneratedMethodAccessor1209.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:498)
    at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:277)
    at org.apache.catalina.security.SecurityUtil$1.run(SecurityUtil.java:274)
    at java.security.AccessController.doPrivileged(Native Method)
    at javax.security.auth.Subject.doAsPrivileged(Subject.java:549)
    at org.apache.catalina.security.SecurityUtil.execute(SecurityUtil.java:309)
    at org.apache.catalina.security.SecurityUtil.doAsPrivilege(SecurityUtil.java:249)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:237)
    at org.apache.catalina.core.ApplicationFilterChain.access$000(ApplicationFilterChain.java:55)
    at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:191)
    at org.apache.catalina.core.ApplicationFilterChain$1.run(ApplicationFilterChain.java:187)
    at java.security.AccessController.doPrivileged(Native Method)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:186)
    at blackboard.platform.servlet.DevNonceFilter.doFilter(DevNonceFilter.java:68)
    [SNIP]

The reason the problem occurs is another B2/Project changed the system property javax.xml.parsers.DocumentBuilderFactory value from org.apache.xerces.jaxp.DocumentBuilderFactoryImpl to com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl.

Temporary resolution

Until a fix is released, the temporary resolution options are:

1. Restart Bb services on each node.
2. Turn off SAML response encryption on the IdP side. As the whole communication is over SSL, this will not reduce the security of the authentication.

No option to add SAML to Provider Order

When configuring SAML authentication, an institution may notice there is not an option to add a SAML authentication provider in the Provider Order section in Blackboard Learn GUI when navigating to System Admin > Building Blocks: Authentication > Provider Order.

The reason there is not an option to add a SAML authentication provider to the Provider Order is that redirect type providers such as CAS and SAML hand off authentication to the remote authentication source. Those are not listed in the Provider Order as they are considered the authoritative source for authentication and handle their own authentication failures.

Test SAML connection

Beginning with the Q4 2016 release of Blackboard Learn, there is now an option to test the connection for a SAML provider in the Authentication section in the Blackboard Learn GUI. The connection test will check the following items:

• Parse IdP metadata
• Connect to IdP
• Receive SAML response
• Parse SAML response
• Remote User ID match
• Log in to Blackboard Learn

To test the connection for a SAML authentication provider:

1. Login to Blackboard Learn as an administrator.
2. Navigate to System Admin > Building Blocks: Authentication > "SAML Provider Name" > Test Connection.
3. Enter the IdP login credentials if prompted.

The Test Connection feature can be used in lieu of manually enabling SAML debug logging in Blackboard Learn for multiple reasons.

The Identity Provider Entity ID value that is displayed on the Test Connection output page is pulled from the Issuer element in the SAML POST from the IdP to Blackboard Learn after the user has been authenticated:

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://bbpdcsi-adfs1.bbpdcsi.local/a...services/trust</Issuer>

The SAML Attribute values displayed on the Test Connection output page in the SAML Response section are pulled from the Subject and AttributeStatement elements in the SAML POST from the IdP to Blackboard Learn after the user has been authenticated:

<Subject>
    <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">luke.skywalker</NameID>
    [SNIP]
</Subject>
<AttributeStatement>
    <Attribute Name="SamAccountName">
        <AttributeValue>luke.skywalker</AttributeValue>
    </Attribute>
    <Attribute Name="urn:oid:2.5.4.42">
        <AttributeValue>Luke</AttributeValue>
    </Attribute>
    <Attribute Name="urn:oid:2.5.4.4">
        <AttributeValue>Skywalker</AttributeValue>
    </Attribute>
</AttributeStatement>

Debug logging

If the attributes being released from the IdP and sent to Blackboard Learn during the authentication process are encrypted in the SAML response, the Firefox browser SAML tracer Add-on or Chrome SAML Message Decoder can't be used to view those attributes. However, viewing the attributes and additional SAML related events in a log on the Blackboard Learn side can be accomplished by temporarily enabling debug logging inside the SAML 2.0 B2. Also, if a site has Blackboard Learn Q4 2016 or higher, the Test Connection feature can be used in lieu of manually enabling SAML debug logging in Blackboard Learn.

To temporarily enable debug logging for the SAML 2.0 B2:

1. Open the /usr/local/blackboard/content/vi/BBLEARN/plugins/bb-auth-provider-saml/webapp/WEB-INF/classes/log4j.properties

   log4j.rootCategory=DEBUG, CONSOLE
    
   # CONSOLE is set to be a ConsoleAppender using a PatternLayout.
   log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
   log4j.appender.CONSOLE.Threshold=DEBUG
   log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
   log4j.appender.CONSOLE.layout.ConversionPattern=- %m%n
    
   # Logging of Spring Security extension
   log4j.logger.org.springframework.security.saml=INFO
    
   # Logging of SAML messages, set to FINEST to enable
   log4j.logger.PROTOCOL_MESSAGE=FINEST
    
   # Logging of OpenSAML library
   log4j.logger.org.opensaml=INFO

   1. on line 1, change the log4j.rootCategory= from INFO to DEBUG
   2. on line 5, change the log4j.appender.CONSOLE.Threshold= from INFO to DEBUG
   3. on line 13, change the log4j.logger.PROTOCOL_MESSAGE= from INFO to FINEST
2. Then have Bb services restarted with a rolling pushconfig being done so the new debug logging settings for the B2 are recognized by Blackboard Learn.
3. Once the SAML 2.0 B2 is set to use debug, perform a test SAML authentication login as normal. This will get a dump of the SAML response sent back from the client's IdP. The event is captured in the Tomcat stdout-stderr log and can be found by searching for AttributeValue or Attribute Name.

Example:

INFO   | jvm 1    | 2016/05/20 04:54:27 | - <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_50725d4fa80d0d5689bd3ca9ac43b97c" IssueInstant="2016-05-20T08:54:26.793Z" Version="2.0"><saml2:Issuer>https://accounts.google.com/o/saml2?idpid=C00j2kl1x</saml2:Issuer><saml2:Subject><saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml2:NameID><saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml2:SubjectConfirmationData InResponseTo="a32977i74g7e88c731df1915ibj0iec" NotOnOrAfter="2016-05-20T08:59:26.793Z" Recipient="https://mhtest3.blackboard.com/auth-saml/saml/SSO"></saml2:SubjectConfirmationData></saml2:SubjectConfirmation></saml2:Subject><saml2:Conditions NotBefore="2016-05-20T08:49:26.793Z" NotOnOrAfter="2016-05-20T08:59:26.793Z"><saml2:AudienceRestriction><saml2:Audience>https://mhtest3.blackboard.com/shibboleth</saml2:Audience></saml2:AudienceRestriction></saml2:Conditions><saml2:AttributeStatement><saml2:Attribute Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">[email protected]</saml2:AttributeValue></saml2:Attribute><saml2:Attribute Name="urn:oid:2.5.4.42"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Bb</saml2:AttributeValue></saml2:Attribute><saml2:Attribute Name="urn:oid:2.5.4.4"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">User_SAML2</saml2:AttributeValue></saml2:Attribute><saml2:Attribute Name="urn:oid:0.9.2342.19200300.100.1.3"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">[email protected]</saml2:AttributeValue></saml2:Attribute></saml2:AttributeStatement><saml2:AuthnStatement AuthnInstant="2016-05-20T08:54:26.000Z" SessionIndex="_50725d4fa80d0d5689bd3ca9ac43b97c"><saml2:AuthnContext><saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef></saml2:AuthnContext></saml2:AuthnStatement></saml2:Assertion>
INFO   | jvm 1    | 2016/05/20 04:54:27 | - Verification successful for URI "#_50725d4fa80d0d5689bd3ca9ac43b97c"
INFO   | jvm 1    | 2016/05/20 04:54:27 | - The Reference has Type
INFO   | jvm 1    | 2016/05/20 04:54:27 | - Redirecting to DefaultSavedRequest Url: https://mhtest3.blackboard.com/webap...ute/defaultTab
INFO   | jvm 1    | 2016/05/20 04:54:27 | - Redirecting to 'https://mhtest3.blackboard.com/webap...ute/defaultTab'
INFO   | jvm 1    | 2016/05/20 04:54:27 | - SecurityContext 'org.springframework.security.core.context.SecurityContextImpl@63e17344: Authentication: org.springframework.security.providers.ExpiringUsernameAuthenticationToken@63e17344: Principal: [email protected]; Credentials: [PROTECTED]; Authenticated: true; Details: blackboard.auth.provider.saml.credential.impl.SamlUserDetails@5971c59d; Not granted any authorities' stored to HttpSession: 'org.apache.catalina.session.StandardSessionFacade@5a2b1e7c
INFO   | jvm 1    | 2016/05/20 04:54:27 | - SecurityContextHolder now cleared, as request processing completed

Using the above example, that whole embedded saml2:Assertion document (from <saml2:Assertion opening XML element to </saml2:Assertion> closing XML element) that contains the attributes can also be selected using a method of choice to format it in a human readable way.

Option 1

1. Copy the whole embedded saml2:Assertion document (from <saml2:Assertion opening XML element to </saml2:Assertion> closing XML element).
2. Open a web browser, go to the Onelogin SAML Developer Tools page and select the XML Pretty Print tool.
3. Paste the copied saml2:Assertion into the XML window and select Turn Pretty.

Option 2

1. Select the whole embedded saml2:Assertion document (from <saml2:Assertion opening XML element to </saml2:Assertion> closing XML element)
2. Save that into a new file somewhere; either on the server or on a local workstation. If saving on a local workstation copy that file to a Linux server and save in /tmp/incoming_response.xml.
3. Run xmllint on the file so that it can be formatted it in a human readable way.

   # xmllint --format /tmp/incoming_response.xml > /tmp/formatted_response.xml

4. Open the /tmp/formatted_response.xml and observe the attributes can be easily viewed line by line:

   <?xml version="1.0"?>
   <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_50725d4fa80d0d5689bd3ca9ac43b97c" IssueInstant="2016-05-20T08:54:26.793Z" Version="2.0">
     <saml2:Issuer>https://accounts.google.com/o/saml2?idpid=C00j2kl1x</saml2:Issuer>
     <saml2:Subject>
       <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml2:NameID>
       <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
         <saml2:SubjectConfirmationData InResponseTo="a32977i74g7e88c731df1915ibj0iec" NotOnOrAfter="2016-05-20T08:59:26.793Z" Recipient="https://mhtest3.blackboard.com/auth-saml/saml/SSO"/>
       </saml2:SubjectConfirmation>
     </saml2:Subject>
     <saml2:Conditions NotBefore="2016-05-20T08:49:26.793Z" NotOnOrAfter="2016-05-20T08:59:26.793Z">
       <saml2:AudienceRestriction>
         <saml2:Audience>https://mhtest3.blackboard.com/shibboleth</saml2:Audience>
       </saml2:AudienceRestriction>
     </saml2:Conditions>
     <saml2:AttributeStatement>
       <saml2:Attribute Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6">
         <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">[email protected]</saml2:AttributeValue>
       </saml2:Attribute>
       <saml2:Attribute Name="urn:oid:2.5.4.42">
         <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Bb</saml2:AttributeValue>
       </saml2:Attribute>
       <saml2:Attribute Name="urn:oid:2.5.4.4">
         <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">User_SAML2</saml2:AttributeValue>
       </saml2:Attribute>
       <saml2:Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">
         <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">[email protected]</saml2:AttributeValue>
       </saml2:Attribute>
     </saml2:AttributeStatement>
     <saml2:AuthnStatement AuthnInstant="2016-05-20T08:54:26.000Z" SessionIndex="_50725d4fa80d0d5689bd3ca9ac43b97c">
       <saml2:AuthnContext>
         <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef>
       </saml2:AuthnContext>
     </saml2:AuthnStatement>
   </saml2:Assertion>

Create a SAML authentication provider and IdP for testing

Use the steps below to create an Identity Provider (IdP) using Centrify's free SSO authentication solution.

That IdP can then be configured as the SAML authentication provider in a Blackboard Learn Service Provider (SP):

Blackboard Learn Service Provider

1. Login to the Blackboard Learn GUI as an administrator and navigate to System Admin > Authentication.
2. Select Create Provider > SAML.
3. Input the following settings:
   • Name > SAML or anything you want.
   • Authentication Provider > Inactive (for now).
   • User Lookup Method > Username
   • Restrict by Hostname > Use this provider for any hostnames
   • Link Text > SAML Centrify Login
4. Select Save and Configure.
5. In the Entity ID field, set this to anything you want (but if you change it you must provide the updated Service Provider Metadata to the Identity Provider). Simply copy/paste the ACS URL.
6. Under Service Provider Metadata, select Generate and save the file to your desktop.
7. Under Data Source, it is recommended to create a new Data Source for this named CENTRIFY, otherwise use SYSTEM or whatever you choose
8. Next to Enable JIT Provisioning, check this box so that an account is automatically created when attempting to login via this SAML authentication provider if the user does not exist. If JIT Provisioning is not selected, the user in Blackboard Learn will need to be created manually.
9. In the Compatible Data Sources list, be sure to select the data sources that this authentication provider should be compatible with.
10. Select Point Identity Provider for the Identity Provider Type.
11. Skip the Identity Provider Metadata for now, you will upload the file after it has been created in the Centrify IdP section.
12. For the Map SAML Attributes section, use NameID for the Remote User ID.
13. Select Submit.

Centrify Identity Provider

1. Go to https://www.centrify.com/express/identity-service and select Start Now in the Express column at the bottom of the page.
2. Enter your info to sign up and select Start Now.
3. A welcome email is then sent with your admin credentials, use that to login to: https://cloud.centrify.com.
4. Select Skip on the Welcome to Centrify Identify Service window.
5. In the Apps tab at the top of the page, select the Add Web Apps button.
6. In the Custom tab, scroll down and select the Add button for SAML. Select Yes.
7. Select Close at the bottom of the Add Web Apps window.
8. Go to the Apps tab. In the Application Settings section, select the Upload SP Metadata button and upload the file that was created in Step 6 of the Blackboard Learn SP section.
9. The Assertion Consumer Service URL should automatically populate after uploading the SP Metadata.
10. Uncheck Encrypt Assertion. This allows the attributes being released from the IdP and sent to Blackboard Learn to be viewed using the Firefox browser SAML tracer Add-on or Chrome SAML Message Decoder.

    As the whole communication is over SSL this will not reduce the security of the authentication

11. Scroll down and select Download Identity Provider SAML Metadata. Save the file to your desktop.
12. Select Save and go to the next section.
13. Enter a name for the Description section. Select Save and go to the next section.
14. In the User Access section, select Everybody and System Administrator. Select Save.
15. Do not make any selections in the Policy section.
16. For the Account Mapping section, confirm that userprincipalname is entered for the Directory Service field name.
17. For the Advanced section, add the following line to the bottom of the script used to generate a SAML assertion for the application:

    The complete script will be:

    setIssuer(Issuer);
    setSubjectName(UserIdentifier);
    setAudience('https://YourLearnServer.blackboard.c...saml/saml/SSO');
    setRecipient(ServiceUrl);
    setHttpDestination(ServiceUrl);
    setSignatureType('Assertion');
    setNameFormat('emailaddress');
    setAttribute("NameID", LoginUser.Get("userprincipalname"));

    Which will allow the Centrify IdP to release an AttributeStatement with the User ID in the SAML POST.

    Example:

    <AttributeStatement>
        <Attribute Name="NameID"
                   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                   >
            <AttributeValue>[email protected]</AttributeValue>
        </Attribute>
    </AttributeStatement>

    More on specifying assertion elements in the Centrify SAML script

18. Select Save.
19. No changes should need to be made to the remaining sections (App Gateway, Changelog and Workflow).
20. In the Apps tab, confirm the SAML app was automatically deployed.
21. In the Users tab, select Add Users, enter the account info for a user, and select Create User.
22. Log back into the Blackboard Learn GUI as an administrator, navigate to System Admin > Authentication > SAML Authentication Provider Name > SAML Settings > Identity Provider Settings, upload the IdP Metadata file that was saved to your desktop in Step 13 and select Submit.

The Centrify IdP user that was created can now login to Blackboard Learn via SAML by selecting that authentication provider on the login page, and logout of Blackboard Learn using the extra End SSO Session logout button on the End all sessions? page that is displayed after selecting the logout button at the top right of Blackboard Learn.

Configuration details in Blackboard Learn database IdP Metadata

If for some reason the original IdP metadata XML file that was uploaded in the Blackboard Learn GUI on the SAML Authentication Settings page is no longer available locally, the contents of that file can be viewed in the Blackboard Learn database. The IdP metadata XML file contents are stored in the extended_data field as a blob data type in the auth_provider table.

Oracle

With the Oracle database used for Enterprise Blackboard Learn systems running Red Hat Linux, since blob is the data type for the extended_data field, the BLOB2CLOB stored procedure should be used in order to view the data:

SELECT  blob2clob(extended_data)
FROM    auth_provider
WHERE   name = '<Authentication Provider Name>'

Certificate and key

The SAML B2 certificate and key values are stored in the Blackboard Learn database in the system_registry table in the registry_key column. They can be viewed with the following query:

SELECT  pk1, dtmodified, registry_key, registry_long_value
FROM    system_registry
WHERE   upper(registry_key) LIKE upper('%saml%')

Change text on End SSO Session logout page

An institution may inquire if it is possible to change the text on the End SSO Session logout page. It is possible to change the text on the End SSO Session logout page by editing the Language Pack:

1. Open the Language Pack file.
2. Navigate to auth-provider-saml/src/main/webapp/WEB-INF/bundles/bb-manifest-en_US.properties.
3. Update the Message Keys:

   saml.single.logout.warning.conent.description // the first line
   saml.single.logout.warning.conent.recommend // second line
   saml.single.logout.warning.endsso.title // third line
   saml.single.logout.warning.endsso.button // the button
   saml.single.logout.warning.backtolearn // the cancel button

Redirect users to the IdP login page

The standard Blackboard Learn login page presents username and password fields for the default Learn Internal authentication provider. When you enable SAML authentication, a small "Sign in using..." link for SAML appears at the bottom of this page, so you may want to redirect users to the IdP's authentication server automatically when they access the Learn login page.

One option to accomplish this is to navigate to System Admin > Authentication and set the default Learn Internal authentication to Inactive, which means a login page is no longer displayed, and immediately the user is redirected to the SAML login. The problem with that option is that it overrides the default login URL and prevents any non-SAML user to login.

To avoid this issue and provide almost the same result, use a Custom Login Page. Users are redirected to the SAML authentication provider's IdP login page, but the default login link is also usable.

1. Ensure the default Learn Internal authentication is active
2. On the default login page, copy the location of the provider redirect e.g. Sign in using... SAML. Right-click on the link and select Copy Link Location.
3. Navigate to System Admin > Communities > Brands and Themes > Customize Login Page.
4. Select Download next to Default Login Page to download the default login JSP file.
5. Open the JSP file with a text editor. Add the following sample HTML to the login JSP file and replace the URL text with the URL that was copied in Step 2.

   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   <html>
   <head>
   <title>Blackboard Learn - Redirect</title>
   <meta http-equiv="REFRESH" content="0;url=https://URL_Goes_Here"></HEAD>
   <BODY style="font-family: arial,sans-serif;font-size: small; color: grey; padding: 1em; ">
   Redirecting... <a style="color:grey" href="https://URL_Goes_Here">Go to login page</a> if you are not automatically redirected.
   </BODY>
   </HTML>

6. Navigate to Customize Login Page in Learn once more. Select Use Custom Page and then upload the updated login JSP file.
7. After making the changes, select Preview on the Customize Login Page to confirm the redirect is working properly.

Users going to the main URL will now be redirected to the login page for the SAML authentication provider. Administrators can still log in using the Learn internal authentication via the default login page: /webapps/login/?action=default_login or/webapps/login/login.jsp.

More on customizing the login page in the Ultra experience