Integra l'autenticazione immersiva

• Tipo non definito

Documentation

Un'applicazione può utilizzare Schermate di login RestFrontage per autenticare i propri utenti, applicare MFA e recuperare un token utilizzabile con WebAPI e OData. Non deve riprodurre password, codice QR o schermate di inserimento TOTP.

Questa guida offre due progetti completi: un Applicazione WPF per Windows e un Applicazione web basata su JavaScript, ospitato da un piccolo progetto ASP.NET Core. Nessuno dei due fa riferimento a GraphicStream.Immersive.Server.Interop o ad altre DLL Immersive. Il futuro pacchetto di autenticazione indipendente non è obbligatorio per usarli.

Le illustrazioni sono screenshot degli esempi e del login RestFrontage in un ambiente di test isolato. Gli account mostrati sono account demo. Le porte e gli ID delle catture provengono dal banco di test; usa i valori dalla tua configurazione.

1. Comprendere il principio

1.1 Un'interfaccia di connessione comune

L'utente clicca Accedi nella tua applicazione. Il browser mostra l'accesso Immersive. Inserisce il suo nome utente e la password, poi il codice MFA quando richiesto dalla policy del server. Se la verifica deve essere configurata, il server gli mostra il codice QR e gli chiede di confermare un primo codice.

L'applicazione riceve quindi automaticamente un token. Questo token le permette di chiamare le API con i diritti dell'utente effettuato l'accesso. Una connessione di successo non concede loro diritti aggiuntivi.

MFA segue l'impostazione già impostata in Immersive: disabilitata, richiesta con esenzioni o obbligatoria per tutti gli utenti interessati. L'applicazione client non sceglie di aggirare questa politica.

1.2 Due codici che hanno ruoli diversi

Il Codice TOTP è il codice a sei cifre mostrato dall'app del telefono. Viene usato per confermare l'identità dopo la password. Di solito cambia ogni 30 secondi ed è calcolato senza internet.

Il Codice di ritorno è un codice tecnico, generato dal server dopo l'accesso. Viene automaticamente trasmesso all'applicazione, che lo scambia con il token. L'utente non deve mai copiarlo, conservarlo o trasmetterlo a un amministratore. Questo codice scade dopo 60 secondi E funziona solo una volta.

1.3 Il viaggio completo

sequenceDiagram
    participant A as Votre application
    participant N as Navigateur
    participant R as RestFrontage
    A->>A: Préparer state et une preuve PKCE
    A->>N: Ouvrir Browser/Authorize
    N->>R: Demander la connexion pour l'application déclarée
    R-->>N: Afficher le login Immersive
    N->>R: Saisir identifiant et mot de passe
    opt MFA requise
        R-->>N: QR code si inscription nécessaire, puis saisie TOTP
        N->>R: Confirmer un code à six chiffres
    end
    R-->>N: Rediriger vers le callback avec un code temporaire
    N-->>A: Transmettre code, state et iss
    A->>A: Vérifier le retour attendu
    A->>R: Browser/Token avec le code et la preuve PKCE
    R-->>A: Token Immersive et durée restante
    A->>R: WebAPI ou OData avec Authorization: Bearer
    R-->>A: Réponse autorisée selon les droits du compte

Protezione PKCE S256 collega lo scambio di codici all'applicazione che ha avviato la connessione. L'applicazione mantiene un valore casuale privato, il code_verifier, e inizialmente trasmetteva solo la sua impronta digitale, il code_challenge. Intercettare il solo codice di ritorno quindi non è sufficiente per ottenere il token. Questo meccanismo è descritto da RFC 7636.

state Collega il ritorno alla richiesta di connessione corrente. iss Identifica il server che sta rispondendo. I client forniti verificano questi valori e l'indirizzo di ritorno prima dello scambio.

2. Prepara i due esempi

2.1 Contenuto del file fornito

Open Campioni/Immersive.Authentication.Samples.slnx in Visual Studio. La soluzione contiene esattamente due progetti indipendenti.

Il dossier Eseguibili/WPF, nell'archivio di consegna, contiene l'eseguibile pubblicato e la sua configurazione. Questa release richiede il Runtime desktop .NET 10 x64 e, per la modalità integrata, la Microsoft Edge WebView runtime2. Tieni insieme tutti i file pubblicati, incluso il caricatore WebView2.

Per compilare le sorgenti, utilizzare l'SDK .NET 10 e, in Visual Studio, i componenti di sviluppo Desktop .NET e ASP.NET/Web. Entrambi i progetti possono essere staccati dal repository server: puoi copiare la cartella Samples su un altro computer.

2.2 Dichiara le app su RestFrontage

Aggiungi questa sezione alla configurazione dell'istanza di RestFrontage, sostituendo gli indirizzi in base al tuo ambiente. Il appsettings.example.json contiene lo stesso esempio. Non sovrascrive la tua configurazione esistente.

{
  "BrowserAuthentication": {
    "Issuer": "https://localhost:44333",
    "Clients": [
      {
        "ClientId": "immersive-desktop",
        "DisplayName": "Exemple Immersive WPF",
        "RedirectUris": [ "http://127.0.0.1/callback/" ],
        "AllowLoopbackRedirect": true
      },
      {
        "ClientId": "immersive-web",
        "DisplayName": "Exemple Immersive Web",
        "RedirectUris": [ "https://localhost:5173/auth/callback" ]
      }
    ]
  }
}

Emittente è l'origine HTTPS di RestFrontage quando il browser vi accede: schema, host e opzionalmente port, senza path o barra finale. Questo percorso attende un server montato alla radice di questa origine. Se viene utilizzato un reverse proxy, il server deve ricevere lo schema esterno corretto e l'host tramite la sua configurazione affidabile.

ClientId identifica la domanda e non è un segreto. DisplayName è il suo nome visualizzato nell'accesso. Dichiara solo le applicazioni autorizzate a utilizzare i diritti dei loro utenti. Per questi esempi nessun segreto condiviso dovrebbe essere incorporato in un binario o in JavaScript.

RedirectUris Elenca gli indirizzi di ritorno esatti. Non vengono accettati wildcard, parametri di richiesta o frammenti. Ogni indirizzo web utilizza HTTPS. AllowLoopbackRedirect Permette solo al client nativo di scegliere una porta libera sull'indirizzo locale del loop dichiarato. L'host letterale e il percorso rimangono controllati. Con l'esempio WPF, il ritorno diventa ad esempio http://127.0.0.1:54321/callback/.

Per mettere in pausa un'app, aggiungi "Enabled": false alla sua dichiarazione. Un ingresso assente o disabile non può utilizzare questo percorso.

2.3 Controlla HTTPS e l'accesso alla rete

RestFrontage deve essere raggiungibile per estensione e possedere un certificato riconosciuto. Il progetto web utilizza anche HTTPS. Per i test locali ASP.NET Core, se necessario, installa il certificato di sviluppo affidabile con:

dotnet dev-certs https --trust

Le applicazioni fornite non disabilitano la validazione dei certificati. Per una rete interna, si utilizza un certificato riconosciuto dai dispositivi rilevanti.

Per il progetto web, RestFrontage deve permettere, ad esempio, chiamate dall'origine dell'applicazione https://localhost:5173, nella sua politica CORS. In particolare, la richiesta WebAPI deve essere in grado di inviare il Authorization. L'autorizzazione CORS non sovrascrive la dichiarazione di callback. Le chiamate WPF non dipendono dal CORS.

La connessione funziona senza Internet se l'estensione raggiunge RestFrontage e qualsiasi applicazione Web sulla rete interna. Le risorse negli esempi sono locali. Il telefono calcola il suo codice TOTP offline; le impostazioni di data e ora devono rimanere corrette.

3. Usa il campione WPF

3.1 Lancio e collegamento

Nel progetto Immersive.Authentication.Wpf, il appsettings.json Imposta i valori iniziali:

{
  "Server": "https://localhost:44333",
  "ClientId": "immersive-desktop",
  "BrowserMode": "External",
  "ApiPath": "/api/Security/Mfa/Context"
}

Dalla cartella Esempi, esegui:

dotnet run --project Immersive.Authentication.Wpf

Puoi anche correre Immersive.Authentication.Wpf.exe dalla cartella pubblicata, oppure impostare questo progetto come progetto di avvio in Visual Studio.

1. Controlla l'indirizzo RestFrontage e l'ID della domanda.
2. Scegli Browser esterno oppure Browser integrato (WebView2), poi clicca Accedi.
3. Inserire la password completa e, se richiesto, verificare la MFA.
4. In modalità esterna, torna al WPF. In modalità integrata, la finestra di accesso si chiude automaticamente.
5. Click Chiama GET. La rotta proposta restituisce il nome dell'account collegato.

Dopo una connessione riuscita, il WPF mostra la data di scadenza del token. La chiamata proposta ritorna HTTP 200 e il nome dell'account collegato.

In esterno, il ritorno utilizza un ascolto temporaneo di rete, limitato a 127.0.0.1, su una porta scelta automaticamente. Questo ascolto inizia prima che il browser venga aperto e si interrompe alla fine del viaggio. Il tempo massimo di connessione è di dieci minuti. Il Cancella Pausa l'attesa nell'app. Non chiude la scheda del browser.

3.2 Scegli il browser

Entrambe le scelte usano lo stesso server, lo stesso ClientId, e gli stessi controlli di ritorno e PKCE. La MFA è ancora applicata da Immersive. Non è necessario dichiarare un'applicazione aggiuntiva per passare tra di essi.

Adattamento BrowserMode in appsettings.json sceglie il valore iniziale: Esterno oppure Embedded. La lista ti permette di cambiare modalità per la connessione successiva; non riscrive il file di configurazione.

La finestra integrata mostra l'origine del server sopra il login. Mantiene i passaggi usuali, incluso l'inserimento del codice a sei cifre e la registrazione con un codice QR quando il server lo richiede. Cancella, il cross di chiusura, o timeout, interrompe la connessione e restituisce il WPF al WPF.

Il profilo WebView2 è privato e separato dal consueto profilo browser. Il salvataggio della password e il completamento automatico sono disabilitati. La navigazione fuori dal server configurato, nuove finestre, download e accesso agli oggetti nativi sono bloccati. Non vengono iniettati script di lettura delle credenziali dal campione. Gli errori di certificato non vengono ignorati.

Il browser esterno rimane la scelta predefinita per isolare la pagina di autenticazione dell'applicazione. La variante integrata è adatta a un'applicazione masterizzata: il suo host può tecnicamente accedere ai contenuti web. Il PKCE protegge lo scambio di codice, ma non toglie questa capacità al programma che ospita WebView2. I principi per proteggere il componente sono descritti nel Documentazione Microsoft WebView2.

3.3 Prepara le stazioni per WebView2

Il progetto di riferimento WPF Microsoft.Web.WebView2. Questo pacchetto fornisce il controllo e il suo caricatore; il Microsoft Edge WebView runtime2 Deve essere presente sul computer per la modalità integrata. La sua presenza è separata da quella del browser Edge. Se manca l'runtime, il campione mostra un messaggio e permette di scegliere il browser esterno.

Per una posizione senza Internet, pianifica ilInstallatore Evergreen Standalone l'architettura appropriata nel tuo processo di implementazione. Il piccolo bootstrapper web richiede un download ed è adatto a un'installazione completamente offline. La connessione può comunque funzionare sulla rete interna una volta installata la runtime. Visualizza Distribuire WebView2.

Il file tecnico del componente viene creato sotto %LOCALAPPDATA%/Immersive.Authentication.Sample/WebView2, in una posizione accessibile dall'utente. Il profilo di accesso si apre in modalità privata. L'app conserva il token Immersive in memoria in entrambe le modalità.

3.4 Riutilizza il codice nella tua app

Il BrowserAuthenticationClient.cs contiene il client standalone. Utilizza le librerie standard .NET per preparare la richiesta, aprire il browser, controllare il ritorno e scambiare il codice. Non dipende dall'Immersive SDK.

using Immersive.Authentication.Wpf;

using var http = new HttpClient(new HttpClientHandler
{
    AllowAutoRedirect = false,
    UseCookies = false
});

var authentication = new BrowserAuthenticationClient(
    "https://localhost:44333", http);

var session = await authentication.SignInAsync(
    "immersive-desktop", cancellationToken);

// session.Token : token Immersive à garder en mémoire.
// session.ExpiresAt : échéance du token.

MainWindow.xaml.cs mostra il pulsante connetti, la cancellazione, lo stato della sessione e la chiamata API. Puoi cambiare il namespace del file standalone quando lo integri nel tuo progetto.

Per la modalità integrata, i file EmbeddedLoginWindow.xaml e EmbeddedLoginWindow.xaml.cs completare il client standalone. La chiamata viene effettuata dal thread UI WPF, con la finestra principale come proprietario:

var session = await EmbeddedLoginWindow.SignInAsync(
    this, authentication, "immersive-desktop", cancellationToken);

Il risultato ha le stesse proprietà Token e ExpiresAt. I controlli di callback e lo scambio HTTP rimangono attivi BrowserAuthenticationClient.cs ; La finestra si occupa solo di mostrare e intercettare la navigazione finale.

Il metodo del browser esterno può ricevere una funzione openBrowser Se la tua app ha già il browser aperto in astrazione. Metodi CreateBrowserLoginRequest e CompleteBrowserLoginAsync Ti permettono di gestire separatamente l'inizio e il ritorno se hai già un meccanismo di callback compatibile.

Il browser di sistema mantiene l'inserimento delle credenziali nella pagina server. Questa scelta segue il principio raccomandato per applicazioni native dal RFC 8252. Un iframe non è una modalità di integrazione di questo login.

4. Usa il Campione Web

4.1 Lancio del sito

Il appsettings.json del progetto Immersive.Authentication.Web Contiene:

{
  "Authentication": {
    "Server": "https://localhost:44333",
    "ClientId": "immersive-web",
    "ApiPath": "/api/Security/Mfa/Context"
  }
}

Dai campioni:

dotnet run --project Immersive.Authentication.Web

Open https://localhost:5173. In Visual Studio, il profilo di avvio apre automaticamente questo indirizzo. La rotta di ritorno è https://localhost:5173/auth/callback ; deve essere dichiarata esattamente come tale in RestFrontage.

1. Click Accedi : La scheda viene reindirizzata a RestFrontage.
2. Inserisci le tue credenziali, poi il codice MFA se necessario.
3. Il server reindirizza la scheda a /auth/callback nella tua app.
4. JavaScript verifica il ritorno e scambia il codice con il token.
5. Click Chiama GET per leggere il contesto del racconto.

Lo stesso esempio web adatta il suo layout a piccoli schermi. Il percorso di accesso e l'uso del token rimangono gli stessi.

4.2 Riutilizzare il modulo JavaScript

I fascicoli wwwroot/ImmersiveAuthentication.js e wwwroot/app.js mostra rispettivamente il client di connessione e la sua integrazione nella pagina. Il piccolo server ASP.NET Core serve queste risorse e la configurazione pubblica. Non riceve il token: il browser chiama direttamente RestFrontage.

import { ImmersiveAuthentication } from "/ImmersiveAuthentication.js";

const authentication = new ImmersiveAuthentication({
    Server: "https://localhost:44333",
    ClientId: "immersive-web",
    RedirectUri: location.origin + "/auth/callback"
});

// Dans l'action « Se connecter » :
await authentication.SignIn();

Nella pagina di reso, ricrea il cliente con le stesse opzioni, e poi chiama:

const session = await authentication.CompleteSignIn();
// session.Token : token Immersive.
// session.ExpiresIn : durée restante, en secondes.

Il modulo mantiene solo la transazione provvisoria PKCE in sessionStorage durante la modifica della pagina. Cancella questa transazione dopo la validazione e rimuove il codice dall'indirizzo del browser. Il token non è scritto su localStorage, sessionStorage o cookie.

Il ritorno deve avvenire nella stessa scheda e sulla stessa origine dell'applicazione che ha avviato la richiesta. Il percorso /auth/callback deve essere accessibile direttamente dal tuo hosting, anche prima che JavaScript venga caricato. Nell'esempio, il server restituisce index.html per questa strada.

Per l'alloggio, mantieni Referrer-Policy: no-referrer Nella pagina di ritorno, evita risorse di terze parti su quella pagina e non registrare i parametri URL del D. Una configurazione proxy o di hosting dovrebbe preservare queste proprietà.

5. Chiamate WebAPI e OData

5.1 Lo stesso gettone indipendentemente dal cliente

Una volta completata la connessione, entrambe le applicazioni utilizzano lo stesso tipo di token Immersive. Aggiungono l'intestazione Autorizzazione: Titolare alle loro richieste. Ecco la stessa operazione in C#, JavaScript e HTTP; server si riferisce all'origine di RestFrontage e token il gettone ottenuto.

using System.Net.Http.Headers;

using var request = new HttpRequestMessage(
    HttpMethod.Get, server + "/api/Security/Mfa/Context");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using var response = await http.SendAsync(request, cancellationToken);
string content = await response.Content.ReadAsStringAsync(cancellationToken);
response.EnsureSuccessStatusCode();

const response = await fetch(server + "/api/Security/Mfa/Context", {
    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
    credentials: "omit",
    cache: "no-store",
    redirect: "error"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const context = await response.json();

GET {{server}}/api/Security/Mfa/Context
Authorization: Bearer {{token}}
Accept: application/json

Una risposta di successo contiene AccountName. Per OData, cambia il percorso verso una rotta OData della tua istanza: l'intestazione rimane la stessa. Gli esempi fanno solo richieste GET. Impediscono che il token venga inviato a un altro server tramite il campo path e negano i reindirizzamenti HTTP sulle chiamate autenticate.

A 401 significa che la richiesta non è autenticata o che il token non viene più accettato; Ripeti la connessione. A 403 Indica un diniego di accesso: Controlla i diritti e le regole dell'API pertinente. Passare MFA non dà accesso a tutte le risorse.

5.2 Scadenza e fine della sessione

Il token mantiene il suo solito periodo di validità in Immersive. La risposta dell'exchange indica il suo Tempo rimanente. I campioni smettono di usarlo quando scade; è quindi necessaria una nuova connessione. Questo percorso non fornisce un token di refresh.

Cancella la mia sessione rimuove il token dalla memoria del campione. Questo pulsante non revoca il token già emesso al server né disconnette tutte le altre applicazioni. Chiudere l'eseguibile WPF o ricaricare la scheda Web cancella anche lo stato della connessione.

I progetti mostrano volontariamente una sessione in memoria. Un'applicazione che vuole mantenere una sessione più a lungo deve definire esplicitamente la propria politica di archiviazione e logout. Per un sito con backend, è possibile mantenere il token esclusivamente lato server.

6. Comprendere il contratto HTTP

6.1 Avvio della connessione

L'applicazione prepara valori casuali state e code_verifier. I client forniti utilizzano 32 byte casuali codificati in Base64URL, senza alcun riempimento. La sfida è BASE64URL(SHA256(ASCII(code_verifier))).

Poi apre questo indirizzo nel browser, codificando i valori dei parametri:

GET {{server}}/api/Security/Browser/Authorize?response_type=code&client_id={{clientId}}&redirect_uri={{redirectUriEncoded}}&state={{state}}&code_challenge={{challenge}}&code_challenge_method=S256

Non iniziare l'integrazione aprendo direttamente /Login : l'ingresso Browser/Autorizza Contiene le informazioni della domanda e il ritorno atteso. La richiesta di connessione è valida per dieci minuti.

Dopo il successo, il server reindirizza al callback dichiarato con Codice, Stato e ISS. Dopo aver cancellato dal login, torna errore=access_denied, Stato e ISS. Una richiesta iniziale non valida rimane su un errore locale: non reindirizza a un indirizzo non autorizzato.

6.2 Codice di riscatto

Dopo aver controllato il callback, state e iss, l'applicazione passa un modulo HTTP. I valori sono codificati come un modulo, senza conversione in JSON.

POST {{server}}/api/Security/Browser/Token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={{clientId}}&redirect_uri={{redirectUriEncoded}}&code={{code}}&code_verifier={{verifier}}

using var content = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "authorization_code",
    ["client_id"] = clientId,
    ["redirect_uri"] = redirectUri,
    ["code"] = code,
    ["code_verifier"] = verifier
});
using var response = await http.PostAsync(server + "/api/Security/Browser/Token", content);
response.EnsureSuccessStatusCode();

const response = await fetch(server + "/api/Security/Browser/Token", {
    method: "POST",
    credentials: "omit",
    cache: "no-store",
    redirect: "error",
    body: new URLSearchParams({
        grant_type: "authorization_code",
        client_id: clientId,
        redirect_uri: redirectUri,
        code,
        code_verifier: verifier
    })
});
if (!response.ok) throw new Error("Échange refusé : recommencez la connexion.");

La risposta contiene:

{
  "access_token": "JWT Immersive",
  "token_type": "Bearer",
  "expires_in": 3600
}

La durata è illustrativa. Questi tre nomi seguono il contratto OAuth, in minuscole. Il client WPF espone Token e ExpiresAt, e il modulo JavaScript esposto Token e ExpiresIn. Le altre Immersive WebAPI mantengono la loro convenzione PascalCase.

Strade Browser/VerifyCredentials, Browser/VerifyTotp e Browser/Annulla. fanno parte del funzionamento interno dell'interfaccia ospitata. La tua integrazione utilizza Autorizzare e Gettone ; Non deve controllare i passaggi di accesso.

7. Altri mezzi di integrazione

WPF e JavaScript non sono le uniche opzioni. Il contratto è HTTP: entrambi i progetti mostrano due modi di utilizzarlo, non una restrizione tecnologica.

7.1 Variante web con backend

In questa variante, il backend mantiene state e la prova PKCE nella sessione utente prima del redirect. Controlla il callback e poi scambia il codice lato server. Poi conserva il token Immersive e effettua le chiamate API per il browser.

sequenceDiagram
    participant N as Navigateur
    participant B as Backend de votre site
    participant R as RestFrontage
    N->>B: Se connecter
    B->>B: Stocker state et PKCE dans la session
    B-->>N: Redirection vers le login hébergé
    N->>R: Mot de passe et MFA éventuelle
    R-->>N: Redirection vers le callback du site
    N->>B: Callback avec code et state
    B->>B: Vérifier session, state et iss
    B->>R: Échanger code et PKCE
    R-->>B: Token Immersive
    B-->>N: Session du site, cookie sécurisé HttpOnly
    N->>B: Demander une ressource
    B->>R: Appeler l'API avec le token
    R-->>B: Résultat autorisé
    B-->>N: Résultat pour l'interface

In particolare, il cookie di sessione deve essere sicuro, solo Http e adatto per la navigazione dei feedback. Proteggere le azioni del sito contro richieste cross-site. Il token rimane nel backend; non deve essere inviato al browser tramite una utility route. PKCE e state rimane necessario in questa variante.

8. Ambito e diagnosi

8.1 Cosa tratta questo corso

Le coperture del tour ospitato nome utente/password e TOTP, con le esenzioni, la prima registrazione e la riregistrazione autorizzata previste in Immersive. Non collega ancora i fornitori SSO esistenti a questa voce; la loro operatività rimane distinta.

Il server utilizza il Codice di autorizzazione con PKCE, ma non è rappresentato come un provider completo OpenID Connect. Questo lotto non fornisce la scoperta OIDC, il token ID, il consenso tramite ambiti, il token di aggiornamento o il Flusso di Autorizzazione del Dispositivi. Un componente che richiede queste funzioni non può essere collegato senza adattamento.

Per più istanze di RestFrontage, l'operatore deve mantenere un keyring persistente condiviso di Protezione dei Dati, la stessa identità di applicazione Data Protection e lo stesso database di Sicurezza. Le chiavi JWT e le impostazioni MFA devono anch'esse essere coerenti. La perdita delle protezioni temporanee richiede che le connessioni attuali vengano riavviate.

8.2 Correggere gli errori comuni

Non registrare token, prove PKCE, password, segreti TOTP o impostazioni di callback. Questo vale anche per IIS, reverse proxy, e log delle applicazioni client. Le migliori pratiche generali sono dettagliate nel RFC 9700.

8.3 Verifica la tua integrazione

Prova un account soggetto a MFA, un account che deve essere configurato per la prima volta e, se la tua politica lo permette, un account esente. Controlla anche se cancellazioni, errori TOTP e accesso all'API negato per mancanza di diritti.

Il risultato atteso è sempre lo stesso: La tua applicazione recupera un token solo dopo i passaggi di connessione richiesti dal server. Possono quindi utilizzare le API entro i limiti dei diritti dell'account.