요청 서비스 REST API 발급 사양
Microsoft Entra Verified ID는 요청 서비스 REST API를 포함합니다. 이 API를 사용하면 자격 증명을 발급하고 확인할 수 있습니다. 이 문서에서는 발급 요청에 대한 요청 서비스 REST API를 지정합니다. 또 다른 문서에서는 요청 서비스 REST API를 호출하는 방법을 설명합니다.
HTTP 요청
요청 서비스 REST API 발급 요청은 다음 HTTP 메서드를 지원합니다.
| 메서드 | 주의 |
|---|---|
| 게시 | 이 문서에 지정된 JSON 페이로드를 사용합니다. |
요청 서비스 REST API 발급 요청에는 다음 HTTP 헤더가 필요합니다.
| 속성 | 값 |
|---|---|
Authorization |
HTTP 요청의 인증 헤더에 액세스 토큰을 전달자 토큰으로 연결합니다. 예: Authorization: Bearer <token>. |
Content-Type |
application/json |
요청 서비스 REST API에 대한 HTTP POST 요청을 생성합니다.
https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
다음 HTTP 요청은 요청 서비스 REST API에 대한 요청을 보여 줍니다.
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>
{
"includeQRCode": true,
"callback": {
"url": "https://contoso.com/api/issuer/issuanceCallback",
"state": "Aaaabbbb11112222",
"headers": {
"api-key": "an-api-key-can-go-here"
}
},
...
}
요청 서비스 REST API를 호출하려면 다음 권한이 필요합니다. 자세한 내용은 액세스 토큰을 얻을 수 있는 권한 부여를 참조하세요.
| 권한 유형 | Permission |
|---|---|
| 애플리케이션 | 3db474b9-6a0c-4840-96ac-1fceb342124f/.default |
발급 요청 페이로드
발급 요청 페이로드에는 확인 가능한 자격 증명 발급 요청에 대한 정보가 포함되어 있습니다. 다음 예제에서는 이름 및 성 같은 사용자 클레임으로 PIN 코드 흐름을 사용하여 발급 요청을 보여 줍니다. 이 요청의 결과는 발급 프로세스를 시작하기 위한 링크가 포함된 QR 코드를 반환합니다.
{
"includeQRCode": false,
"callback": {
"url": "https://contoso.com/api/issuer/issuanceCallback",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
"headers": {
"api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
}
},
"authority": "did:web:verifiedid.contoso.com",
"registration": {
"clientName": "Verifiable Credential Expert Sample"
},
"type": "VerifiedCredentialExpert",
"manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
"pin": {
"value": "3539",
"length": 4
},
"claims": {
"given_name": "Megan",
"family_name": "Bowen"
},
"expirationDate": "2024-12-31T23:59:59.000Z"
}
페이로드에는 다음과 같은 속성이 포함되어 있습니다.
| 매개 변수 | 형식 | 설명 |
|---|---|---|
includeQRCode |
부울 | 이 요청의 응답에 QR 코드가 포함되는지 여부를 결정합니다. QR 코드를 제공하고 사용자에게 검색하도록 요청합니다. QR 코드를 스캔하면 이 발급 요청으로 인증자 앱이 시작됩니다. 가능한 값은 true(기본값) 또는 false입니다. 값을 false로 설정하는 경우 반환 url 속성을 사용하여 딥 링크를 렌더링합니다. |
callback |
Callback | 필수. 개발자가 확인 가능한 자격 증명 발급 프로세스 중에 흐름에 대한 정보를 비동기식으로 가져올 수 있도록 합니다. 예를 들어 사용자가 QR 코드를 검사하거나, 발급 요청이 성공하거나 실패한 경우 개발자는 호출을 원할 수 있습니다. |
authority |
string | 발급자의 DID(분산된 식별자)입니다. 자세한 내용은 샘플 애플리케이션을 설정하기 위한 자격 증명 및 환경 세부 정보 수집을 참조하세요. |
registration |
RequestRegistration | 인증자 앱에 표시될 수 있는 발급자에 대한 정보를 제공합니다. |
type |
string | 확인 가능한 자격 증명 형식입니다. 확인 가능한 자격 증명 매니페스트에 정의된 형식과 일치해야 합니다. 예: VerifiedCredentialExpert 자세한 내용은 Azure에서 확인된 자격 증명 전문가 카드 만들기를 참조하세요. |
manifest |
string | 확인 가능한 자격 증명 매니페스트 문서의 URL입니다. 자세한 내용은 샘플 애플리케이션을 설정하기 위한 자격 증명 및 환경 세부 정보 수집을 참조하세요. |
claims |
string | 선택 사항. 확인 가능한 자격 증명의 대상에 대한 어설션 모음을 포함하기 위한 ID 토큰 힌트 증명 흐름에만 사용할 수 있습니다. |
pin |
PIN | 선택 사항. PIN 코드는 ID 토큰 힌트 증명 흐름에서만 사용할 수 있습니다. 발급 중에 추가 보안을 제공하는 PIN 번호입니다. PIN 코드를 생성하고 앱의 사용자에게 제공합니다. 사용자는 생성된 PIN 코드를 제공해야 합니다. |
expirationDate |
string | 선택 사항. expirationDate는 ID 토큰 힌트 증명 흐름에서만 사용할 수 있습니다. 지정된 경우 값은 ISO8601 형식으로 표현된 날짜여야 합니다. 날짜는 이 발급 요청에 대한 자격 증명 규칙 정의의 validityInterval을 재정의합니다. 이 설정을 사용하면 발급 시기와 상관없이 자격 증명이 만료되는 시기(예: 일말, 월말, 연말 등)를 명시적으로 제어할 수 있습니다. 날짜는 UTC 형식으로 표시됩니다. 시간을 23:59:59로 설정하고 연말을 지정하는 경우 이는 UTC 시간으로 자정까지 1초입니다. 다른 시간대에 있는 모든 사용자는 Microsoft Authenticator에서 로컬 시간대로 표시되는 만료 날짜를 가져오게 됩니다. 즉, CET 시간대에 있는 경우 1월 1일 오전 1시로 표시됩니다.자격 증명 계약에는 allowOverrideValidityOnIssuance 플래그가 true로 설정되어 있어야 합니다. |
현재 페이로드에서 보낼 수 있는 클레임 증명 형식은 네 가지가 있습니다. Microsoft Entra Verified ID는 네 가지 방법을 사용하여 확인 가능한 자격 증명에 클레임을 삽입하고 발급자의 DID를 사용하여 해당 정보를 증명합니다. 다음과 같은 네 가지 형식입니다.
- ID 토큰
- ID 토큰 힌트
- 확인 가능한 프레젠테이션을 통해 확인 가능한 자격 증명
- 자체 증명 클레임
확인 가능한 자격 증명 사용자 지정에서 입력 형식에 대한 자세한 정보를 찾을 수 있습니다.
RequestRegistration 형식
RequestRegistration 형식은 발급자에 대한 정보 등록을 제공합니다. RequestRegistration 형식은 다음 속성을 포함합니다.
| 속성 | Type | 설명 |
|---|---|---|
clientName |
string | 확인 가능한 자격 증명의 발급자 표시 이름입니다. |
logoUrl |
string | 선택 사항. 발급자 로고에 대한 URL입니다. |
termsOfServiceUrl |
string | 선택 사항. 발급하는 확인 가능한 자격 증명의 사용 약관에 대한 URL입니다. |
참고 항목
이번에는 Microsoft Authenticator 앱에서 발급하는 동안 RequestRegistration 정보가 제공되지 않습니다. 그러나 이 정보는 페이로드에 사용될 수 있습니다.
콜백 유형
요청 서비스 REST API는 콜백 엔드포인트에 여러 이벤트를 생성합니다. 이러한 이벤트를 통해 UI를 업데이트하고 결과를 애플리케이션에 반환한 후에 프로세스를 계속할 수 있습니다. Callback 형식은 다음 속성을 포함합니다.
| 속성 | Type | 설명 |
|---|---|---|
url |
string | 애플리케이션의 콜백 엔드포인트에 대한 URI입니다. URI는 인터넷에서 연결할 수 있는 엔드포인트를 가리켜야 합니다. 그렇지 않으면 서비스에서 콜백 URL을 읽을 수 없음 오류가 throw됩니다. 허용되는 형식 IPv4, IPv6 또는 DNS 확인 가능 호스트 이름 |
state |
string | 콜백 이벤트와 원래 페이로드에 전달된 상태의 상관 관계를 지정합니다. |
headers |
string | 선택 사항. POST 메시지의 수신 끝에 필요한 HTTP 헤더 컬렉션을 포함할 수 있습니다. 현재 지원되는 헤더 값은 api-key 또는 Authorization 헤더입니다. 다른 모든 헤더는 잘못된 콜백 헤더 오류를 throw합니다. |
Pin 형식
pin 형식은 발급의 일부로 표시될 수 있는 PIN 코드를 정의합니다. pin은 선택 사항이며, 사용되는 경우 항상 대역 외로 전송되어야 합니다. 해시 PIN 코드를 사용하는 경우 salt, alg 및 iterations 속성을 정의해야 합니다. pin에는 다음 속성이 있습니다.
| 속성 | Type | 설명 |
|---|---|---|
value |
string | PIN 값을 일반 텍스트로 포함합니다. 해시된 PIN을 사용하는 경우 값 속성에는 base64로 인코딩된 솔트된 해시가 포함됩니다. |
type |
string | PIN 코드의 형식입니다. 가능한 값: numeric(기본값) |
length |
정수 | PIN 코드의 길이입니다. 기본 길이는 6, 최솟값은 4, 최댓값은 16입니다. |
salt |
string | 해시된 PIN 코드의 솔트입니다. 해시를 계산하는 동안 솔트가 앞에 붙습니다. 인코딩 = UTF-8 |
alg |
string | 해시된 PIN에 대한 해시 알고리즘입니다. 지원되는 알고리즘: sha256 |
iterations |
정수 | 해시 반복 횟수입니다. 가능한 값: 1. |
성공적인 응답
성공하면 이 메서드는 응답 코드(HTTP 201 Created)와 응답 본문에 있는 이벤트 개체의 컬렉션을 반환합니다. 다음 JSON은 성공적인 응답을 보여 줍니다.
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",
"expiry": 1622227690,
"qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"
}
응답에는 다음 속성이 포함됩니다.
| 속성 | Type | 설명 |
|---|---|---|
requestId |
string | 자동 생성된 요청 ID입니다. 콜백은 동일한 요청을 사용하므로 발급 요청 및 해당 콜백을 추적할 수 있습니다. |
url |
string | 인증자 앱을 시작하고 발급 프로세스를 시작하는 URL입니다. QR 코드를 스캔할 수 없는 경우 사용자에게 이 URL을 제공할 수 있습니다. |
expiry |
정수 | 응답이 만료되는 시기를 나타냅니다. |
qrCode |
string | 사용자가 발급 흐름을 시작하기 위해 검색할 수 있는 QR 코드입니다. |
앱에서 응답을 수신하면 앱은 사용자에게 QR 코드를 제공해야 합니다. 사용자가 QR 코드를 검색하면 인증자 앱이 열리고 발급 프로세스가 시작됩니다.
오류 응답
요청에 오류가 있는 경우 오류 응답이 반환되며 앱에서 적절하게 처리해야 합니다.
콜백 이벤트
콜백 엔드포인트는 사용자가 QR 코드를 검색하거나, 인증자 앱의 딥 링크를 사용하거나, 발급 프로세스를 완료할 때 호출됩니다.
| 속성 | Type | 설명 |
|---|---|---|
requestId |
string | 페이로드를 확인 가능한 자격 증명 서비스에 게시했을 때 원래 요청에 매핑됩니다. |
requestStatus |
string | 요청에 대해 반환된 상태입니다. 가능한 값:
|
state |
string | 원래 페이로드에 전달된 상태 값을 반환합니다. |
error |
error | code 속성 값이 issuance_error이면 이 속성은 오류에 대한 정보를 포함합니다. |
error.code |
string | 반환 오류 코드입니다. |
error.message |
string | 오류 메시지입니다. |
다음 예제에서는 인증자 앱이 발급 요청을 시작할 때 콜백 페이로드를 보여 줍니다.
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus":"request_retrieved",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}
다음 예제에서는 사용자가 발급 프로세스를 성공적으로 완료한 후의 콜백 페이로드를 보여 줍니다.
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus":"issuance_successful",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}
콜백 오류
콜백 엔드포인트는 오류 메시지를 사용하여 호출될 수 있습니다. 다음 표에서는 오류 코드를 나열합니다.
| 메시지 | 정의 |
|---|---|
fetch_contract_error |
확인 가능한 자격 증명 계약을 가져올 수 없습니다. 이 오류는 일반적으로 API가 요청 페이로드 RequestIssuance 개체에 지정한 매니페스트를 가져올 수 없을 때 발생합니다. |
issuance_service_error |
확인 가능한 자격 증명 서비스가 요구 사항의 유효성을 검사할 수 없거나 확인 가능한 자격 증명에 문제가 있습니다. |
unspecified_error |
이 오류는 일반적이지 않지만 조사할 가치가 있습니다. |
다음 예제에서는 오류가 발생했을 때의 콜백 페이로드를 보여 줍니다.
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus": "issuance_error",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
"error": {
"code":"IssuanceFlowFailed",
"message":"issuance_service_error”,
}
}
다음 단계
요청 서비스 REST API를 호출하는 방법을 알아봅니다.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기