AD FS 登录页的高级自定义

  • 项目

Windows Server 2012 R2 及更高版本中的 Active Directory 联合身份验证服务 (AD FS) 支持自定义用户登录体验。 在大多数情况下，可以使用内置的 Windows PowerShell cmdlet 来配置 AD FS 登录页。 建议的方法是尽可能使用内置的 Windows PowerShell 命令进行自定义。 有关详细信息，请参阅 AD-FS 用户登录自定义。

有时，可能需要提供无法使用 AD FS 附带的 PowerShell 命令启用的登录体验。 可以通过将自定义代码添加到随 AD FS 提供的 onload.js 文件来配置登录体验。 文件代码在所有 AD FS 页上执行。

注意事项

在开始自定义 AD FS 登录页之前，请查看以下重要注意事项。

重要

不支持任何影响重定向流或修改 AD FS 使用的协议参数的自定义更改。

  • onload.js 文件在所有 AD FS 页上执行，包括基于窗体的登录页、主领域发现页等。 始终确保自定义代码仅按预期执行，而不会意外执行。

  • AD FS 附带称为“默认”的内置 Web 主题。 无法修改创建默认 Web 主题的 onload.js 内容。 若要更新 onload.js 文件，请创建并使用 AD FS 登录页的自定义 Web 主题。 有关详细信息，请参阅 AD-FS 用户登录自定义。

  • 默认 Web 主题的原始 onload.js 文件还包含用于处理不同外形规格的页面呈现的代码。 建议的自定义方法是将自定义逻辑代码追加到现有的 onload.js 文件。 不要修改原始 onload.js 文件内容。

  • 引用 HTML 元素时，请务必在对元素执行操作之前检查该元素是否存在。 这个步骤比较稳妥，可确保自定义逻辑不会在不包含此元素的页面上执行。 若要标识现有 HTML 元素，请在 AD FS 登录页上查看 HTML 源。

  • 建议在将自定义项移动到生产 AD FS 服务器之前，在备用环境中验证自定义项并运行测试。 此步骤降低了在验证之前最终用户接触到这些自定义项的可能性。

自定义步骤

以下部分提供为 AD FS 登录页自定义 onload.js 文件内容的步骤。

创建自定义 Web 主题

若要将自定义逻辑添加到 onload.js 文件，第一步是创建自定义 Web 主题。 快速方法是导出默认 Web 主题，然后使用原始代码作为自定义的基础。

运行以下 cmdlet，通过复制默认 Web 主题创建自定义 Web 主题：

New-AdfsWebTheme –Name custom –SourceName default

生成 onload.js 文件

下一步是导出自定义 Web 主题，以便拥有可更新的 onload.js 文件。

运行以下 cmdlet 以导出自定义 Web 主题并生成 onload.js 文件：

Export-AdfsWebTheme –Name default –DirectoryPath c:\theme

onload.js 文件放置在 cmdlet 指定目录中的 script 文件夹中。 在此示例中，指定的文件夹为 c:\theme。

添加自定义项

现在，你已准备好修改 onload.js 内容并为方案添加自定义逻辑代码。 如上所述，请务必将自定义代码添加到 onload.js 文件的末尾。

有关演示常见自定义的代码片段，请参阅以下示例部分。

更改目标 onload.js 文件

添加自定义项后，需要更新 AD FS Web 主题以使用你的 onload.js 文件而不是原始 onload.js 文件。

运行以下 cmdlet，将 onload.js 文件设置为 Web 主题定义的目标：

  • Windows Server 2016 和更高版本上的 AD FS：

    Set-AdfsWebTheme -TargetName custom -OnLoadScriptPath "c:\theme\script\onload.js"

  • 对于 Windows Server 2012 R2 上的 AD FS：

    Set-AdfsWebTheme -TargetName custom -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\theme\script\onload.js"}

将自定义应用于 AD FS

最后一步是将自定义项应用于 AD FS 登录页。

运行以下 cmdlet 以使用自定义项更新 AD FS：

Set-AdfsWebConfig -ActiveThemeName custom

示例

以下示例提供可添加到 onload.js 文件以配置 AD FS 登录页的自定义代码。

备注

始终将自定义代码追加到 onload.js 文件的末尾。

更改登录页标题字符串

AD FS 基于窗体的登录页在用户输入字段上方显示标题。 默认标题值为“使用组织帐户登录”。

通过将以下代码添加到 onload.js 文件，将默认字符串值替换为自定义字符串。 在代码中，将 loginMessage.innerHTML 参数的值设置为要用于标题的自定义字符串。

// Sample code to change page title string

// Check if loginMessage element is present
var loginMessage = document.getElementById('loginMessage');
if (loginMessage)
{
       // If loginMessage element is present, change title to custom value
       loginMessage.innerHTML = 'Custom title string value';
}

接受 SAM 帐户名称登录

默认情况下，AD FS 基于窗体的登录页支持两种登录方法：

  • userPrincipalName": A user principal name (UPN), such as user@contoso.com`.
  • samAccountName：域限定的安全帐户管理员 (SAM) 帐户名称，例如 contoso\user 或 contoso.com\user。

假设所有用户都在同一域中，并且用户只知道其 SAM 帐户名称。 可以更新登录页，以允许用户仅使用其 SAM 帐户名称登录。

通过将以下代码添加到 onload.js 文件，仅支持从 SAM 帐户登录。 在代码中，将 userNameValue 参数的值设置为所需的域。

// Sample code to enable user login from SAM account name only

if (typeof Login != 'undefined'){

    Login.submitLoginRequest = function () {
    
    var u = new InputUtil();
    var e = new LoginErrors();
    var userName = document.getElementById(Login.userNameInput);
    var password = document.getElementById(Login.passwordInput);

    // Update login method with desired domain value
    if (userName.value && !userName.value.match('[@\\\\]'))
    {
        var userNameValue = 'contoso.com\\' + userName.value;
        document.forms['loginForm'].UserName.value = userNameValue;
    }
    
    // Check for user name errors
    if (!userName.value) {
       u.setError(userName, e.userNameFormatError);
       return false;
    }

    // Check for password errors
    if (!password.value)
    {
        u.setError(password, e.passwordEmpty);
        return false;
    }

    // Update the form page 
    document.forms['loginForm'].submit();
    return false;
    };

}