확인 가능한 자격 증명 관리자 API
Microsoft Entra 확인된 ID 관리자 API를 사용하면 확인 가능한 자격 증명 서비스의 모든 측면을 관리할 수 있습니다. 완전히 새로워진 서비스를 설정하고 확인 가능한 자격 증명 계약을 관리하고 만들고 확인 가능한 자격 증명을 해지하며 서비스를 완전히 옵트아웃하는 방법을 제공합니다.
API는 RESTful API에 익숙하고 서비스를 사용할 수 있도록 Microsoft Entra 테넌트에 대한 충분한 권한이 있는 개발자를 위해 설계되었습니다.
기준 URL
관리자 API는 HTTPS를 통한 서버입니다. 설명서에서 참조되는 모든 URL은 https://verifiedid.did.msidentity.com을 기반으로 합니다.
인증
API는 Microsoft Entra ID를 통해 보호되며 OAuth2 전달자 토큰을 사용합니다. 액세스 토큰은 사용자 또는 애플리케이션용일 수 있습니다.
사용자 전달자 토큰
앱 등록에는 Verifiable Credentials Service Admin에 대한 API 권한이 있어야 하며 액세스 토큰을 얻을 때 앱은 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access 범위를 사용해야 합니다. 액세스 토큰은 전역 관리자 또는 인증 정책 관리자 역할이 있는 사용자를 위한 토큰이어야 합니다. 전역 읽기 권한자 역할이 있는 사용자는 읽기 전용 API를 호출할 수 있습니다.
애플리케이션 전달자 토큰
Verifiable Credentials Service Admin 서비스는 다음 애플리케이션 권한을 지원합니다.
| Permission | 설명 |
|---|---|
| VerifiableCredential.Authority.ReadWrite | 읽기/쓰기 권한자 개체에 대한 권한 |
| VerifiableCredential.Contract.ReadWrite | 계약 개체에 대한 읽기/쓰기 권한 |
| VerifiableCredential.Credential.Search | 해지할 자격 증명을 검색할 수 있는 권한 |
| VerifiableCredential.Credential.Revoke | 이전에 발급한 자격 증명을 해지할 수 있는 권한 |
| VerifiableCredential.Network.Read | 확인된 ID 네트워크에서 항목을 읽을 수 있는 권한 |
앱을 등록하려면 Verifiable Credentials Service Admin에 대한 API 권한과 위의 표에 필요한 권한이 있어야 합니다. 액세스 토큰을 가져올 때 클라이언트 자격 증명 흐름을 통해 앱은 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default 범위를 사용해야 합니다.
앱이 새 기관을 만들려는 경우 두 가지가 필요합니다. 먼저 앱 등록에는 VerifiableCredential.Authority.ReadWrite 권한이 필요합니다. 둘째, 앱에는 Key Vault 액세스 정책에 Create Key 권한이 있어야 합니다. 앱이 기존 기관만 읽거나 쓰는 경우 Key Vault 권한이 필요하지 않습니다.
온보딩
이 API는 새 인증 기관을 설정할 수 있도록 새 환경을 만드는 데 도움이 됩니다. Azure Portal에서 확인 가능한 자격 증명 페이지로 이동하여 수동으로 트리거할 수도 있습니다. API를 사용하여 완전히 새로워진 환경을 설정하려는 경우에만 이 API를 한 번만 호출해야 합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/onboard
이 엔드포인트를 사용하여 테넌트에서 확인 가능한 자격 증명 서비스 프로비전을 완료합니다. 아직 프로비전되지 않으면 시스템에서 나머지 서비스 주체를 만듭니다.
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
반환 메시지
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
"verifiableCredentialServicePrincipalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
"verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
"status": "Enabled"
}
이 API를 반복적으로 호출하면 정확하게 동일한 반환 메시지가 발생합니다.
인증 기관
이 엔드포인트를 확인 가능한 자격 증명 서비스 인스턴스를 만들거나 업데이트하는 데 사용할 수 있습니다.
메서드
| 메서드 | 반환 형식 | 설명 |
|---|---|---|
| Get Authority | 인증 기관 | 인증 기관 속성 읽기 |
| List Authority | 인증 기관 배열 | 구성된 모든 인증 기관/확인 가능한 자격 증명 서비스 목록 가져오기 |
| Create Authority | 인증 기관 | 새 인증 기관 만들기 |
| Update authority | 인증 기관 | 인증 기관 업데이트 |
| 권한 삭제 | Authority | 기관 삭제 |
| Generate Well known DID Configuration | ||
| Generate DID Document | ||
| Validate Well-known DID config | ||
| Rotate Signing Key | Authority | 서명 키 회전 |
| DID 문서 동기화 | Authority | DID 문서를 새 서명 키와 동기화 |
Get authority
구성된 인증 기관이나 확인 가능한 자격 증명 서비스 인스턴스의 속성을 검색합니다.
HTTP 요청
GET /v1.0/verifiableCredentials/authorities/:authorityId
:authorityId를 구성된 인증 기관 중 하나의 값으로 바꿉니다.
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드의 요청 본문을 제공하지 마세요.
응답 메시지
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
응답에는 다음 속성이 포함됩니다.
인증 기관 유형
| 속성 | Type | 설명 |
|---|---|---|
Id |
string | 확인 가능한 자격 증명 서비스의 특정 인스턴스를 검색하거나 업데이트하는 데 사용할 수 있는 자동으로 생성된 고유 ID |
name |
string | 확인 가능한 자격 증명 서비스의 이 인스턴스 식별 이름 |
status |
string | 서비스 상태. 이 값은 항상 enabled입니다. |
| didModel | didModel | DID 및 키에 대한 정보 |
| keyVaultMetadata | keyVaultMeta data | 사용된 Key Vault에 대한 정보 |
didModel type
웹
| 속성 | Type | 설명 |
|---|---|---|
did |
string | 이 확인 가능한 자격 증명 서비스 인스턴스의 DID |
signingKeys |
문자열 배열 | 서명 키의 URL |
linkedDomainUrls |
문자열 배열 | 이 DID에 연결된 도메인(단일 항목 하나 예상) |
| didModel | didModel | DID 및 키에 대한 정보 |
didDocumentStatus |
string | DID의 상태. 이 메서드 값은 항상 published입니다. |
keyVaultMetadata 형식
| 속성 | Type | 설명 |
|---|---|---|
subscriptionId |
string | 이 Key Vault가 있는 Azure 구독 |
resourceGroup |
string | 이 Key Vault의 리소스 그룹 이름 |
resourceName |
string | Key Vault 이름 |
resourceUrl |
string | 이 Key Vault의 URL |
List authorities
이 테넌트에 구성된 모든 인증 기관이나 확인 가능한 자격 증명 서비스를 가져옵니다.
HTTP 요청
GET /v1.0/verifiableCredentials/authorities
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
응답 메시지는 기관의 배열입니다.
예시:
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName2",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid2.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
Create authority
이 호출은 새로운 프라이빗 키, 복구 키 및 업데이트 키를 만들고, 이러한 키를 지정된 Azure Key Vault에 저장하고, 확인 가능한 자격 증명 서비스를 위해 이 Key Vault에 대한 권한을 설정하고 해당 DID 문서로 새 DID를 만듭니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
요청 본문에서 다음과 같은 JSON 표현을 입력합니다.
| 속성 | Type | 설명 |
|---|---|---|
name |
string | 이 서비스의 이 인스턴스 표시 이름 |
linkedDomainUrl |
string | 이 DID에 연결된 도메인 |
didMethod |
string | web이어야 합니다. |
keyVaultMetadata |
keyVaultMetadata | 특정 키 자격 증명 모음의 메타 데이터 |
예제 메시지:
{
"name":"ExampleName",
"linkedDomainUrl":"https://verifiedid.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
응답 메시지
성공하면 응답 메시지에 인증 기관 이름이 포함됩니다.
did:web 메시지 예제:
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
did:ion 메시지 예제:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
설명
고유한 DID 및 프라이빗 키를 사용하여 인증 기관을 여러 개 만들 수 있으며 이러한 인증 기관은 Azure Portal의 UI에 표시되지 않습니다. 현재 인증 기관 1개만 지원합니다. 생성된 여러 인증 기관에서 모든 시나리오를 완전히 테스트하지 않았습니다. 이 작업을 시도하는 경우 경험을 알려주세요.
인증 기관 업데이트
이 메서드는 확인 가능한 자격 증명 서비스의 이 특정 인스턴스의 표시 이름을 업데이트하는 데 사용될 수 있습니다.
HTTP 요청
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
:authorityId 값을 업데이트하려는 인증 기관 ID 값으로 바꿉니다.
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
요청 본문에서 다음과 같은 JSON 표현을 입력합니다.
| 속성 | Type | 설명 |
|---|---|---|
name |
string | 이 서비스의 이 인스턴스 표시 이름 |
예제 메시지
{
"name":"ExampleIssuerName"
}
기관 삭제
이 메서드를 사용하여 권한을 삭제할 수 있습니다. 현재 did:ion 기관만 삭제할 수 있습니다. 기관을 삭제하면 발급된 확인된 ID 자격 증명이 유효하지 않으며 발급 기관이 사라지면 더 이상 확인할 수 없습니다.
HTTP 요청
DELETE /beta/verifiableCredentials/authorities/:authorityId
:authorityId 값을 삭제하려는 기관 ID의 값으로 바꿉니다.
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
요청 본문 없음
응답 메시지
응답 메시지 예제:
권한 삭제 응답에 성공했습니다.
HTTP/1.1 200 OK
권한 삭제가 성공했지만 Azure Key Vault 키 정리에 실패한 경우 아래 응답을 받게 됩니다.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "deleteIssuerSuccessfulButKeyDeletionFailed",
"message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
}
}
Well-known DID configuration
이 generateWellknownDidConfiguration 메서드는 서명된 did-configuration.json 파일을 생성합니다. 이 확인 가능한 자격 증명 인스턴스의 연결된 도메인에 있는 도메인에 호스트되는 웹 사이트의 루트에 있는 .well-known 폴더에 파일을 업로드해야 합니다. 지침은 여기를 참조하세요.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
지정된 인증 기관의 linkedDomains에 있는 도메인 중 하나를 지정해야 합니다.
{
"domainUrl":"https://atest/"
}
응답 메시지
응답 메시지 예제:
HTTP/1.1 200 OK
Content-type: application/json
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbGciOiJFUzI1NksiL...<SNIP>..."
]
}
이 결과를 did-configuration.json 파일 이름으로 저장하고 이 파일을 올바른 폴더와 웹 사이트에 업로드합니다. 이 DID/DID 문서에 연결되지 않은 도메인을 지정하면 다음 오류가 발생합니다.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"079192a95fbf56a661c1b2dd0e012af5",
"date":"Mon, 07 Feb 2022 18:55:53 GMT",
"mscv":"AVQh55YiU3FxMipB.0",
"error":
{
"code":"wellKnownConfigDomainDoesNotExistInIssuer",
"message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
}
}
설명
DID 여러 개를 동일한 도메인으로 가리킬 수 있습니다. 이 구성을 선택하는 경우 생성된 토큰을 결합하고 동일한 did-configuration.json 파일에 배치해야 합니다. 파일에는 이러한 토큰의 배열이 포함되어 있습니다.
예시:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Generate DID document
이 호출은 DID:WEB 식별자에 사용되는 DID 문서를 생성합니다. 이 DID 문서를 생성한 후 관리자는 파일을 https://domain/.well-known/did.json 위치에 배치해야 합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "did:web:verifiedid.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:verifiedid.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://verifiedid.contoso.com/"
]
}
},
{
"id": "#hub",
"type": "IdentityHub",
"serviceEndpoint": {
"instances": [
"https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
]
}
}
],
"verificationMethod": [
{
"id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
"controller": "did:web:verifiedid.contoso.com",
"type": "EcdsaSecp256k1VerificationKey2019",
"publicKeyJwk": {
"crv": "secp256k1",
"kty": "EC",
"x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
"y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
}
}
],
"authentication": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
],
"assertionMethod": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
]
}
설명
호출자에게 대상 키 자격 증명 모음에 대한 KEY 목록 권한이 있어야 합니다.
Validate well-known DID configuration
이 호출은 DID 설정을 확인합니다. 잘 알려진 DID 구성을 다운로드하고 올바른 DID가 사용되며 서명이 올바른지 검증합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
HTTP/1.1 204 No Content
Content-type: application/json
서명 키 회전
회전 서명 키는 did:web authority에 대한 새 프라이빗 키를 만듭니다. 업데이트를 반영하도록 DID 문서를 다시 등록해야 합니다. 이 작업이 완료되면 synchronizeWithDidDocument 서명에 새 키 사용을 시작하도록 시스템에 지시합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
didDocumentStatus이(가) outOfSync(으)로 변경됩니다.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
DID 문서와 동기화
서명 키를 회전한 후에는 업데이트를 반영하도록 DID 문서를 다시 등록합니다. 이 작업이 완료되면 synchronizeWithDidDocument는 서명에 새 키 사용을 시작하도록 시스템에 지시합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
didDocumentStatus 호출이 성공하면 outOfSync이(가) published(으)로 변경됩니다.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
계약
이 엔드포인트를 사용하면 새 계약을 만들고 기존 계약을 업데이트할 수 있습니다. 계약은 JSON 정의 두 개로 표현되는 두 부분으로 구성됩니다. 수동으로 계약을 디자인하고 만드는 방법은 여기를 참조하세요.
- 표시 정의는 관리자가 확인 가능한 자격 증명의 모양(예: 배경색, 로고 및 확인 가능한 자격 증명 제목)을 제어하는 데 사용됩니다. 이 파일에는 확인 가능한 자격 증명 내에 저장해야 하는 클레임도 포함되어 있습니다.
- 규칙 정의에는 자체 증명 클레임, 입력으로 확인 가능한 다른 자격 증명 또는 사용자가 OIDC 호환 ID 공급자에 로그인한 후 받은 ID 토큰과 같은 증명을 수집하는 방법에 대한 정보가 포함되어 있습니다.
메서드
| 메서드 | 반환 형식 | 설명 |
|---|---|---|
| Get contract | 계약 | 계약 속성 읽기 |
| List contracts | 계약 컬렉션 | 구성된 모든 계약 목록 가져오기 |
| Create contract | 계약 | 새 계약 만들기 |
| Update contract | 계약 | Update contract |
Get contract
HTTP 요청
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
:authorityId 및 :contractId를 인증 기관과 계약의 올바른 값으로 바꿉니다.
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
예제 메시지:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": <rulesModel>,
"displays": <displayModel[]>,
"allowOverrideValidityIntervalOnIssuance": false
}
응답에는 다음 속성이 포함됩니다.
계약 유형
| 속성 | Type | 설명 |
|---|---|---|
Id |
string | 계약 ID |
name |
string | 이 계약의 식별 이름 |
status |
string | 항상 Enabled입니다. |
manifestUrl |
string | 발급 요청에 사용되는 계약의 URL |
issueNotificationEnabled |
부울 값 | 이 VC가 발급될 준비가 됨을 사용자에게 알리는 경우 true로 설정 |
issueNotificationAllowedToGroupOids |
groupId 문자열 배열 | 이 자격 증명이 제공되는 그룹 ID 배열 |
availableInVcDirectory |
부울 값 | 이 계약이 확인 가능한 자격 증명 네트워크에 게시되었는지 확인 |
| rules | rulesModel | 규칙 정의 |
| displays | displayModel 배열 | 표시 정의 |
allowOverrideValidityIntervalOnIssuance |
부울 값 | createIssuanceRequest API 호출이 자격 증명의 만료를 재정의할 수 있는 경우 idTokenHint 흐름인 경우에만 유효합니다. |
rulesModel 형식
| 속성 | Type | 설명 |
|---|---|---|
attestations |
attestations | 규칙에 지원되는 입력 설명 |
validityInterval |
번호 | 이 값은 자격 증명 수명을 보여 줍니다. |
vc |
vcType 배열 | 이 계약의 형식 |
customStatusEndpoint |
[customStatusEndpoint](#customstatusendpoint-type)(선택 사항) | 이 계약의 확인 가능한 자격 증명에 포함할 상태 엔드포인트 |
customStatusEndpoint 속성을 지정하지 않으면 anonymous 상태 엔드포인트가 사용됩니다.
증명 형식
| 속성 | Type | 설명 |
|---|---|---|
idTokens |
idTokenAttestation(배열)(선택 사항) | ID 토큰 입력 설명 |
idTokenHints |
idTokenHintAttestation(배열)(선택 사항) | ID 토큰 힌트 입력 설명 |
presentations |
verifiablePresentationAttestation(배열)(선택 사항) | 검증 가능한 프레젠테이션 입력 설명 |
selfIssued |
selfIssuedAttestation(배열)(선택 사항) | 자체 발급 입력을 설명합니다. |
accessTokens |
accessTokenAttestation(배열)(선택 사항) | 액세스 토큰 입력 설명 |
idTokenAttestation 형식
| 속성 | Type | 설명 |
|---|---|---|
mapping |
claimMapping(선택 사항) | 확인 가능한 자격 증명의 출력 클레임에 입력 클레임을 매핑하는 규칙 |
configuration |
문자열(URL) | ID 공급자의 구성 문서 위치 |
clientId |
string | ID 토큰을 가져올 때 사용할 클라이언트 ID |
redirectUri |
string | ID 토큰을 가져올 때 사용할 리디렉션 URI는 vcclient://openid/여야 함 |
scope |
string | ID 토큰을 가져올 때 사용할 공백으로 구분된 범위 목록 |
required |
부울(기본값 false) | 이 증명이 필요한지 여부 표시 |
idTokenHintAttestation 형식
| 속성 | Type | 설명 |
|---|---|---|
mapping |
claimMapping(선택 사항) | 확인 가능한 자격 증명의 출력 클레임에 입력 클레임을 매핑하는 규칙 |
required |
부울(기본값 false) | 이 증명이 필요한지 여부 표시 |
trustedIssuers |
문자열(배열) | 이 계약의 확인 가능한 자격 증명을 발급하도록 허용된 DID 목록 |
verifiablePresentationAttestation 형식
| 속성 | Type | 설명 |
|---|---|---|
mapping |
claimMapping(선택 사항) | 확인 가능한 자격 증명의 출력 클레임에 입력 클레임을 매핑하는 규칙 |
credentialType |
문자열(선택 사항) | 입력의 필수 자격 증명 형식 |
required |
부울(기본값 false) | 이 증명이 필요한지 여부 표시 |
trustedIssuers |
문자열(배열) | 이 계약의 확인 가능한 자격 증명을 발급하도록 허용된 DID 목록 |
selfIssuedAttestation 형식
| 속성 | Type | 설명 |
|---|---|---|
mapping |
claimMapping(선택 사항) | 확인 가능한 자격 증명의 출력 클레임에 입력 클레임을 매핑하는 규칙 |
required |
부울(기본값 false) | 이 증명이 필요한지 여부 표시 |
accessTokenAttestation 형식
| 속성 | Type | 설명 |
|---|---|---|
mapping |
claimMapping(선택 사항) | 확인 가능한 자격 증명의 출력 클레임에 입력 클레임을 매핑하는 규칙 |
required |
부울(기본값 false) | 이 증명이 필요한지 여부 표시 |
mappings속성에 지원되는inputClaim값은givenName,displayName,preferredLanguage,userPrincipalName,surname,jobTitle,photo입니다.
claimMapping 형식
| 속성 | Type | 설명 |
|---|---|---|
inputClaim |
string | 입력에서 사용할 클레임의 이름 |
outputClaim |
string | 확인 가능한 자격 증명의 클레임 이름 |
indexed |
부울(기본값 false) | 이 클레임 값이 검색에 사용되는지 여부를 나타냅니다. 지정된 계약에 대해 clientMapping 개체 하나만 인덱싱할 수 있습니다. |
required |
부울(기본값 false) | 이 매핑이 필요한지 여부 표시 |
type |
문자열(선택 사항) | 클레임 형식 |
customStatusEndpoint 형식
| 속성 | Type | 설명 |
|---|---|---|
url |
문자열(URL) | 사용자 지정 상태 엔드포인트의 URL |
type |
string | 엔드포인트의 형식입니다. |
다음과 같습니다.
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
"redirectUri": "vcclient://openid/",
"scope": "openid",
"mapping": [
{
"outputClaim": "givenName",
"required": false,
"inputClaim": "given_name",
"indexed": false
},
{
"outputClaim": "familyName",
"required": false,
"inputClaim": "family_name",
"indexed": true
}
],
"required": false
}
]
},
"validityInterval": 2592000,
"vc": {
"type": [
"BankofWoodgroveIdentity"
]
}
}
displayModel 형식
| 속성 | Type | 설명 |
|---|---|---|
locale |
string | 이 디스플레이의 로캘 |
credential |
displayCredential | 확인 가능한 자격 증명의 표시 속성 |
consent |
displayConsent | 확인 가능한 자격 증명이 발급될 때의 추가 데이터 |
claims |
displayClaims 배열 | 확인 가능한 자격 증명에 포함된 클레임에 대한 레이블 |
displayCredential 형식
| 속성 | Type | 설명 |
|---|---|---|
title |
string | 자격 증명의 제목 |
issuedBy |
string | 자격 증명 발급자의 이름 |
backgroundColor |
수(16진수) | 16진수 형식의 자격 증명 배경색(예: #FFAABB) |
textColor |
수(16진수) | 16진수 형식의 자격 증명 텍스트 색(예: #FFAABB) |
description |
string | 각 자격 증명과 함께 표시되는 추가 텍스트 |
logo |
displayCredentialLogo | 자격 증명에 사용할 로고 |
displayCredentialLogo 형식
| 속성 | Type | 설명 |
|---|---|---|
uri |
문자열(URL) | 로고의 uri입니다. URL인 경우 공용 인터넷을 통해 익명으로 연결할 수 있어야 합니다. |
description |
string | 로고에 대한 설명 |
displayConsent 형식
| 속성 | Type | 설명 |
|---|---|---|
title |
string | 동의의 제목 |
instructions |
string | 동의를 표시할 때 사용할 추가 텍스트 |
displayClaims 형식
| 속성 | Type | 설명 |
|---|---|---|
label |
string | 표시되는 클레임의 레이블 |
claim |
string | 레이블이 적용되는 클레임의 이름 |
type |
string | 클레임의 형식 |
description |
문자열(선택 사항) | 클레임에 대한 설명 |
다음과 같습니다.
{
"displays": [
{
"locale": "en-US",
"card": {
"backgroundColor": "#FFA500",
"description": "ThisisyourBankofWoodgroveIdentity",
"issuedBy": "BankofWoodgrove",
"textColor": "#FFFF00",
"title": "BankofWoodgroveIdentity",
"logo": {
"description": "Defaultbankofwoodgrovelogo",
"uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
List contracts
이 API는 지정된 인증 기관의 현재 테넌트에 구성된 모든 계약을 나열합니다.
HTTP 요청
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
예제 메시지:
{
"value":
[
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "test1",
"authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
"name": "test2",
"authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
}
]
}
Create contract
계약을 만들 때 이름은 테넌트에서 고유해야 합니다. 인증 기관을 여러 개 만든 경우 계약 이름은 모든 인증 기관에서 고유해야 합니다. 계약 이름은 발급 요청에 사용되는 계약 URL의 일부가 됩니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
예제 요청
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
응답 메시지
예제 메시지:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "GUID",
"name": "ExampleContractName1",
"issuerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"rules": "<rules JSON>",
"displays": [{<display JSON}],
"manifestUrl": "https://..."
}
Update contract
이 API를 사용하면 계약을 업데이트할 수 있습니다.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
요청 예제:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
응답 메시지
예제 메시지:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": true,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[],
"allowOverrideValidityIntervalOnIssuance": true
}
자격 증명
이 엔드포인트를 사용하면 발급된 확인 가능한 자격 증명을 검색하고 해지 상태를 확인하며 자격 증명을 해지할 수 있습니다.
메서드
| 메서드 | 반환 형식 | 설명 |
|---|---|---|
| Get credential | 자격 증명 | 자격 증명 속성 읽기 |
| Search credentials | 자격 증명 컬렉션 | 특정 클레임 값을 사용하여 자격 증명 목록 검색 |
| Revoke credential | 특정 자격 증명 해지 |
Get credential
이 API를 사용하면 특정 자격 증명을 검색하고 상태를 확인하여 해지 여부를 확인할 수 있습니다.
HTTP 요청
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
응답 메시지
예제 메시지
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Search credentials
특정 인덱스 클레임을 사용하여 확인 가능한 자격 증명을 검색할 수 있습니다. 해시만 저장되므로 특정 계산 값을 검색해야 합니다. 사용해야 하는 알고리즘은 Base64Encode(SHA256(contractid + 클레임 값))입니다. C#의 예제는 다음과 같습니다.
string claimvalue = "Bowen";
string contractid = "<...your-contract-id-value...>";
string output;
using (var sha256 = SHA256.Create())
{
var input = contractid + claimvalue;
byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
}
다음 요청에서는 계산된 값을 요청의 필터 매개 변수에 추가하는 방법을 보여 줍니다. 현재 filter=indexclaimhash eq 형식만 지원됩니다.
HTTP 요청
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
예제 메시지
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"status": "valid",
"issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
}
]
}
Revoke credential
이 API를 사용하면 특정 자격 증명을 해지할 수 있습니다. 검색 API를 사용하여 자격 증명을 검색한 후 특정 자격 증명 ID를 지정하여 자격 증명을 해지할 수 있습니다.
HTTP 요청
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드에 대한 요청 본문을 제공하지 마십시오.
응답 메시지
HTTP/1.1 204 No Content
Content-type: application/json
옵트아웃
이 메서드는 이 테넌트에서 확인 가능한 자격 증명 서비스의 모든 인스턴스를 완전히 제거합니다. 구성된 모든 계약을 제거합니다. 발급된 모든 확인 가능한 자격 증명 해지를 확인할 수 없습니다. 이 작업은 취소할 수 없습니다.
Warning
이 작업은 실행 취소될 수 없으며 발급된 확인 가능한 자격 증명과 생성된 계약을 모두 무효화합니다.
HTTP 요청
POST /v1.0/verifiableCredentials/optout
요청 헤더
| 헤더 | 값 |
|---|---|
| Authorization | 전달자(토큰). Required |
| 콘텐츠 형식 | application/json |
요청 본문
이 메서드의 요청 본문을 제공하지 마세요.
응답 메시지
응답 메시지 예제
HTTP/1.1 200 OK
Content-type: application/json
OK
설명
참고 항목
Key Vault에 대한 삭제 권한이 없으면 오류 메시지가 반환되고 계속 옵트아웃됩니다.
다음 단계
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기