Naslaginformatie over de aanmeldings-API voor systeemeigen verificatie

Van toepassing op: Groene cirkel met een wit vinkje dat aangeeft dat de volgende inhoud van toepassing is op externe tenants. Externe tenants (meer informatie)

Verificatiemethode: Ingesloten systeemeigen verificatie.

Aanmelding detecteert de methoden die zijn toegestaan voor de id van een klant en voltooit de vereiste referentiecontroles. Eenmalige wachtwoordcode (OTP) voor e-mail met wachtwoord en e-mail gebruiken hetzelfde antwoordgestuurde model. De toepassing selecteert toegestane bewerkingen uit het antwoord via gebruikerskeuze- of toepassingsstroomlogica en voldoet vervolgens aan de resterende verificatievereisten voordat autorisatie wordt hervat.

Voor bestaande V1-integraties gebruikt u de V1 API-verwijzing.

In de voorbeelden wordt een tenant-geverifieerde aangepaste domeininstantie gebruikt. custom_domain is het verificatiedomein en tenant is de tenant-GUID.

Aanmeldingsdetectie starten

Important

De systeemeigen verificatie-API V2 is in preview. De systeemeigen verificatie-API V1 blijft algemeen beschikbaar. Zie de aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor juridische voorwaarden die van toepassing zijn op preview-functies.

In het diagram ziet u één mogelijke aanmeldingsvolgorde. Beleidsvereisten kunnen acties toevoegen, herhalen of opnieuw ordenen; altijd het huidige antwoord volgen.

Sequentiediagram van systeemeigen aanmelding, verificatie van referenties, aanvullende beleidsinteracties en uitwisseling van autorisatiecode.

Start autorisatie en volg vervolgens de geretourneerde sign_in koppeling. De waarde van continuation_token het OAuth-antwoord verzenden als 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 Tekenreeks. Yes. Token van de huidige autorisatievraag.
username Tekenreeks. Yes. Aanmeldings-id geaccepteerd door tenantbeleid. In dit voorbeeld wordt e-mail gebruikt.

Een antwoord voor wachtwoordmethodeselectie kan het volgende zijn:

{
  "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 aanmelding retourneert een e-mailmethode met een eigen id, gemaskeerde en toegestane hintkoppelingen. Uw app kan geretourneerde keuzes presenteren of een beschikbare methode selecteren via toepassingsstroomlogica. Niet elk account biedt zowel wachtwoord als e-mail OTP. Gebruik algemene detectiefouten en beveilig informatie over het bestaan van accounts.

De geselecteerde methode uitdagen

Volg de koppeling van challenge de methode met POST en het meest recente vervolgtoken:

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

Het contract voor gedeelde uitdagingen definieert headers, antwoordvelden en gedrag opnieuw verzenden.

Geretourneerde methode Interactie
password Er wordt geen code verzonden. Verzamel het wachtwoord wanneer het antwoord wordt aangevraagd verify.
email Verzamel de geleverde wachtwoordcode. Gebruik de geretourneerde gemaskeerde hint en codeLength.
sms Wanneer u wordt geadverteerd voor een vereiste factor, verzamelt u de sms-wachtwoordcode met behulp van een eigen hint, lengte en koppelingen.

Gebruik resend deze alleen wanneer de service deze adverteert en de klant een andere code aanvraagt. Niet automatisch opnieuw verzenden na een bezorgingsvertraging.

De referentie controleren

Volg de huidige verify koppeling met behulp van POST. Gebruik JSON en Accept: application/hal+jsoneen van deze lichamen.

Wachtwoord:

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

Eenmalige wachtwoordcode voor e-mail of sms:

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

Gebruik het referentieveld voor het geretourneerde methodetype. Dien geen wachtwoord in otp of een wachtwoordcode in password. De verificatie wordt niet automatisch opnieuw afgespeeld na een dubbelzinnige netwerkfout.

Aanvullende beleidsvereisten voltooien

Een geslaagde verificatie kan een ander interactionRequired antwoord retourneren met action: challenge en _embedded.methods. Selecteer een geadverteerd methode en herhaal de uitdaging en verificatie met het nieuwe token en de koppelingen.

Meervoudige verificatie (MFA) maakt gebruik van dezelfde gedeelde referentiebewerkingen en ondersteunt eenmalige wachtwoordcodes voor e-mail en sms als tweede factoren. MFA via systeembeleid wordt ondersteund. Selecteer een methode uit de methode die wordt geretourneerd voor de vereiste factor. In het SMS-voorbeeld wordt een tweede-factorinteractie beschreven.

Als het volgende antwoord vereist is enroll of activate, gebruikt u het inlineregistratiecontract. E-mail met wachtwoordaccounts kunnen een aangeboden e-mail of sms-factor registreren. Email-OTP accounts van de eerste factor kunnen e-mail niet opnieuw gebruiken als tweede factor; gebruik een aangeboden alternatief, zoals SMS.

Als een vereiste interactie niet wordt ondersteund door uw client of als de service retourneert state: redirect, stopt u systeemeigen aanvragen en biedt u een afzonderlijk geconfigureerde browseraanmelding of een duidelijke fout.

Autorisatie hervatten en tokens verkrijgen

Wanneer aan beleidsvereisten wordt voldaan, kan een antwoord het volgende retourneren:

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

Plaats het token als formuliercodering continuation_token op de geretourneerde koppeling. Wissel vervolgens de autorisatiecode voor tokens uit. Noch een vraagantwoord noch een geslaagd verificatieantwoord vervangt door die uitwisseling.

Fouten

Gebruik de gedeelde foutenvelop met deze aanmeldingsvoorwaarden:

Condition Status of fout projectverbruik
Gebruikersnaam of token ontbreekt 400 Corrigeer de aanvraag.
Onjuiste e-mail of sms-wachtwoordcode 400 invalidGrant, met innerError.code: invalidOneTimeCode Laat de gebruiker de code corrigeren met behulp van de bruikbare huidige status of een geadverteerd opnieuw verzenden.
Ontbrekende wachtwoordcode 400 invalidRequest Corrigeer de ontbrekende invoer.
Ongeldige transactiestatus 400 met de systeemeigen foutenvelop Start opnieuw op in plaats van een eerder token opnieuw af te spelen.
Throttling 429 Stop automatische nieuwe pogingen en volg de serverrichtlijnen.
Niet-ondersteunde systeemeigen interactie state: redirectof OAuth invalid_grant met web_redirect_required Stop systeemeigen aanvragen. Bij een afzonderlijke aanmelding van de browser wordt de verificatie opnieuw gestart.

Voor andere referenties, detectie- of bezorgingsfouten kunt u de werkelijke status en stabiele foutcodes afhandelen zonder details over het bestaan van accounts weer te geven. Deze tabel is geen volledige foutcatalogus. Bewaar alleen veilige aanvraag-id's, correlatie-id's, tijdstempels en statusinformatie, niet referenties of hele antwoordteksten.