Partilhar via

Personalização avançada de páginas de início de sessão do AD FS

Os Serviços de Federação do Ative Directory (AD FS) no Windows Server 2012 R2 e versões posteriores oferecem suporte à personalização da experiência de entrada do usuário. Para a maioria dos cenários, você pode usar os cmdlets internos do Windows PowerShell para configurar as páginas de entrada do AD FS. A abordagem recomendada é usar os comandos internos do Windows PowerShell para personalização sempre que possível. Para obter mais informações, consulte AD-FS personalização de entrada do usuário.

Às vezes, talvez seja necessário fornecer uma experiência de entrada que não pode ser habilitada usando os comandos do PowerShell que vêm com o AD FS. Pode configurar a experiência de início de sessão adicionando código personalizado ao ficheiro onload.js fornecido com o AD FS. O código do ficheiro é executado em todas as páginas do AD FS.

Considerações

Antes de começar a personalizar as páginas de início de sessão do AD FS, reveja as seguintes considerações importantes.

Importante

Não há suporte para qualquer alteração de personalização que afete os fluxos de redirecionamento ou modifique os parâmetros de protocolo usados pelo AD FS.

  • O ficheiro onload.js é executado em todas as páginas do AD FS, incluindo páginas de início de sessão baseadas em formulários, páginas de descoberta do domínio principal, e assim por diante. Certifique-se sempre de que o seu código personalizado é executado apenas como pretendido e não inesperadamente.

  • O AD FS vem com um tema da Web interno padrão chamado . Não é possível modificar o conteúdo onload.js que cria o tema da Web padrão. Para atualizar o ficheiro onload.js, crie e utilize um tema Web personalizado para páginas de início de sessão do AD FS. Para obter mais informações, consulte a personalização de início de sessão do usuário AD-FS .

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

  • Quando você faz referência a elementos HTML, sempre verifique a existência do elemento antes de agir sobre o elemento. Esta 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 elementos HTML existentes, exiba a fonte HTML nas páginas de início de sessão do AD FS.

  • É recomendável validar suas personalizações em um ambiente alternativo e executar testes antes de mover suas personalizações para servidores AD FS de produção. Essa etapa reduz as chances de expor os usuários finais a personalizações antes da validação.

Etapas de personalização

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

Criar 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, em seguida, usar o código original como base para suas 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 arquivo onload.js

A próxima etapa é exportar seu tema da Web personalizado para que você tenha um arquivo de onload.js que possa atualizar.

Execute o seguinte cmdlet para exportar seu 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 no diretório especificado no cmdlet. No exemplo, a pasta especificada é c:\theme.

Adicionar personalizações

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

Consulte 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, você precisa atualizar o tema da Web do AD FS para usar o arquivo onload.js em vez do arquivo onload.js original.

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

  • Para AD FS no Windows Server 2016 e versões posteriores:

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

  • para 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 suas personalizações às páginas de entrada do AD FS.

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

Set-AdfsWebConfig -ActiveThemeName custom

Exemplos

Os exemplos a seguir fornecem código personalizado que você pode adicionar ao arquivo onload.js para configurar páginas de entrada do AD FS.

Observação

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

Alterar a cadeia de caracteres de título da página de início de sessão

A página de entrada baseada 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 é "Entrar com sua conta organizacional".

Substitua o valor da cadeia de caracteres padrão por uma cadeia de caracteres 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 iniciar sessão com o nome da conta SAM

A página de início de sessão baseada em formulários do AD FS suporta dois métodos de início de sessão por predefinição:

  • userPrincipalName": A user principal name (UPN), such as user@contoso.com'.
  • samAccountName: Um nome de conta SAM (Security Account Manager) qualificado para o domínio, como contoso\user ou contoso.com\user.

Considere um cenário em que todos os usuários estejam no mesmo domínio e os usuários saibam apenas o nome da conta SAM. Você pode atualizar a página de logon para permitir que os usuários entrem usando apenas o nome da conta SAM.

Habilite o login de contas SAM somente 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;
    };

}