Compartilhar via

Personalização avançada das páginas de logon do AD FS

O AD FS (Serviços de Federação do Active Directory) no Windows Server 2012 R2 e em versões posteriores dá suporte à personalização da experiência de logon do usuário. Para a maioria dos cenários, é possível usar os cmdlets internos do Windows PowerShell para configurar as páginas de logon do AD FS. A abordagem recomendada é usar, sempre que possível, os comandos internos do Windows PowerShell para a personalização. Para saber mais, confira Personalização de logon do usuário do AD-FS.

Às vezes, pode ser necessário fornecer uma experiência de logon que não é habilitada por meio dos comandos do PowerShell que acompanham o AD FS. Para isso, é possível configurar a experiência de logon adicionando um código personalizado ao arquivo onload.js fornecido com o AD FS. O código do arquivo é executado em todas as páginas do AD FS.

Considerações

Antes de começar a personalizar as páginas de logon do AD FS, examine as considerações importantes a seguir.

Importante

Nenhuma alteração de personalização que afete os fluxos de redirecionamento ou modifique os parâmetros de protocolo usados pelo AD FS é compatível.

  • O arquivo onload.js é executado em todas as páginas do AD FS, incluindo páginas de logon baseado em formulário, páginas de descoberta de realm inicial e assim por diante. Certifique-se sempre de que o código personalizado seja executado somente conforme pretendido e não inesperadamente.

  • O AD FS é fornecido com um tema da Web interno chamado padrão. Não é possível modificar o conteúdo de onload.js que cria o tema da Web padrão. Para atualizar o arquivo onload.js, crie e use um tema da Web personalizado para as páginas de logon do AD FS. Para saber mais, confira Personalização de logon do usuário do AD-FS.

  • O arquivo onload.js original do tema da Web padrão também contém o código para lidar com a renderização de página de diferentes fatores forma. A abordagem de personalização recomendada é anexar seu código lógico personalizado ao arquivo onload.js existente. Não modifique o conteúdo original do arquivo onload.js.

  • Ao fazer referência a elementos HTML, sempre verifique a existência do elemento antes de agir sobre ele. Essa etapa fornece robustez e garante que a lógica personalizada não seja executada em páginas que não contenham esse elemento. Para identificar os elementos HTML existentes, exiba a fonte HTML nas páginas de logon do AD FS.

  • É recomendado validar as personalizações em um ambiente alternativo e executar testes antes de movê-las para os servidores do AD FS de produção. Essa etapa reduz as chances de expor os usuários finais a personalizações não validadas.

Etapas de personalização

As seções a seguir fornecem as etapas para personalizar o conteúdo do arquivo onload.js para as páginas de logon do AD FS.

Criar um tema da Web personalizado

Para adicionar sua lógica personalizada ao arquivo onload.js, a primeira etapa é criar um tema da Web personalizado. Um método rápido é exportar o tema da Web padrão e usar o código original como base para as personalizações.

Execute o seguinte cmdlet para criar um tema da Web personalizado duplicando o tema da Web padrão:

New-AdfsWebTheme –Name custom –SourceName default

Gerar o arquivo onload.js

A próxima etapa é exportar o tema da Web personalizado para ter um arquivo onload.js que possa ser atualizado.

Execute o seguinte cmdlet para exportar o tema da Web personalizado e gerar um arquivo onload.js:

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

O arquivo onload.js é colocado na pasta script do diretório especificado no cmdlet. No exemplo, a pasta especificada é c:\theme.

Adicionar personalizações

Agora você está pronto para modificar o conteúdo de onload.js e adicionar o código lógico customizado relativo aos seus cenários. Conforme mencionado, certifique-se de adicionar o código personalizado ao final do arquivo onload.js.

Confira a seção Exemplos a seguir para obter trechos de código que demonstram personalizações comuns.

Alterar o arquivo onload.js de destino

Depois de adicionar as personalizações, atualize o tema da Web do AD FS para usar o seu arquivo onload.js em vez do arquivo onload.js original.

Execute o seguinte cmdlet para definir o seu arquivo onload.js como o destino para as definições de tema da Web:

  • Para o AD FS no Windows Server 2016 e posterior:

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

  • Para o AD FS no Windows Server 2012 R2:

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

Aplicar personalizações ao AD FS

A última etapa é aplicar as personalizações às páginas de logon do AD FS.

Execute o seguinte cmdlet para atualizar o AD FS com as personalizações:

Set-AdfsWebConfig -ActiveThemeName custom

Exemplos

Os exemplos a seguir fornecem um código personalizado que pode ser adicionado ao arquivo onload.js para configurar as páginas de logon do AD FS.

Observação

Sempre anexe o código personalizado ao final do arquivo onload.js.

Alterar a cadeia de título da página de logon

A página de logon baseado em formulário do AD FS exibe um título acima dos campos de entrada do usuário. O valor de título padrão é "Entre com sua conta organizacional".

Substitua o valor da cadeia de caracteres padrão por uma cadeia personalizada adicionando o código a seguir ao arquivo onload.js. No código, defina o valor do parâmetro loginMessage.innerHTML para a cadeia de caracteres personalizada a ser usada para o título.

// 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';
}

Aceitar o logon com um nome de conta de SAM

A página de logon baseado em formulário do AD FS dá suporte a dois métodos de entrada por padrão:

  • userPrincipalName": A user principal name (UPN), such as user@contoso.com`.
  • samAccountName: um nome de conta de SAM (Gerenciador de Contas de Segurança) qualificado pelo domínio, como contoso\user ou contoso.com\user.

Considere um cenário em que todos os usuários estão no mesmo domínio e sabem apenas o nome da conta de SAM. É possível atualizar a página de logon para permitir que os usuários entrem usando somente o nome da conta de SAM.

Habilite apenas o logon de contas de SAM adicionando o código a seguir ao arquivo onload.js. No código, defina o valor do parâmetro userNameValue para o domínio desejado.

// 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;
    };

}