기본 인증 API 참조
적용 대상: 
인력 테넌트 
외부 테넌트(자세한 정보)
Microsoft Entra의 기본 인증을 사용하면 브라우저에 인증을 위임하는 대신 클라이언트 애플리케이션에서 앱의 사용자 인터페이스를 호스팅할 수 있으므로 기본적으로 통합된 인증 환경을 경험할 수 있습니다. 개발자는 로그인 인터페이스의 모양과 느낌을 완전히 제어할 수 있습니다.
이 API 참조 문서에서는 흐름을 실행하기 위해 원시 HTTP 요청을 수동으로 만드는 경우에만 필요한 세부 정보를 설명합니다. 그러나 이 방식은 권장되지 않습니다. 따라서 가능하면 Microsoft에서 빌드하고 지원하는 인증 SDK를 사용합니다. SDK 사용 방법에 대한 자세한 내용은 자습서: 기본 인증을 위해 Android 모바일 앱 준비 및 자습서: 기본 인증을 위해 iOS/macOS 모바일 앱 준비를 참조하세요.
API 끝점에 대한 호출이 성공하면 사용자 식별을 위한 ID 토큰과 보호된 API 호출을 위한 액세스 토큰을 모두 받게 됩니다. API의 모든 응답은 JSON 형식입니다.
Microsoft Entra의 기본 인증 API는 두 가지 인증 방법에 대한 등록 및 로그인을 지원합니다.
암호가 포함된 메일 - 메일과 암호를 사용한 등록 및 로그인, SSPR(셀프 서비스 암호 재설정)을 지원합니다.
메일 일회용 암호 - 메일 일회용 암호로 등록 및 로그인을 지원합니다.
참고 항목
현재 기본 인증 API 엔드포인트는 CORS(원본 간 리소스 공유)를 지원하지 않습니다.
필수 조건
Microsoft Entra 외부 테넌트입니다. 아직 외부 테넌트가 없다면 외부 테넌트를 생성하세요.
아직 등록하지 않았다면 Microsoft Entra 관리 센터에 응용 프로그램을 등록합니다. 위임된 권한을 부여하고 공용 클라이언트 및 기본 인증 흐름을 사용하도록 설정해야 합니다.
아직 수행하지 않은 경우 Microsoft Entra 관리 센터에서 사용자 흐름을 만듭니다. 사용자 흐름을 만드는 경우 필요한 사용자 특성을 구성해야 한다는 점을 기록해 둡니다. 이러한 특성은 Microsoft Entra가 앱에서 제출할 것으로 예상하는 특성이기 때문입니다.
로그인 흐름의 경우 로그인 API 테스트에 사용하는 고객 사용자를 등록합니다. 또는 등록 흐름을 실행한 후 이 테스트 사용자를 가져올 수 있습니다.
SSPR 흐름의 경우 고객 테넌트의 고객 사용자에 대해 셀프 서비스 암호 재설정을 사용합니다. SSPR은 암호 인증 방법으로 이메일을 사용하는 고객 사용자에게 제공됩니다.
연속 토큰
흐름, 로그인, 등록 또는 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에서 지원하는 챌린지 유형 목록을 사용하여 이 엔드포인트를 호출합니다. 그런 다음 Microsoft Entra는 사용자가 인증할 수 있도록 지원되는 인증 방법 중 하나를 선택합니다. |
/signup/v1.0/continue |
이 엔드포인트는 사용자 계정을 만드는 흐름을 계속하거나 암호 정책 요구 사항이나 잘못된 특성 형식과 같은 요구 사항 누락으로 인해 흐름을 중단하는 데 도움이 됩니다. 이 엔드포인트는 연속 토큰을 생성한 다음 이를 앱에 반환합니다. 엔드포인트는 애플리케이션이 Microsoft Entra에서 선택한 인증 방법이 아닌 경우 웹 기반 인증 흐름을 사용하도록 애플리케이션에 나타내기 위해 응답을 반환할 수 있습니다. |
/token |
애플리케이션은 이 엔드포인트를 호출하여 최종적으로 보안 토큰을 요청합니다. 앱은 /signup/v1.0/continue 엔드포인트에 대한 마지막 성공적인 호출에서 획득한 연속 토큰을 포함해야 합니다. |
등록 챌린지 유형
API를 사용하면 클라이언트 앱이 Microsoft Entra를 호출할 때 지원하는 인증 방법을 보급할 수 있습니다. 이를 위해 앱은 앱 요청에 challenge_type 매개 변수를 사용합니다. 이 매개 변수는 서로 다른 인증 방법을 나타내는 미리 정의된 값을 보유합니다.
기본 인증 챌린지 유형에서 챌린지 유형에 대해 자세히 알아봅니다. 이 문서에서는 인증 방법에 대해 수행해야 하는 챌린지 유형 값을 설명합니다.
등록 흐름 프로토콜 세부 정보
시퀀스 다이어그램은 등록 프로세스의 흐름을 보여 줍니다.
이 다이어그램은 앱이 서로 다른 시간에(별도의 화면에서) 사용자로부터 사용자 이름(메일), 암호(암호 인증 방법을 사용하는 메일의 경우), 특성을 수집한다는 것을 나타냅니다. 그러나 동일한 화면에서 사용자 이름(메일), 암호, 모든 필수 및 선택적 특성 값을 수집한 다음 /signup/v1.0/start 엔드포인트를 통해 모두 제출하도록 앱을 설계할 수 있습니다. 이 경우 앱은 전화를 걸고 선택적 단계에 대한 응답을 처리할 필요가 없습니다.
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는 사용자가 제출하지만 존재하지 않는 특성은 무시합니다. |
성공 응답
다음은 성공적인 업로드의 예입니다.
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 |
유효성 검사에 실패한 특성의 목록(개체 배열)입니다. 이 응답은 앱이 사용자 특성을 제출하고 suberror 매개 변수의 값이 attribute_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 매개 변수를 포함합니다. invalid_grant 오류에 대한 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 매개 변수를 포함합니다. invalid_client 오류에 대한 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는 사용자의 메일로 일회용 암호를 보낸 다음 oob 값과 일회용 암호에 대한 추가 정보가 포함된 챌린지 유형으로 응답합니다.
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에서 연속 토큰을 발급합니다. 앱은 5단계에 표시된 대로 연속 토큰을 사용하여 보안 토큰을 요청할 수 있습니다. |
앱은 /signup/v1.0/start를 통해 사용자의 암호(암호 인증 방법을 포함하는 메일의 경우)를 성공적으로 제출하지만, 일부 필수 사용자 특성은 제출하지 않으며, Microsoft Entra는 필요한 사용자 특성에 표시된 대로 앱이 제출해야 하는 특성을 나타냅니다. |
앱은 /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 매개 변수를 포함합니다. invalid_grant 오류에 대한 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 엔드포인트를 통해 제출된 경우 앱은 특성을 제출하지 않고 연속 토큰을 가져옵니다. 앱은 5단계에 표시된 대로 연속 토큰을 사용하여 보안 토큰을 요청할 수 있습니다. 그렇지 않으면 Microsoft Entra의 응답은 앱이 필수 특성을 제출해야 함을 나타냅니다. 기본 제공 또는 사용자 지정 특성은 테넌트 관리자가 Microsoft Entra 관리 센터에서 구성했습니다.
필요한 사용자 특성
이 응답은 앱이 name, *age 및 phone 특성에 대한 값을 제출하도록 요청합니다.
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}", "postaCode": "{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는 앱이 보안 토큰을 요청하는 데 사용할 수 있는 연속 토큰을 발급합니다.
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 매개 변수 값이 attribute_validation_failed인 경우 응답에 포함됩니다. |
suberror |
오류 형식을 추가로 분류하는 데 사용할 수 있는 오류 코드 문자열입니다. |
발생할 수 있는 오류(error 매개 변수의 가능한 값)는 다음과 같습니다.
| 오류 값 | 설명 |
|---|---|
invalid_request |
연속 토큰 유효성 검사 실패와 같이 요청 매개 변수 유효성 검사에 실패했거나 요청에 client_id 매개 변수가 포함되지 않았거나 클라이언트 ID 값이 비어 있거나 유효하지 않습니다. |
invalid_grant |
제공된 권한 부여 유형이 유효하지 않거나 지원되지 않거나 유효성 검사에 실패했습니다(예: 특성 유효성 검사 실패). suberror 매개 변수를 사용하여 정확한 오류 원인을 알아봅니다. |
expired_token |
요청에 포함된 연속 토큰이 만료되었습니다. |
attributes_required |
하나 이상의 사용자 특성이 필요합니다. |
오류 매개 변수의 값이 invalid_grant인 경우 Microsoft Entra는 응답에 suberror 매개 변수를 포함합니다. invalid_grant 오류에 대한 suberror 매개 변수의 가능한 값은 다음과 같습니다.
| 하위 오류 값 | 설명 |
|---|---|
attribute_validation_failed |
사용자 특성 유효성 검사에 실패했습니다. invalid_attributes 매개 변수에는 유효성 검사에 실패한 특성의 목록(개체 배열)이 포함되어 있습니다. |
5단계: 보안 토큰 요청
앱은 /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=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| 매개 변수 | 필수 | 설명 |
|---|---|---|
tenant_subdomain |
예 | 만든 외부 테넌트의 하위 도메인입니다. URL에서 {tenant_subdomain}을 디렉터리(테넌트) 하위 도메인으로 바꿉니다. 예를 들어, 테넌트의 기본 도메인이 contoso.onmicrosoft.com인 경우 contoso를 사용합니다. 테넌트 하위 도메인이 없는 경우 테넌트 세부 정보를 읽는 방법을 알아봅니다. |
client_id |
예 | Microsoft Entra 관리 센터에 등록한 앱의 애플리케이션(클라이언트) ID입니다. |
grant_type |
예 | 매개 변수 값은 연속 토큰이어야 합니다. |
continuation_token |
예 | 이전 단계에서 Microsoft Entra가 반환한 연속 토큰입니다. |
scope |
예 | 액세스 토큰이 유효한 범위의 공백으로 구분된 목록입니다. {scopes}를 Microsoft Entra가 반환하는 액세스 토큰이 유효한 범위로 바꿉니다. |
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..."
}
| 매개 변수 | 설명 |
|---|---|
access_token |
앱이 /token 엔드포인트에서 요청한 액세스 토큰입니다. 앱은 이 액세스 토큰을 사용하여 웹 API와 같은 보안 리소스에 대한 액세스를 요청할 수 있습니다. |
token_type |
토큰 형식 값을 나타냅니다. Microsoft Entra가 지원하는 유일한 형식은 전달자입니다. |
expires_in |
액세스 토큰이 유효한 상태로 유지되는 시간(초)입니다. |
scopes |
액세스 토큰이 유효한 범위의 공백으로 구분된 목록입니다. |
refresh_token |
OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 다른 액세스 토큰을 획득할 수 있습니다. 새로 고침 토큰은 장기적으로 존재합니다. 오랜 기간 동안 리소스에 대한 액세스를 유지할 수 있습니다. 액세스 토큰 새로 고침에 대한 자세한 내용은 액세스 토큰 새로 고침 문서를 참조하세요. 참고: offline_access 범위가 요청된 경우에만 발급됩니다. |
id_token |
고객 사용자를 식별하는 데 사용되는 Jwt(JSON Web Token)입니다. 앱은 토큰을 디코딩하여 로그인한 사용자에 대한 정보를 읽을 수 있습니다. 앱은 값을 캐시하고 표시할 수 있으며 기밀 클라이언트는 권한 부여에 이 토큰을 사용할 수 있습니다. ID 토큰에 대한 자세한 내용은 ID 토큰을 참조하세요. 참고: openid 범위가 요청된 경우에만 발급됩니다. |
오류 응답
예시:
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"
}
| 매개 변수 | 설명 |
|---|---|
error |
오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
인증 오류의 원인을 식별하는 데 도움이 될 수 있는 특정 오류 메시지입니다. |
error_codes |
오류를 진단하는 데 도움이 될 수 있는 Microsoft Entra 관련 오류 코드 목록입니다. |
timestamp |
오류가 발생한 시간입니다. |
trace_id |
오류를 진단하는 데 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
correlation_id |
여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
발생할 수 있는 오류(error 매개 변수의 가능한 값)는 다음과 같습니다.
| 오류 값 | 설명 |
|---|---|
invalid_request |
클라이언트/앱에 요청된 범위에 대한 동의가 없기 때문에 요청 매개 변수 유효성 검사에 실패했습니다. |
invalid_grant |
요청에 포함된 연속 토큰이 잘못되었습니다. |
unauthorized_client |
요청에 포함된 클라이언트 ID가 잘못되었거나 존재하지 않습니다. |
unsupported_grant_type |
요청에 포함된 권한 부여 유형이 지원되지 않거나 올바르지 않습니다. |
엔드포인트에 사용자 특성 제출
Microsoft Entra 관리 센터에서는 사용자 특성을 필수 또는 선택 사항으로 구성할 수 있습니다. 이 구성은 엔드포인트를 호출할 때 Microsoft Entra가 응답하는 방식을 결정합니다. 선택 특성은 등록 흐름을 완료하는 데 필수가 아닙니다. 따라서 모든 특성이 선택 사항인 경우 사용자 이름을 확인하기 전에 제출해야 합니다. 그렇지 않으면 선택적 특성 없이 등록이 완료됩니다.
다음 표에는 Microsoft Entra 엔드포인트에 사용자 특성을 제출할 수 있는 경우가 요약되어 있습니다.
| 엔드포인트 | 필수 특성 | 선택적 특성 | 필수 특성과 선택 특성 모두 |
|---|---|---|---|
/signup/v1.0/start 엔드포인트 |
예 | 예 | 예 |
사용자 이름 확인 전 /signup/v1.0/continue 엔드포인트 |
예 | 예 | 예 |
사용자 이름 확인 후 /signup/v1.0/continue 엔드포인트 |
예 | 아니요 | 예 |
사용자 특성 값의 형식
Microsoft Entra 관리 센터에서 사용자 흐름 설정을 구성하여 사용자로부터 수집하려는 정보를 지정합니다. 기본 제공 특성과 사용자 지정 특성 모두에 대한 값을 수집하는 방법을 알아보려면 등록 시 사용자 지정 사용자 특성 수집 문서를 참조하세요.
구성하는 특성에 대해 사용자 입력 형식을 지정할 수도 있습니다. 다음 표에는 지원되는 사용자 입력 형식과 UI 컨트롤에서 수집한 값을 Microsoft Entra에 제출하는 방법이 요약되어 있습니다.
| 사용자 입력 유형 | 제출된 값의 형식 |
|---|---|
| TextBox | 직함, 소프트웨어 엔지니어와 같은 단일 값입니다. |
| SingleRadioSelect | 언어, 노르웨이어와 같은 단일 값입니다. |
| CheckboxMultiSelect | 취미, 춤 또는 춤, 수영, 여행과 같은 하나 이상의 값입니다. |
다음은 특성 값을 제출하는 방법을 보여 주는 요청 예입니다.
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 참조
사용자는 등록을 사용하는 인증 방법으로 로그인해야 합니다. 예를 들어, 암호 인증 방법이 포함된 메일을 사용하여 등록하는 사용자는 메일과 암호로 로그인해야 합니다.
보안 토큰을 요청하기 위해 앱은 세 개의 엔드포인트(/initiate, /challenge 및 /token)와 상호 작용합니다.
로그인 API 엔드포인트
| 엔드포인트 | 설명 |
|---|---|
/initiate |
이 엔드포인트는 로그인 흐름을 시작합니다. 앱이 이미 존재하는 사용자 계정의 사용자 이름으로 이를 호출하면 연속 토큰과 함께 성공 응답을 반환합니다. 앱이 Microsoft Entra에서 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다. |
/challenge |
앱은 ID 서비스에서 지원하는 챌린지 유형 목록을 사용하여 이 엔드포인트를 호출합니다. ID 서비스는 일회용 암호를 생성한 다음 메일과 같이 선택한 챌린지 채널로 보냅니다. 앱이 이 엔드포인트를 반복적으로 호출하는 경우 호출이 이루어질 때마다 새 OTP가 전송됩니다. |
/token |
이 엔드포인트는 앱에서 수신한 일회용 암호를 확인한 다음 앱에 보안 토큰을 발급합니다. |
로그인 챌린지 유형
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
| 매개 변수 | 필수 | 설명 |
|---|---|---|
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여야 합니다. |
성공 응답
다음은 성공적인 업로드의 예입니다.
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 매개 변수를 포함합니다. invalid_client 오류에 대한 suberror 매개 변수의 가능한 값은 다음과 같습니다.
| 하위 오류 값 | 설명 |
|---|---|
nativeauthapi_disabled |
기본 인증이 사용하도록 설정되지 않은 앱의 클라이언트 ID입니다. |
2단계: 인증 방법 선택
흐름을 계속하기 위해 앱은 이전 단계에서 획득한 연속 토큰을 사용하여 사용자가 인증하기 위해 지원되는 챌린지 유형 중 하나를 선택하도록 Microsoft Entra에 요청합니다. 앱이 /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가 반환한 연속 토큰입니다. |
challenge_type |
아니요 | oob password redirect와 같이 앱이 지원하는 권한 부여 챌린지 유형 문자열의 공백으로 구분된 목록입니다. 목록에는 항상 redirect 챌린지 유형이 포함되어야 합니다. 값은 메일 일회용 암호의 경우 oob redirect, 암호가 있는 메일의 경우 password redirect여야 합니다. |
성공 응답
테넌트 관리자가 사용자 인증 방법으로 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에서 필요한 인증 방법을 지원할 수 없는 경우 웹 기반 인증 흐름으로 대체해야 합니다. 이 시나리오에서는 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단계: 보안 토큰 요청
앱은 /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 |
예 | 값은 암호 인증 방법을 포함한 메일의 경우 password이고 메일 일회용 암호 인증의 경우 oob여야 합니다. |
scope |
예 | 공백으로 구분된 범위 목록입니다. 모든 범위는 profile, *openid 및 email과 같은 OIDC(OpenID Connect) 범위와 함께 단일 리소스에서 나와야 합니다. ID 토큰을 발급하려면 앱에 Microsoft Entra의 openid 범위가 포함되어야 합니다. 새로 고침 토큰을 발급하려면 앱에 Microsoft Entra의 offline_access 범위가 포함되어야 합니다. Microsoft ID 플랫폼의 권한 및 동의에 대해 자세히 알아봅니다. |
password |
예 (암호가 있는 메일인 경우) |
앱이 고객 사용자로부터 수집하는 암호 값입니다. {secure_password}를 앱이 고객 사용자로부터 수집하는 암호 값으로 바꿉니다. |
oob |
예 (메일 일회용 암호인 경우) |
고객 사용자가 메일에서 받은 일회용 암호입니다. {otp_code}를 고객 사용자가 메일로 받은 일회용 암호로 바꿉니다. 일회용 암호를 다시 보내려면 앱이 /challenge 엔드포인트에 다시 요청해야 합니다. |
성공적인 응답
다음은 성공적인 업로드의 예입니다.
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가 지원하는 유일한 형식은 전달자입니다. |
scopes |
액세스 토큰이 유효한 범위의 공백으로 구분된 목록입니다. |
expires_in |
액세스 토큰이 유효한 상태로 유지되는 시간(초)입니다. |
access_token |
앱이 /token 엔드포인트에서 요청한 액세스 토큰입니다. 앱은 이 액세스 토큰을 사용하여 웹 API와 같은 보안 리소스에 대한 액세스를 요청할 수 있습니다. |
refresh_token |
OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 다른 액세스 토큰을 획득할 수 있습니다. 새로 고침 토큰은 장기적으로 존재합니다. 오랜 기간 동안 리소스에 대한 액세스를 유지할 수 있습니다. 액세스 토큰 새로 고침에 대한 자세한 내용은 액세스 토큰 새로 고침 문서를 참조하세요. 참고: offline_access 범위를 요청하는 경우에만 발급됩니다. |
id_token |
고객 사용자를 식별하는 데 사용되는 Jwt(JSON Web Token)입니다. 앱은 토큰을 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱은 값을 캐시하고 표시할 수 있으며 기밀 클라이언트는 권한 부여에 이 토큰을 사용할 수 있습니다. 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 |
요청에 포함된 범위 중 하나 이상이 잘못되었습니다. |
오류 매개 변수가 invalid_grant의 값을 가질 경우 Microsoft Entra는 해당 응답에 suberror 매개 변수를 포함합니다. invalid_grant 오류에 대한 suberror 매개 변수의 가능한 값은 다음과 같습니다.
| 하위 오류 값 | 설명 |
|---|---|
invalid_oob_value |
일회용 암호 값이 잘못되었습니다. 이 하위 오류는 메일 일회용 암호만 적용합니다. |
SSPR(셀프 서비스 암호 재설정)
앱에서 인증 방법으로 메일과 암호를 사용하는 경우 SSPR(셀프 서비스 암호 재설정) API를 사용하여 고객 사용자가 암호를 다시 설정할 수 있도록 합니다. 암호를 잊어버렸거나 암호를 변경하는 경우 이 API를 사용합니다.
셀프 서비스 암호 재설정 API 엔드포인트
이 API를 사용하기 위해 앱은 다음 표에 표시된 엔드포인트와 상호 작용합니다.
| 엔드포인트 | 설명 |
|---|---|
/start |
고객 사용자가 앱에서 암호 찾기 또는 암호 변경 링크나 단추를 선택하면 앱에서 이 엔드포인트를 호출합니다. 이 엔드포인트는 사용자의 사용자 이름(메일)의 유효성을 검사한 다음 암호 재설정 흐름에 사용할 연속 토큰을 반환합니다. 앱이 Microsoft Entra에서 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다. |
/challenge |
클라이언트와 연속 토큰이 지원하는 챌린지 유형 목록을 허용합니다. 기본 복구 자격 증명 중 하나에 인증 확인이 발급됩니다. 예를 들어, oob 챌린지는 고객 사용자 계정과 연결된 메일에 대해 대역 외 일회용 암호를 발급합니다. 앱이 Microsoft Entra에서 지원하지 않는 인증 방법을 사용하도록 요청하는 경우 이 엔드포인트 응답은 브라우저 기반 인증 흐름을 사용해야 함을 앱에 나타낼 수 있습니다. |
/continue |
/challenge 엔드포인트에서 발급한 챌린지의 유효성을 검사한 후 /submit 엔드포인트에 대한 연속 토큰을 반환하거나 사용자에게 다른 챌린지를 발급합니다. |
/submit |
암호 재설정 흐름을 완료하기 위해 연속 토큰과 함께 사용자가 입력한 새 암호를 수락합니다. 이 엔드포인트는 또 다른 연속 토큰을 발급합니다. |
/poll_completion |
마지막으로 앱은 /submit 엔드포인트에서 발급한 연속 토큰을 사용하여 암호 재설정 요청 상태를 확인할 수 있습니다. |
셀프 서비스 암호 재설정 챌린지 유형
API를 사용하면 앱이 Microsoft Entra를 호출할 때 지원하는 인증 방법을 보급할 수 있습니다. 이를 위해 앱은 요청에 challenge_type 매개 변수를 사용합니다. 이 매개 변수에는 다양한 인증 방법을 나타내는 미리 정의된 값이 포함되어 있습니다.
SSPR 흐름의 경우 챌린지 유형 값은 oob 및 redirect입니다.
기본 인증 챌린지 유형에서 챌린지 유형에 대해 자세히 알아봅니다.
셀프 서비스 암호 재설정 흐름 프로토콜 세부 정보
시퀀스 다이어그램은 암호 재설정 프로세스의 흐름을 보여 줍니다.
이 다이어그램은 앱이 서로 다른 시간에(별도의 화면에서) 사용자로부터 사용자 이름(메일)과 암호를 수집한다는 것을 나타냅니다. 그러나 동일한 화면에서 사용자 이름(메일)과 새 암호를 수집하도록 앱을 설계할 수 있습니다. 이 경우 앱은 암호를 보유하고 있으며 필요한 경우 /submit 엔드포인트를 통해 암호를 제출합니다.
1단계: 셀프 서비스 암호 재설정 흐름 시작 요청
암호 재설정 흐름은 앱이 셀프 서비스 암호 재설정 흐름을 시작하기 위해 /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를 포함해야 합니다. |
성공 응답
예시:
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 매개 변수를 포함합니다. invalid_client 오류에 대한 suberror 매개 변수의 가능한 값은 다음과 같습니다.
| 하위 오류 값 | 설명 |
|---|---|
nativeauthapi_disabled |
기본 인증이 사용하도록 설정되지 않은 앱의 클라이언트 ID입니다. |
2단계: 인증 방법 선택
흐름을 계속하기 위해 앱은 이전 단계에서 획득한 연속 토큰을 사용하여 사용자가 인증할 지원되는 챌린지 유형 중 하나를 선택하도록 Microsoft Entra에 요청합니다. 앱이 /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=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 |
일회용 암호를 보낸 난독 처리된 메일입니다. |
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단계: 일회용 암호 제출
그런 다음 앱은 /continue 엔드포인트에 POST 요청을 보냅니다. 요청에서 앱은 이전 단계에서 선택한 사용자의 자격 증명과 /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}를 고객 사용자가 메일로 받은 일회용 암호로 바꿉니다. 일회용 암호를 다시 보내려면 앱이 /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 매개 변수를 포함합니다. invalid_grant 오류에 대한 suberror 매개 변수의 가능한 값은 다음과 같습니다.
| 하위 오류 값 | 설명 |
|---|---|
invalid_oob_value |
사용자가 제공한 일회용 암호가 잘못되었습니다. |
4단계: 새 암호 제출
앱은 사용자로부터 새 암호를 수집한 다음 /continue 엔드포인트에서 발급한 연속 토큰을 사용하여 /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 |
앱이 /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단계: 암호 재설정 상태 폴링
마지막으로, 새 암호로 사용자 구성을 업데이트하면 약간의 지연이 발생하므로 앱은 /poll_completion 엔드포인트를 사용하여 Microsoft Entra에서 암호 재설정 상태를 폴링할 수 있습니다. 앱이 폴링 요청 사이에 기다려야 하는 최소 시간(초)은 poll_interval 매개 변수의 /submit 엔드포인트에서 반환됩니다.
다음은 예입니다(가독성을 위해 예 요청을 여러 줄로 표시합니다).
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가 실패 상태를 반환하는 경우 앱은 /submit 엔드포인트에 또 다른 요청을 하여 새 암호를 다시 제출하고 새 연속 토큰을 포함할 수 있습니다. |
continuation_token |
Microsoft Entra가 반환하는 연속 토큰입니다. 상태가 성공인 경우 앱은 등록 흐름의 5단계에 설명된 대로 Microsoft Entra가 반환하는 연속 토큰을 사용하여 /token 엔드포인트를 통해 보안 토큰을 요청할 수 있습니다. 즉, 사용자가 암호를 성공적으로 다시 설정한 후에는 새로운 로그인 흐름을 시작하지 않고도 해당 사용자를 앱에 직접 로그인할 수 있습니다. |
Microsoft Entra가 반환할 수 있는 상태는 다음과 같습니다(status 매개 변수의 가능한 값).
| 오류 값 | 설명 |
|---|---|
succeeded |
암호 재설정이 성공적으로 완료되었습니다. |
failed |
암호 재설정에 실패했습니다. 앱은 /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 |
연속 토큰이 만료되었습니다. |