다음을 통해 공유

확인 가능한 자격 증명 관리자 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, mail, 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에 대한 삭제 권한이 없으면 오류 메시지가 반환되고 계속 옵트아웃됩니다.

다음 단계