本主题提供了相关说明,用于通过 Active Directory 联合身份验证服务 (ADFS) 在 Blackboard Learn 实例上将 SAML 验证设置为身份验证提供程序。您的 Blackboard Learn 环境充当服务提供程序 (SP)。虽然以下步骤在 Windows Server 2012 R2 上使用 ADFS 3.0 版本,但其也适用于 ADFS 2.0。

Learn 服务提供程序

  1. 以管理员身份登录到 Blackboard Learn 并导航到系统管理员 > 验证
  2. 依次选择创建提供程序 > SAML
  3. 输入以下设置:
    • 名称 > 键入 ADFS SAML 或所需的任何内容。
    • 验证提供程序 > 设为非活动
    • 用户查找方法 > 用户名
    • 受主机名限制 > 将此提供程序用于任何主机名。
    • 链接文本 > 键入 ADFS 登录或所需的任何内容。
  4. 选择保存并配置
  5. 实体 ID 字段,确保其中的值与 ACS URL 相同。
  6. 服务提供程序元数据下方,选择生成,然后将文件保存到您的桌面。
  7. 建议为这个名为 SAML 的提供程序新建一个数据源,否则,使用系统或您所选的任何内容。
  8. 选中启用 JIT 配置复选框,以允许系统在未知用户试图通过此 SAML 验证提供程序登录时自动创建帐户。如果未选中此框,则首先需要在 Blackboard Learn 中手动创建用户帐户。
  9. 兼容数据源列表中,务必选择应与此验证提供程序兼容的数据源。
  10. 身份验证提供程序类型选择单点身份验证提供程序
  11. 对于身份验证提供程序元数据,ADFS 的元数据 XML 文件包括与 SAML 2.0 不兼容的元素。在上传元数据之前,您需要对其编辑,以删除不兼容的元素。
    1. ADFS 联合默认元数据的位置为 https://[ADFS server hostname]/FederationMetadata/2007-06/FederationMetadata.xml
    2. 下载此文件并在文本编辑器中将其打开。谨慎删除开头为 <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"&gt; ... </X509Data></KeyInfo>和结尾为 </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&gt; 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>

    3. 将更新后的元数据 XML 文件上传到 Blackboard Learn。
  12. 对于映射 SAML 属性部分,将 SamAccountName 用于 远程用户 ID
  13. 选择提交

ADFS 身份验证提供程序

  1. 在 ADFS 服务器上,访问 ADFS 管理控制台
  2. 导航到信任关系 > 信赖方信任 > 添加信赖方信任
  3. 添加信赖方信任向导页面上选择开始
  4. 选择从文件导入有关信赖方的数据
  5. 选择浏览,然后上传在 Learn SP 部分第 6 步创建的文件。选择下一步
  6. 输入显示名称(如 yourlearnserver.blackboard.com)并选择下一步
  7. 选择我不想配置多重身份验证设置…,然后选择下一步
  8. 选择允许所有用户访问此信赖方并选择下一步
  9. 选择准备好添加信任这一步骤中的下一步,然后在完成步骤中选择关闭
  10. 创建完信赖方信任之后,如果最后一个复选框被选中,则其应该会打开编辑声明规则。否则,右键单击信赖方信任并选择编辑声明

为信赖方信任添加声明规则

以声明方式发送属性

为信赖方信任添加声明规则会以声明方式将 LDAP 属性从 ADFS 服务器发送到 Blackboard Learn。在 ADFS 管理控制台中,右键单击“信赖方信任”。

发送用户名

  1. 颁发转换规则标签上,选择添加规则
  2. 选择规则模板页面上,将以声明方式发送 LDAP 特性选为声明规则模板,然后选择下一步
  3. 配置规则页面的声明规则名称框中,键入将用户名转换为 NameID
  4. 特性存储下拉列表中,选择 Active Directory
  5. 在左侧的映射框中,选择 SAM-Account-Name公司
  6. 在右侧的映射框中,键入 SamAccountName,然后选择完成

发送名字和姓氏(可选)

如果 Blackboard Learn SAML 验证设置页面上的 JIT 配置选项处于选中状态,也就是说,用户帐户会在不存在时在 Blackboard Learn 中创建,则通过映射相应的属性,名字姓氏 LDAP 属性也可以从 ADFS 发送到 Blackboard Learn。

  1. 颁发转换规则标签上,选择添加规则
  2. 选择规则模板页面上,将以声明方式发送 LDAP 特性选为声明规则模板,然后选择下一步
  3. 配置规则页面的声明规则名称框中,键入发送名字
  4. 特性存储下拉列表中,选择 Active Directory
  5. 在左侧的映射框中,选择 Given-Name
  6. 在右侧的映射框中,键入 urn:oid:2.5.4.42,然后选择完成
  7. 颁发转换规则标签上,选择添加规则
  8. 选择规则模板页面上,将以声明方式发送 LDAP 特性选为声明规则模板,然后选择下一步
  9. 配置规则页面的“声明规则名称”框中,键入发送姓氏
  10. 特性存储下拉列表中,选择 Active Directory
  11. 在左侧的映射框中,选择姓氏
  12. 在右侧的映射框中,键入 urn:oid:2.5.4.4,然后选择完成

转换传入声明

  1. 选择添加规则
  2. 选择规则模板页面上,为声明规则模板选择转换传入声明,然后选择下一步
  3. 配置规则页面的声明规则名称框中,键入将电子邮件转换名称 ID
  4. 传入声明类型应该为 SamAccountName。它必须与在之前规则中创建的传出声明类型匹配。
  5. 传出声明类型名称 ID
  6. 传出名称 ID 格式未指定
  7. 确认已选择传递所有声明值,然后选择完成
  8. 选择确定以保存规则,再选择一次确定以完成属性映射。

示例属性语句

信赖方信任添加上文所述的所有声明规则后,规则会显示在颁发转换规则标签中。

主题AttributeStatement 元素(类似于下文)会在用户经过验证后通过 SAML POST 从 ADFS 发送到 Blackboard Learn:

<Subject>
    <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified ">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>

如果来自 IdP 的属性在 SAML 响应中未经过加密,则 Firefox 浏览器 SAML 跟踪器附加组件Chrome SAML Message Decoder 可用于查看此类属性(即从 IdP 发出并在验证过程中发送给 Blackboard Learn)。


将 ADFS 配置为使用 SHA-1

  1. 导航至“管理员面板”。
  2. Building Block 下方,选择 Building Block
  3. 选择已安装的工具
  4. 在列表中找到验证提供程序 - SAML。打开菜单并选择设置
  5. 在“签名算法设置”下方,选择列表中的“SHA-1”。选择签名算法类型后,重新启动 SAML Building Block 以应用新设置。
  6. 选择提交以保存更改。

其他重要的 ADFS 配置

默认情况下,ADFS 采用 AES-256 对其发送的属性加密。Blackboard Learn 使用的 Java 运行时不支持立即可用的 AES-256。用户将无法通过 SAML 验证登录,日志中会记录以下与 SAML 相关的错误消息。

/usr/local/blackboard/logs/bb-services-log.txt中:

2016-10-26 13:16:51 -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)
 [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

/usr/local/blackboard/logs/tomcat/catalina-log.txt中:

ERROR 2016-10-26 13:16:51,519 connector-38: userId={unset id}, sessionId=85DC3851365512EE96AABFBB8E5A519C 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:87)
    [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.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)
    ... 238 more

由于 Blackboard Learn SaaS 后端配置通常不受支持,因此,通用解决方法是,在 ADFS 服务器上打开 PowerShell,并设置为 Blackboard Learn 创建的信赖方,以未加密的形式发送属性。由于整个通信都是通过 SSL 进行的,因此这不会降低验证的安全性。它还可以使任何问题的调试变得更加轻松,因为属性可以通过调试工具进行查看,而且无需重新启动 Blackboard Learn 系统。

要设置为 Blackboard Learn 创建的信赖方以未加密的形式发送属性,请打开 PowerShell 并执行以下命令,从而使用为上文创建的信赖方所提供的名称替换 TargetName:

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

做出上述更改后,需要通过以下命令重新启动 ADFS 服务:Restart-Service ADFSSRV


将 SAML 验证提供程序设为活动状态

  1. 在 Blackboard Learn 中,导航到“系统管理员”>“验证”。
  2. 打开 SAML 验证提供程序名称旁边的菜单,然后将其设为活动

随后,ADFS IdP 会成功配置为 SAML 验证提供程序,可用于登录到 Blackboard Learn。

  1. 在 Blackboard Learn 登录页面,选择使用第三方帐户登录
  2. 选择 SAML 验证提供程序。
  3. 在 ADFS 登录页面输入登录凭证。

自动重新定向到 IdP 登录页面

由于标准 Blackboard Learn 登录页面会显示默认 Blackboard Learn 内部验证提供程序的用户名/密码字段以及 SAML 的登录方式…小链接,因此,当机构启用 SAML 验证时,其可能会请求在用户首次访问 Blackboard Learn 站点时自动将用户重新定向到 IdP 验证服务器。

在 Blackboard Learn GUI 完成此操作的一个方法是,导航到系统管理员 > 验证并将默认 Blackboard Learn 内部验证设置为非活动,这意味着,登录页面不再显示,系统会立即将用户重新定向到 SAML 登录。但使用此方法的问题是,它会覆盖默认登录 URL 并阻止任何非 SAML 用户登录。

避免此问题和提供几乎相同结果的方法是使用“定制登录页面”,以便用户重新定向到 SAML 验证提供程序的 IdP 登录页面,但默认登录链接还可供使用。

您可以 创建自定义登录页面,这样用户会被重定向到 SAML 验证提供程序的 IdP 登录页面。如果需要,默认登录链接仍可供使用。

  1. 请确保默认 Blackboard Learn 内部验证处于活动状态。
  2. 转到默认登录页面,然后复制提供程序重新定向的位置,如登录方式…SAML(不要打开该链接,使用复制链接位置)。
  3. 在 Blackboard Learn GUI 中,导航到系统管理员 > 社区:主页面和主题风格 > 定制登录页面
  4. 选择默认登录页面文本旁边的下载,以下载默认登录 JSP 文件。
  5. 使用文本编辑器打开下载的登录 JSP 文件。
  6. 向登录 JSP 文件添加以下示例 HTML,同时将 URL 文本替换为在第 2 步复制的 URL(在两个地方,它显示 https://URL_Goes_Here)

    <!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&gt; if you are not automatically redirected.
    </BODY>
    </HTML>

  7. 返回到 Blackboard Learn GUI 的定制登录页面,选择使用定制登录页面,然后上传更新后的登录 JSP 文件。
  8. 做出相应更改后,选择定制登录页面上的预览,确认重新定向可以正常运行。

现在,转到主要 URL 的用户可以重新定向到 SAML 验证提供程序的登录页面。此外,管理员仍可以使用 Blackboard Learn 内部验证通过默认登录页面进行登录:/webapps/login/?action=default_login(aka /webapps/login/login.jsp)。

详细了解自定义原始体验的登录页面

详细了解自定义 Ultra 体验的登录页面