Informazioni di riferimento sulle API di accesso per l'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.

L'accesso individua i metodi consentiti per l'identificatore di un cliente e completa i controlli delle credenziali necessari. L'accesso tramite posta elettronica con password e posta elettronica con passcode monouso (OTP) usa lo stesso modello basato su risposta. L'applicazione seleziona le operazioni consentite dalla risposta tramite la logica del flusso dell'utente o dell'applicazione, quindi soddisfa i requisiti di autenticazione rimanenti prima di riprendere l'autorizzazione.

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'individuazione dell'accesso

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 possibile sequenza di accesso. I requisiti dei criteri possono aggiungere, ripetere o riordinare le azioni; seguire sempre la risposta corrente.

Diagramma di sequenza dell'accesso nativo, della verifica delle credenziali, delle interazioni aggiuntive con i criteri e dello scambio di codice di autorizzazione.

Avviare l'autorizzazione, quindi seguire il collegamento restituito sign_in . Inviare il valore della continuation_token risposta OAuth come continuationToken:

POST https://{custom_domain}/{tenant}/api/v2.0/signin/start
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "username": "user@contoso.com"
}
Property Type Required Description
continuationToken Stringa. Yes. Token della richiesta di autorizzazione corrente.
username Stringa. Yes. Identificatore di accesso accettato dai criteri del tenant. In questo esempio viene usata la posta elettronica.

Una risposta di selezione del metodo password può essere:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "challenge",
  "_embedded": {
    "methods": [
      {
        "id": "{password_method_id}",
        "type": "password",
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/verify"
          }
        }
      }
    ]
  }
}

Email-OTP l'accesso restituisce un metodo di posta elettronica con collegamenti id, mascherati hinte consentiti. L'app può presentare scelte restituite o selezionare un metodo disponibile tramite la logica del flusso dell'applicazione. Non tutti gli account offrono sia la password che la posta elettronica OTP. Usare errori di individuazione generici e proteggere le informazioni sull'esistenza dell'account.

Sfidare il metodo selezionato

Seguire il collegamento del metodo con POST e il token di challenge continuazione più recente:

{
  "continuationToken": "******"
}

Il contratto di verifica condiviso definisce intestazioni, campi di risposta e comportamento di invio di nuovo.

Metodo restituito Interazione
password Non viene inviato alcun codice. Raccogliere la password quando la risposta richiede verify.
email Raccogliere il passcode recapitato. Usare la maschera restituita hint e codeLength.
sms Quando viene annunciato per un fattore obbligatorio, raccogliere il passcode SMS usando il proprio hint, lunghezza e collegamenti.

Usare resend solo quando il servizio lo annuncia e il cliente richiede un altro codice. Non inviare di nuovo automaticamente dopo un ritardo di recapito.

Verificare le credenziali

Seguire il collegamento corrente verify usando POST. Usare JSON, Accept: application/hal+jsone uno di questi corpi.

Password:

{
  "continuationToken": "******",
  "password": "******"
}

Passcode monouso tramite posta elettronica o SMS:

{
  "continuationToken": "******",
  "otp": "{one_time_passcode}"
}

Usare il campo credenziali per il tipo di metodo restituito. Non inviare una password in otp o un passcode in password. Non riprodurre automaticamente la verifica dopo un errore di rete ambiguo.

Completare i requisiti aggiuntivi dei criteri

Una verifica riuscita può restituire un'altra interactionRequired risposta con action: challenge e _embedded.methods. Selezionare un metodo annunciato e ripetere la verifica e la verifica con il nuovo token e i collegamenti.

L'autenticazione a più fattori (MFA) usa le stesse operazioni di credenziali condivise e supporta i passcode di posta elettronica e SMS una tantum come secondi fattori. L'autenticazione a più fattori tramite i criteri di sistema è supportata. Selezionare un metodo da quelli restituiti per il fattore richiesto. L'esempio SMS descrive un'interazione a due fattori.

Se la risposta successiva richiede enroll o activate, usare il contratto di registrazione inline. Gli account di posta elettronica con password possono registrare un messaggio di posta elettronica o un fattore SMS offerto. Email-OTP gli account di primo fattore non possono riutilizzare la posta elettronica come secondo fattore; usare un'alternativa offerta, ad esempio SMS.

Se un'interazione richiesta non è supportata dal client o il servizio restituisce state: redirect, arrestare le richieste native e offrire un accesso al browser configurato separatamente o un errore chiaro.

Riprendere l'autorizzazione e acquisire i token

Quando vengono soddisfatti i requisiti dei criteri, una risposta può restituire:

{
  "continuationToken": "******",
  "state": "continue",
  "_links": {
    "continue": {
      "href": "/{tenant}/oauth2/v2.0/authorize-challenge"
    }
  }
}

Pubblicare il token come codificato continuation_token in formato nel collegamento restituito. Scambiare quindi il codice di autorizzazione per i token. Né una risposta di verifica né una risposta di verifica riuscita sostituisce tale scambio.

Errors

Usare la busta di errore condivisa con queste condizioni di accesso:

Condition Stato o errore Movimentazione
Nome utente o token mancante 400 Correggere la richiesta.
Codice di posta elettronica o SMS 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.
Stato della transazione non valido 400 con la busta di errore nativa Riavviare invece di riprodurre un token precedente.
Throttling 429 Arrestare i tentativi automatici e rispettare le indicazioni sul server.
Interazione nativa non supportata state: redirecto OAuth invalid_grant con web_redirect_required Arrestare le richieste native. Un browser separato riavvia l'autenticazione.

Per altre credenziali, individuazione o errori di recapito, gestire lo stato effettivo e i codici di errore stabili senza esporre i dettagli dell'esistenza dell'account. Questa tabella non è un catalogo degli errori esaustivo. Mantenere solo id richiesta sicura, ID correlazione, timestamp e informazioni sullo stato, non credenziali o corpi di risposta interi.