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 隨附一個名為 [預設] 的內建網頁佈景主題。 您無法修改建立預設網頁佈景主題的 onload.js 內容。 若要更新 onload.js 檔案，請建立並使用 AD FS 登入頁面的自訂網頁佈景主題。 如需詳細資訊，請參閱 AD-FS 使用者登入自訂。

  • 預設網頁佈景主題的原始 onload.js 檔案也包含處理不同外形規格的頁面呈現的程式碼。 建議的自訂方法是將自訂邏輯程式碼附加到現有的 onload.js 檔案中。 請勿修改原始的 onload.js 檔案內容。

  • 當您引用 HTML 元素時，請務必在對元素進行動作之前檢查該元素是否存在。 此步驟提供了穩健性並確保自訂邏輯不會在不包含此元素的頁面上執行。 若要識別現有 HTML 元素，請檢視 AD FS 登入頁面上的 HTML 原始碼。

  • 建議您在將自訂項目移至生產 AD FS 伺服器之前在替代環境中驗證您的自訂項目並執行測試。 此步驟可降低在驗證之前讓一般使用者接觸到自訂項目的機會。

自訂步驟

下列各節提供自訂 AD FS 登入頁面的 onload.js 檔案內容的步驟。

自訂網頁佈景主題

若要將自訂邏輯新增至 onload.js 檔案，第一個步驟是建立自訂網頁佈景主題。 一種快速的方法是匯出預設的網頁佈景主題，然後使用原始的程式碼作為自訂的基礎。

執行下列的 Cmdlet，以藉由複製預設的網頁佈景主題來建立自訂網頁佈景主題：

New-AdfsWebTheme –Name custom –SourceName default

產生 onload.js 檔案

下一個步驟是匯出自訂網頁佈景主題，以便您擁有可以更新的 onload.js 檔案。

執行下列的 Cmdlet，以匯出自訂網頁佈景主題並產生 onload.js 檔案：

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

onload.js 檔案會放在該 Cmdlet 中指定的目錄的 script 資料夾中。 在此範例中，指定的資料夾是 c:\theme。

新增自訂項目

現在您可以修改 onload.js 內容並為您的案例新增自訂邏輯程式碼了。 如前所述，請務必將自訂程式碼新增至 onload.js 檔案的末尾。

請參閱下列的範例小節，以了解示範常見自訂的程式碼片段。

變更目標 onload.js 檔案

新增自訂項目後，您需要更新 AD FS 網頁佈景主題來使用您的 onload.js 檔案，而不是原始的 onload.js 檔案。

執行下列的 Cmdlet，將您的 onload.js 檔案設為網頁佈景主題定義的目標：

  • 對於 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;
    };

}