進階 AD FS 登入頁面的自訂項目Advanced Customization of AD FS Sign-in Pages

適用於:Windows Server 2016、Windows Server 2012 R2Applies To: Windows Server 2016, Windows Server 2012 R2

AD FS Sign\ 在網頁中的進階的自訂項目Advanced Customization of AD FS Sign-in Pages

在 Windows Server 2012 R2 AD FS 提供 built\ 中支援自訂 sign\ 中的體驗。AD FS in Windows Server 2012 R2 provides built-in support for customizing the sign-in experience. 針對大部分在這些案例中,built\ 中的 Windows PowerShell cmdlet 是所需的所有。For a majority of these scenarios, the built-in Windows PowerShell cmdlets are all that is required. 建議使用 built\ 中的 Windows PowerShell 命令自訂 AD FS sign\ 中體驗盡可能標準項目。It is recommended that you use the built-in Windows PowerShell commands to customize standard elements for AD FS sign-in experience whenever possible. 查看AD FS 使用者登入自訂如需詳細資訊。See AD-FS user sign-in customization for more information.

有時候,AD FS 管理員可能會想要提供其他 sign\ 中體驗未可以透過出貨 in\ 隨 AD FS 使用的現有 PowerShell 命令。In some cases, AD FS administrators may want to provide additional sign-in experiences that are not possible through the existing PowerShell commands that ship in-box with AD FS. 在某些案例中,會 \ (在提供指導方針 below) sign\ 中體驗進一步自訂透過新增額外的邏輯以系統管理員的onload.js ,AD FS 提供,並將會執行的所有 AD FS 頁面上。In certain instances, it is feasible (within the guidelines provided below) for administrators to customize the sign-in experience further by adding additional logic to onload.js that is provided by AD FS and will be executed on all the AD FS pages.

在您開始之前必須知道的事項Things to know before you start

  • 不支援影響的重新導向流程或修改通訊協定參數 AD FS 使用的任何變更。Any change that impacts the redirect flows or modifies protocol parameters that AD FS works with is not supported.

  • 原始 onload.js,其中隨附的預設網頁主題,包含處理的不同尺寸規格頁面轉譯的程式碼。The original onload.js, the one that comes with the default web theme, contains code that handles page rendering for different form factors. 最好不是修改原始 onload.js content,但僅限處理自訂邏輯現有 onload.js 附加程式碼。It is recommended not to modify the original onload.js content but only append your code to the existing onload.js that handles custom logic.

  • AD FS 隨附 built\ 中 web 主題稱為預設值。AD FS ships with a built-in web theme which is called Default. 您無法修改 onload.js 的預設網頁主題。You cannot modify the onload.js of the Default web theme. 若要更新 onload.js,您必須建立和自訂 web 主題使用 AD FS sign\ 在網頁。To update onload.js, you have to create and use a custom web theme for AD FS sign-in pages. 查看AD FS 使用者登入自訂如需如何建立自訂 web 主題的資訊。See AD-FS user sign-in customization for information on how to create a custom web theme.

  • 在所有 ADFS 頁面 (ex.來執行相同 onload.jsThe same onload.js will execute on all ADFS pages (ex. form\ 登入頁面,家用領域探索頁面等。 )。form-based logon page, home realm discovery page and etc.). 您必須先確認指令碼的程式碼僅限取得執行的設計目的是並不會意外地執行。You need to make sure the code in your script only gets executed as it is designed and does not get executed unexpectedly.

  • 當參考 HTML 的任何項目,請確定您總是檢查有差的項目上做之前的項目。When referencing any HTML element, ensure that you always check for the existence of the element prior to acting on the element. 這提供穩定性,並確保自訂邏輯不包含此項目網頁上並不會執行。This provides robustness and ensures that the custom logic would not be executed on pages that do not contain this element. 您只是可以檢視 HTML 來源 AD FS sign\ 在頁面上,檢視現有的項目。You can simply view the HTML source on the AD FS sign-in pages to view the existing elements.

  • 建議來驗證您的備用環境中的自訂項目及復原出到 production AD FS 伺服器前進行測試。It is strongly recommended to validate your customizations in an alternate environment and test them prior to rolling it out onto production AD FS servers. 這樣可以降低公開驗證之前這些自訂給終端使用者的機會。This reduces the chances of end users being exposed to these customizations prior to validation.

自訂體驗 sign\ 中 AD FS 使用 onload.jsCustomizing the AD FS sign-in experience by using onload.js

自訂 onload.js AD FS 服務時,請使用下列步驟。Use the following steps when customizing the onload.js for the AD FS service.

自訂 onload.js AD FS 服務Customizing onload.js for the AD FS Service

  1. 若要加入 onload.js 您自訂的邏輯,您需要先建立自訂 web 主題。To add your custom logic to onload.js, you need to first create a custom web theme. 預設稱為「已推出的 out\ of-the-方塊的主題。The theme that is shipped out-of-the-box is called Default. 您可以匯出預設的主題,並使用它,以便您可以快速開始。You can export the default theme and use it so that you can start quickly. 下列 cmdlet 建立自訂 web 主題,請重複的預設網頁主題:The following cmdlet creates a custom web theme, which duplicates the default web theme:

    New-AdfsWebTheme –Name custom –SourceName default  
    
  2. 然後,您可以匯出自訂或 web 主題取得 onload.js 檔案的預設值。You can then export the custom or default web theme to get onload.js file. 若要匯出 web 主題,請使用下列 cmdlet:To export a web theme, use the following cmdlet:

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

    您會找到 onload.js 指令碼資料夾中的 [directory 您指定匯出 cmdlet 上述,並加入您的自訂邏輯指令碼 \ (查看使用案例中範例區段 below)。You will find onload.js under the script folder in the directory that you specify in the export cmdlet above and add your custom logic to the script (see use cases in the Example section below).

  3. 進行需要修改自訂 onload.js 根據您的需求。Make the necessary modification to customize onload.js based on your need.

  4. 已修改 onload.js 更新的主題。Update the theme with the modified onload.js. 使用下列 cmdlet 更新 onload.js 自訂 web 主題適用於:Use the following cmdlet to apply the update onload.js to custom web theme:

    Set-AdfsWebTheme -TargetName custom -AdditionalFileResource @{Uri=’/adfs/portal/script/onload.js’;path="c:\theme\script\onload.js"}  
    
  5. AD FS 来套用的自訂 web 主題,請使用下列 cmdlet:To apply the custom web theme to AD FS, use the following cmdlet:

    Set-AdfsWebConfig -ActiveThemeName custom  
    

其他自訂範例Additional Customization Examples

以下是新增到不同的 fine\ 調整供 onload.js 自訂的程式碼範例。The following are the examples of custom code added to onload.js for different fine-tune purposes. 新增時自訂的程式碼,請附加自訂您的驗證碼至 onload.js 底部。When adding the custom code, please always append your custom code to the bottom of the onload.js.

變更 「 使用 account 組織的登入] 字串,例如 1:Example 1: change “Sign in with organizational account” string

預設 AD FS form\ 型 sign\ 在頁面上有 「 登入您的組織帳號 「 標題上述方塊中輸入的使用者。The default AD FS form-based sign-in page has a title of “Sign in with your organizational account” above user input boxes.

如果您想要這個字串取代您自己的字串,您可以加入 onload.js 下列程式碼。If you want to replace this string with your own string, you can add the following code to onload.js.

// Sample code to change “Sign in with organizational account” string.  

// Check whether the loginMessage element is present on this page.  
var loginMessage = document.getElementById('loginMessage');  
if (loginMessage)  
{  
       // loginMessage element is present, modify its properties.  
       loginMessage.innerHTML = 'Your company description text';  
}  

範例 2: 接受 SAM\ 帳號 AD FS form\ 型 sign\ 在頁面上的登入格式Example 2: accept SAM-account name as a login format on an AD FS form-based sign-in page

預設的使用者主體名稱 (UPNs) (for example, ** johndoe@contoso.com ) 或網域 AD FS form\ 型 sign\ 中頁面支援登入格式完整 sam-account 名稱 \ (contoso\johndoecontoso.com\johndoe)。The default AD FS form-based sign-in page supports login format of User Principal Names (UPNs) (for example, **johndoe@contoso.com) or domain qualified sam-account names (contoso\johndoe or contoso.com\johndoe). 以方便您使用者的所有來自相同的網域,只有關於 sam-account 名稱知道您可能想要支援可以在登入的使用者案例中使用只 sam-account 名稱。In case all of your users come from the same domain and they only know about sam-account names, you may want to support the scenario where the users can sign in using them sam-account names only. 您可以新增下列程式碼來 onload.js 支援此案例,只是想要使用的網域取代網域 」 contoso.com 」 在範例如下。You can add the following code to onload.js to support this scenario, just replace the domain “contoso.com” in the example below with the domain that you want to use.

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);  
    if (userName.value && !userName.value.match('[@\\\\]'))   
    {  
        var userNameValue = 'contoso.com\\' + userName.value;  
        document.forms['loginForm'].UserName.value = userNameValue;  
    }  

    if (!userName.value) {  
       u.setError(userName, e.userNameFormatError);  
       return false;  
    }  

    if (!password.value)   
    {  
        u.setError(password, e.passwordEmpty);  
        return false;  
    }  
    document.forms['loginForm'].submit();  
    return false;  
};  
}  

其他參考資料Additional references

AD FS 使用者登入自訂AD FS User Sign-in Customization