Gestore di autenticazioni Web

Questo articolo illustra come connettere l'app UWP (Universal Windows Platform) a un provider di identità online che usa protocolli di autenticazione come OpenID o OAuth. Il metodo AuthenticateAsync invia una richiesta al provider di identità online e ottiene un token di accesso che descrive le risorse del provider a cui l'app ha accesso.

Annotazioni

Per un esempio di codice completo e funzionante, clonare il repository WebAuthenticationBroker in GitHub.

Registra la tua app con il tuo provider online

Devi registrare l'app con il provider di identità online a cui vuoi connetterti. Puoi scoprire come registrare la tua app presso il fornitore di identità. Dopo la registrazione, il provider online fornisce in genere un ID o una chiave privata per l'app.

Costruire l'URI della richiesta di autenticazione

L'URI della richiesta è costituito dall'indirizzo in cui si invia la richiesta di autenticazione al provider online aggiunto con altre informazioni necessarie, ad esempio un ID app o un segreto, un URI di reindirizzamento in cui l'utente viene inviato dopo il completamento dell'autenticazione e il tipo di risposta previsto. È possibile scoprire dal provider quali parametri sono necessari.

L'URI della richiesta viene inviato come parametro requestUri del metodo AuthenticateAsync. Deve essere un indirizzo sicuro (deve iniziare con https://)

Nell'esempio seguente viene illustrato come compilare l'URI della richiesta.

string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";

System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);

Connettersi al provider online

Chiamare il metodo AuthenticateAsync per connettersi al provider di identità online e ottenere un token di accesso. Il metodo accetta l'URI costruito nel passaggio precedente come parametro requestUri e un URI a cui si vuole che l'utente venga reindirizzato come parametro callbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI, 
        endURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Avvertimento

Oltre a AuthenticateAsync, lo spazio dei nomi Windows.Security.Authentication.Web contiene un metodo AuthenticateAndContinue. Non chiamare questo metodo. È progettato per le app destinate solo a Windows Phone 8.1 ed è deprecato a partire da Windows 10.

Connessione con Single Sign-On (SSO).

Per impostazione predefinita, Il broker di autenticazione Web non consente la persistenza dei cookie. Per questo motivo, anche se l'utente dell'app indica che vuole rimanere connesso (ad esempio, selezionando una casella di controllo nella finestra di dialogo di accesso del provider), dovrà accedere ogni volta che vuole accedere alle risorse per tale provider. Per accedere con SSO, il provider di identità online deve aver abilitato SSO per il broker di autenticazione Web e l'app deve chiamare l'overload di AuthenticateAsync che non accetta un parametro callbackUri. In questo modo i cookie persistenti verranno archiviati dal gestore di autenticazione Web, in modo che le chiamate di autenticazione future dalla stessa app non richiedano l'accesso ripetuto da parte dell'utente (l'utente è effettivamente "connesso" fino alla scadenza del token di accesso).

Per supportare l'SSO, il provider online deve consentire la registrazione di un URI di reindirizzamento nel formato ms-app://<appSID>, dove <appSID> è il SID per la tua app. Puoi trovare il SID dell'app dalla pagina di sviluppo dell'app per la tua app oppure chiamando il metodo GetCurrentApplicationCallbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Risoluzione dei problemi

Esistono diversi modi per risolvere i problemi relativi alle API del broker di autenticazione Web, tra cui la revisione dei log operativi e la revisione delle richieste Web e delle risposte tramite Fiddler.

Log operativi.

Spesso è possibile determinare cosa non funziona usando i log operativi. È disponibile un canale dedicato del registro eventi Microsoft-Windows-WebAuth\Operational che consente agli sviluppatori di siti Web di comprendere come le pagine Web vengono elaborate dal broker di autenticazione Web. Per abilitarla, avviare eventvwr.exe e abilitare il registro operativo in Application and Services\Microsoft\Windows\WebAuth. Inoltre, il gestore di autenticazione Web aggiunge una stringa univoca alla stringa dell'agente utente per identificarsi nel server Web. La stringa è "MSAuthHost/1.0". Si noti che il numero di versione potrebbe cambiare in futuro, quindi non è consigliabile dipendere da tale numero di versione nel codice. Di seguito è riportato un esempio della stringa completa dell'agente utente, seguita dai passaggi di debug completi.

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Abilitare i log operativi.
Eseguire l'applicazione di social networking Contoso.
Le voci di log generate possono essere usate per comprendere in maggiore dettaglio il comportamento del gestore di autenticazione Web. In questo caso, questi possono includere:
- Avvio navigazione: Registra quando AuthHost viene avviato e contiene informazioni sugli URL di avvio e di chiusura.
- Navigazione completata: registra il completamento del caricamento di una pagina Web.
- Meta Tag: registra quando viene rilevato un meta-tag, inclusi i dettagli.
- Navigation Terminate(Termina navigazione): navigazione terminata dall'utente.
- Errore di navigazione: AuthHost rileva un errore di navigazione in un URL che include HttpStatusCode.
- Fine spostamento: viene rilevato l'URL di terminazione.

Violinista

Il debugger Web Fiddler può essere usato con le app. Per altre informazioni, vedere documentazione di Fiddler

Poiché AuthHost viene eseguito nel proprio contenitore di app, per offrire la funzionalità di rete privata è necessario impostare una chiave del Registro di sistema: Editor del Registro di sistema di Windows versione 5.00

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\opzioni di esecuzione dei file di immagine\authhost.exe\EnablePrivateNetwork = 00000001

Se questa chiave del Registro di sistema non è disponibile, è possibile crearla in un prompt dei comandi con privilegi di amministratore.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Aggiungere una regola per AuthHost perché si tratta di ciò che genera il traffico in uscita.

CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
List Loopback Exempted AppContainers
[1] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
    SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
[2] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
    SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
[3] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
    SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935

Aggiungere una regola firewall per il traffico in ingresso a Fiddler.

È possibile creare la regola del firewall usando la riga di comando o l'interfaccia utente grafica di Windows Defender Firewall:

Opzione A: Uso del comando netsh (esegui come amministratore):
```
netsh advfirewall firewall add rule name="Fiddler for AuthHost Debugging" dir=in action=allow program="C:\Program Files\Fiddler\Fiddler.exe" enable=yes
```
Se Fiddler viene installato in un percorso diverso, modificare il percorso di conseguenza. In alternativa, è possibile creare una regola basata su porta:
```
netsh advfirewall firewall add rule name="Fiddler Port for AuthHost" dir=in action=allow protocol=TCP localport=8888
```
Opzione B: Uso di Windows Defender Firewall con sicurezza avanzata:
1. Aprire Windows Defender Firewall con sicurezza avanzata (eseguire wf.msc)
2. Fare clic su "Regole in ingresso" nel riquadro sinistro
3. Fare clic su "Nuova regola..." nel riquadro destro
4. Selezionare "Programma" e fare clic su Avanti
5. Passare al file eseguibile di Fiddler (in C:\Program Files\Fiddler\Fiddler.exe genere in un'installazione per computer) e fare clic su Avanti
6. Selezionare "Consenti connessione" e fare clic su Avanti
7. Controllare tutti i tipi di rete (Dominio, Privato, Pubblico) e fare clic su Avanti
8. Assegnare alla regola un nome come "Fiddler per il debug di AuthHost" e fare clic su Fine

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-08-28