Api-referens för intern autentisering

Gäller för: Personalklientorganisationer Externa klienter (läs mer)

Med Microsoft Entras interna autentisering kan du vara värd för användargränssnittet för din app i klientprogrammet i stället för att delegera autentisering till webbläsare, vilket resulterar i en inbyggd integrerad autentiseringsupplevelse. Som utvecklare har du fullständig kontroll över utseendet och känslan i inloggningsgränssnittet.

Den här API-referensartikeln beskriver endast information som krävs när du manuellt gör råa HTTP-begäranden för att köra flödet. Vi rekommenderar dock inte den här metoden. Så när det är möjligt använder du ett Microsoft-byggt och stödt autentiserings-SDK. Mer information om hur du använder SDK finns i Självstudie: Förbereda din Android-mobilapp för intern autentisering och Självstudie: Förbered din iOS/macOS-mobilapp för intern autentisering.

När ett anrop till API-slutpunkterna lyckas får du både en ID-token för användaridentifiering och en åtkomsttoken för att anropa skyddade API:er. Alla svar från API:et är i JSON-format.

Microsoft Entras api för intern autentisering stöder registrering och inloggning för två autentiseringsmetoder:

• E-post med lösenord, som stöder registrering och inloggning med ett e-postmeddelande och lösenord, samt lösenordsåterställning via självbetjäning (SSPR).

• Skicka ett engångslösenord via e-post, som stöder registrering och inloggning med engångslösenord för e-post.

Förutsättningar

1. En extern Microsoft Entra-klientorganisation. Om du inte redan har en skapar du en extern klientorganisation.

2. Om du inte redan har gjort det registrerar du ett program i administrationscentret för Microsoft Entra. Se till att du beviljar delegerade behörigheter och aktiverar offentliga klient- och inbyggda autentiseringsflöden.

3. Om du inte redan har gjort det skapar du ett användarflöde i administrationscentret för Microsoft Entra. När du skapar användarflödet noterar du de användarattribut som du konfigurerar efter behov eftersom dessa attribut är de som Microsoft Entra förväntar sig att din app ska skicka.

4. Associera appregistreringen med användarflödet.

5. För inloggningsflöde registrerar du en kundanvändare som du använder för att testa inloggnings-API:erna. Du kan också hämta den här testanvändaren när du har kört registreringsflödet.

6. För SSPR-flöde aktiverar du självbetjäning av lösenordsåterställning för kundanvändare i den externa klientorganisationen. SSPR är tillgängligt för kundanvändare som använder e-post med lösenordsautentiseringsmetod.

Fortsättningstoken

Varje gång du anropar en slutpunkt i något av flödena, inloggningen, registreringen eller SSPR innehåller slutpunkten en fortsättningstoken i svaret. Fortsättningstoken är en unik identifierare som Microsoft Entra ID använder för att underhålla tillstånd mellan anrop till olika slutpunkter i samma flöde. Du måste inkludera den här token i efterföljande begäranden i samma flöde.

Varje fortsättningstoken är giltig under en viss period och kan endast användas för efterföljande begäranden inom samma flöde.

Referens för registrerings-API

För att slutföra ett användarregistreringsflöde för någon av autentiseringsmetoderna interagerar appen med fyra slutpunkter, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continueoch /token.

Registrerings-API-slutpunkter

Registreringsutmaningstyper

MED API:et kan klientappen annonsera de autentiseringsmetoder som den stöder när den anropar Microsoft Entra. För att göra det använder appen parametern challenge_type i appens begäran. Den här parametern innehåller fördefinierade värden som representerar olika autentiseringsmetoder.

Läs mer om utmaningstyper i de inbyggda autentiseringsutmaningstyperna. I den här artikeln beskrivs de utmaningstypvärden som du bör använda för en autentiseringsmetod.

Information om registreringsflödesprotokoll

Sekvensdiagrammet visar flödet i registreringsprocessen.

Det här diagrammet anger att appen samlar in användarnamn (e-post), lösenord (för e-post med metoder för lösenordsautentisering) och attribut från användaren vid olika tidpunkter (och eventuellt på separata skärmar). Du kan dock utforma din app för att samla in användarnamnet (e-postmeddelandet), lösenordet och alla obligatoriska och valfria attributvärden på samma skärm och sedan skicka dem alla via /signup/v1.0/start slutpunkten. I det här fallet behöver appen inte göra anrop och hantera svar för de valfria stegen.

Steg 1: Begäran om att starta registreringsflödet

Registreringsflödet börjar med att programmet gör en POST-begäran till /signup/v1.0/start slutpunkten för att starta registreringsflödet.

Här är exempel på begäran (vi presenterar exempelbegäran i flera rader för läsbarhet):

Exempel 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com 

Exempel 2 (inkludera användarattribut och lösenord i begäran):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com 

Svar om lyckad åtgärd

Här är ett exempel på ett lyckat svar:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
} 

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_grant fel:

Om felparametern har värdet invalid_client innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_client fel:

Steg 2: Välj en autentiseringsmetod

Appen begär att Microsoft Entra väljer någon av de utmaningstyper som stöds för användaren att autentisera med. För att göra det gör appen ett anrop till /signup/v1.0/challenge slutpunkten. Appen måste inkludera den fortsättningstoken som den hämtar från /signup/v1.0/start slutpunkten i begäran.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet).

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

Svar om lyckad åtgärd

Microsoft Entra skickar ett engångslösenord till användarens e-post och svarar sedan med utmaningstypen med värdet oob och ytterligare information om engångslösenordet:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
} 

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Steg 3: Skicka engångslösenord

Appen skickar engångslösenordet som skickas till användarens e-post. Eftersom vi skickar engångslösenord krävs en oob parameter och parametern grant_type måste ha värdet oob.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

När appen har skickat engångslösenordet beror registreringsflödet på scenarierna enligt tabellen:

Svar

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_grant fel:

För att lösenordsautentiseringsuppgifterna ska samlas in från användaren måste appen göra ett anrop till /signup/v1.0/challenge slutpunkten för att fastställa de autentiseringsuppgifter som användaren måste ange.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

Svar om lyckad åtgärd

Om lösenordet är den autentiseringsmetod som konfigurerats för användaren i administrationscentret för Microsoft Entra returneras ett lyckat svar med fortsättningstoken till appen.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Steg 4: Autentisera och hämta token för att registrera dig

Appen måste skicka användarens autentiseringsuppgifter, i det här fallet lösenord, som Microsoft Entra begärde i föregående steg. Appen måste skicka in en lösenordsautentiseringsuppgift om den inte gjorde det via /signup/v1.0/start slutpunkten. Appen skickar en begäran till /signup/v1.0/continue slutpunkten om att skicka lösenordet. Eftersom vi skickar ett lösenord krävs en password parameter och parametern måste ha ett värdelösenordgrant_type.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}

Svar om lyckad åtgärd

Om begäran lyckas, men inga attribut har konfigurerats i administrationscentret för Microsoft Entra eller om alla obligatoriska attribut har skickats via /signup/v1.0/start slutpunkten, hämtar appen en fortsättningstoken utan att skicka några attribut. Appen kan använda fortsättningstoken för att begära säkerhetstoken enligt steg 5. Annars anger Microsoft Entras svar att appen måste skicka nödvändiga attribut. Dessa attribut, inbyggda eller anpassade, konfigurerades i administrationscentret för Microsoft Entra av klientadministratören.

Användarattribut krävs

Det här svaret begär att appen skickar värden för namn, *ålder och telefonattribut .

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror :

Skicka användarattribut

För att fortsätta med flödet måste appen göra ett anrop till /signup/v1.0/continue slutpunkten för att skicka de nödvändiga användarattributen. Eftersom vi skickar attribut krävs en attributes parameter och parametern grant_type måste ha ett värde som är lika med attribut.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Svar om lyckad åtgärd

Om begäran lyckas utfärdar Microsoft Entra en fortsättningstoken som appen kan använda för att begära säkerhetstoken.

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_grant fel:

Steg 5: Begäran om säkerhetstoken

Appen gör en POST-begäran till /token slutpunkten och tillhandahåller fortsättningstoken som hämtades från föregående steg för att hämta säkerhetstoken.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token 

Lyckat svar

Här är ett exempel på ett lyckat svar:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Skicka användarattribut till slutpunkter

I administrationscentret för Microsoft Entra kan du konfigurera användarattribut efter behov eller valfritt. Den här konfigurationen avgör hur Microsoft Entra svarar när du gör ett anrop till dess slutpunkter. Valfria attribut är inte obligatoriska för att registreringsflödet ska slutföras. När alla attribut är valfria måste de därför skickas innan användarnamnet verifieras. Annars slutförs registreringen utan de valfria attributen.

I följande tabell sammanfattas när det är möjligt att skicka användarattribut till Microsoft Entra-slutpunkter.

Format för värden för användarattribut

Du anger den information som du vill samla in från användaren genom att konfigurera användarflödesinställningarna i administrationscentret för Microsoft Entra. Använd artikeln Samla in anpassade användarattribut under registreringen för att lära dig hur du samlar in värden för både inbyggda och anpassade attribut.

Du kan också ange indatatypen för användaren för de attribut som du konfigurerar. I följande tabell sammanfattas de användarindatatyper som stöds och hur du skickar värden som samlas in av användargränssnittskontrollerna till Microsoft Entra.

Här är en exempelbegäran som visar hur du skickar attributens värden:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

Läs mer om indatatyper för användarattribut i artikeln Indatatyper för anpassade användarattribut.

Referera till användarattribut

När du skapar ett användarflöde för registrering konfigurerar du användarattribut som du vill samla in från användaren under registreringen. Namnen på användarattributen i administrationscentret för Microsoft Entra skiljer sig från hur du refererar till dem i det interna autentiserings-API:et.

Visningsnamn i administrationscentret för Microsoft Entra refereras till som displayName i API:et.

Använd artikeln Användarprofilattribut för att lära dig hur du refererar till både inbyggda och anpassade användarattribut i det interna autentiserings-API:et.

Inloggnings-API-referens

Användarna måste logga in med den autentiseringsmetod som de använder för registrering. Användare som registrerar sig med e-post med lösenordsautentiseringsmetod måste till exempel logga in e-post och lösenord.

Om du vill begära säkerhetstoken interagerar appen med tre slutpunkter, /initiate, /challenge och /token.

Inloggnings-API-slutpunkter

Typer av inloggningsutmaningar

MED API:et kan appen annonsera de autentiseringsmetoder som den stöder när den anropar Microsoft Entra. För att göra det använder appen parametern challenge_type i sina begäranden. Den här parametern innehåller fördefinierade värden som representerar olika autentiseringsmetoder.

För en viss autentiseringsmetod är de utmaningstypvärden som en app skickar till Microsoft Entra under registreringsflödet desamma som när appen loggar in. Till exempel använder metoden e-post med lösenordsautentisering oob, lösenord och omdirigeringsutmaningstyp för både registrerings- och inloggningsflöden.

Läs mer om utmaningstyper i artikeln om inbyggda autentiseringsutmaningstyper .

Information om inloggningsflödesprotokoll

Sekvensdiagrammet visar flödet för inloggningsprocessen.

I de avsnitt som följer sammanfattar vi sekvensdiagramflödet i tre grundläggande steg.

Steg 1: Begäran om att starta inloggningsflödet

Autentiseringsflödet börjar med att programmet gör en POST-begäran till /initiate slutpunkten för att starta inloggningsflödet.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com 

Svar om lyckad åtgärd

Här är ett exempel på ett lyckat svar:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_client innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_client fel:

Steg 2: Välj en autentiseringsmetod

För att fortsätta med flödet använder appen den fortsättningstoken som hämtas från föregående steg för att begära att Microsoft Entra väljer någon av de utmaningstyper som stöds för användaren att autentisera med. Appen skickar en POST-begäran till /challenge slutpunkten.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY... 

Svar om lyckad åtgärd

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

HTTP/1.1 200 OK
Content-Type: application/json

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Steg 3: Begäran om säkerhetstoken

Appen skickar en POST-begäran till /token slutpunkten och tillhandahåller användarens autentiseringsuppgifter som valdes i föregående steg, i det här fallet lösenord, för att hämta säkerhetstoken.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 

Lyckat svar

Här är ett exempel på ett lyckat svar:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_grant fel:

Självbetjäning av lösenordsåterställning (SSPR)

Om du använder e-post och lösenord som autentiseringsmetod i din app använder du API:et för självbetjäning av lösenordsåterställning (SSPR) för att göra det möjligt för kundanvändare att återställa sitt lösenord. Använd det här API:et för att glömma lösenord eller ändra lösenordsscenarier.

API-slutpunkter för lösenordsåterställning med självbetjäning

Om du vill använda det här API:et interagerar appen med slutpunkten som visas i följande tabell:

Utmaningstyper för självbetjäning av lösenordsåterställning

MED API:et kan appen annonsera de autentiseringsmetoder som den stöder när den anropar Microsoft Entra. För att göra det använder appen parametern challenge_type i sina begäranden. Den här parametern innehåller fördefinierade värden som representerar olika autentiseringsmetoder.

För SSPR-flödet är utmaningstypvärdena oob och omdirigering.

Läs mer om utmaningstyper i de inbyggda autentiseringsutmaningstyperna.

Protokollinformation för självbetjäning av lösenordsåterställningsflöde

Sekvensdiagrammet visar flödet för processen för lösenordsåterställning.

Det här diagrammet anger att appen samlar in användarnamn (e-post) och lösenord från användaren vid olika tidpunkter (och eventuellt på separata skärmar). Du kan dock utforma din app för att samla in användarnamnet (e-postmeddelandet) och det nya lösenordet på samma skärm. I det här fallet innehåller appen lösenordet och skickar det sedan via slutpunkten /submit där det krävs.

Steg 1: Begäran om att starta självbetjäningsflödet för lösenordsåterställning

Flödet för lösenordsåterställning börjar med att appen gör en POST-begäran till /start slutpunkten för att starta självbetjäningsflödet för lösenordsåterställning.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com 

Svar om lyckad åtgärd

Exempel:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_client innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_client fel:

Steg 2: Välj en autentiseringsmetod

För att fortsätta med flödet använder appen fortsättningstoken som hämtades från föregående steg för att begära att Microsoft Entra väljer någon av de utmaningstyper som stöds för användaren att autentisera med. Appen skickar en POST-begäran till /challenge slutpunkten. Om den här begäran lyckas skickar Microsoft Entra ett engångslösenord till användarens konto-e-post. För närvarande stöder vi endast e-post-OTP.

Här är ett exempel (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 

Svar om lyckad åtgärd

Exempel:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

Om en app inte kan stödja en obligatorisk autentiseringsmetod av Microsoft Entra krävs en återställning till det webbaserade autentiseringsflödet. I det här scenariot informerar Microsoft Entra appen genom att returnera en typ av omdirigeringsutmaning i svaret:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Det här svaret anses vara lyckat, men appen krävs för att växla till ett webbaserat autentiseringsflöde. I det här fallet rekommenderar vi att du använder ett autentiseringsbibliotek som stöds av Microsoft.

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Steg 3: Skicka engångslösenord

Appen skickar sedan en POST-begäran till /continue slutpunkten. I begäran måste appen inkludera användarens autentiseringsuppgifter som valdes i föregående steg och fortsättningstoken som utfärdades från /challenge slutpunkten.

Här är ett exempel på begäran (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

Svar om lyckad åtgärd

Exempel:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror för ett invalid_grant fel:

Steg 4: Skicka ett nytt lösenord

Appen samlar in ett nytt lösenord från användaren och använder sedan fortsättningstoken som utfärdats av /continue slutpunkten för att skicka lösenordet genom att göra en POST-begäran till /submit slutpunkten.

Här är ett exempel (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}

Svar om lyckad åtgärd

Exempel:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Om felparametern har värdet invalid_grant innehåller Microsoft Entra en suberror parameter i svaret. Här är de möjliga värdena för parametern suberror :

Steg 5: Sök efter status för lösenordsåterställning

Eftersom uppdateringen av användarens konfiguration med det nya lösenordet medför viss fördröjning kan appen använda /poll_completion slutpunkten för att söka efter status för lösenordsåterställning i Microsoft Entra. Den minsta tid i sekunder som appen ska vänta mellan avsökningsbegäranden returneras från /submit slutpunkten i parametern poll_interval .

Här är ett exempel (vi presenterar exempelbegäran på flera rader för läsbarhet):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0... 

Svar om lyckad åtgärd

Exempel:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Här är de möjliga statusar som Microsoft Entra returnerar (möjliga värden för parametern status ):

Felsvar

Exempel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

Här är de möjliga fel som du kan stöta på (möjliga värden för parametern error ):

Relaterat innehåll

• Konfigurera en anpassad anspråksprovider.