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.
Questo riferimento descrive l'iscrizione tramite la raccolta di attributi basata su server. L'iscrizione tramite posta elettronica con password e posta elettronica con passcode monouso usa le stesse operazioni e forme di messaggio. Per questi metodi di posta elettronica, il flusso utente associato all'applicazione seleziona il metodo di iscrizione; il client non lo seleziona nella richiesta di avvio.
Gli esempi mostrano l'iscrizione basata su posta elettronica. Per le integrazioni V1 esistenti, usare le informazioni di riferimento sulle API V1.
Gli esempi usano un'autorità di dominio personalizzata verificata dal tenant.
custom_domain è il dominio di autenticazione ed tenant è il GUID del tenant.
Avviare l'iscrizione
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.
Il diagramma mostra una sequenza di iscrizione guidata dalla risposta. Il flusso utente determina il metodo di iscrizione e la risposta corrente determina quali attributi e interazioni sono necessari.
Avviare l'autorizzazione, quindi seguire il sign_up collegamento con il token restituito:
POST https://{custom_domain}/{tenant}/api/v2.0/signup/start
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
continuationToken è una stringa obbligatoria. La risposta iniziale può richiedere un messaggio di posta elettronica:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "collectAttributes",
"attributes": [
{
"attributeId": "email",
"inputType": "text",
"hidden": false,
"required": true,
"canChange": true,
"label": "Email"
}
],
"_links": {
"submitAttributes": {
"href": "/{tenant}/api/v2.0/signup/submitattributes"
}
}
}
Le etichette, l'obbligatorietà e i metadati di convalida provengono dai criteri. Usare questi requisiti all'interno dell'interfaccia e della logica di raccolta dell'applicazione.
Attributi di invio
Seguire _links.submitAttributes.href. La raccolta può verificarsi più volte:
POST https://{custom_domain}/{tenant}/api/v2.0/signup/submitattributes
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"attributes": {
"email": "user@contoso.com"
}
}
| Property | Type | Required | Description |
|---|---|---|---|
continuationToken |
Stringa. | Yes. | Token di iscrizione più recente. |
attributes |
Oggetto di valori stringa. | Yes. | Valori con chiave in base ai valori restituiti esatti attributeId . |
Prima del completamento dell'iscrizione, è necessario specificare tutti i valori obbligatori. I valori facoltativi possono essere omessi. I valori obbligatori mancanti possono generare un errore di convalida o un'altra collectAttributes risposta.
Per l'iscrizione tramite posta elettronica con password, inviare una password quando richiesto. Ad esempio, un ciclo di raccolta che richiede campi password e profilo può accettare:
{
"continuationToken": "******",
"attributes": {
"email": "user@contoso.com",
"password": "******",
"givenName": "Example",
"surname": "User"
}
}
Inviare i campi in base ai descrittori restituiti dal flusso utente. L'iscrizione con passcode monouso tramite posta elettronica crea un account senza password che accede con un passcode di posta elettronica.
Ordine di raccolta
Il servizio può richiedere prima di tutto il messaggio di posta elettronica, raccogliere diversi attributi o tornare alla raccolta di attributi dopo la verifica. Inviare gli attributi richiesti dalla risposta più recente anziché prevedere la sequenza dai valori inviati.
L'app può organizzare la raccolta in base alla logica del flusso e ai descrittori disponibili. Vedere Ordine di raccolta e verifica tramite posta elettronica. Ogni risposta determina le operazioni successive disponibili.
Interpretare i descrittori di attributi e pagine
Ogni risposta descrive il modulo corrente. I campi seguenti definiscono un attributo:
| Field | Meaning |
|---|---|
attributeId |
Chiave di invio. |
inputType |
Tipo di controllo di input, ad esempio text, passwordboolean, date, o checkboxMultiSelect. |
required |
Indica se è necessario specificare un valore. |
hidden |
Indica se il campo è nascosto. |
canChange |
Informazioni di modifica, se incluse. |
label |
Etichetta di visualizzazione facoltativa. |
initialValue |
Valore prepopolato facoltativo. |
validation.validationRegEx |
Modello di convalida facoltativo. |
options |
Opzioni facoltative con label le proprietà e value . |
confirmationInput |
Comportamento di conferma facoltativo, ad esempio retype, revealo none. |
Non richiedere un pages membro. La matrice corrente attributes definisce i campi e i requisiti; i metadati di raggruppamento di pagine, se restituiti, sono informazioni aggiuntive sulla presentazione. I tipi di controllo di input non modificano l'oggetto invio con valori stringa. Vedere Concetti relativi agli attributi utente.
Verificare la posta elettronica
Quando l'invio di attributi richiede la verifica tramite posta elettronica, invia il passcode e restituisce:
{
"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"
}
}
}
Il servizio ha già inviato il passcode; procedere direttamente alla verifica. Usare la lunghezza restituita e l'hint mascherato. Pubblica in verify:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
Per richiedere un altro codice, inserire solo l'ultimo continuationToken al collegamento corrente resend , soggetto ai limiti del servizio.
La verifica può restituire più raccolte di attributi:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "collectAttributes",
"attributes": [
{
"attributeId": "givenName",
"inputType": "text",
"hidden": false,
"required": true,
"canChange": true,
"label": "First name"
}
],
"_links": {
"submitAttributes": {
"href": "/{tenant}/api/v2.0/signup/submitattributes"
}
}
}
Inviare i valori richiesti e continuare a gestire la risposta successiva.
Completare i requisiti dei criteri e l'autorizzazione
Dopo la creazione dell'account e la verifica richiesta, completare eventuali requisiti di autenticazione a più fattori (MFA) e di accesso condizionale prima di riprendere l'autorizzazione.
Se la risposta annuncia un'altra richiesta di verifica, usare le operazioni di verifica e verifica condivise. La registrazione del metodo è diversa dalla verifica di un messaggio di posta elettronica di iscrizione. Vedere Individuazione e registrazione dei metodi per il contratto di registrazione.
Quando il servizio restituisce state: continue, seguire _links.continue, riprendere l'autorizzazione e scambiare il codice. In questo modo vengono acquisiti i token senza avviare una transazione di accesso non correlata.
Errori e ciclo di vita
Usare la busta di errore condivisa. Le voci di convalida strutturata possono contenere code, messageattributeIds, , suggestionse facoltative recovery.
| Condition | Stato o comportamento | Movimentazione |
|---|---|---|
| Token di continuazione non valido | 400 |
Riavviare il flusso. |
| Attributo mancante o non valido |
400 o un'altra collectAttributes risposta |
Presentare commenti e suggerimenti a livello di campo e inviare valori corretti. |
| L'utente esiste già | 400 invalidRequest |
Offrire indicazioni generica per l'accesso o il ripristino senza disconnettere inutilmente l'esistenza dell'account. |
| Violazione dei criteri password | 400 |
Raccogliere una password conforme. |
| Passcode di posta elettronica non corretto |
400 invalidGrant con innerError.code: invalidOneTimeCode |
Consentire all'utente di correggere il codice usando lo stato corrente utilizzabile o un nuovo invio annunciato. |
| Passcode mancante | 400 invalidRequest |
Correggere l'input mancante. |
| Throttling | 429 |
Rispettare le linee guida per i tentativi del server. |
| Interazione nativa non supportata | state: redirect |
Arrestare le richieste native e offrire il percorso del browser configurato o un errore chiaro. |
Gestire altri errori tramite lo stato effettivo e i codici di errore stabili. Non considerare una transazione scaduta come una voce di codice non corretta recuperabile.
L'invio di attributi non è idempotente dopo la creazione dell'utente. Non riprodurre invii riusciti, registrare valori di attributo sensibili o considerare la convalida lato client come autorevole.