Api-verwijzing voor systeemeigen verificatie voor wachtwoordherstel

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.

Wachtwoordherstel verifieert de herstelmethode van een klant, accepteert een vervangend wachtwoord en peilt een asynchrone update. E-mail- en SMS-methoden voor eenmalige wachtwoordcode (OTP) ondersteunen herstel. Vereisten voor meervoudige verificatie (MFA) en voorwaardelijke toegang kunnen worden toegepast na het opnieuw instellen en voordat de autorisatie is voltooid.

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

Prerequisites

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 de voorbeelden wordt een tenant-geverifieerde aangepaste domeininstantie gebruikt. custom_domain is het verificatiedomein en tenant is de tenant-GUID.

E-mailaccounts zonder wachtwoord hebben geen wachtwoord om opnieuw in te stellen.

Wachtwoord opnieuw instellen starten

In het diagram ziet u een zelfstandige herstelreeks met eenmalige verificatie van wachtwoordcodes voor e-mail. Inlineherstel maakt in plaats daarvan gebruik van de koppeling van recover de wachtwoordmethode binnen de actieve aanmeldingstransactie.

Sequentiediagram van wachtwoordherstel, wachtwoordcodeverificatie, wachtwoordupdate, optionele polling en uitwisseling van autorisatiecode.

Start autorisatie en volg de geretourneerde koppeling voor het opnieuw instellen van het wachtwoord (resetPassword of reset_password). Roep aanmeldingsdetectie niet eerst aan:

POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
  "username": "user@contoso.com",
  "continuationToken": "******"
}

Verzend de id van de klant in username en het huidige autorisatietoken in continuationToken. In het voorbeeld wordt een e-mailadres gebruikt. Een antwoord kan een e-mailherstelmethode adverteren:

{
  "state": "interactionRequired",
  "action": "challenge",
  "continuationToken": "******",
  "_links": {
    "self": {
      "href": "/{tenant}/api/v2.0/resetpassword/start"
    }
  },
  "_embedded": {
    "methods": [
      {
        "id": "{email_method_id}",
        "type": "email",
        "hint": "j****n@c****o",
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
          }
        }
      }
    ]
  }
}

Selecteer een geretourneerde e-mail- of SMS-herstelmethode via gebruikerskeuze- of toepassingsstroomlogica. In het voorbeeld ziet u e-mail; voor SMS volgt u de koppelingen van de geretourneerde SMS-methode zonder de voorbeeld-URL te herschrijven. Gebruik de gemaskeerde hint waar de interface een doellabel nodig heeft.

Inlineherstel tijdens aanmelding

Bied inlineherstel alleen aan wanneer een wachtwoordmethode in het huidige aanmeldingsantwoord een recover koppeling adverteert. Volg deze koppeling met behulp van het huidige vervolgtoken voor aanmelding. Start geen andere autorisatieaanvraag of verzend de gebruikersnaam of het wachtwoord opnieuw.

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

Beide toegangspunten gebruiken de herstelmethode, uitdaging, verificatie, wachtwoordupdate en pollingbewerkingen die door de service worden geretourneerd.

De herstelmethode uitdagen en verifiëren

Plaats een bericht op de koppeling naar challenge de geselecteerde methode:

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

Gebruik JSON en Accept: application/hal+json. De bewerking voor gedeelde uitdagingen retourneert het huidige methodetype, gemaskeerde hinten codeLengthverify optionele resend koppelingen.

Plaats de ingevoerde wachtwoordcode op de geretourneerde verify koppeling:

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

Gebruik het nieuwste token voor elke aanvraag. Gebruik voor een andere code de huidige resend koppelings- en servicelimieten, niet een eerder uitdagings-URL/tokenpaar.

Een geslaagde verificatie kan de wachtwoordmethode retourneren:

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

Gebruik de wachtwoordmethode-id van de geretourneerde update koppeling, niet de id van de e-mail- of SMS-herstelmethode. Inlineherstel kan de id van de wachtwoordmethode behouden van de bovenliggende aanmelding.

Een wachtwoord bijwerken

Verzend het vervangende wachtwoord met PUT, niet POST:

PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
  "newPassword": "{new_password}",
  "continuationToken": "******"
}
Property Type Required Description
continuationToken Tekenreeks. Yes. Het huidige token dat wachtwoordupdate aanvraagt.
newPassword Tekenreeks. Yes. Vervangend wachtwoord. Wachtwoordbevestiging is lokaal voor uw interface, niet een extra aanvraagveld.

De service kan het volgende retourneren:

{
  "state": "interactionRequired",
  "action": "poll",
  "pollInterval": "2",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "poll": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
    }
  }
}

Dit geeft een asynchrone update aan, niet de definitieve autorisatie. Verzend het wachtwoord niet opnieuw tijdens het wachten of herhaal de update automatisch na een niet-eenduidige netwerkfout.

Update van peilingswachtwoord

Volg de meest recente poll koppeling:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

Terwijl de update wordt uitgevoerd, retourneert interactionRequired de service met action: poll, een bijgewerkt token en een poll koppeling. Vervang het vorige antwoord vóór de volgende poll.

Indien opgenomen, pollInterval is een tekenreeks die het interval in seconden bevat. Gebruik het interval van het huidige antwoord voor de volgende aanvraag en volg de richtlijnen voor het opnieuw proberen van de server. Het voorbeeld "2" is geen vast service-interval. Stop polling wanneer de actie wordt gewijzigd of als er een fout wordt geretourneerd en voer eventuele latere verificatie af die vereist is voor beleid.

Een vervolgantwoord is:

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

Beleidsvereisten voltooien en tokens verkrijgen

Wachtwoord opnieuw instellen omzeilt MFA of voorwaardelijke toegang niet. Als er een andere uitdaging wordt geretourneerd, voltooit u deze met behulp van de bewerkingen voor gedeelde methoden. Tokenuitwisseling volgt de voltooiing van de resterende beleidsstappen en autorisatievervolging.

Daarna state: continuekunt u de autorisatie hervatten met behulp van het meest recente token en de code uitwisselen. De aangevraagde bereiken en claims blijven die aan het begin van de transactie tot stand zijn gebracht.

Resultaten en fouten

Gebruik de gedeelde foutafhandeling. In het herstelcontract worden deze resultaten beschreven:

Condition Verwerking van resultaten en client
Onbekende gebruikersnaam Herstel wordt niet gestart. Gebruik een algemeen klantgericht bericht.
Onjuiste e-mail of sms-wachtwoordcode HTTP 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 HTTP 400 invalidRequest. Corrigeer de ontbrekende invoer.
Opnieuw verzenden Er wordt een nieuwe wachtwoordcode verzonden via de geretourneerde resend koppeling.
Verlopen token voor wachtwoordupdate HTTP 400 expiredToken met innerError.code: expiredContinuationToken. Autorisatie opnieuw opstarten.
Zwak of gemeenschappelijk vervangend wachtwoord HTTP 400 invalidRequest met een toepasselijke interne fout, zoals passwordTooWeak of passwordTooCommon. Een compatibel wachtwoord verzamelen.
Update wordt uitgevoerd Volg de meest recente richtlijnen voor pollingreacties en nieuwe pogingen voor de server.
Poll mislukt wachtwoordbeleid HTTP 400 invalidRequest met een interne fout, zoals passwordTooCommon of passwordBannedByPolicy. De fout afhandelen in plaats van voor onbepaalde tijd polling.
Account vergrendeld of uitgeschakeld tijdens polling HTTP 403 forbidden met innerError.code: accountLocked. Stop de herstelbewerking.
Taak voor wachtwoordupdate mislukt HTTP 500 serverError. Een duidelijke fout weergeven zonder de wachtwoordupdate automatisch te herhalen.
Voltooid herstel Eventuele resterende beleidsacties verwerken, autorisatie hervatten en tokens aanvragen.

In deze tabel worden specifieke resultaten beschreven, niet een volledige foutcatalogus. Acceptatie van wachtwoordupdates, voltooiing van polling en tokenuitgifte zijn afzonderlijke grenzen.

Registreer geen wachtwoordcodes voor herstel, vervangende wachtwoorden of transactietokens. Noteer alleen veilige diagnostische id's, tijdstempels en HTTP-status. Voer verificatie- of wachtwoordupdates niet automatisch opnieuw af.