Personalizzazione avanzata delle pagine di accesso ad AD FS

  • Articolo

Active Directory Federation Services (AD FS) in Windows Server 2012 R2 e versioni successive supporta la personalizzazione dell'esperienza di accesso degli utenti. Nella 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 Personalizzazione dell'accesso utente ad AD FS.

In alcuni casi può essere necessario fornire un'esperienza di accesso che non è possibile abilitare 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 di AD FS.

Considerazioni

Prima di iniziare a personalizzare le pagine di accesso ad AD FS, esaminare le considerazioni importanti che seguono.

Importante

Le personalizzazioni che incidono sui flussi di reindirizzamento o modificano i parametri di protocollo usati da AD FS non sono supportate.

  • 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 nel modo voluto e non in modo imprevisto.

  • AD FS include un tema Web predefinito denominato default. Non è possibile modificare il contenuto di 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 Personalizzazione dell'accesso utente ad AD FS.

  • 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 consigliato per la personalizzazione consiste nell'aggiungere il codice della logica personalizzata al file onload.js esistente. Non modificare il contenuto del file onload.js originale.

  • Quando si fa riferimento a elementi HTML, verificare sempre l'esistenza dell'elemento prima di agire su di esso. Questo passaggio offre affidabilità e assicura 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 ad AD FS.

  • È consigliabile convalidare le personalizzazioni in un ambiente alternativo ed eseguire test prima di spostarle 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 veloce 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 il file onload.js

Il passaggio successivo consiste nell'esportare il tema Web personalizzato in modo da disporre un file onload.js che sia 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 script della directory specificata nel cmdlet. Nell'esempio la cartella specificata è c:\theme.

Aggiungere personalizzazioni

A questo punto si è pronti per modificare il contenuto di onload.js e aggiungere il codice della logica personalizzata per gli scenari. Come già accennato, aggiungere sempre il codice personalizzato alla fine del file onload.js.

La sezione Esempi più avanti contiene frammenti di codice che dimostrano le personalizzazioni comuni.

Modificare il file onload.js di destinazione

Dopo aver aggiunto le personalizzazioni, è necessario aggiornare il tema Web di AD FS in modo da usare il file onload.js modificato al posto di quello originale.

Eseguire il cmdlet seguente per impostare il file onload.js modificato come destinazione per le definizioni del tema 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 le personalizzazioni ad AD FS

L'ultimo passaggio consiste nell'applicare le personalizzazioni alle pagine di accesso ad 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 ad AD FS.

Nota

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

Modificare la stringa del titolo della pagina di accesso

La pagina di accesso basata su form di AD FS mostra un titolo sopra i campi di input dell'utente. Il valore predefinito del titolo è "Accedere con il proprio account aziendale".

Sostituire il valore predefinito della stringa 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';
}

Accettare l'accesso con il nome dell'account SAM

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

  • userPrincipalName": A user principal name (UPN), such as user@contoso.com`.
  • samAccountName: un nome di account SAM (Security Account Manager) completo del dominio, ad esempio 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 proprio 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 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;
    };

}