Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Si applica a:
Tenant esterni (altre informazioni)
Approccio di autenticazione: Autenticazione nativa incorporata.
L'API di autenticazione nativa usa un flusso basato su risposta in Microsoft Entra per ID esterno tenant esterni. Avviare l'autorizzazione, completare le interazioni di autenticazione restituite, riprendere l'autorizzazione e scambiare il codice di autorizzazione per i token. Questo riferimento definisce le operazioni condivise; I riferimenti specifici di journey definiscono l'individuazione dell'accesso, gli attributi di iscrizione e la reimpostazione della password.
Per un'integrazione V1 esistente, usare le informazioni di riferimento sull'API V1. Vedere Eseguire la migrazione da V1 a V2 per le versioni dei pacchetti, i requisiti di migrazione e i dettagli sull'integrazione dell'SDK.
Prerequisites
Importante
L'API di autenticazione nativa V2 è disponibile in anteprima. L'API di autenticazione nativa V1 rimane disponibile a livello generale. Vedere le Condizioni per l'utilizzo supplementari per Microsoft Azure anteprime per le condizioni legali applicabili alle funzionalità di anteprima.
- Un tenant esterno e un'applicazione configurata per i flussi di autenticazione pubblici e client nativi. Vedere Configurare un'applicazione.
- Flusso utente associato all'applicazione.
- Per le app basate su browser, ad esempio le applicazioni a pagina singola, un dominio URL personalizzato verificato dal tenant configurato per le chiamate API del servizio.
- Le autorizzazioni delegate e il consenso richiesti dalla risorsa di destinazione, se si richiede l'accesso a un'API.
- Per le applicazioni a pagina singola con autenticazione nativa incorporata e siti Web BYO UX, un proxy o un criterio perimetrale che implementa i requisiti del proxy del browser.
Operazioni e autorità
Gli esempi usano https://{custom_domain}/{tenant}, dove custom_domain è un dominio di autenticazione verificato dal tenant, ad esempio login.contoso.come tenant è il relativo ID directory (tenant), un GUID.
client_id è l'ID applicazione (client). In questi esempi, tutti gli URL delle chiamate API del servizio usano questo dominio personalizzato, inclusi i problemi di autorizzazione 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 i contratti a pagina singola, per proteggersi dalla richiesta intersito falso (CSRF). I client non browser, ad esempio le app iOS e Android che usano trasporti HTTP nativi, non richiedono un dominio personalizzato. Un browser o una visualizzazione Web incorporata non è un trasporto HTTP nativo. L'esperienza utente BYO rimane basata su browser e richiede un dominio personalizzato verificato dal tenant. Vedere Configurare l'autorità API.
Ad eccezione della richiesta di autorizzazione iniziale e dello scambio di token, usare l'URL annunciato dalla risposta corrente. Gli ID dei metodi sono opachi. Risolvere i collegamenti relativi rispetto all'origine dell'autorità configurata, convalidare la destinazione e mantenere invariato il percorso restituito e la query.
L'avvio, la ripresa e lo scambio di codice di autorizzazione seguenti descrivono l'autenticazione nativa incorporata. Una pagina dell'esperienza utente BYO usa invece il relativo handoff del browser e ha restituito il collegamento completo per le operazioni di interazione nativa condivisa. Non avviare o riprendere /authorize-challenge all'interno di tale transazione UX BYO.
| Operazione | Metodo | Percorso o collegamento |
|---|---|---|
| Avviare l'autorizzazione | POST |
/{tenant}/oauth2/v2.0/authorize-challenge |
| Riprendere l'autorizzazione | POST |
Collegamento restituito continue . |
| Avviare l'accesso | POST |
Collegamento restituito sign_in . Gli esempi usano /{tenant}/api/v2.0/signin/start. |
| Avviare l'iscrizione | POST |
Collegamento restituito sign_up . Gli esempi usano /{tenant}/api/v2.0/signup/start. |
| Inviare gli attributi di iscrizione | POST |
Collegamento restituito submitAttributes . |
| Avviare la reimpostazione della password | POST |
È stato restituito il collegamento reset-password; esempi usano /{tenant}/api/v2.0/resetpassword/start. |
| Avviare la reimpostazione della password inline | POST |
Collegamento restituito recover del metodo password. |
| Registrare un metodo di autenticazione | POST |
Collegamento restituito del metodo selezionato enroll . |
| Attivare un metodo di autenticazione | POST |
Collegamento restituito activate . |
| Richiesta di verifica o invio di nuovo | POST |
Restituito o resend collegatochallenge. |
| Verificare una credenziale | POST |
Collegamento restituito verify . |
| Aggiornare una password | PUT |
Collegamento restituito update . |
| Aggiornamento della password di polling | POST |
Collegamento restituito poll . |
| Exchange un codice di autorizzazione | POST |
/{tenant}/oauth2/v2.0/token |
Gli esempi nativi usano /api/v2.0; Le operazioni OAuth usano /oauth2/v2.0. Usare il GUID del tenant in questi esempi di autorità. Seguire i collegamenti restituiti senza riscrivere i percorsi, le versioni o i parametri di query.
Headers
Le operazioni di autenticazione OAuth e native usano codifiche del corpo diverse.
| Intestazione | Utilizza |
|---|---|
Content-Type: application/x-www-form-urlencoded |
Obbligatorio per richieste di richiesta di autorizzazione e token. |
Content-Type: application/json |
Obbligatorio per i corpi di richiesta di autenticazione nativa. |
Accept: application/hal+json |
Consigliato per le richieste di autenticazione native. |
client-request-id: {guid} |
Consigliato. Generare un nuovo valore per ogni flusso e conservarlo per la diagnostica. |
Requisiti del proxy del browser
Questi requisiti si applicano alle chiamate API del browser da spA con autenticazione nativa incorporata e siti Web BYO UX. Le app Android e iOS che usano trasporti HTTP nativi non richiedono la configurazione CORS o un proxy CORS.
Le route di autenticazione native gestiscono OPTIONS, ma non concedono l'accesso all'origine del browser tramite Access-Control-Allow-Origin. Le integrazioni del browser tra le origini necessitano quindi di una configurazione proxy o perimetrale che:
- Inoltra la risposta preliminare del servizio e applica i criteri di origine browser configurati.
- Restituisce
Access-Control-Allow-Originper l'origine esatta consentita, non*per . - Consente il metodo o
PUTobbligatorioPOSTdell'operazione e le intestazioni della richiesta usate dall'integrazione. - Mantiene i corpi delle richieste, i codici di stato della risposta, i tipi di contenuto e i collegamenti di transazione senza memorizzare nella cache le risposte di autenticazione.
- Gestisce l'origine e il routing in modo coerente tra autorizzazioni, operazioni native e scambio di token.
- Mantiene le linee guida per i tentativi, incluso
Retry-Aftere lo espone al codice del browser quando necessario.
Per informazioni sui limiti del browser e sulla configurazione del proxy locale per lo sviluppo, vedere Concetti di CORS per l'autenticazione nativa.
Token di continuazione
Un token di continuazione rappresenta la transazione di autenticazione nella fase corrente. È associato al tenant, al client, allo scenario e all'azione.
| Formato del messaggio | Field |
|---|---|
| OAuth | continuation_token |
| API di autenticazione nativa | continuationToken |
Usare solo il token corrente con l'operazione identificata dalla stessa risposta. Non analizzare, modificare, registrare o rendere persistente la transazione oltre la transazione attiva. Quando una risposta fornisce una sostituzione, interrompere l'uso del token precedente. Non spostare un token in un altro utente o percorso. Riavviare l'autorizzazione dopo la scadenza.
La validità predefinita documentata è di 10 minuti per un singolo token di continuazione. Gestire la scadenza in base alla risposta del servizio; un token più recente non garantisce l'estensione dell'intero percorso. Il token e un passcode monouso hanno durate separate. I codici di autorizzazione sono di breve durata e monouso; non interpretare una risposta del expires_in token come durata del codice di autorizzazione.
Modello di risposta
Le operazioni di interazione native riuscite restituiscono HAL JSON. L'azione successiva può essere diversa anche per le chiamate successive allo stesso endpoint. I campi sono specifici della risposta: ad esempio, un reindirizzamento può contenere solo state.
| Membro | Purpose |
|---|---|
continuationToken |
Token per la successiva richiesta consentita, se inclusa. |
state |
Stato della transazione corrente. |
action |
Interazione necessaria per una interactionRequired risposta. |
_links |
URL per le operazioni consentite. |
_embedded |
Risorse correlate, inclusi i metodi disponibili. |
Il concetto di flusso illustra gli stati e le azioni. Per interactionRequired, gestire l'azione restituita usando un'operazione consentita. Per continue, riprendere l'autorizzazione tramite il collegamento restituito. Lo stato di completed una singola operazione non conferma che i token sono stati emessi.
Una transazione nativa che non può continuare può restituire:
{
"state": "redirect"
}
Questa risposta non fornisce un token di continuazione, collegamenti o un URL di handoff del browser. Arrestare le richieste native e offrire un accesso al browser configurato separatamente o un errore chiaro. L'accesso al browser riavvia l'autenticazione; non riprende lo stato di avanzamento nativo.
Azione di selezione dell'account
Note
La selezione dell'account non è rilevante nell'autenticazione nativa incorporata e non è ancora supportata per le pagine self-hosted dell'esperienza utente BYO.
disambiguate identifica la selezione dell'account in state: interactionRequired.
Relazioni di collegamento
Usare i collegamenti dalla risposta più recente e convalidare l'autorità prima di inoltrare i segreti.
| Relazione | Purpose |
|---|---|
self |
Risorsa o operazione corrente. |
discover |
Inviare un identificatore di accesso. |
challenge |
Avviare la richiesta di verifica del metodo selezionato. |
verify |
Verificare una password o un passcode monouso. |
resend |
Richiedere un altro passcode monouso. |
submitAttributes |
Inviare i valori di iscrizione richiesti. |
recover |
Avviare il ripristino delle password all'interno della transazione di accesso attiva. |
enroll |
Avviare la registrazione di un metodo di autenticazione annunciato. |
activate |
Verificare il codice per un metodo registrato. |
update |
Inviare una password sostitutiva. |
poll |
Controllare un aggiornamento asincrono. |
continue |
Riprendere l'autorizzazione OAuth. |
Questa azione è rilevante per la selezione dell'account BYO (Bring Your Own UX). Le integrazioni di autenticazione nativa incorporate non lo usano e la selezione dell'account nella pagina dell'esperienza utente BYO self-hosted non è attualmente supportata.
Se l'integrazione dell'esperienza utente BYO segue la soluzione alternativa consigliata inviando login_hint o prompt=login nella richiesta di autorizzazione, l'introduzione della selezione dell'account non interrompe o interrompe l'esperienza utente esistente.
Il payload dell'azione fa parte dell'handoff initialResponse del browser BYO UX esistente e include:
-
state: interactionRequired,action: disambiguatee uncontinuationTokenoggetto per la selezione in sospeso. - Matrice
_embedded.usercon informazioni su ogni account offerto e collegamenti supportati. Un account attivo ha un URL specifico_links.resumedell'account. - URL a livello
_links.discoverdi risposta per un account inattivo o Usa un altro account.
Risorse del metodo di autenticazione
La selezione del metodo credenziale esistente usa _embedded.methods. Il servizio può anche selezionare un singolo metodo. Una credenziale esistente ha un oggetto opaco id, ad type esempio password, emailo smse collegamenti per le operazioni consentite. Un mascherato hint identifica una destinazione senza dislozzarla completamente. isPreferred È metadati di preferenza facoltativi. Le scelte di registrazione hanno una rappresentazione separata e non richiedono un ID credenziale esistente.
{
"_embedded": {
"methods": [
{
"id": "{id}",
"type": "email",
"hint": "u***@contoso.com",
"isPreferred": true,
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/verify"
}
}
}
]
}
}
Questo frammento illustra i metadati del metodo. La disponibilità del metodo viene determinata per ogni transazione. L'app può presentare metodi disponibili o selezionare uno tramite la logica del flusso dell'applicazione. La verifica e la verifica operano sul metodo selezionato; la registrazione del metodo ha un contratto separato.
Non richiedere metadati di presentazione facoltativi, pages ad esempio o scenario. Negli esempi vengono descritte le interazioni di base con password e posta elettronica/SMS, non tutti i requisiti aggiuntivi specifici del metodo.
Avviare l'autorizzazione
Inviare l'applicazione, gli ambiti e le attestazioni facoltative nella richiesta iniziale. Valori con codifica form; le interruzioni di riga riportate di seguito sono destinate alla leggibilità.
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=openid%20profile%20offline_access&
response_type=code
| Parametro | Utilizza |
|---|---|
client_id |
ID applicazione (client) obbligatorio. |
scope |
Definisce l'ambito delle richieste dell'applicazione. Includere gli ambiti OIDC (OpenID Connect) e delle risorse necessari per i token risultanti. |
response_type |
code in questo esempio. L'endpoint restituisce un codice di autorizzazione dopo l'autenticazione. |
claims |
Richiesta di attestazioni OpenID Connect con codifica JSON facoltativa. |
Quando è necessaria l'autenticazione, la risposta è 401 Unauthorized, con Content-Type: application/json:
{
"error": "InsufficientAuthorization",
"error_description": "AADSTS500127: No authenticated credentials found in request.",
"error_codes": [
500127
],
"timestamp": "2026-08-28T17:30:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"continuation_token": "******",
"reset_password": "/{tenant}/api/v2.0/resetpassword/start",
"sign_in": "/{tenant}/api/v2.0/signin/start",
"sign_up": "/{tenant}/api/v2.0/signup/start"
}
Gli URL di accesso e iscrizione sono condizionali. I collegamenti di percorso sono proprietà di risposta OAuth di primo livello, non _links voci. Selezionare un percorso annunciato e inviare il token come continuationToken nella richiesta JSON. Gestire qualsiasi criterio o rifiuto specifico dell'account.
Riprendere l'autorizzazione
Quando la risposta corrente restituisce state: continue, pubblicare il token più recente in _links.continue.href. Non inviare nuovamente l'oggetto iniziale client_id, scopeo claims in questa richiesta.
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
continuation_token={continuation_token}
La risposta riuscita è 200 OK e JSON:
{
"code": "{authorization_code}"
}
I codici di autorizzazione sono di breve durata e monouso. Exchange il codice anziché considerarlo come token di accesso.
Exchange il codice di autorizzazione
Inserire il codice con lo stesso ID applicazione:
POST https://{custom_domain}/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
grant_type=authorization_code&
code={authorization_code}
Tutti e tre i parametri sono obbligatori.
grant_type è authorization_code. Questa richiesta public-client non contiene un segreto client.
La risposta riuscita è 200 OK e JSON:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "******",
"id_token": "******",
"refresh_token": "******"
}
I campi del token dipendono inizialmente dagli ambiti e dalle attestazioni stabilite. Un token di aggiornamento viene restituito solo quando la richiesta iniziale include offline_access. Il valore di scadenza di esempio non è una garanzia di durata fissa. Non richiedere offline_access se l'applicazione non richiede un token di aggiornamento.
Richiesta di verifica o invio di nuovo
Seguire il collegamento del challenge metodo selezionato o un collegamento corrente resend quando il cliente richiede un altro passcode:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/challenge
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Una richiesta di posta elettronica può restituire:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "verify",
"id": "{email_method_id}",
"type": "email",
"hint": "u***@contoso.com",
"codeLength": 8,
"_links": {
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
}
}
}
SMS usa la stessa forma di verifica delle credenziali con type: sms, un hint per il telefono mascherato e i relativi collegamenti al metodo restituito. Le sfide relative alle password non inviano passcode e restituiscono un'azione password verify . Usare l'oggetto restituito codeLength, non la lunghezza dell'esempio. Seguire i tentativi controllati dal servizio e inviare di nuovo i limiti.
Verificare una credenziale
Pubblica sul collegamento corrente verify . Per un metodo password:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"password": "******"
}
Per un metodo di posta elettronica o SMS:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
La verifica può restituire un'altra verifica, una raccolta di attributi, un aggiornamento della password o una continuazione. Gestire l'azione restituita. La verifica non è idempotente; non riprovare automaticamente dopo un errore di rete ambiguo.
Registrazione del metodo di autenticazione
L'iscrizione o l'accesso possono richiedere la registrazione inline tramite action: enroll, seguita da action: activate. La registrazione è separata dalla raccolta degli attributi del profilo o dalla verifica di credenziali esistenti.
Importante
La registrazione è separata dall'autenticazione con un metodo registrato. Utilizzare solo i metodi di registrazione annunciati per la transazione corrente; non dedurre un'operazione di registrazione da una richiesta di verifica delle credenziali.
Selezionare e registrare un metodo
Selezionare un metodo supportato da _embedded.methods e seguire il relativo _links.enroll URL.
| Metodo | Annuncio | Campi JSON obbligatori |
|---|---|---|
| SMS telefonico |
type: phone, con sms in channels. |
continuationToken, phoneNumber incluso il codice paese e channel: sms. |
| Messaggio e-mail |
type: email. |
continuationToken e email. Non inviare un oggetto channel. |
La registrazione telefonica usa type: phone, non il sms tipo usato dai metodi di verifica SMS esistenti. L'URL di registrazione telefono di esempio è /{tenant}/api/v2.0/auth/methods/phone. L'URL di posta elettronica è /{tenant}/api/v2.0/auth/methods/email. Usare POST con JSON e seguire l'URL annunciato anziché crearne uno.
Per la registrazione tramite SMS telefonico, il corpo è:
{
"continuationToken": "******",
"phoneNumber": "+1 2025550123",
"channel": "sms"
}
Per la registrazione tramite posta elettronica, il corpo è:
{
"continuationToken": "******",
"email": "user@contoso.com"
}
Il servizio invia un passcode e restituisce action: activate, un nuovo token di continuazione e un activate collegamento. Visualizzare la maschera restituita hint e codeLength , quando presente. La posta elettronica e l'SMS possono usare lunghezze di codice diverse.
Una risposta di attivazione telefonica può essere:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "activate",
"id": "{phone_method_id}",
"type": "phone",
"channel": "sms",
"hint": "***0123",
"codeLength": 6,
"_links": {
"activate": {
"href": "/{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/phone"
}
}
}
Usare i campi e i collegamenti dalla risposta effettiva; email usa il proprio tipo di metodo, lunghezza del codice e collegamenti.
Attivare o inviare di nuovo
Inviare un codice JSON POST al collegamento corrente activate con la versione più recente continuationToken e il codice dell'utente in otp. Gli esempi di telefono usano /{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate; il messaggio di posta elettronica usa il proprio collegamento pubblicizzato. Non inviare codici di attivazione al collegamento di verify una credenziale.
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
Se la risposta di attivazione annuncia resend, inviare un file JSON POST contenente solo l'ultima versione continuationToken a tale collegamento. Il collegamento può tornare alla registrazione. Non conservare o inviare di nuovo i dettagli di contatto; il token contiene il contesto di registrazione.
{
"continuationToken": "******"
}
Sostituire il token attivo, i collegamenti, l'hint e la lunghezza del codice dopo ogni risposta. Continuare a gestire le azioni restituite dopo l'attivazione; consente solo state: continue la ripresa dell'autorizzazione. La registrazione può soddisfare l'autenticazione a più fattori, quindi non è sempre necessaria una verifica separata delle credenziali.
Per invalidGrant con innerError.code: invalidOneTimeCode, mantenere il token di attivazione corrente e i collegamenti annunciati. Consentire all'utente di correggere il codice o richiedere un nuovo invio. Non riprodurre automaticamente la registrazione o l'attivazione dopo un errore di connessione ambiguo.
Errors
Gli errori OAuth usano campi come error, error_description, trace_ide correlation_id. Gli errori di autenticazione nativa usano una busta annidata. Ad esempio, un codice di verifica della posta elettronica non corretto può restituire HTTP 400 con:
{
"error": {
"code": "invalidGrant",
"message": "AADSTS50181: Unable to validate the otp.",
"timestamp": "2026-08-28T17:30:00Z",
"traceId": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
"innerError": {
"code": "invalidOneTimeCode"
}
}
}
Usare codici stabili per la gestione anziché i messaggi localizzati. La convalida degli attributi può restituire error.innerError.code: attributeValidationError con details voci contenenti code, messagee attributeIds, più facoltative suggestions o recovery. Controllare lo stato HTTP e il tipo di contenuto prima dell'analisi; non eseguire il rendering di un corpo di errore HTML imprevisto nell'app.
| Condition | Stato o errore | Movimentazione |
|---|---|---|
| Parametro OAuth non valido | 400 invalid_request |
Correggere la richiesta; non riprovare invariato. |
| Codice non valido o scaduto | 400 invalid_grant |
Riavviare l'autorizzazione. |
| Applicazione non valida | 400 invalid_client |
Correggere la configurazione dell'app. |
| Ambito non valido o nongrantato | 400 invalid_scope |
Controllare gli ambiti richiesti e il consenso. |
| Autenticazione richiesta | 401 InsufficientAuthorization |
Seguire un collegamento di percorso abilitato. |
| Token/stato di continuazione non valido | 400 invalidRequest |
Riavviare il flusso applicabile. |
| Token di aggiornamento password scaduto |
400 expiredToken con innerError.code: expiredContinuationToken |
Riavviare l'autorizzazione. |
| Codice di verifica mancante | 400 invalidRequest |
Correggere l'input mancante. |
| Messaggio di posta elettronica o codice di verifica SMS non corretto |
400 invalidGrant con innerError.code: invalidOneTimeCode |
Consentire all'utente di correggere il codice usando lo stato di verifica corrente utilizzabile o seguire un collegamento di nuovo invio annunciato. Non inviare di nuovo automaticamente. |
| Codice di attivazione non corretto |
400 invalidGrant con innerError.code: invalidOneTimeCode |
Mantenere il token di attivazione corrente e i collegamenti annunciati. Consentire all'utente di correggere il codice o usare un'azione di reinvio annunciata. Non inviare di nuovo automaticamente. |
| Interazione del browser richiesta |
invalid_grant con web_redirect_required |
Arrestare le richieste native e usare il percorso di ripristino interattivo configurato. Non inoltrare il token di continuazione a un URL arbitrario. |
| La transazione nativa non può continuare | Corpo nativo {"state":"redirect"} |
Arrestare le richieste native. Un accesso del browser separato non mantiene lo stato di avanzamento nativo. |
| Throttling | 429 |
Rispettare e le Retry-After indicazioni sul server. |
Gli errori di rete e di servizio possono usare altri formati di risposta. Considerare un tipo di contenuto imprevisto come errore esplicito. La tabella descrive casi comuni specifici, non un catalogo di errori completo per ogni operazione.
Sicurezza e diagnostica
Usare HTTPS per ogni richiesta upstream. Mantenere password, passcode, token di continuazione, codici e token emessi da URL, log, dati di telemetria, eccezioni, screenshot e allegati supportati. Non memorizzare nella cache le risposte di autenticazione o condividere lo stato delle transazioni tra gli utenti.
Rifiutare le autorità impreviste e i reindirizzamenti anziché inoltrare i segreti. Non ripetere automaticamente la verifica delle credenziali, gli invii di creazione di account o gli aggiornamenti delle password dopo un errore ambiguo.
Visualizzare solo gli hint mascherati forniti dal servizio. Usare errori di individuazione generici in modo che i messaggi e la presentazione del metodo non divulghino inutilmente l'esistenza dell'account.
Mantenere la diagnostica sicura: stato HTTP, categoria di operazioni, , client-request-idID di traccia/correlazione del servizio e timestamp. I nomi OAuth usano caratteri di sottolineatura; I nomi degli errori di autenticazione nativa usano il caso camel. Estrarre questi campi di diagnostica senza conservare i corpi di richiesta o risposta completi.
Estensioni di autenticazione personalizzate
La configurazione e i contratti degli eventi sono specifici di ogni estensione e percorso. L'app continua a selezionare le operazioni consentite dalle risposte del servizio quando un'estensione partecipa al flusso.
La copertura degli eventi nativi include OnOtpSend per la posta elettronica e OnTokenIssuanceStart.
OnAttributeCollectionStart e OnAttributeCollectionSubmit non sono supportati per l'autenticazione nativa incorporata o Bring Your Own UX. Vedere Estensioni di autenticazione personalizzate per il comportamento specifico dell'evento. Questo set di eventi non stabilisce hook di migrazione delle password, sincronizzazione degli aggiornamenti delle password o propagazione arbitraria del contesto.