다음을 통해 공유

기본 인증 API 참조

적용 대상: 외부 테넌트에 다음 내용이 적용되었음을 나타내는 흰색 확인 표시 기호가 있는 녹색 원입니다. 외부 테넌트(자세한 정보)

Microsoft Entra native Authentication을 사용하면 브라우저에 인증을 위임하는 대신 클라이언트 애플리케이션에서 앱의 사용자 인터페이스를 호스트할 수 있으므로 기본적으로 통합된 인증 환경이 생성됩니다. 개발자는 로그인 인터페이스의 모양과 느낌을 완전히 제어할 수 있습니다.

이 API 참조 문서에서는 흐름을 실행하기 위해 원시 HTTP 요청을 수동으로 만드는 경우에만 필요한 세부 정보를 설명합니다. 그러나 이 방식은 권장되지 않습니다. 따라서 가능하면 Microsoft에서 빌드하고 지원하는 인증 SDK를 사용합니다. 네이티브 인증 SDK에 대해 자세히 알아봅니다. API 끝점에 대한 호출이 성공하면 사용자 식별을 위한 ID 토큰과 보호된 API 호출을 위한 액세스 토큰을 모두 받게 됩니다. API의 모든 응답은 JSON 형식입니다.

Microsoft Entra 네이티브 인증 API는 다음 두 가지 인증 흐름에 대한 등록 및 로그인을 지원합니다.

  • 암호가 포함된 메일 - 메일과 암호를 사용한 등록 및 로그인, SSPR(셀프 서비스 암호 재설정)을 지원합니다.

  • 메일 일회용 암호 - 메일 일회용 암호로 등록 및 로그인을 지원합니다.

참고 항목

현재 기본 인증 API 엔드포인트는 CORS(원본 간 리소스 공유)를 지원하지 않습니다.

필수 조건

  1. Microsoft Entra 외부 테넌트입니다. 아직 외부 테넌트가 없다면 외부 테넌트를 생성하세요.

  2. 아직 등록하지 않은 경우 Microsoft Entra 관리 센터에서 애플리케이션 등록. 다음을 수행해야 합니다.

  3. 아직 수행하지 않은 경우 Microsoft Entra 관리 센터에서 사용자 흐름을 만듭니다. 사용자 흐름을 만들 때 필요에 따라 구성하는 사용자 특성을 기록해 둡니다. 이러한 특성은 앱이 제출해야 하는 특성이므로 Microsoft Entra.

  4. 앱 등록을 사용자 흐름과 연결합니다.

  5. 로그인 플로우의 경우, 고객 사용자를 등록하여 플로우를 테스트하세요. 또는 등록 흐름을 실행한 후 이 테스트 사용자를 가져올 수 있습니다.

  6. SSPR 흐름의 경우 고객 테넌트의 고객 사용자에 대해 셀프 서비스 암호 재설정을 사용합니다. SSPR은 암호 인증 방법으로 이메일을 사용하는 고객 사용자에게 제공됩니다.

  7. 이메일 주소와 비밀번호로 로그인하는 사용자도 사용자명과 비밀번호로도 로그인할 수 있게 하고 싶다면, '별칭 또는 사용자 이름으로 로그인 ' 기사의 단계를 참고하세요:

    1. 로그인에서 사용자 이름을 사용하도록 설정합니다.
    2. 관리 센터에서 사용자 이름을 가진 사용자를 만들 거나 사용자 이름을 추가하여 기존 사용자를 업데이트합니다. 또는 Microsoft Graph API 사용하여 앱에서 사용자 만들기 및 업데이트를 인증할 수도 있습니다.

  8. 고객에게 MFA(다단계 인증)를 적용하려면 앱에 MFA(다단계 인증) 추가 의 단계를 사용하여 로그인 흐름에 MFA를 추가합니다. 네이티브 인증은 MFA의 두 번째 요소로 이메일 일회용 암호 및 SMS를 지원합니다.

연속 토큰

로그인, 등록 또는 SSPR 엔드포인트를 호출할 때마다 응답에는 연속 토큰이 포함됩니다. 이 토큰은 현재 흐름을 고유하게 식별하고 Microsoft Entra ID 엔드포인트에서 상태를 유지할 수 있도록 합니다. 해당 흐름의 모든 후속 요청에 토큰을 포함합니다. 제한된 시간 동안만 유효하며 동일한 흐름 내의 후속 요청에만 사용할 수 있습니다.

가입을 위한 API 참조

인증 방법 중 하나에 대한 사용자 등록 흐름을 완료하기 위해 앱은 4개의 엔드포인트, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continue 및 /token과 상호 작용합니다.

가입을 위한 API 엔드포인트

엔드포인트 설명
/signup/v1.0/start 이 엔드포인트는 등록 흐름을 시작합니다. 유효한 애플리케이션 ID, 새 사용자 이름, 챌린지 유형을 전달한 후 새 연속 토큰을 다시 가져옵니다. 엔드포인트는 애플리케이션에서 선택한 인증 방법이 Microsoft Entra 지원되지 않는 경우 웹 인증 흐름을 사용하도록 애플리케이션에 나타내는 응답을 반환할 수 있습니다.
/signup/v1.0/challenge 앱은 Microsoft Entra 지원하는 challenge 형식 목록을 사용하여 이 엔드포인트를 호출합니다. 그런 다음 Microsoft Entra 사용자가 인증할 수 있도록 지원되는 인증 방법 중 하나를 선택합니다.
/signup/v1.0/continue 이 엔드포인트는 사용자 계정을 만드는 흐름을 계속하거나 암호 정책 요구 사항이나 잘못된 특성 형식과 같은 요구 사항 누락으로 인해 흐름을 중단하는 데 도움이 됩니다. 이 엔드포인트는 연속 토큰을 생성한 다음 이를 앱에 반환합니다. 엔드포인트는 애플리케이션이 Microsoft Entra 선택한 인증 방법이 없는 경우 웹 기반 인증 흐름을 사용하도록 애플리케이션에 나타내는 응답을 반환할 수 있습니다.
oauth/v2.0/token 애플리케이션은 이 엔드포인트를 호출하여 최종적으로 보안 토큰을 요청합니다. 앱은 엔드포인트에 대한 마지막 호출에서 획득한 연속 토큰을 /signup/v1.0/continue 사용해야 합니다.

등록 챌린지 유형

API를 사용하면 클라이언트 앱이 Microsoft Entra 호출할 때 지원하는 인증 방법을 보급할 수 있습니다. 이를 위해 앱은 앱 요청에 challenge_type 매개 변수를 사용합니다. 이 매개 변수는 서로 다른 인증 방법을 나타내는 미리 정의된 값을 보유합니다.

기본 인증 챌린지 유형에서 챌린지 유형에 대해 자세히 알아봅니다. 이 문서에서는 인증 방법에 사용해야 하는 챌린지 형식 값을 설명합니다.

등록 흐름 프로토콜 세부 정보

시퀀스 다이어그램은 등록 프로세스의 흐름을 보여 줍니다.

등록 흐름의 네이티브 인증 다이어그램

이 다이어그램은 앱이 사용자 이름(이메일), 암호(암호 인증 흐름이 있는 전자 메일의 경우) 및 사용자의 특성을 서로 다른 시간(그리고 별도의 화면에서)에 수집한다는 것을 나타냅니다. 그러나 동일한 화면에서 사용자 이름(이메일), 암호 및 모든 필수 및 선택적 특성 값을 수집하도록 앱을 디자인한 다음, 모두 엔드포인트에 /signup/v1.0/start 제출할 수 있습니다. 앱이 필요한 모든 정보를 엔드포인트에 /signup/v1.0/start 제출하는 경우 앱은 선택적 단계에서 호출을 수행하고 응답을 처리할 필요가 없습니다.

21단계에서 사용자가 이미 등록되어 있습니다. 그러나 앱이 등록 후 사용자를 자동으로 로그인해야 하는 경우 앱은 엔드포인트를 oauth/v2.0/token 호출하여 보안 토큰을 요청합니다.

1단계: 등록 흐름 시작 요청

등록 흐름은 애플리케이션이 등록 흐름을 시작하기 위해 /signup/v1.0/start 엔드포인트에 POST 요청을 하는 것으로 시작됩니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

예제 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

예 2(요청에 사용자 특성 및 암호 포함):

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
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
username 예 등록하려는 고객 사용자의 메일입니다(예: contoso-consumer@contoso.com).
challenge_type 예 oob password redirect와 같이 앱이 지원하는 권한 부여 챌린지 유형 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 값은 암호 인증 방법을 포함하는 메일의 경우 oob redirect 또는 oob password redirect여야 합니다.
password 아니요 앱이 고객 사용자로부터 수집하는 암호 값입니다. /signup/v1.0/start를 통해 또는 나중에 /signup/v1.0/continue 엔드포인트에서 사용자의 암호를 제출할 수 있습니다. {secure_password}를 앱이 고객 사용자로부터 수집하는 암호 값으로 바꿉니다. 앱 UI에 암호 확인 필드를 제공하여 사용자가 사용하려는 암호를 알고 있는지 확인하는 것은 사용자의 책임입니다. 또한 사용자가 조직의 정책에 따라 강력한 암호를 구성하는 것을 알고 있는지 확인해야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
이 매개 변수는 암호 인증 방법을 포함하는 메일에만 적용됩니다.
attributes 아니요 앱이 고객 사용자로부터 수집하는 사용자 특성 값입니다. 값은 문자열이지만 키 값이 사용자 특성의 프로그래밍 가능한 이름인 JSON 개체로 형식이 지정됩니다. 이러한 특성은 기본 제공되거나 사용자 지정될 수 있으며 필수 또는 선택 사항일 수 있습니다. 개체의 키 이름은 관리자가 Microsoft Entra 관리 센터에서 구성한 특성에 따라 달라집니다. /signup/v1.0/start 엔드포인트를 통해 또는 나중에 /signup/v1.0/continue 엔드포인트를 통해 일부 또는 모든 사용자 특성을 제출할 수 있습니다. /signup/v1.0/start 엔드포인트를 통해 필수 특성을 모두 제출하는 경우 /signup/v1.0/continue 엔드포인트에서 어떤 특성도 제출할 필요가 없습니다. 그러나 /signup/v1.0/start 엔드포인트를 통해 일부 필수 특성을 제출하는 경우 나중에 /signup/v1.0/continue 엔드포인트에서 나머지 필수 특성을 제출할 수 있습니다. {given_name}, {user_age} 및 {postal_code}를 각각 앱이 고객 사용자로부터 수집하는 이름, 나이 및 우편 번호 값으로 바꿉니다. Microsoft Entra 존재하지 않는 모든 특성을 무시합니다.
capabilities 아니요 클라이언트 앱의 기능을 설명하는 공간으로 구분된 플래그입니다. 챌린지 challenge_type 할 수 있는 메서드를 정의하는 동안 capabilities 클라이언트 앱이 처리할 수 있는 추가 흐름과 사용자에게 표시할 수 있는 UI를 네이티브 인증 API에 알릴 수 있습니다. 예를 들어 mfa_required 다른 /challenge 루프와 루프 /token 를 의미합니다registration_required. 즉, 클라이언트 앱이 등록 API를 호출하고 등록 UI를 표시합니다. 필요한 접근 권한 값이 클라이언트 앱에서 보급되지 않으면 API는 리디렉션을 반환합니다. 지원되는 값은 mfa_requiredregistration_required. 기능에 대해 자세히 알아봅니다.

성공 응답

다음은 성공적인 업로드의 예입니다.

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

{
    "continuation_token": "AQABAAEAAA…",
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
invalid_attributes 유효성 검사에 실패한 특성의 목록(개체 배열)입니다. 앱이 사용자 특성을 제출하고 속성 값이 suberrorattribute_validation_failed 경우 이 응답이 가능합니다.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 요청 매개 변수 유효성 검사에 실패했습니다(challenge_type 매개 변수 값에 지원되지 않는 인증 방법이 포함되어 있는 경우 또는 요청에 client_id 매개 변수가 포함되지 않았거나, 클라이언트 ID 값이 비어 있거나, 유효하지 않은 경우). error_description 매개 변수를 사용하여 정확한 오류 원인을 알아봅니다.
invalid_client 앱이 요청에 포함하는 클라이언트 ID는 공용 클라이언트가 아니거나 기본 인증이 사용하도록 설정되지 않은 등 기본 인증 구성이 부족한 앱을 위한 것입니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
unauthorized_client 요청에 사용된 클라이언트 ID는 유효한 클라이언트 ID 유형을 가지고 있지만 외부 테넌트에 존재하지 않거나 올바르지 않습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.
user_already_exists 사용자가 이미 존재합니다.
invalid_grant 앱이 제출하는 암호가 너무 짧은 경우처럼 암호가 복잡성 요구 사항을 모두 충족하지 않습니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
이 매개 변수는 암호 인증 방법을 포함하는 메일에만 적용됩니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
password_too_weak 암호는 복잡성 요구 사항을 충족하지 않으므로 너무 약합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.
password_too_short 새 암호는 8자 미만입니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.
password_too_long 새 암호가 256자보다 깁니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.
password_recently_used 새 암호는 최근에 사용한 암호와 동일하지 않아야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.
password_banned 새 암호에 금지된 단어, 구 또는 패턴이 포함되어 있습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.
password_is_invalid 예를 들어, 허용되지 않는 문자를 사용하고 있기 때문에 암호가 유효하지 않습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.

오류 매개 변수의 값이 invalid_client이면 Microsoft Entra 응답에 suberror 속성을 포함합니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
nativeauthapi_disabled 기본 인증이 사용하도록 설정되지 않은 앱의 클라이언트 ID입니다.

참고 항목

/signup/v1.0/start 엔드포인트를 통해 모든 필수 특성을 제출하지만, 선택적 특성은 일부 제출하지 않은 경우 나중에 /signup/v1.0/continue 엔드포인트를 통해 추가 선택적 특성을 제출할 수 없습니다. Microsoft Entra 등록 흐름을 완료하는 데 필수가 아니므로 선택적 특성을 명시적으로 요청하지 않습니다. 및 /signup/v1.0/start 엔드포인트에 제출할 수 있는 사용자 특성을 알아보려면 /signup/v1.0/continue 섹션의 표를 참조하세요.

2단계: 인증 방법 선택

앱은 사용자가 인증할 지원되는 챌린지 유형 중 하나를 선택하도록 Microsoft Entra 요청합니다. 이를 위해 앱은 /signup/v1.0/challenge 엔드포인트에 호출합니다. 앱은 /signup/v1.0/start 엔드포인트에서 획득하는 연속 토큰을 요청에 포함해야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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…
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
challenge_type 아니요 와 같이 앱이 지원하는 권한 부여 oob password redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 값은 메일 일회용 암호의 경우 oob redirect, 암호 인증 방법을 포함하는 메일의 경우 oob password redirect여야 합니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.

성공 응답

Microsoft Entra 사용자의 전자 메일에 일회성 암호를 보낸 다음, ob 및 일회성 암호에 대한 추가 정보를 사용하여 챌린지 유형으로 응답합니다.

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
}
재산 설명
interval 앱이 OTP 재전송을 시도하기 전에 기다려야 하는 시간(초)입니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.
challenge_type 사용자가 인증할 수 있도록 선택된 챌린지 유형입니다.
binding_method 유일한 유효한 값은 프롬프트입니다. 이 매개 변수는 향후 사용자에게 일회용 암호를 입력하는 더 많은 방법을 제공하는 데 사용될 수 있습니다. challenge_type이 oob인 경우 발급됩니다.
challenge_channel 일회용 암호가 전송된 채널의 형식입니다. 현재는 메일 채널만 지원됩니다.
challenge_target_label 일회용 암호를 보낸 난독 처리된 메일입니다.
code_length Microsoft Entra 생성하는 일회성 암호의 길이입니다.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{
   "challenge_type": "redirect"
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 클라이언트 ID가 비어 있거나 유효하지 않은 등의 요청 매개 변수 유효성 검사에 실패했습니다.
expired_token 연속 토큰이 만료되었습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.
invalid_grant 연속 토큰이 잘못되었습니다.

3단계: 일회용 암호 제출

앱은 사용자의 메일로 전송된 일회용 암호를 제출합니다. 일회용 암호를 제출하므로 oob 매개 변수가 필요하며 grant_type 매개 변수의 값은 oob여야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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}
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
grant_type 예 /signup/v1.0/continue 엔드포인트에 대한 요청을 사용하여 일회용 암호, 암호 또는 사용자 특성을 제출할 수 있습니다. 이 경우 grant_type 값은 세 가지 사용 사례를 구별하는 데 사용됩니다. grant_type에 가능한 값은 oob, password, attributes입니다. 이 호출에서는 일회용 암호를 전송하므로 값은 oob여야 합니다.
oob 예 고객 사용자가 메일에서 받은 일회용 암호입니다. {otp_code}를 고객 사용자가 메일로 받은 일회용 암호 값으로 바꿉니다. 일회용 암호를 다시 보내려면 앱이 /signup/v1.0/challenge 엔드포인트에 다시 요청해야 합니다.

앱이 일회용 암호를 성공적으로 제출하면 등록 흐름은 표에 표시된 시나리오에 따라 달라집니다.

시나리오 진행 방법
앱은 /signup/v1.0/start 엔드포인트를 통해 사용자의 암호(암호 인증 방법을 사용하는 전자 메일의 경우)를 성공적으로 제출하고 Microsoft Entra 관리 센터에 특성이 구성되지 않거나 모든 필수 사용자 특성이 /signup/v1.0/start 엔드포인트를 통해 제출됩니다. Microsoft Entra 연속 토큰을 발급합니다. 앱은 보안 토큰 요청에 표시된 대로 연속 토큰을 사용하여 보안 토큰을 요청할 수 있습니다.
앱은 /signup/v1.0/start 통해 사용자의 암호(암호 인증 방법을 사용하는 전자 메일의 경우)를 성공적으로 제출하지만 모든 필수 사용자 특성은 제출하지 Microsoft Entra 앱이 필요한 user 특성에 표시된 대로 제출해야 하는 특성을 나타냅니다. 앱은 /signup/v1.0/continue 엔드포인트를 통해 필요한 사용자 특성을 제출해야 합니다. 응답은 필요한 사용자 특성의 특성과 유사합니다. 사용자 특성 제출에 표시된 사용자 특성을 제출합니다.
앱은 /signup/v1.0/start 엔드포인트를 통해 사용자의 암호(암호 인증 방법을 포함하는 메일의 경우)를 제출하지 않습니다. Microsoft Entra 응답은 자격 증명이 필요하다는 것을 나타냅니다. 응답을 참조하세요.
이 응답은 암호 인증 방법을 포함하는 메일에 사용할 수 있습니다.

응답

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..."
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
credential_required 계정 만들기에는 인증이 필요하므로 사용자가 제공해야 하는 자격 증명을 확인하려면 /signup/v1.0/challenge 엔드포인트를 호출해야 합니다.
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않거나 외부 테넌트 관리자가 모든 테넌트 사용자에 대해 메일 OTP를 사용하도록 설정하지 않았습니다.
invalid_grant 요청에 포함된 권한 부여 유형이 유효하지 않거나 지원되지 않거나 OTP 값이 올바르지 않습니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
invalid_oob_value 일회용 암호 값이 잘못되었습니다.

사용자로부터 암호 자격 증명을 수집하려면 앱이 /signup/v1.0/challenge 엔드포인트를 호출하여 사용자가 제공해야 하는 자격 증명을 확인해야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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…
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
challenge_type 아니요 와 같이 앱이 지원하는 권한 부여 oob password redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 암호 등록 절차가 포함된 메일의 경우 값은 password redirect를 포함해야 합니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.

성공 응답

암호가 Microsoft Entra 관리 센터의 사용자에 대해 구성된 인증 방법인 경우 연속 토큰이 있는 성공 응답이 앱에 반환됩니다.

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}
재산 설명
challenge_type 필수 자격 증명에 대한 응답으로 암호가 반환됩니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
    "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

4단계: 등록을 위한 인증 및 토큰 가져오기

앱은 이전 단계에서 요청한 Microsoft Entra 사용자의 자격 증명(이 경우 암호)을 제출해야 합니다. 앱은 /signup/v1.0/start 엔드포인트를 통해 암호 자격 증명을 제출하지 않은 경우 암호 자격 증명을 제출해야 합니다. 앱은 /signup/v1.0/continue 엔드포인트에 암호 제출을 요청합니다. 암호를 제출하므로 password 매개 변수가 필요하며 grant_type 매개 변수의 값은 암호여야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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}
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 단계에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
grant_type 예 /signup/v1.0/continue 엔드포인트에 대한 요청을 사용하여 일회용 암호, 암호 또는 사용자 특성을 제출할 수 있습니다. 이 경우 grant_type 값은 세 가지 사용 사례를 구별하는 데 사용됩니다. grant_type에 가능한 값은 oob, password, attributes입니다. 이 호출에서는 사용자의 암호를 전송하므로 값은 password여야 합니다.
password 예 앱이 고객 사용자로부터 수집하는 암호 값입니다. {secure_password}를 앱이 고객 사용자로부터 수집하는 암호 값으로 바꿉니다. 앱 UI에 암호 확인 필드를 제공하여 사용자가 사용하려는 암호를 알고 있는지 확인하는 것은 사용자의 책임입니다. 또한 사용자가 조직의 정책에 따라 강력한 암호를 구성하는 것을 알고 있는지 확인해야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.

성공 응답

요청이 성공했지만 Microsoft Entra 관리 센터에서 특성이 구성되지 않거나 모든 필수 특성이 /signup/v1.0/start 엔드포인트를 통해 제출된 경우 앱은 특성을 제출하지 않고 연속 토큰을 가져옵니다. 앱은 보안 토큰 요청에 표시된 대로 연속 토큰을 사용하여 보안 토큰을 요청할 수 있습니다. 그렇지 않으면 Microsoft Entra 응답은 앱이 필요한 특성을 제출해야 했음을 나타냅니다. 기본 제공 또는 사용자 지정 특성은 테넌트 관리자가 Microsoft Entra 관리 센터에서 구성했습니다.

필요한 사용자 특성

이 응답은 앱에 이름, 연령 및 전화 특성에 대한 값을 제출하도록 요청합니다.

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]*$"
            }
        }
    ],
}

참고 항목

사용자 지정 특성(디렉터리 확장이라고도 함)은 extension_{appId-without-hyphens}_{attribute-name} 규칙을 사용하여 이름이 지정됩니다. 여기서 {appId-without-hyphens}는 확장 앱에 대한 클라이언트 ID의 제거된 버전입니다. 예를 들어, 확장 앱의 클라이언트 ID가 2588a-bcdwh-tfeehj-jeeqw-ertc이고 특성 이름이 hobbies인 경우 사용자 지정 특성 이름은 extension_2588abcdwhtfeehjjeeqwertc_hobbies로 지정됩니다. 사용자 지정 특성 및 확장 앱에 대해 자세히 알아봅니다.

재산 설명
error 특성을 확인하거나 제출해야 하기 때문에 Microsoft Entra 사용자 계정을 만들 수 없는 경우 이 특성이 설정됩니다.
error_description 오류의 원인을 식별하는 데 도움이 되는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.
required_attributes 계속하려면 앱이 다음 호출을 제출해야 하는 특성의 목록(개체 배열)입니다. 이러한 특성은 앱이 사용자 이름과 별도로 제출해야 하는 추가 특성입니다. Microsoft Entra 이 매개 변수는 error 매개 변수 값이 attributes_required 경우 응답입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않습니다.
invalid_grant 요청에 포함된 권한 부여 유형이 유효하지 않거나 지원되지 않습니다. grant_type에 대해 가능한 값은 oob, 암호, 특성입니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.
attributes_required 하나 이상의 사용자 특성이 필요합니다.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request challenge_type 매개 변수에 잘못된 챌린지 유형이 포함된 경우와 같이 요청 매개 변수 유효성 검사에 실패했습니다.
invalid_grant 제출된 암호가 너무 짧아서 제출된 권한 부여가 유효하지 않습니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
expired_token 연속 토큰이 만료되었습니다.
attributes_required 하나 이상의 사용자 특성이 필요합니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. 속성의 가능한 값은 suberror 다음과 같습니다.

하위 오류 값 설명
password_too_weak 암호는 복잡성 요구 사항을 충족하지 않으므로 너무 약합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_too_short 새 암호는 8자 미만입니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_too_long 새 암호가 256자보다 깁니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_recently_used 새 암호는 최근에 사용한 암호와 동일하지 않아야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_banned 새 암호에 금지된 단어, 구 또는 패턴이 포함되어 있습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_is_invalid 예를 들어, 허용되지 않는 문자를 사용하고 있기 때문에 암호가 유효하지 않습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.

사용자 특성 제출

흐름을 계속하려면 앱이 /signup/v1.0/continue 엔드포인트를 호출하여 필수 사용자 특성을 제출해야 합니다. 특성을 제출 중이므로 attributes 매개 변수가 필요하며 grant_type 매개 변수는 특성과 동일한 값을 가져야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
grant_type 예 /signup/v1.0/continue 엔드포인트에 대한 요청을 사용하여 일회용 암호, 암호 또는 사용자 특성을 제출할 수 있습니다. 이 경우 grant_type 값은 세 가지 사용 사례를 구별하는 데 사용됩니다. grant_type에 가능한 값은 oob, password, attributes입니다. 이 호출에서는 사용자 특성을 전송하므로 값은 attributes여야 합니다.
attributes 예 앱이 고객 사용자로부터 수집하는 사용자 특성 값. 값은 문자열이지만 키 값이 기본 제공되거나 사용자 지정된 사용자 특성의 이름인 JSON 개체로 형식이 지정됩니다. 개체의 키 이름은 관리자가 Microsoft Entra 관리 센터에서 구성한 특성에 따라 달라집니다. {given_name}, {user_age} 및 {postal_code}를 각각 앱이 고객 사용자로부터 수집하는 이름, 나이 및 우편 번호 값으로 바꿉니다. Microsoft Entra 존재하지 않는 모든 특성을 무시합니다.

성공 응답

요청이 성공하면 Microsoft Entra 사용자를 등록한 다음 연속 토큰을 발급합니다. 앱은 연속 토큰을 사용하여 엔드포인트에서 보안 토큰을 oauth/v2.0/token 요청할 수 있습니다.

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

{  
    "continuation_token": "AQABAAEAAAYn..."
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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" 
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.
unverified_attributes 확인해야 하는 특성 키 이름의 목록(개체 배열)입니다. 이 매개 변수는 error 매개 변수 값이 verification_required인 경우 응답에 포함됩니다.
required_attributes 앱이 제출해야 하는 특성의 목록(개체 배열)입니다. Microsoft Entra error 매개 변수의 값이 attributes_required인 경우 해당 응답에 이 매개 변수를 포함합니다.
invalid_attributes 유효성 검사에 실패한 특성의 목록(개체 배열)입니다. 이 매개 변수는 속성 값이 suberror 때 응답에 포함됩니다.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않습니다.
invalid_grant 제공된 권한 부여 유형이 유효하지 않거나 지원되지 않거나 유효성 검사에 실패했습니다(예: 특성 유효성 검사 실패). suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.
attributes_required 하나 이상의 사용자 특성이 필요합니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
attribute_validation_failed 사용자 특성 유효성 검사에 실패했습니다. invalid_attributes 매개 변수에는 유효성 검사에 실패한 특성의 목록(개체 배열)이 포함되어 있습니다.

5단계: 등록 후 자동으로 로그인

사용자가 등록 후 자동으로 로그인해야 하는 경우 앱은 엔드포인트에 oauth/v2.0/token POST 요청을 수행하고 보안 토큰을 획득하기 위해 이전 단계에서 얻은 연속 토큰을 제공합니다. 토큰 엔드포인트를 호출하는 방법을 알아봅니다.

엔드포인트에 사용자 특성 제출

Microsoft Entra 관리 센터에서 사용자 특성을 필수 또는 선택 사항으로 구성할 수 있습니다. 이 구성은 엔드포인트를 호출할 때 Microsoft Entra 응답하는 방법을 결정합니다. 선택 특성은 등록 흐름을 완료하는 데 필수가 아닙니다. 따라서 모든 특성이 선택 사항인 경우 사용자 이름을 확인하기 전에 제출해야 합니다. 그렇지 않으면 선택적 특성 없이 등록이 완료됩니다.

다음 표에서는 사용자 특성을 Microsoft Entra 엔드포인트에 제출할 수 있는 경우를 요약합니다.

엔드포인트 필수 특성 선택적 특성 필수 특성과 선택 특성 모두
/signup/v1.0/start 엔드포인트 예 예 예
사용자 이름 확인 전 /signup/v1.0/continue 엔드포인트 예 예 예
사용자 이름 확인 후 /signup/v1.0/continue 엔드포인트 예 아니요 예

사용자 특성 값의 형식

Microsoft Entra 관리 센터에서 사용자 흐름 설정을 구성하여 사용자로부터 수집하려는 정보를 지정합니다. 기본 제공 특성과 사용자 지정 특성 모두에 대한 값을 수집하는 방법을 알아보려면 등록 시 사용자 지정 사용자 특성 수집 문서를 참조하세요.

구성하는 특성에 대해 사용자 입력 형식을 지정할 수도 있습니다. 다음 표에는 지원되는 사용자 입력 유형과 UI 컨트롤에서 수집한 값을 Microsoft Entra 제출하는 방법이 요약되어 있습니다.

사용자 입력 유형 제출된 값의 형식
텍스트 상자  직함, 소프트웨어 엔지니어와 같은 단일 값입니다.
SingleRadioSelect 언어, 노르웨이어와 같은 단일 값입니다. 
체크박스 다중 선택 취미, 춤 또는 춤, 수영, 여행과 같은 하나 이상의 값입니다.

다음은 특성 값을 제출하는 방법을 보여 주는 요청 예입니다.

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...

사용자 지정 사용자 특성 입력 형식 문서에서 사용자 특성 입력 형식에 대해 자세히 알아봅니다.

사용자 특성을 참조하는 방법

등록 사용자 흐름을 만들 때 등록 중에 사용자로부터 수집하려는 사용자 특성을 구성합니다. Microsoft Entra 관리 센터의 사용자 특성 이름은 네이티브 인증 API에서 참조하는 방법과 다릅니다.

예를 들어 Microsoft Entra 관리 센터의 디플레이 이름은 API에서 displayName으로 참조됩니다.

기본 인증 API에서 네이티브 제공 특성과 사용자 지정 사용자 특성을 모두 참조하는 방법을 알아보려면 사용자 프로필 특성 문서를 참조하세요.

로그인 흐름에 대한 API 참조

사용자는 등록하는 데 사용하는 인증 방법으로 로그인해야 합니다. 예를 들어, 암호 인증 방법이 포함된 메일을 사용하여 등록하는 사용자는 메일과 암호로 로그인해야 합니다.

보안 토큰을 요청하기 위해 앱은 세 개의 엔드포인트, oauth/v2.0/initiate즉, oauth/v2.0/challengeoauth/v2.0/token필요에 따라 상호 작용합니다oauth/v2.0/introspect.

로그인을 위한 API 엔드포인트

엔드포인트 설명
oauth/v2.0/initiate 이 엔드포인트는 로그인 흐름을 시작합니다. 앱이 이미 존재하는 사용자 계정의 사용자 이름으로 이를 호출하면 연속 토큰과 함께 성공 응답을 반환합니다. 앱이 Microsoft Entra 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다.
oauth/v2.0/challenge 앱은 이 엔드포인트를 호출하여 사용자가 인증할 수 있도록 지원되는 사인 챌린지 유형 중 하나를 선택하도록 Microsoft Entra 요청합니다. 테넌트 관리자가 고객 사용자에 대해 MFA를 적용하는 경우 앱은 이 엔드포인트를 호출하여 사용자에게 2단계 인증 방법을 요청합니다.
oauth/v2.0/token 이 엔드포인트는 앱에서 받은 사용자의 자격 증명을 확인한 다음 앱에 보안 토큰을 발급합니다. 이 엔드포인트의 응답은 사용자가 MFA 챌린지를 완료해야 하는지 아니면 강력한 인증 방법을 등록해야 하는지를 나타낼 수도 있습니다.
oauth/v2.0/introspect 앱은 MFA(다단계 인증)를 위해 등록된 강력한 인증 방법 목록을 요청하도록 호출합니다. 내성 엔드포인트를 사용하는 방법 알아보기

로그인 챌린지 유형

API를 사용하면 앱이 Microsoft Entra 호출할 때 지원하는 인증 방법을 보급할 수 있습니다. 이를 위해 앱은 요청에 challenge_type 매개 변수를 사용합니다. 이 매개 변수는 서로 다른 인증 방법을 나타내는 미리 정의된 값을 보유합니다.

지정된 인증 방법의 경우 등록 흐름 중에 앱이 Microsoft Entra 보내는 챌린지 형식 값은 앱이 로그인할 때와 동일합니다. 예를 들어, 암호 인증 방법을 포함한 메일은 등록 및 로그인 흐름 모두에 oob, password 및 redirect 챌린지 유형 값을 사용합니다.

기본 인증 챌린지 유형 문서에서 챌린지 유형에 대해 자세히 알아보세요.

로그인 흐름 프로토콜 세부 정보

시퀀스 다이어그램은 로그인 프로세스의 흐름을 보여 줍니다. 로그인 흐름은 사용자의 인증 방법에 따라 달라집니다.

메일 일회용 암호를 사용한 기본 인증 로그인 다이어그램

앱은 OTP로 사용자의 메일을 확인한 후 보안 토큰을 받습니다. 일회용 암호 배달이 지연되거나 사용자의 메일로 배달되지 않는 경우, 사용자는 일회용 암호를 다시 보내달라고 요청할 수 있습니다. Microsoft Entra 이전 암호가 확인되지 않은 경우 다른 일회성 암호를 다시 보냅니다. Microsoft Entra 일회성 암호를 다시 보내면 이전에 보낸 코드가 무효화됩니다.

다음 섹션에서는 로그인 흐름을 세 가지 기본 단계로 요약합니다.

1단계: 로그인 흐름 시작 요청

인증 흐름은 애플리케이션이 로그인 흐름을 시작하기 위해 /initiate 엔드포인트에 POST 요청을 하는 것으로 시작됩니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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
&capabilities=registration_required mfa_required
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
username 예 고객 사용자의 메일입니다(예: contoso-consumer@contoso.com).
challenge_type 예 와 같이 앱이 지원하는 권한 부여 oob password redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 값은 메일 일회용 암호의 경우 oob redirect, 암호가 있는 메일의 경우 password redirect여야 합니다.
capabilities 아니요 클라이언트 앱의 "방법" 준비 상태를 설명하는 공간으로 구분된 플래그입니다. 챌린지 challenge_type 할 수 있는 메서드를 정의하는 동안 capabilities 클라이언트 앱이 처리할 수 있는 추가 흐름과 표시할 수 있는 UI를 네이티브 인증 API에 알릴 수 있습니다. 예를 들어 mfa_required , 및 /introspect/challenge 루프 /token 는 클라이언트 앱이 등록 API를 호출하고 등록 UI를 표시한다는 것을 의미합니다registration_required. 필요한 기능이 클라이언트 앱에 포함되지 않은 경우 API는 리디렉션을 반환합니다. 지원되는 값은 mfa_requiredregistration_required. 기능에 대해 자세히 알아봅니다.

성공 응답

다음은 성공적인 업로드의 예입니다.

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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


{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request challenge_type 매개 변수에 잘못된 챌린지 유형이 포함된 경우와 같이 요청 매개 변수 유효성 검사에 실패했습니다. 또는 요청에 client_id 매개 변수가 포함되지 않았습니다. 클라이언트 ID 값이 비어 있거나 유효하지 않습니다. error_description 매개 변수를 사용하여 정확한 오류 원인을 알아봅니다.
unauthorized_client 요청에 사용된 클라이언트 ID는 유효한 클라이언트 ID 유형을 가지고 있지만 외부 테넌트에 존재하지 않거나 올바르지 않습니다.
invalid_client 앱이 요청에 포함하는 클라이언트 ID는 공용 클라이언트가 아니거나 기본 인증이 사용하도록 설정되지 않은 등 기본 인증 구성이 부족한 앱을 위한 것입니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
user_not_found 사용자 이름이 존재하지 않습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.

오류 매개 변수의 값이 invalid_client이면 Microsoft Entra 응답에 suberror 속성을 포함합니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
nativeauthapi_disabled 기본 인증이 사용하도록 설정되지 않은 앱의 클라이언트 ID입니다.

2단계: 인증 방법 선택

흐름을 계속하기 위해 앱은 이전 단계에서 획득한 연속 토큰을 사용하여 Microsoft Entra 요청하여 사용자가 MFA 챌린지를 인증하거나 완료할 수 있도록 지원되는 챌린지 유형 중 하나를 선택합니다. 앱이 /oauth2/v2.0/challenge 엔드포인트에 POST 요청을 보냅니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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...
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰. 이전 요청은 엔드포인트를 호출하거나 /oauth2/v2.0/initiate 사용자가 MFA 챌린지를 완료하는 경우 엔드포인트를 호출 /oauth2/v2.0/introspect 합니다.
challenge_type 아니요 와 같이 앱이 지원하는 권한 부여 oob password redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 값은 메일 일회용 암호의 경우 oob redirect, 암호가 있는 메일의 경우 password redirect여야 합니다.
id 아니요 엔드포인트에서 /oauth2/v2.0/introspect 반환되는 강력한 인증 방법의 문자열 식별자입니다. 이 매개 변수는 클라이언트 앱이 사용자에게 두 번째 단계 인증에 대해 이의를 제기할 때 필요합니다. 내성 엔드포인트를 사용하는 방법을 알아봅니다.

성공 응답

성공 응답은 사용자의 인증 방법에 따라 달라집니다.

테넌트 관리자가 사용자의 인증 방법으로 Microsoft Entra 관리 센터에서 전자 메일 일회용 암호를 구성한 경우 Microsoft Entra 사용자의 전자 메일에 일회성 암호를 보낸 다음 oob의 챌린지 유형으로 응답하고 일회성 암호에 대한 자세한 정보를 제공합니다.

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
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
challenge_type 사용자가 인증할 수 있도록 선택된 챌린지 유형입니다.
binding_method 유일한 유효한 값은 프롬프트입니다. 이 매개 변수는 나중에 사용자가 일회용 암호를 입력하는 더 많은 방법을 제공하는 데 사용될 수 있습니다. challenge_type이 oob인 경우 발급됩니다.
challenge_channel 일회용 암호가 전송된 채널의 형식입니다. 현재는 메일을 지원합니다.
challenge_target_label 일회용 암호를 보낸 난독 처리된 메일입니다.
code_length Microsoft Entra 생성하는 일회성 암호의 길이입니다.

리디렉션 응답

다음 시나리오에서는 웹 기반 인증 흐름에 대한 대체가 필요할 수 있습니다.

  • 클라이언트 앱은 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않습니다.
  • 사용자는 SMS를 강력한 인증 방법으로 사용하려고 시도하지만 사기 방지는 높은 위험으로 간주되는 경우 요청을 차단합니다(암호 인증이 있는 전자 메일에서만).

이러한 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 유형을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request challenge_type 매개 변수에 잘못된 챌린지 유형이 포함된 경우와 같이 요청 매개 변수 유효성 검사에 실패했습니다.
invalid_grant 요청에 포함된 연속 토큰이 유효하지 않습니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.

3단계: 보안 토큰 요청

앱은 엔드포인트에 oauth2/v2.0/token POST 요청을 하고 보안 토큰을 획득하기 위해 이전 단계에서 선택한 사용자의 자격 증명을 제공합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
grant_type 예 부여 유형입니다. 토큰 엔드포인트를 호출할 때 이 값은
- 사용자의 첫 번째 단계 인증을 확인하기 위해 로그인 흐름에서 암호 인증 방법을 사용하는 전자 메일의 암호여야 합니다.
- 로그인 흐름에서 전자 메일 일회용 암호 인증 방법에 대한 oob입니다.
- 등록 흐름 후 자동 로그인에 대한 continuation_token.
- 셀프 서비스 암호 재설정 흐름 후 자동 로그인에 대한 continuation_token.
- 강력한 인증 방법 등록 흐름 후에 continuation_token.
- 사용자의 두 번째 단계 인증을 확인할 때 mfa_oob.
scope 예 공백으로 구분된 범위 목록입니다. 모든 범위는 프로필, openid 및 전자 메일과 같은 OIDC(OpenID Connect) 범위와 함께 단일 리소스에서 온 것이어야 합니다. Microsoft Entra ID 토큰을 발급하려면 앱에 openid 범위가 포함되어야 합니다. Microsoft Entra 새로 고침 토큰을 발급하려면 앱에 offline_access 범위가 포함되어야 합니다. Microsoft ID 플랫폼의 권한 및 동의에 대해 자세히 알아봅니다.
password 아니요 앱이 사용자로부터 수집하는 암호 값입니다. 앱이 사용자로부터 수집하는 암호 값으로 바꿉 {secure_password} 니다. 인증 방법이 암호가 있는 전자 메일인 경우 이 매개 변수가 필요합니다 .
oob 아니요 사용자가 전자 메일로 받는 일회성 암호입니다. 필수 경우:
- 기본 인증 방법은 이메일 일회용 암호입니다.
- 기본 인증 방법이 암호가 있는 전자 메일인 경우 앱이 MFA 챌린지를 충족하기 위해 이메일 일회용 암호를 제출합니다.
일회성 암호를 다시 보내려면 엔드포인트를 /challenge 다시 호출합니다.
username 아니요 등록하려는 사용자의 전자 메일(예: contoso-consumer@contoso.com.) 이 매개 변수는 등록 흐름에 필요합니다 .

성공적인 응답

다음은 성공적인 업로드의 예입니다.

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..."
}
재산 설명
token_type 토큰 형식 값을 나타냅니다. Microsoft Entra 지원하는 유일한 형식은 Bearer입니다.
scopes 액세스 토큰이 유효한 범위의 공백으로 구분된 목록입니다.
expires_in 액세스 토큰이 유효한 상태로 유지되는 시간(초)입니다.
access_token 앱이 /token 엔드포인트에서 요청한 액세스 토큰입니다. 앱은 이 액세스 토큰을 사용하여 웹 API와 같은 보안 리소스에 대한 액세스를 요청할 수 있습니다.
refresh_token OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 다른 액세스 토큰을 획득할 수 있습니다. 새로 고침 토큰은 장기적으로 존재합니다. 오랜 기간 동안 리소스에 대한 액세스를 유지할 수 있습니다. 액세스 토큰 새로 고침에 대한 자세한 내용은 액세스 토큰 새로 고침을 참조하세요.
참고: offline_access 범위를 요청하는 경우에만 발급됩니다.
id_token 사용자를 식별하는 데 사용되는 Jwt(JSON 웹 토큰)입니다. 앱은 토큰을 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱은 값을 캐시하고 표시할 수 있으며 기밀 클라이언트는 권한 부여에 이 토큰을 사용할 수 있습니다. ID 토큰에 대한 자세한 내용은 Microsoft ID 플랫폼의 ID 토큰을 참조하세요.
참고: openid 범위를 요청하는 경우에만 발급됩니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 요청 매개 변수 유효성 검사에 실패했습니다. 발행한 오류를 이해하려면 오류 설명에 있는 메시지를 사용합니다.
invalid_grant 요청에 포함된 연속 토큰이 유효하지 않거나, 요청에 포함된 사용자 로그인 자격 증명이 유효하지 않거나, 사용자로부터 추가 상호 작용이 필요하거나, 요청에 포함된 권한 부여 유형을 알 수 없습니다.
invalid_client 요청에 포함된 클라이언트 ID가 공용 클라이언트용이 아닙니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.
invalid_scope 요청에 포함된 범위 중 하나 이상이 잘못되었습니다.
unauthorized_client 요청에 포함된 클라이언트 ID가 잘못되었거나 존재하지 않습니다.
unsupported_grant_type 요청에 포함된 권한 부여 유형이 지원되지 않거나 올바르지 않습니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
invalid_oob_value 앱이 제출하는 일회용 암호 값이 잘못되었습니다.
mfa_required MFA가 필요합니다. 응답에는 연속 토큰이 포함됩니다. 엔드포인트를 oauth2/v2.0/introspect 호출하여 사용자의 등록된 강력한 인증 방법을 가져옵니다. 이 하위 서버는 사용자의 기본 인증 방법이 암호가 있는 전자 메일인 경우에만 발생합니다. 사용자의 등록된 강력한 인증 방법을 가져오는 방법을 참조하세요.

참고: MFA가 필요하지만 네이티브 인증이 반환 mfa_required되지 않는 경우도 있습니다. 또는 예를 들어 강력한 인증 방법 등록 흐름이 호출 /oauth2/v2.0/token 앞에 있고 해당 흐름 중에 사용 가능한 유일한 메서드(이메일)가 이미 확인된 경우입니다.
registration_required 사용자는 MFA 챌린지를 완료해야 하지만 등록된 강력한 인증 방법이 없습니다. 사용자에게 등록하라는 메시지를 표시합니다. 이 오류는 사용자의 기본 인증 방법이 암호가 포함된 전자 메일일 때 발생합니다. 강력한 인증 방법을 등록하는 방법을 알아봅니다.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.
redirect_reason 리디렉션이 필요한 이유입니다. 예를 들어 Microsoft Entra MFA 또는 강력한 인증 방법에 대한 등록이 필요하지만 앱이 요청에 이러한 기능을 포함하지 않았음을 감지합니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

사용자 등록 강력한 인증 방법 가져오기

엔드포인트를 oauth2/v2.0/introspect 사용하여 등록된 강력한 인증 방법의 사용자 목록을 요청합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.

성공 응답

예시:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6"
        }
    ]
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
methods 사용자가 등록한 강력한 인증 방법의 목록(개체)

MFA 메서드 개체에는 다음과 같은 속성이 있습니다.

재산 설명
id MFA 메서드에 대한 자동 생성된 고유 문자열 식별자입니다. 앱은 엔드포인트를 호출할 때 이 id 문자열을 /oauth2/v2.0/challenge 사용합니다.
challenge_type 사용자가 MFA 메서드로 사용할 챌린지 유형이 선택되었습니다. 현재 지원되는 챌린지 유형은 oob입니다.
challenge_channel MFA 메서드가 전송되는 채널의 형식입니다. 현재 지원되는 챌린지 채널은 전자 메일입니다.
login_hint 난독 분석된 전자 메일과 같은 강력한 인증 방법에 대한 힌트입니다.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}

오류 응답

예시:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 요청 매개 변수 유효성 검사에 실패했습니다. 발행한 오류를 이해하려면 오류 설명에 있는 메시지를 사용합니다.
invalid_client 요청에 포함된 클라이언트 ID가 공용 클라이언트용이 아닙니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.
server_error 요청에 문제가 발생했습니다.

클라이언트 앱이 사용자에 대해 등록된 강력한 인증 방법 목록을 성공적으로 검색한 후 사용자는 MFA 챌린지를 완료하는 데 사용할 방법을 선택합니다. 그런 다음 흐름은 다음과 같이 진행합니다.

  1. 클라이언트 앱은 선택한 MFA 메서드와 MFA 메서드에서 /oauth2/v2.0/challenge 가져온 연속 토큰을 호출 /oauth2/v2.0/introspect 하고 id 포함합니다.

    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
&id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
&continuation_token=uY29tL2F1dGhlbnRpY...

  2. Microsoft Entra 이메일과 같은 사용자의 챌린지 채널에 챌린지 코드를 보낸 다음 연속 토큰 및 MFA 챌린지 세부 정보를 사용하여 클라이언트 앱에 다시 응답합니다.

    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
}

  3. 이제 앱은 엔드포인트에 /oauth2/v2.0/token POST 요청을 수행할 수 있으며 연속 토큰, 올바른 권한 부여 형식 및 보안 토큰을 가져오기 위한 해당 권한 부여 형식 값을 포함합니다. 보안 토큰 요청에서 예상 응답을 참조하세요.

    POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded    
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&continuation_token=uY29tL2F1dGhlbnRpY...   
&grant_type=mfa_oob  
&oob={otp_code}
&scope=openid offline_access

강력한 인증 방법 API 참조 등록

네이티브 인증은 강력한 인증 방법의 등록을 지원합니다. 앱이 /oauth2/v2.0/토큰 엔드포인트를 호출하고 MFA가 필요하지만 사용자가 등록한 강력한 메서드가 없는 경우 응답 registeration_required 토큰을 발급하기 전에 사용자에게 등록하도록 앱에 지시합니다.

클라이언트 앱이 강력한 인증 방법을 등록하는 흐름을 완료한 후 엔드포인트를 /oauth2/v2.0/token 호출하여 보안 토큰을 요청합니다.

강력한 인증 방법 등록 엔드포인트

강력한 인증 방법 등록 API를 사용하기 위해 앱은 다음 표에 표시된 엔드포인트를 사용합니다.

엔드포인트 설명
/register/v1.0/introspect 이 엔드포인트를 호출하여 사용자가 등록할 수 있는 강력한 인증 방법 목록을 가져옵니다.
/register/v1.0/challenge 이 엔드포인트를 호출하여 전자 메일 일회용 암호와 같은 챌린지를 사용자에게 보냅니다.
/register/v1.0/continue 이 엔드포인트를 호출하여 앱이 사용자로부터 수집하는 챌린지(예: 일회성 암호)를 제출하여 강력한 인증 방법을 등록하는 흐름을 완료합니다. 호출이 성공하고 연속 토큰을 가져온 후 엔드포인트 엔드포인트를 /oauth2/v2.0/token 호출하여 보안 토큰을 요청합니다. 토큰 엔드포인트를 호출하는 방법을 알아봅니다.

1단계: 강력한 인증 방법 목록 가져오기

등록 흐름은 앱이 사용자가 등록할 수 있는 강력한 인증 방법 목록을 요청할 때 시작됩니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.

성공 응답

다음은 성공적인 업로드의 예입니다.

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
methods 사용자가 등록할 수 있는 강력한 인증 방법의 목록(개체)입니다.

강력한 인증 방법 개체에는 다음과 같은 속성이 있습니다.

재산 설명
id 메서드의 문자열 키입니다. 지원되는 값 은 이메일, sms입니다.
challenge_type 사용자가 MFA 메서드로 사용할 챌린지 유형이 선택되었습니다. 현재 지원되는 챌린지 유형은 oob입니다.
challenge_channel MFA 메서드가 전송되는 채널의 형식입니다. 지원되는 값 은 이메일, sms입니다.
login_hint 전자 메일과 같은 강력한 인증 방법에 대한 힌트입니다. 이 값은 클라이언트 앱에서 전자 메일 텍스트 상자를 미리 채우기 위해 사용됩니다.

오류 응답

예시:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않거나 외부 테넌트 관리자가 모든 테넌트 사용자에 대해 메일 OTP를 사용하도록 설정하지 않았습니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.

2단계: 강력한 인증 방법 선택

이 단계에서는 사용자가 등록하려는 강력한 인증 방법을 제출합니다. 그런 다음 Microsoft Entra 사용자에게 이메일 일회용 암호와 같은 챌린지를 보냅니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
continuation_token 예 Microsoft Entra 엔드포인트에서 반환하는 /register/v1.0/introspect
challenge_type 예 인증 방법의 챌린지 유형입니다. 현재 형식은 oob입니다.
challenge_target 예 사용자가 등록하려는 전자 메일 또는 전화 번호입니다.
challenge_channel 아니요 챌린지를 보낼 채널입니다. 지원되는 챌린지 채널 값: 이메일, sms.

성공 응답

다음은 성공적인 응답의 예입니다.

예제 1:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
}

예 2:

등록 흐름이 강력한 인증 방법 등록 흐름 앞에 있고 엔드포인트에 /register/v1.0/challenge 제출된 전자 메일이 등록 흐름에서 확인된 것과 일치하는 경우 네이티브 인증 API는 사용자에게 챌린지를 보내지 않고 메서드를 등록합니다. 이 경우 응답은 다음 코드 조각과 유사하게 표시됩니다.

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
challenge_type oob과 같이 인증할 사용자를 위해 선택된 챌린지 유형 또는 강력한 인증 방법이 미리 정해진 경우 미리 정해진 챌린지 유형입니다.
binding_method 유일한 유효한 값은 프롬프트입니다. 이 매개 변수는 향후 사용자에게 일회용 암호를 입력하는 더 많은 방법을 제공하는 데 사용될 수 있습니다. challenge_type이고 강력한 인증 방법이 미리 정해지지 않은 경우 발급됩니다.
challenge_channel 일회용 암호가 전송된 채널의 형식입니다. 지원되는 값 은 이메일, sms입니다. 강력한 인증 방법이 미리 정해지지 않은 경우 반환됩니다.
code_length 프롬프트인 경우 binding_method 일회성 암호의 길이입니다. 강력한 인증 방법이 미리 정해지지 않은 경우 반환됩니다.
challenge_target 챌린지가 전송된 대상입니다. 이는 요청에 제공된 입력과 동일합니다. 강력한 인증 방법이 미리 정해지지 않은 경우 반환됩니다.
interval 클라이언트가 /register/continue의 폴링 사이에 대기해야 하는 간격(초)입니다. 강력한 인증 방법이 미리 정해지지 않은 경우에만 prompt=none 반환됩니다. 클라이언트는 네이티브 인증 API에서 받을 때마다 간격을 HTTP 429 두 배로 설정해야 합니다.

오류 응답

여기서 발생하는 오류는 엔드포인트를 호출할 때 발생할 수 있는 오류와 /register/v1.0/introspect 유사합니다. 그러나 전화 번호를 등록할 때 전화 번호가 위험 수준이 높은 것으로 간주되는 경우 요청이 차단될 수 있습니다.

요청이 차단된 경우 발생할 수 있는 오류는 다음과 같습니다.

오류 값 설명
access_denied SMS가 차단되었습니다.

오류 매개 변수의 값이 access_denied이면 Microsoft Entra 응답에 하위 서버 속성을 포함합니다. 다음은 invalid_grant 오류에 대한 하위 오류 속성의 가능한 값입니다.

하위 오류 값 설명
provider_blocked_by_admin 테넌트 관리자가 전화 지역을 차단했습니다.
provider_blocked_by_rep 다단계 인증 방법이 차단되었습니다(전화 번호가 RepMap에 의해 차단됨).

3단계: 챌린지 제출

이 단계에서는 엔드포인트를 호출하여 /register/v1.0/continue 강력한 인증 방법의 등록을 완료합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&grant_type=oob  
&oob={otp_code}
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
grant_type 예 부여 유형입니다. 현재 지원되는 값은 oob이거나, 강력한 인증 방법이 엔드포인트에서 미리 제공되는 경우 /register/v1.0/challenge.
oob 아니요 고객 사용자가 메일에서 받은 일회용 암호입니다. {otp_code}를 고객 사용자가 메일로 받은 일회용 암호 값으로 바꿉니다. 일회용 암호를 다시 보내려면 앱이 /register/v1.0/challenge 엔드포인트에 다시 요청해야 합니다. 엔드포인트에서 /register/v1.0/challenge 강력한 인증 방법을 미리 지정하지 않은 경우 필요합니다.

성공 응답

다음은 성공적인 업로드의 예입니다.

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰입니다. 이 연속 토큰을 사용하여 엔드포인트를 /oauth2/v2.0/token 호출하여 보안 토큰을 요청합니다. 토큰 엔드포인트를 호출하는 방법을 알아봅니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않거나 외부 테넌트 관리자가 모든 테넌트 사용자에 대해 메일 OTP를 사용하도록 설정하지 않았습니다.
invalid_grant 요청에 포함된 권한 부여 유형이 유효하지 않거나 지원되지 않거나 OTP 값이 올바르지 않습니다.
expired_token 요청에 포함된 연속 토큰이 만료되었습니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
invalid_oob_value 일회용 암호 값이 잘못되었습니다.

SSPR(셀프 서비스 암호 재설정)

기본 인증 방법이 암호가 있는 전자 메일인 사용자의 경우 SSPR(셀프 서비스 암호 재설정) API를 사용하여 고객 사용자가 암호를 재설정할 수 있도록 합니다. 암호를 잊어버리거나 암호 시나리오를 변경하는 데 이 API를 사용할 수 있습니다.

셀프 서비스 비밀번호 재설정을 위한 API 엔드포인트

이 API를 사용하기 위해 앱은 다음 표에 표시된 엔드포인트를 사용합니다.

엔드포인트 설명
/resetpassword/v1.0/start 고객 사용자가 앱에서 암호 찾기 또는 암호 변경 링크나 단추를 선택하면 앱에서 이 엔드포인트를 호출합니다. 이 엔드포인트는 사용자의 사용자 이름(이메일)의 유효성을 검사한 다음 암호 재설정 흐름에서 사용할 연속 토큰 을 반환합니다. 앱이 Microsoft Entra 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다.
/resetpassword/v1.0/challenge 클라이언트와 연속 토큰이 지원하는 챌린지 유형 목록을 허용합니다. 기본 복구 자격 증명 중 하나에 인증 확인이 발급됩니다. 예를 들어, oob 챌린지는 고객 사용자 계정과 연결된 메일에 대해 대역 외 일회용 암호를 발급합니다. 앱이 Microsoft Entra 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다.
/resetpassword/v1.0/continue /resetpassword/v1.0/challenge 엔드포인트에서 발급한 챌린지의 유효성을 검사한 후 엔드포인트에 대한 /resetpassword/v1.0/submit을 반환하거나 사용자에게 다른 챌린지를 발급합니다.
/resetpassword/v1.0/submit 암호 재설정 흐름을 완료하기 위해 연속 토큰과 함께 사용자가 입력한 새 암호를 수락합니다. 이 엔드포인트는 또 다른 연속 토큰을 발급합니다.
/resetpassword/v1.0/poll_completion 앱은 엔드포인트에서 발급한 연속 토큰 을 /resetpassword/v1.0/submit 사용하여 암호 재설정 요청의 상태를 확인할 수 있습니다.
oauth2/v2.0/token 암호 재설정에 성공하면 앱은 엔드포인트에서 가져온 연속 토큰을 사용하여 엔드포인트에서 /resetpassword/v1.0/poll_completionoauth2/v2.0/token 보안 토큰을 가져올 수 있습니다.

셀프 서비스 암호 재설정 챌린지 유형

API를 사용하면 앱이 Microsoft Entra 호출할 때 지원하는 인증 방법을 보급할 수 있습니다. 이를 위해 앱은 요청에 challenge_type 매개 변수를 사용합니다. 이 매개 변수는 서로 다른 인증 방법을 나타내는 미리 정의된 값을 보유합니다.

SSPR 흐름의 경우 챌린지 유형 값은 oob 및 redirect입니다.

기본 인증 챌린지 유형에서 챌린지 유형에 대해 자세히 알아봅니다.

셀프 서비스 암호 재설정 흐름 프로토콜 세부 정보

시퀀스 다이어그램은 암호 재설정 프로세스의 흐름을 보여 줍니다.

기본 인증 셀프 서비스 암호 재설정 흐름 다이어그램.

이 다이어그램은 앱이 서로 다른 시간에(별도의 화면에서) 사용자로부터 사용자 이름(메일)과 암호를 수집한다는 것을 나타냅니다. 그러나 동일한 화면에서 사용자 이름(메일)과 새 암호를 수집하도록 앱을 설계할 수 있습니다. 이 경우 앱은 암호를 보유하고 있으며 필요한 경우 /resetpassword/v1.0/submit 엔드포인트를 통해 암호를 제출합니다.

1단계: 셀프 서비스 암호 재설정 흐름 시작 요청

암호 재설정 흐름은 앱이 셀프 서비스 암호 재설정 흐름을 시작하기 위해 /resetpassword/v1.0/start 엔드포인트에 POST 요청을 하는 것으로 시작됩니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
username 예 고객 사용자의 메일입니다(예: contoso-consumer@contoso.com).
challenge_type 예 와 같이 앱이 지원하는 권한 부여 oob password redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 이 요청의 경우 값은 oob redirect를 포함해야 합니다.
capabilities 아니요 클라이언트 앱의 "방법" 준비 상태를 설명하는 공간으로 구분된 플래그입니다. 챌린지 challenge_type 할 수 있는 메서드를 정의하는 동안 capabilities 클라이언트 앱이 처리할 수 있는 추가 흐름과 표시할 수 있는 UI를 네이티브 인증 API에 알릴 수 있습니다. 예를 들어 mfa_required 다른 /challenge 루프와 루프 /token 를 의미합니다registration_required. 즉, 클라이언트 앱이 등록 API를 호출하고 등록 UI를 표시합니다. 필요한 접근 권한 값이 클라이언트 앱에서 보급되지 않으면 API는 리디렉션을 반환합니다. 지원되는 값은 mfa_requiredregistration_required. 기능에 대해 자세히 알아봅니다.

성공 응답

예시:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request challenge_type 매개 변수에 잘못된 챌린지 유형이 포함되어 있거나 요청에 client_id 매개 변수가 포함되지 않았거나, 클라이언트 ID 값이 비어 있거나 유효하지 않은 경우와 같이 요청 매개 변수 유효성 검사에 실패했습니다. error_description 매개 변수를 사용하여 정확한 오류 원인을 알아봅니다.
user_not_found 사용자 이름이 존재하지 않습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.
invalid_client 앱이 요청에 포함하는 클라이언트 ID는 공용 클라이언트가 아니거나 기본 인증이 사용하도록 설정되지 않은 등 기본 인증 구성이 부족한 앱을 위한 것입니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
unauthorized_client 요청에 사용된 클라이언트 ID는 유효한 클라이언트 ID 유형을 가지고 있지만 외부 테넌트에 존재하지 않거나 올바르지 않습니다.

오류 매개 변수의 값이 invalid_client이면 Microsoft Entra 응답에 suberror 속성을 포함합니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
nativeauthapi_disabled 네이티브 인증에 사용하도록 설정되지 않은 앱의 클라이언트 ID입니다.

2단계: 인증 방법 선택

흐름을 계속하기 위해 앱은 이전 단계에서 획득한 연속 토큰을 사용하여 사용자가 인증할 지원되는 챌린지 유형 중 하나를 선택하도록 Microsoft Entra 요청합니다. 앱이 /resetpassword/v1.0/challenge 엔드포인트에 POST 요청을 보냅니다. 이 요청이 성공하면 Microsoft Entra 사용자의 계정 전자 메일에 일회성 암호를 보냅니다. 현재는 메일 OTP만 지원됩니다.

다음은 예입니다(가독성을 위해 예 요청을 여러 줄로 표시합니다).

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
challenge_type 아니요 와 같이 앱이 지원하는 권한 부여 oob redirect 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 이 요청의 경우 값은 oob redirect를 포함해야 합니다.

성공 응답

예시:

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
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
challenge_type 사용자가 인증할 수 있도록 선택된 챌린지 유형입니다.
binding_method 유일한 유효한 값은 프롬프트입니다. 이 매개 변수는 향후 사용자에게 일회용 암호를 입력하는 더 많은 방법을 제공하는 데 사용될 수 있습니다. challenge_type이 oob인 경우 발급됩니다.
challenge_channel 일회용 암호가 전송된 채널의 형식입니다. 현재는 메일을 지원합니다.
challenge_target_label 일회용 암호를 보낸 난독 처리된 메일입니다. 사용자에 대해 MFA를 사용하도록 설정하면 일회성 암호가 포함된 전자 메일이 다음으로 전송됩니다.
- 전자 메일 주소가 계정 전자 메일 주소와 다른 경우 강력한 인증 방법으로 사용되는 전자 메일 주소입니다.
- 강력한 인증 방법이 SMS인 경우 계정 전자 메일 주소입니다.
code_length Microsoft Entra 생성하는 일회성 암호의 길이입니다.

리디렉션 응답

클라이언트 앱이 Microsoft Entra 필요한 인증 방법 또는 기능을 지원하지 않는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서 Microsoft Entra 응답에서 redirect 챌린지 형식을 반환하여 앱에 알릴 수 있습니다.

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

{     
   "challenge_type": "redirect" 
}
재산 설명
challenge_type Microsoft Entra 챌린지 유형이 있는 응답을 반환합니다. 이 챌린지 유형의 값은 앱이 웹 기반 인증 흐름을 사용할 수 있도록 하는 리디렉션입니다.

이 응답은 성공한 것으로 간주되지만 앱이 웹 기반 인증 흐름으로 전환해야 합니다. 이 경우 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하는 것이 좋습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request challenge_type 매개 변수에 잘못된 챌린지 유형이 포함되거나 연속 토큰 유효성 검사가 실패한 경우와 같이 요청 매개 변수 유효성 검사에 실패했습니다.
expired_token 연속 토큰이 만료되었습니다.
unsupported_challenge_type challenge_type 매개 변수 값에는 redirect 챌린지 유형이 포함되지 않습니다.

3단계: 일회용 암호 제출

그런 다음 앱은 /resetpassword/v1.0/continue 엔드포인트에 POST 요청을 보냅니다. 요청에서 앱은 이전 단계에서 선택한 사용자의 자격 증명과 /resetpassword/v1.0/challenge 엔드포인트에서 발급된 연속 토큰을 포함해야 합니다.

다음은 요청의 예입니다(가독성을 위해 여러 줄로 예제 요청을 표시합니다.)

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}
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
grant_type 예 유일한 유효한 값은 oob입니다.
oob 예 고객 사용자가 메일에서 받은 일회용 암호입니다. {otp_code}를 고객 사용자가 메일로 받은 일회용 암호로 바꿉니다. 일회용 암호를 다시 보내려면 앱이 /resetpassword/v1.0/challenge 엔드포인트에 다시 요청해야 합니다.

성공 응답

예시:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
}
재산 설명
expires_in continuation_token이 만료되기까지의 시간(초)입니다. expires_in의 최댓값은 600초입니다.
continuation_token Microsoft Entra 반환하는 지속 토큰.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않거나 외부 테넌트 관리자가 모든 테넌트 사용자에 대해 SSPR 및 메일 OTP를 사용하도록 설정하지 않았습니다. error_description 매개 변수를 사용하여 정확한 오류 원인을 알아봅니다.
invalid_grant 권한 부여 유형을 알 수 없거나 예상 권한 부여 유형 값과 일치하지 않습니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.
expired_token 연속 토큰이 만료되었습니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. suberror 오류에 대한 속성의 가능한 값입니다.

하위 오류 값 설명
invalid_oob_value 일회용 암호 값이 잘못되었습니다.

4단계: 새 암호 제출

앱은 사용자로부터 새 암호를 수집한 다음 엔드포인트에서 발급한 /resetpassword/v1.0/continue을 사용하여 /resetpassword/v1.0/submit 엔드포인트에 POST 요청을 수행하여 암호를 제출합니다.

다음은 예입니다(가독성을 위해 예 요청을 여러 줄로 표시합니다).

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}
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.
new_password 예 사용자의 새 암호. {new_password}를 사용자의 새 암호로 바꿉니다. 앱 UI에 암호 확인 필드를 제공하여 사용자가 사용하려는 암호를 알고 있는지 확인하는 것은 사용자의 책임입니다. 또한 사용자가 조직의 정책에 따라 강력한 암호를 구성하는 것을 알고 있는지 확인해야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.

성공 응답

예시:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}
재산 설명
continuation_token Microsoft Entra 반환하는 지속 토큰.
poll_interval 앱이 /resetpassword/v1.0/poll_completion 엔드포인트를 통해 암호 재설정 요청 상태를 확인하기 위해 폴링 요청 사이에 기다려야 하는 최소 시간(초)입니다. 5단계를 참조하세요.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
suberror 오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했습니다.
expired_token 연속 토큰이 만료되었습니다.
invalid_grant 제출된 암호가 너무 짧아서 제출된 권한 부여가 유효하지 않습니다. suberror 이 속성을 사용하여 오류의 정확한 원인을 알아봅니다.

오류 매개 변수의 값이 invalid_grant이면 Microsoft Entra 응답에 suberror 속성이 포함됩니다. 속성의 가능한 값은 suberror 다음과 같습니다.

하위 오류 값 설명
password_too_weak 암호는 복잡성 요구 사항을 충족하지 않으므로 너무 약합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_too_short 새 암호는 8자 미만입니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_too_long 새 암호가 256자보다 깁니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_recently_used 새 암호는 최근에 사용한 암호와 동일하지 않아야 합니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_banned 새 암호에 금지된 단어, 구 또는 패턴이 포함되어 있습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요.
password_is_invalid 예를 들어, 허용되지 않는 문자를 사용하고 있기 때문에 암호가 유효하지 않습니다. Microsoft Entra 암호 정책 대해 자세히 알아보세요. 앱이 사용자 암호를 제출하는 경우 이 응답이 가능합니다.

5단계: 암호 재설정 상태 폴링

마지막으로, 새 암호로 사용자 구성을 업데이트하면 약간의 지연이 발생하므로 앱은 /resetpassword/v1.0/poll_completion 엔드포인트를 사용하여 암호 재설정 상태에 대한 Microsoft Entra 폴링할 수 있습니다. 앱이 폴링 요청 사이에 기다려야 하는 최소 시간(초)은 /resetpassword/v1.0/submit 매개 변수의 poll_interval 엔드포인트에서 반환됩니다.

다음은 예입니다(가독성을 위해 예 요청을 여러 줄로 표시합니다).

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...
매개 변수 필수 설명
tenant_subdomain 예 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다.
continuation_token 예 이전 요청에서 반환된 Microsoft Entra 지속 토큰.
client_id 예 Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다.

성공 응답

예시:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}
재산 설명
status 암호 초기화 요청 상태입니다. Microsoft Entra failed 상태를 반환하는 경우 앱은 /resetpassword/v1.0/submit 엔드포인트에 다른 요청을 수행하여 새 암호를 다시 제출하고 새 연속 토큰을 포함할 수 있습니다.
continuation_token Microsoft Entra 반환하는 지속 토큰. 상태가 succeeded이면 앱은 Microsoft Entra 반환하는 연속 토큰을 사용하여 oauth2/v2.0/token 설명한 대로 엔드포인트를 통해 보안 토큰을 요청할 수 있습니다. 즉, 사용자가 암호를 성공적으로 다시 설정한 후에는 새로운 로그인 흐름을 시작하지 않고도 해당 사용자를 앱에 직접 로그인할 수 있습니다.

다음은 Microsoft Entra 반환할 수 있는 상태(status 매개 변수의 가능한 값)입니다.

오류 값 설명
succeeded 암호 재설정이 성공적으로 완료되었습니다.
failed 암호 재설정에 실패했습니다. 앱은 /resetpassword/v1.0/submit 엔드포인트에 또 다른 요청을 하여 새 암호를 다시 제출할 수 있습니다.
not_started 암호 재설정이 시작되지 않았습니다. 앱은 나중에 상태를 다시 확인할 수 있습니다.
in_progress 암호 재설정이 진행 중입니다. 앱은 나중에 상태를 다시 확인할 수 있습니다.

오류 응답

예시:

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"
}
재산 설명
error 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
error_description 인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다.
error_codes 오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다.
timestamp 오류가 발생한 시간입니다.
trace_id 오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다.
correlation_id 여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다.

발생할 수 있는 오류(속성의 error 가능한 값)는 다음과 같습니다.

오류 값 설명
invalid_request 연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했습니다.
expired_token 연속 토큰이 만료되었습니다.

암호 재설정 후 자동으로 로그인

암호 재설정에 성공한 후 사용자가 로그인해야 하는 경우 앱은 엔드포인트를 /oauth2/v2.0/token 호출해야 합니다. 토큰 엔드포인트를 호출하는 방법을 알아봅니다.

관련 콘텐츠

  • Last updated on