요청 서비스 REST API 프레젠테이션 사양

아티클
02/06/2024

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 요청을 생성합니다. tenantId는 access_token에서 클레임으로 존재하기 때문에 URL에 더 이상 필요하지 않습니다.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

다음 HTTP 요청은 요청 서비스 REST API에 대한 프레젠테이션 요청을 보여 줍니다.

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "includeQRCode": true,
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

요청 서비스 REST API를 호출하려면 다음 권한이 필요합니다. 자세한 내용은 액세스 토큰을 얻을 수 있는 권한 부여를 참조하세요.

권한 유형	Permission
애플리케이션	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

프레젠테이션 요청 페이로드

프레젠테이션 요청 페이로드에는 확인 가능한 자격 증명 프레젠테이션 요청에 대한 정보가 포함됩니다. 다음 예제에서는 특정 발급자의 프레젠테이션 요청을 보여 줍니다. 이 요청의 결과는 프레젠테이션 프로세스를 시작하기 위한 링크가 포함된 QR 코드를 반환합니다.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

페이로드는 다음 속성을 포함합니다.

매개 변수	형식	설명
`includeQRCode`	부울	선택 사항. 이 요청의 응답에 QR 코드가 포함되는지 여부를 결정합니다. QR 코드를 제공하고 사용자에게 검색하도록 요청합니다. QR 코드를 스캔하면 이 프레젠테이션 요청으로 인증자 앱이 시작됩니다. 가능한 값은 `true`(기본값) 또는 `false`입니다. 값을 `false`로 설정하는 경우 반환 `url` 속성을 사용하여 딥 링크를 렌더링합니다.
`includeReceipt`	부울	선택 사항. 이 요청의 응답에 영수증을 포함해야 하는지 여부를 결정합니다. 가능한 값은 `true` 또는 `false`(기본값)입니다. 영수증에는 인증자에서 확인 가능한 자격 증명 서비스로 전송된 원래 페이로드가 포함됩니다. 영수증은 문제 해결 시 또는 페이로드의 전체 세부 정보를 확인해야 하는 경우에 유용합니다. 그렇지 않으면 기본적으로 이 값을 `true` 로 설정할 필요가 없습니다. `OpenId Connect SIOP` 요청에서 영수증에는 원래 요청의 ID 토큰이 포함됩니다.
`authority`	string	검증 도구 Microsoft Entra ID 테넌트의 DID(탈중앙화 식별자)입니다. 자세한 내용은 샘플 애플리케이션을 설정하기 위한 테넌트 세부 정보 수집을 참조하세요.
`registration`	RequestRegistration	검증 도구에 대한 정보를 제공합니다.
`callback`	Callback	필수. 개발자가 확인 가능한 자격 증명 프레젠테이션 프로세스 중에 UI를 업데이트할 수 있습니다. 사용자가 프로세스를 완료하면 결과가 애플리케이션에 반환된 후 프로세스를 계속합니다.
`requestedCredentials`	컬렉션	RequestCredential 개체의 컬렉션입니다.

RequestRegistration 형식

RequestRegistration 형식은 발급자에 대한 정보 등록을 제공합니다. RequestRegistration 형식은 다음 속성을 포함합니다.

속성	Type	설명
`clientName`	string	확인 가능한 자격 증명의 검증자 표시 이름입니다. 이 이름은 인증자 앱에서 사용자에게 표시됩니다.
`purpose`	string	선택 사항. 확인 가능한 자격 증명이 요청되는 이유를 사용자에게 알리기 위해 표시되는 문자열입니다.
`logoUrl`	URL	선택 사항. 검증자 로고 형식에 대한 URL입니다. Authenticator 앱에서는 사용되지 않습니다.
`termsOfServiceUrl`	URL	선택 사항. 검증자 서비스 약관에 대한 URL입니다. Authenticator 앱에서는 사용되지 않습니다.

다음 스크린샷에서는 프레젠테이션 요청의 clientName 속성 및 authority(검증 도구)의 표시 이름을 보여 줍니다.

프레젠테이션 요청을 승인하는 방법을 보여 주는 스크린샷

콜백 유형

요청 서비스 REST API는 콜백 엔드포인트에 여러 이벤트를 생성합니다. 이러한 이벤트를 통해 UI를 업데이트하고 결과를 애플리케이션에 반환한 후에 프로세스를 계속할 수 있습니다. Callback 형식은 다음 속성을 포함합니다.

속성	Type	설명
`url`	string	애플리케이션의 콜백 엔드포인트에 대한 URI입니다. URI는 인터넷에서 연결할 수 있는 엔드포인트를 가리켜야 합니다. 그렇지 않으면 서비스에서 콜백 URL을 읽을 수 없음 오류가 throw됩니다. 허용되는 입력 IPv4, IPv6 또는 DNS 확인 가능 호스트 이름.
`state`	string	콜백 이벤트와 원래 페이로드에 전달된 상태의 상관 관계를 지정합니다.
`headers`	string	선택 사항. POST 메시지의 수신 끝에 필요한 HTTP 헤더 컬렉션을 포함할 수 있습니다. 현재 지원되는 헤더 값은 `api-key` 또는 `Authorization` 헤더입니다. 다른 모든 헤더는 잘못된 콜백 헤더 오류를 throw합니다.

RequestCredential 형식

RequestCredential은 사용자가 제공해야 하는 요청된 자격 증명에 대한 정보를 제공합니다. RequestCredential에는 다음 속성이 있습니다.

속성	Type	설명
`type`	string	확인 가능한 자격 증명 형식입니다. `type`은 `issuer` 확인 가능한 자격 증명 매니페스트에 정의된 형식과 일치해야 합니다(예: `VerifiedCredentialExpert`). 발급자 매니페스트를 가져오려면 샘플 애플리케이션을 설정하기 위한 자격 증명 및 환경 세부 정보 수집을 참조하세요. 자격 증명 URL 발급을 복사하고 웹 브라우저에서 열고 ID 속성을 확인합니다.
`purpose`	string	선택 사항. 이 확인 가능한 자격 증명을 요청하는 용도에 대한 정보를 제공합니다. Authenticator 앱에서는 사용되지 않습니다.
`acceptedIssuers`	문자열 컬렉션	선택 사항. 주체가 표시할 수 있는 확인 가능한 자격 증명 형식을 발급할 수 있는 발급자의 DID 컬렉션입니다. 발급자 DID를 얻으려면 샘플 애플리케이션을 설정하기 위한 자격 증명 및 환경 세부 정보 수집을 참조하고, DID(탈중앙화 식별자) 값을 복사합니다. `acceptedIssuers` 컬렉션이 비어 있거나 없는 경우 프레젠테이션 요청은 모든 발급자가 발급한 자격 증명 형식을 수락합니다.
`configuration.validation`	Configuration.Validation	프레젠테이션 유효성 검사에 대한 선택적 설정입니다.
`constraints`	제약 조건	선택 사항. 클레임 제약 조건의 컬렉션입니다.

Configuration.Validation 유형

Configuration.Validation은 제시된 자격 증명의 유효성을 검사해야 하는 방법에 대한 정보를 제공합니다. 다음과 같은 속성이 포함되어 있습니다.

속성	Type	설명
`allowRevoked`	부울	선택 사항. 해지된 자격 증명을 수락해야 하는지 여부를 결정합니다. 기본값은 `false`(수락하지 않아야 함)입니다.
`validateLinkedDomain`	부울	선택 사항. 연결된 도메인의 유효성을 검사해야 하는지 여부를 결정합니다. 기본값은 `false`입니다. 이 플래그를 `false`로 설정하면 신뢰 당사자 애플리케이션으로서 확인되지 않은 연결된 도메인의 자격 증명을 수락하게 됩니다. 이 플래그를 `true`로 설정하면 연결된 도메인의 유효성이 검사되고 확인된 도메인만 허용됩니다.
`faceCheck`	faceCheck	선택 사항. 프레젠테이션 중에 활동성 검사 요청할 수 있습니다.

제약 조건 형식

constraints 형식에는 전자 지갑이 후보 자격 증명을 선택할 때 충족해야 하는 클레임 제약 조건 컬렉션이 포함되어 있습니다. 이를 통해 특정 클레임 값이 포함된 자격 증명을 요청할 수 있습니다. 지정된 제약 조건은 AND 논리를 사용합니다. 즉, 세 가지 제약 조건을 지정하면 모두 충족되어야 합니다. 컬렉션의 각 제약 조건에 대해 값의 피연산자(contains 또는 startWith) 하나를 선택해야 합니다. 값은 정규식일 수 없습니다. 모든 비교는 대/소문자를 구분하지 않습니다.

속성	Type	설명
`claimName`	string	필수. 제약 조건에 대한 클레임의 이름입니다. 확인 가능한 자격 증명의 클레임 이름입니다. claimMapping 형식의 outputClaim을 참조하세요.
`values`	문자열 컬렉션	클레임 값과 일치해야 하는 값 집합입니다. ["red", "green", "blue"]와 같은 여러 값을 지정하는 경우 자격 증명의 클레임 값에 컬렉션의 값이 있으면 일치하는 것입니다.
`contains`	string	클레임 값에 지정된 값이 포함되어 있으면 제약 조건은 true로 평가됩니다.
`startsWith`	string	클레임 값이 지정된 값으로 시작하면 제약 조건은 true로 평가됩니다.

faceCheck 유형

faceCheck 유형에는 자격 증명을 프레젠테이션하는 동안 활동성 검사 수행하기 위한 정보가 포함됩니다. 요청된 자격 증명은 sourcePhotoClaimName에서 명명된 클레임에 있는 소유자의 사진을 포함해야 합니다. 활동성 검사 속성 matchConfidenceThreshold에 지정된 것과 같거나 큰 신뢰 수준에 도달하면 프레젠테이션이 성공합니다. 임계값이 충족되지 않으면 전체 프레젠테이션이 실패합니다.

속성	Type	설명
`sourcePhotoClaimName`	string	필수. 사진이 포함된 자격 증명의 클레임 이름입니다. claimMapping 형식의 outputClaim을 참조하세요.
`matchConfidenceThreshold`	정수	선택 사항. 사진과 활동성 데이터 간의 성공적인 검사 대한 기밀 임계값입니다. 50에서 100 사이의 정수여야 합니다. 기본값은 70입니다.

성공적인 응답

성공하면 이 메서드는 응답 코드(HTTP 201 Created)와 응답 본문에 있는 이벤트 개체의 컬렉션을 반환합니다. 다음 JSON은 성공적인 응답을 보여 줍니다.

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "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	인증자 앱에서 요청을 검색했을 때 반환된 상태입니다. 가능한 값: `request_retrieved`: 사용자가 QR 코드를 검색했거나 프레젠테이션 흐름을 시작하는 링크를 선택했습니다. `presentation_verified`: 확인 가능한 자격 증명 유효성 검사가 성공적으로 완료되었습니다. li>`presentation_error`: 프레젠테이션에 오류가 발생했습니다.
`state`	string	원래 페이로드에 전달된 상태 값을 반환합니다.
`subject`	string	확인 가능한 자격 증명 사용자 DID입니다.
`verifiedCredentialsData`	배열	요청된 확인 가능한 자격 증명의 배열을 반환합니다. 각 확인 가능한 자격 증명에 대해 다음을 제공합니다. 확인 가능한 자격 증명 형식입니다. 발급자의 DID 검색된 클레임입니다. 확인 가능한 자격 증명 발급자의 도메인입니다. 확인 가능한 자격 증명 발급자의 도메인 유효성 검사 상태입니다.
`receipt`	string	선택 사항. 영수증에는 전자지갑에서 확인 가능한 자격 증명 서비스로 전송된 원래 페이로드가 포함됩니다. 영수증은 문제 해결/디버깅에만 사용해야 합니다. 영수증의 형식은 수정되지 않으며 사용된 전자지갑 및 버전에 따라 변경할 수 있습니다.

다음 예제에서는 인증자 앱이 프레젠테이션 요청을 시작할 때 콜백 페이로드를 보여 줍니다.

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

다음 예제에서는 확인 가능한 자격 증명 프레젠테이션이 성공적으로 완료된 후의 콜백 페이로드를 보여 줍니다.

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

다음 단계

요청 서비스 REST API를 호출하는 방법을 알아봅니다.