Concetti relativi al flusso di autenticazione nativa

Si applica a: cerchio verde con un simbolo di segno di spunta bianco che indica il contenuto seguente si applica ai tenant esterni. Tenant esterni (altre informazioni)

Approccio di autenticazione: Autenticazione nativa incorporata.

Il flusso di autenticazione nativa è una transazione basata su risposta. Microsoft Entra per ID esterno restituisce lo stato corrente, l'azione richiesta e le operazioni consentite. L'applicazione presenta l'interfaccia e seleziona un'operazione consentita tramite una scelta dell'utente o la logica del flusso dell'applicazione.

L'autorizzazione accompagna l'intero percorso

Importante

L'API di autenticazione nativa V2 è disponibile in anteprima. L'API di autenticazione nativa V1 rimane generalmente disponibile. Vedere le Condizioni d'uso supplementari per le anteprime di Microsoft Azure per le condizioni legali applicabili alle funzionalità di anteprima.

La richiesta di verifica dell'autorizzazione iniziale contiene l'ID applicazione, gli ambiti richiesti e le attestazioni facoltative. Se è necessaria l'autenticazione, la 401 InsufficientAuthorization risposta contiene un token di continuazione e link del flusso. Questa risposta è un invito a interagire, non una verifica della password non riuscita.

Usare l'autorità di servizio configurata in modo coerente per l'autorizzazione, le interazioni native e lo scambio di token. L'API di autenticazione nativa V2 richiede un dominio personalizzato verificato dal tenant per le app basate su browser, ad esempio le applicazioni a pagina singola, ma non per i client non browser, ad esempio le app iOS e Android che usano trasporti HTTP nativi. Gli esempi usano un DOMINIO personalizzato e un GUID tenant. Vedere Operations and authority.

L'accesso, l'iscrizione e la reimpostazione della password tornano all'endpoint di autorizzazione quando il servizio restituisce state: continue. L'applicazione invia il token di continuazione più recente al collegamento continue restituito. Scambia quindi il codice di autorizzazione risultante presso l'endpoint dei token.

Dopo la verifica della password, la creazione dell'account o un aggiornamento della password, l'app gestisce i requisiti dei criteri rimanenti e riprende l'autorizzazione prima di richiedere i token.

Questi confini dell'autorizzazione definiscono l'autenticazione nativa incorporata. L'esperienza utente BYO usa le operazioni di interazione nativa condivise tra il relativo handoff del browser e il collegamento restituito per completare il flusso. La pagina self-hosted non viene avviata o ripresa /authorize-challenge; L'applicazione relying completa il flusso di autorizzazione originale del browser. Vedere Scegliere un approccio di autenticazione.

Limite Richiesta o risposta
Avvia l'autorizzazione Codifica del client_idmodulo , scope, response_type=codee facoltativo claims.
Inserisci un viaggio URL e continuation_token di primo livello sign_in, sign_up o reset_password dalla risposta OAuth.
Interazione Richieste JSON e risposte HAL con continuationToken, stato, azioni e collegamenti.
Riprendi autorizzazione Codificato in continuation_tokenformato , inviato solo quando la risposta corrente consente la continuazione.
Token di richiesta Scambio del codice di autorizzazione con codifica form.

La sequenza seguente illustra il perimetro di autorizzazione e il ciclo di interazione basata sulla risposta. Seguire la risposta corrente anziché impostare come hardcoded l'ordine del diagramma.

Diagramma di sequenza dell'autenticazione nativa dall'autorizzazione tramite interazioni guidate dalla risposta allo scambio di token.

La risposta corrente è il modello di controllo

Ogni risposta di autenticazione nativa riuscita sostituisce il modello di interazione precedente. I criteri tenant, il flusso utente dell'applicazione e lo stato della transazione possono aggiungere, ripetere o riordinare le azioni. L'app seleziona le operazioni dalla risposta più recente e organizza le relative schermate in base ai requisiti restituiti.

Stato o azione Significato per il cliente
interactionRequired Gestire action tramite un'operazione consentita, raccogliendo l'input dell'utente, se necessario.
continue Segui _links.continue per riprendere l'autorizzazione.
redirect Arresta la transazione nativa. Questa risposta può contenere solo state, senza un token di continuazione o un URL del browser. Un accesso al browser configurato avvia un nuovo tentativo.
discover Raccogliere l'identificatore di accesso dell'utente.
disambiguate Identifica la selezione dell'account sotto state: interactionRequired.
collectAttributes Raccogli gli attributi di registrazione richiesti.
challenge Avviare la verifica del metodo selezionato.
verify Inviare la password richiesta o il passcode monouso.
enroll Selezionare un metodo disponibile e inviare i relativi dettagli di iscrizione.
activate Inviare un passcode monouso per attivare il metodo registrato.
update Inviare una password sostitutiva.
poll Controllare un aggiornamento asincrono della password.

Ad esempio, l'accesso può restituire un metodo password, quindi un'azione di verifica, quindi i metodi di posta elettronica o SMS per l'autenticazione a più fattori (MFA). L'app gestisce il fattore aggiuntivo prima di riprendere l'autorizzazione.

Durante l'iscrizione, l'inserimento di un indirizzo email può inviare immediatamente un passcode e restituire verify. L'app raccoglie il passcode e usa il collegamento di verifica restituito.

Il completamento di una singola operazione non significa che l'applicazione abbia token. Nei percorsi nativi descritti qui, continue consente la ripresa dell'autorizzazione. Lo scambio di codice successivo acquisisce i token. Lo stato completed indica il completamento dell'operazione. Non indica necessariamente un risultato con accesso effettuato né include un altro collegamento.

I token di continuazione vincolano l'operazione successiva

Un token di continuazione rappresenta la transazione in una fase specifica. È associato al tenant, al client, allo scenario e all'azione corrente. I messaggi OAuth lo chiamano continuation_token; i messaggi di autenticazione nativi lo chiamano continuationToken.

Mantenere solo il token più recente per la transazione attiva. Associarlo ai collegamenti della stessa risposta. Non analizzare, modificare, registrare o conservarlo oltre la transazione e non usarlo per un altro utente o percorso. Riavviare l'autorizzazione dopo la scadenza anziché riutilizzare un token precedente.

La validità predefinita documentata è di 10 minuti per un singolo token di continuazione. Un token più recente non garantisce l'estensione dell'intero percorso. Un token di continuazione e un passcode monouso hanno durate separate; gestire la scadenza in base alla risposta del servizio.

Gli ID dei metodi e gli URL restituiti sono opachi. Gli esempi di API di autenticazione nativa usano /api/v2.0. Seguire il collegamento restituito; non sostituire una versione né costruire un URL in base al tipo di metodo. Risolvere i collegamenti relativi rispetto all'origine dell'autorità configurata e convalidare la destinazione prima di inviare le credenziali.

L'individuazione dei metodi non è la registrazione dei metodi

Una risorsa del metodo descrive un metodo di autenticazione disponibile. Il relativo type, il hint mascherato, l'isPreferred facoltativo e i collegamenti consentono all'app di presentare una scelta e completare una verifica. codeLength descrive l'input del passcode quando viene restituito.

I collegamenti challenge e verify operano sui metodi disponibili. La registrazione di un metodo è un'interazione separata governata da criteri con la propria azione e il contratto di richiesta. Anche la raccolta di attributi del profilo ha un contratto separato.

La registrazione dei metodi inline usa enroll e activate azioni. La registrazione tramite telefono mostra type: phone con channels: ["sms"]. La registrazione tramite posta elettronica usa type: email. L'attivazione invia il codice nel campo radice otp al collegamento activate, non al collegamento verify di una credenziale. La registrazione può soddisfare un requisito di autenticazione a più fattori, quindi non è garantita un'altra sfida. Vedi Registrazione del metodo di autenticazione.

Interazioni tra criteri/policy e attributi

Il flusso utente determina il metodo di iscrizione tramite posta elettronica e gli attributi richiesti. L'iscrizione tramite posta elettronica con password raccoglie un attributo password. L'iscrizione con passcode monouso tramite posta elettronica crea un account senza password e non raccoglie una password.

I descrittori di attributi possono contenere etichette, tipi di input, validation.validationRegExe valori iniziali. Usare ogni attributeId esatto come chiave di invio. I metadati di raggruppamento delle pagine non sono necessari per visualizzare il modulo. La convalida del server rimane autorevole. Vedi Attributi utente per l'autenticazione nativa.

L'autenticazione a più fattori tramite i criteri di sistema è supportata. Dopo l'iscrizione o la reimpostazione della password, l'autenticazione a più fattori e l'accesso condizionale possono richiedere più interazioni prima del completamento dell'autorizzazione. L'app continua a gestire le risposte anziché mantenere un flusso separato per chi ha già effettuato l'accesso che salta questi requisiti.

Errori e interazioni non supportate

Gli errori di autenticazione nativa e OAuth hanno strutture diverse. Usare codici stabili per la gestione, non i messaggi localizzati. Mantenere gli identificatori di richiesta sicuri e i timestamp per la diagnostica; non registrare corpi di credenziali o token.

Ignora le proprietà facoltative sconosciute e le relazioni di collegamento. Al contrario, un'azione richiesta sconosciuta, un campo obbligatorio mancante o una risposta in formato non valido impedisce la continuazione sicura. Arrestare l'operazione nativa quando non è possibile elaborare un'interazione necessaria.

Un errore OAuth con invalid_grant e web_redirect_requiredo una risposta nativa con state: redirectindica che la transazione nativa non può continuare. Nessuna delle due risposte stabilisce un passaggio al browser riprendibile. Offrire un accesso al browser configurato separatamente o un chiaro fallimento. Mantenere il token di continuazione nativo all'interno della transazione nativa.

La federazione, TOTP, passkey, l'autenticazione telefonica a primo fattore, lo step-up per operazioni successive e l'interoperabilità del profilo o della gestione delle credenziali non sono supportati tramite questo contratto nativo. Vedere le matrici di supporto.