Informazioni di riferimento sulle API di iscrizione all'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.

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.

Diagramma di sequenza dell'iscrizione nativa con raccolta di attributi, verifica e scambio di codice di autorizzazione definiti dalla risposta.

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.