Condividi tramite

Personalizzazione avanzata delle pagine di accesso di AD FS

Active Directory Federation Services (AD FS) in Windows Server 2012 R2 e versioni successive supporta la personalizzazione dell'esperienza di accesso utente. Per la maggior parte degli scenari, è possibile usare i cmdlet predefiniti di Windows PowerShell per configurare le pagine di accesso di AD FS. L'approccio consigliato consiste nell'usare i comandi predefiniti di Windows PowerShell per la personalizzazione quando possibile. Per altre informazioni, vedere AD-FS personalizzazione dell'accesso utente.

In alcuni casi, potrebbe essere necessario fornire un'esperienza di accesso che non può essere abilitata usando i comandi di PowerShell forniti con AD FS. È possibile configurare l'esperienza di accesso aggiungendo codice personalizzato al file onload.js fornito con AD FS. Il codice del file viene eseguito in tutte le pagine AD FS.

Considerazioni

Prima di iniziare a personalizzare le pagine di accesso di AD FS, esaminare le considerazioni importanti seguenti.

Importante

Qualsiasi modifica della personalizzazione che influisce sui flussi di reindirizzamento o modifica i parametri del protocollo usati da AD FS non è supportata.

  • Il file onload.js viene eseguito in tutte le pagine di AD FS, incluse le pagine di accesso basate su form, le pagine di individuazione dell'area di autenticazione principale e così via. Assicurarsi sempre che il codice personalizzato venga eseguito solo come previsto e non in modo imprevisto.

  • AD FS include un tema Web integrato denominato predefinito. Non è possibile modificare il contenuto onload.js che crea il tema Web predefinito. Per aggiornare il file onload.js, creare e usare un tema Web personalizzato per le pagine di accesso ad AD FS. Per altre informazioni, vedere AD-FS personalizzazione dell'accesso utente.

  • Il file onload.js originale per il tema Web predefinito contiene anche il codice per gestire il rendering della pagina per diversi fattori di forma. L'approccio di personalizzazione consigliato consiste nell'aggiungere il codice della logica personalizzato al file di onload.js esistente. Non modificare il contenuto originale del file onload.js.

  • Quando si fa riferimento agli elementi HTML, verificare sempre l'esistenza dell'elemento prima di agire sull'elemento. Questo passaggio offre affidabilità e garantisce che la logica personalizzata non venga eseguita nelle pagine che non contengono questo elemento. Per identificare gli elementi HTML esistenti, visualizzare l'origine HTML nelle pagine di accesso di AD FS.

  • È consigliabile convalidare le personalizzazioni in un ambiente alternativo ed eseguire test prima di spostare le personalizzazioni nei server AD FS di produzione. Questo passaggio riduce le probabilità di esporre gli utenti finali alle personalizzazioni prima della convalida.

Passaggi di personalizzazione

Le sezioni seguenti illustrano la procedura per personalizzare il contenuto del file onload.js per le pagine di accesso ad AD FS.

Creare un tema Web personalizzato

Per aggiungere la logica personalizzata al file onload.js, il primo passaggio consiste nel creare un tema Web personalizzato. Un metodo rapido consiste nell'esportare il tema Web predefinito e quindi usare il codice originale come base per le personalizzazioni.

Eseguire il cmdlet seguente per creare un tema Web personalizzato duplicando il tema Web predefinito:

New-AdfsWebTheme –Name custom –SourceName default

Generare onload.js file

Il passaggio successivo consiste nell'esportare il tema Web personalizzato in modo da avere un file onload.js che è possibile aggiornare.

Eseguire il cmdlet seguente per esportare il tema Web personalizzato e generare un file onload.js:

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

Il file onload.js viene inserito nella cartella dello script nella directory specificata nel cmdlet . Nell'esempio la cartella specificata è c:\theme.

Aggiungere personalizzazioni

A questo momento si è pronti per modificare il contenuto onload.js e aggiungere codice logico personalizzato per gli scenari. Come accennato, assicurarsi di aggiungere il codice personalizzato alla fine del file onload.js.

Vedere la sezione seguente esempi per i frammenti di codice che illustrano le personalizzazioni comuni.

Cambiare il file di destinazione onload.js

Dopo aver aggiunto le personalizzazioni, è necessario aggiornare il tema Web AD FS per usare il file onload.js anziché il file onload.js originale.

Eseguire il cmdlet seguente per impostare il file onload.js come destinazione per le definizioni dei temi Web:

  • Per AD FS in Windows Server 2016 e versioni successive:

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

  • Per AD FS in Windows Server 2012 R2:

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

Applicare personalizzazioni ad AD FS

L'ultimo passaggio consiste nell'applicare le personalizzazioni alle pagine di accesso di AD FS.

Eseguire il cmdlet seguente per aggiornare AD FS con le personalizzazioni:

Set-AdfsWebConfig -ActiveThemeName custom

Esempi

Gli esempi seguenti forniscono codice personalizzato che è possibile aggiungere al file onload.js per configurare le pagine di accesso di AD FS.

Nota

Aggiungere sempre codice personalizzato alla fine del file onload.js.

Modificare la stringa del titolo della pagina di accesso

La pagina di accesso basata su moduli di AD FS visualizza un titolo sopra i campi di input dell'utente. Il valore predefinito del titolo è "Accedi con l'account aziendale".

Sostituire il valore stringa predefinito con una stringa personalizzata aggiungendo il codice seguente al file onload.js. Nel codice impostare il valore del parametro loginMessage.innerHTML sulla stringa personalizzata da usare per il titolo.

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

Consenti l'autenticazione con il nome dell'account SAM

La pagina di accesso basata su moduli di AD FS supporta due metodi di accesso per impostazione predefinita:

  • userPrincipalName": A user principal name (UPN), such as user@contoso.com'.
  • samAccountName: un nome di account di Security Account Manager (SAM) qualificato di dominio, come contoso\user o contoso.com\user.

Si consideri uno scenario in cui tutti gli utenti si trovano nello stesso dominio e gli utenti conoscono solo il nome dell'account SAM. È possibile aggiornare la pagina di accesso per consentire agli utenti di accedere usando solo il nome dell'account SAM.

Abilitare l'accesso dagli account SAM solo aggiungendo il codice seguente al file onload.js. Nel codice impostare il valore del parametro userNameValue sul dominio desiderato.

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

}