API admin kredensial yang dapat diverifikasi

Artikel
03/12/2024

API Admin ID Terverifikasi Microsoft Entra memungkinkan Anda mengelola semua aspek layanan Kredensial yang Dapat Diverifikasi. API tersebut menawarkan cara untuk menyiapkan layanan baru, mengelola dan membuat kontrak kredensial yang Dapat Diverifikasi, mencabut kredensial yang Dapat Diverifikasi dan sepenuhnya menolak layanan juga.

API ditujukan untuk pengembang yang nyaman dengan API RESTful dan izin yang cukup pada penyewa Microsoft Entra untuk mengaktifkan layanan

URL Dasar

API Admin adalah server melalui HTTPS. Semua URL yang dirujuk dalam dokumentasi memiliki basis berikut: https://verifiedid.did.msidentity.com.

Autentikasi

API dilindungi melalui ID Microsoft Entra dan menggunakan token pembawa OAuth2. Token akses dapat untuk pengguna atau untuk aplikasi.

Token pembawa pengguna

Pendaftaran aplikasi harus memiliki Izin API untuk Verifiable Credentials Service Admin dan kemudian saat memperoleh token akses, aplikasi harus menggunakan cakupan 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access. Token akses harus untuk pengguna dengan peran administrator global atau administrator kebijakan autentikasi. Pengguna dengan pembaca global peran dapat melakukan panggilan API baca-saja.

Token pembawa aplikasi

Layanan ini Verifiable Credentials Service Admin mendukung izin aplikasi berikut.

Izin	Deskripsi
VerifiableCredential.Authority.ReadWrite	Izin untuk membaca/menulis objek otoritas
VerifiableCredential.Contract.ReadWrite	Izin untuk membaca/menulis objek kontrak
VerifiableCredential.Credential.Search	Izin untuk mencari kredensial yang akan dicabut
VerifiableCredential.Credential.Revoke	Izin untuk mencabut kredensial yang dikeluarkan sebelumnya
VerifiableCredential.Network.Read	Izin untuk membaca entri dari Jaringan ID Terverifikasi

Pendaftaran aplikasi harus memiliki Izin API untuk Verifiable Credentials Service Admin dan izin yang diperlukan dari tabel di atas. Saat memperoleh token akses, melalui alur kredensial klien, aplikasi harus menggunakan cakupan 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default.

Jika aplikasi berniat untuk membuat otoritas baru, aplikasi memerlukan dua hal. Pertama, pendaftaran aplikasi memerlukan VerifiableCredential.Authority.ReadWrite izin. Kedua, aplikasi harus memiliki Create Key izin dalam Kebijakan Akses Key Vaults. Jika aplikasi hanya membaca/menulis otoritas yang ada, aplikasi tidak memerlukan izin Key Vault.

Onboarding

API ini untuk membantu menciptakan lingkungan baru agar otoritas baru dapat disiapkan. API ini dapat dipicu secara manual dengan bernavigasi ke halaman kredensial yang Dapat Diverifikasi di portal Microsoft Azure juga. Anda hanya perlu memanggil API ini sekali dan hanya jika Anda ingin menyiapkan lingkungan baru dengan API saja.

Permintaan HTTP

POST /v1.0/verifiableCredentials/onboard

Gunakan titik akhir ini untuk menyelesaikan provisi layanan Kredensial yang Dapat Diverifikasi di penyewa Anda. Sistem membuat perwakilan layanan lainnya jika belum disediakan.

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Mengembalikan pesan

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
    "verifiableCredentialServicePrincipalId": "90e10a26-94cd-49d6-8cd7-cacb10f00686",
    "verifiableCredentialRequestServicePrincipalId": "870e10a26-94cd-49d6-8cd7-cacb10f00fe",
    "verifiableCredentialAdminServicePrincipalId": "760e10a26-94cd-49d6-8cd7-cacb10f00ab",
    "status": "Enabled"
}

Berulang kali memanggil API ini menghasilkan pesan pengembalian yang sama persis.

Otoritas

Titik akhir ini dapat digunakan untuk membuat atau memperbarui instans layanan Kredensial yang Dapat Diverifikasi.

Metode

Metode	Jenis Hasil	Deskripsi
Dapatkan Otoritas	Otoritas	Membaca properti otoritas
Cantumkan Otoritas	Array otoritas	Mendapatkan daftar semua Otoritas yang dapat dikonfigurasi/layanan kredensial yang dapat diverifikasi
Buat Otoritas	Otoritas	Membuat otoritas baru
Perbarui otoritas	Otoritas	Perbarui otoritas
Menghapus otoritas	Otoritas	Menghapus otoritas
Buat Konfigurasi DID yang Terkenal
Buat Dokumen DID
Memvalidasi konfigurasi DID yang Terkenal
Kunci Penandatanganan Rotasi	Otoritas	Memutar kunci penandatanganan
Menyinkronkan dengan Dokumen DID	Otoritas	Menyinkronkan dokumen DID dengan kunci penandatanganan baru

Mendapatkan otoritas

Ambil properti otoritas yang dikonfigurasi atau instans layanan kredensial yang dapat diverifikasi.

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId

Ganti :authorityId dengan nilai salah satu otoritas yang dikonfigurasi.

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini

Pesan respons

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ffea7eb3-0000-1111-2222-000000000000",
    "name": "ExampleAuthorityName",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/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/"
    }
}

Respons berisi properti berikut.

Jenis otoritas

Properti	Tipe	Deskripsi
`Id`	string	ID unik yang dibuat secara otomatis, yang dapat digunakan untuk mengambil atau memperbarui instans spesifik dari layanan kredensial yang dapat diverifikasi
`name`	string	Nama instans layanan kredensial yang dapat diverifikasi yang mudah diingat
`status`	string	status layanan, nilai ini akan selalu `enabled`
didModel	didModel	Informasi tentang DID dan kunci
keyVaultMetadata	data keyVaultMeta	Informasi tentang Key Vault yang digunakan

jenis didModel

Web

Properti	Tipe	Deskripsi
`did`	string	DID untuk instans layanan kredensial yang dapat diverifikasi ini
`signingKeys`	array string	URL ke kunci penandatanganan
`linkedDomainUrls`	array string	Domain yang ditautkan ke DID ini, mengharapkan satu entri tunggal
didModel	didModel	Informasi tentang DID dan kunci
`didDocumentStatus`	string	status DID, nilai selalu `published` untuk metode ini

jenis keyVaultMetadata

Properti	Tipe	Deskripsi
`subscriptionId`	string	Langganan Azure tempat Key Vault ini berada
`resourceGroup`	string	nama grup sumber daya dari Key Vault ini
`resourceName`	string	Nama Key Vault
`resourceUrl`	string	URL ke Key Vault ini

Mencantumkan otoritas

Mendapatkan semua otoritas yang dikonfigurasi atau layanan kredensial yang dapat diverifikasi untuk penyewa ini

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

Pesan respons adalah array Contoh Otoritas:

HTTP/1.1 200 OK
Content-type: application/json
{
    value:

    [
        {
            "id": "ffea7eb3-0000-1111-2222-000000000000",
            "name": "AuthorityName",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/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/"
            }
        }
    ]
}

Membuat otoritas

Panggilan ini membuat kunci privat baru, kunci pemulihan, dan kunci pembaruan, menyimpan kunci ini di Azure Key Vault yang ditentukan dan mengatur izin ke Key Vault ini untuk layanan kredensial yang dapat diverifikasi dan membuat DID baru dengan Dokumen DID yang sesuai.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Dalam isi permintaan, berikan representasi JSON berikut ini

Properti	Tipe	Deskripsi
`name`	string	Nama tampilan instans layanan ini
`linkedDomainUrl`	string	Domain yang ditautkan ke DID ini
`didMethod`	string	Harus berupa `web`
`keyVaultMetadata`	keyVaultMetadata	meta data untuk brankas kunci tertentu

Contoh pesan:

{
  "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/"
  }
}

Pesan respons

Bila berhasil, pesan respons akan berisi nama otoritas

Contoh pesan untuk 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
}

Contoh pesan untuk 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/"
    }
}

Keterangan

Anda dapat membuat beberapa otoritas dengan DID dan kunci privat mereka sendiri, ini tidak akan terlihat di UI portal Azure. Saat ini kami hanya mendukung 1 otoritas. Kami belum sepenuhnya menguji semua skenario dengan beberapa otoritas yang dibuat. Jika Anda mencoba hal ini, beri tahu kami tentang pengalaman Anda.

Perbarui otoritas

Metode ini dapat digunakan untuk memperbarui nama tampilan instans spesifik layanan kredensial yang dapat diverifikasi ini.

Permintaan HTTP

PATCH /v1.0/verifiableCredentials/authorities/:authorityId

Ganti nilai :authorityId dengan nilai ID otoritas yang ingin Anda perbarui.

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Dalam isi permintaan, berikan representasi JSON berikut.

Properti	Tipe	Deskripsi
`name`	string	Nama tampilan instans layanan ini

Contoh pesan

{
  "name":"ExampleIssuerName"
}

Menghapus otoritas

Metode ini dapat digunakan untuk menghapus otoritas. Saat ini hanya did:ion otoritas yang dapat dihapus. Saat Anda menghapus otoritas, kredensial ID Terverifikasi yang dikeluarkan menjadi tidak valid dan tidak dapat diverifikasi lagi karena otoritas penerbit hilang.

Permintaan HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

Ganti nilai :authorityId dengan nilai ID otoritas yang ingin Anda hapus.

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Tidak ada isi permintaan

Pesan respons

Contoh pesan respons:

Respons otoritas penghapusan berhasil.

HTTP/1.1 200 OK

Jika penghapusan otoritas berhasil tetapi pembersihan kunci Azure Key Vault telah gagal, Anda mendapatkan respons di bawah ini.

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"
    }
}

Kojnfigurasi DID yang terkenal

Metode generateWellknownDidConfiguration menghasilkan file did-configuration.json yang ditandatangani. File harus diunggah ke folder .well-known di akar situs web yang dihosting untuk domain di domain tertaut contoh kredensial yang dapat diverifikasi ini. Instruksi dapat ditemukan di sini.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Anda perlu menentukan salah satu domain di linkedDomains otoritas yang ditentukan.

{
    "domainUrl":"https://atest/"
}

Pesan respons

Contoh pesan respons:

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>..."
    ]
}

Simpan hasil ini dengan nama file did-configuration.json dan unggah file ini ke folder dan situs web yang benar. Jika Anda menentukan domain yang tidak ditautkan ke Dokumen DID/DID ini, Anda menerima kesalahan:

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/"
  }
}

Keterangan

Anda dapat mengarahkan beberapa DID ke domain yang sama. Jika Anda memilih konfigurasi ini, Anda perlu menggabungkan token yang dihasilkan dan memasukkannya ke dalam file did-configuration.json yang sama. File berisi array token ini.

Contohnya:

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbG..token1...<SNIP>...",
        "eyJhbG..token2...<SNIP>..."
    ]
}

Membuat dokumen DID

Panggilan ini menghasilkan Dokumen DID yang digunakan untuk pengidentifikasi DID:WEB. Setelah membuat Dokumen DID ini, administrator harus meletakkan file di lokasi https://domain/.well-known/did.json.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

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"
    ]
}

Komentar

Memerlukan penelepon untuk memiliki izin Daftar KUNCI di brankas kunci target.

Validasi konfigurasi DID yang terkenal

Panggilan ini memeriksa pengaturan DID Anda. Panggilan ini mengunduh konfigurasi DID yang terkenal dan memvalidasi jika DID yang benar digunakan dan tanda tangannya benar.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

HTTP/1.1 204 No Content
Content-type: application/json

Memutar kunci penandatanganan

Kunci penandatanganan putar membuat kunci privat baru untuk otoritas did:web. Dokumen DID harus didaftarkan ulang untuk mencerminkan pembaruan. Ketika ini selesai, synchronizeWithDidDocument memberi tahu sistem untuk mulai menggunakan kunci baru untuk penandatanganan.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi Permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

akan didDocumentStatus berubah menjadi 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
}

Menyinkronkan dengan Dokumen DID

Setelah memutar kunci penandatanganan, dokumen DID harus didaftarkan kembali untuk mencerminkan pembaruan. Ketika ini selesai, synchronizeWithDidDocument memberi tahu sistem untuk mulai menggunakan kunci baru untuk penandatanganan.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi Permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

Akan didDocumentStatus berubah dari outOfSync ke published pada panggilan yang berhasil.

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
}

Kontrak

Titik akhir ini memungkinkan Anda membuat kontrak baru, dan memperbarui kontrak yang ada. Kontrak terdiri dari dua bagian yang diwakili oleh dua definisi JSON. Informasi tentang cara merancang dan membuat kontrak secara manual dapat ditemukan di sini.

Definisi tampilan digunakan oleh administrator untuk mengontrol tampilan kredensial yang dapat diverifikasi, misalnya warna latar belakang, logo, dan judul kredensial yang dapat diverifikasi. File ini juga berisi klaim yang perlu disimpan di dalam kredensial yang dapat diverifikasi.
Definisi aturan berisi informasi tentang cara mengumpulkan dan mengumpulkan pengesahan seperti klaim yang dibuktikan sendiri, kredensial lain yang dapat diverifikasi sebagai masukan atau mungkin Token ID yang diterima setelah pengguna masuk ke penyedia identitas yang kompatibel dengan OIDC.

Metode

Metode	Jenis Hasil	Deskripsi
Dapatkan kontrak	Contract	Membaca properti Kontrak
Cantumkan kontrak	Kumpulan kontrak	Mendapatkan daftar semua kontrak yang dikonfigurasi
Membuat kontrak	Contract	Membuat kontainer baru
Perbarui kontrak	Contract	Perbarui kontrak

Mendapatkan kontrak

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

Ganti :authorityId dan :contractId dengan nilai otoritas dan kontrak yang benar.

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

contoh pesan:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": false,
    "manifestUrl": "...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": <rulesModel>,
    "displays": <displayModel[]>,
    "allowOverrideValidityIntervalOnIssuance": false
}

Respons berisi properti berikut

Jenis kontrak

Properti	Tipe	Deskripsi
`Id`	string	ID kontrak
`name`	string	Nama yang mudah diingat dari kontrak ini
`status`	string	Selalu `Enabled`
`manifestUrl`	string	URL ke kontrak yang digunakan dalam permintaan penerbitan
`issueNotificationEnabled`	Boolean	atur ke true jika pengguna akan diberi tahu VC ini siap untuk diterbitkan
`issueNotificationAllowedToGroupOids`	array string groupId	array ID grup kredensial ini akan ditawarkan kepada
`availableInVcDirectory`	Boolean	Apakah kontrak ini diterbitkan di Jaringan Kredensial yang Dapat Diverifikasi
aturan	rulesModel	definisi aturan
tampilkan	array displayModel	tampilkan definisi
`allowOverrideValidityIntervalOnIssuance`	Boolean	Jika panggilan API createIssuanceRequest diizinkan untuk mengambil alih kedaluwarsa kredensial. Ini hanya berlaku untuk alur idTokenHint .

Jenis rulesModel

Properti	Tipe	Deskripsi
`attestations`	pengesahan	menjelaskan input yang didukung untuk aturan
`validityInterval`	number	nilai ini menunjukkan masa pakai kredensial
`vc`	Array vcType	jenis untuk kontrak ini
`customStatusEndpoint`	[customStatusEndpoint] (#customstatusendpoint-type) (opsional)	titik akhir status untuk disertakan dalam kredensial yang dapat diverifikasi untuk kontrak ini

Jika properti properti customStatusEndpoint tidak ditentukan, maka anonymous titik akhir status digunakan.

jenis pengesahan

Properti	Tipe	Deskripsi
`idTokens`	idTokenAttestation (array) (opsional)	menjelaskan input token ID
`idTokenHints`	idTokenHintAttestation (array) (opsional)	menjelaskan input petunjuk token ID
`presentations`	verifiablePresentationAttestation (array) (opsional)	mendeskripsikan input presentasi yang dapat diverifikasi
`selfIssued`	selfIssuedAttestation (array) (opsional)	mendeskripsikan input yang dikeluarkan sendiri
`accessTokens`	accessTokenAttestation (array) (opsional)	mendeskripsikan input token akses

jenis idTokenAttestation

Properti	Tipe	Deskripsi
`mapping`	claimMapping (opsional)	aturan untuk memetakan klaim input ke dalam klaim output dalam kredensial yang dapat diverifikasi
`configuration`	string (url)	lokasi dokumen konfigurasi penyedia identitas
`clientId`	string	ID klien yang akan digunakan saat mendapatkan token ID
`redirectUri`	string	alihkan uri untuk digunakan saat mendapatkan token ID HARUS vcclient://openid/
`scope`	string	daftar cakupan yang dibatasi ruang untuk digunakan saat mendapatkan token ID
`required`	boolean (false default)	menunjukkan apakah pengesahan ini diperlukan atau tidak

Jenis idTokenHintAttestation

Properti	Tipe	Deskripsi
`mapping`	claimMapping (opsional)	aturan untuk memetakan klaim input ke dalam klaim output dalam kredensial yang dapat diverifikasi
`required`	boolean (false default)	menunjukkan apakah pengesahan ini diperlukan atau tidak
`trustedIssuers`	string (array)	daftar DID yang diizinkan untuk menerbitkan kredensial yang dapat diverifikasi untuk kontrak ini

verifiablePresentationAttestation type

Properti	Tipe	Deskripsi
`mapping`	claimMapping (opsional)	aturan untuk memetakan klaim input ke dalam klaim output dalam kredensial yang dapat diverifikasi
`credentialType`	string (opsional)	jenis mandat input yang diperlukan
`required`	boolean (false default)	menunjukkan apakah pengesahan ini diperlukan atau tidak
`trustedIssuers`	string (array)	daftar DID yang diizinkan untuk menerbitkan kredensial yang dapat diverifikasi untuk kontrak ini

Jenis selfIssuedAttestation

Properti	Tipe	Deskripsi
`mapping`	claimMapping (opsional)	aturan untuk memetakan klaim input ke dalam klaim output dalam kredensial yang dapat diverifikasi
`required`	boolean (false default)	menunjukkan apakah pengesahan ini diperlukan atau tidak

jenis accessTokenAttestation

Properti	Tipe	Deskripsi
`mapping`	claimMapping (opsional)	aturan untuk memetakan klaim input ke dalam klaim output dalam kredensial yang dapat diverifikasi
`required`	boolean (false default)	menunjukkan apakah pengesahan ini diperlukan atau tidak

Nilai inputClaim yang didukung untuk properti mappings adalah: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, jobTitle, photo.

jenis claimMapping

Properti	Tipe	Deskripsi
`inputClaim`	string	nama klaim yang akan digunakan dari input
`outputClaim`	string	nama klaim dalam kredensial yang dapat diverifikasi
`indexed`	boolean (false default)	menunjukkan apakah nilai klaim ini digunakan untuk pencarian; hanya satu objek clientMapping yang diizinkan untuk diindeks untuk kontrak tertentu
`required`	boolean (false default)	menunjukkan apakah pemetaan ini diperlukan atau tidak
`type`	string (opsional)	jenis klaim

jenis customStatusEndpoint

Properti	Tipe	Deskripsi
`url`	string (url)	url titik akhir status kustom
`type`	string	jenis titik akhir

contoh:

"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"
        ]
    }
}

jenis displayModel

Properti	Tipe	Deskripsi
`locale`	string	lokal tampilan ini
`credential`	displayCredential	properti tampilan kredensial yang dapat diverifikasi
`consent`	displayConsent	data tambahan saat kredensial yang dapat diverifikasi dikeluarkan
`claims`	array displayClaims	label untuk klaim yang disertakan dalam kredensial yang dapat diverifikasi

jenis displayCredential

Properti	Tipe	Deskripsi
`title`	string	judul mandat
`issuedBy`	string	nama penerbit mandat
`backgroundColor`	nomor (hex)	warna latar belakang kredensial dalam hex, misalnya, #FFAABB
`textColor`	nomor (hex)	warna teks kredensial dalam hex, misalnya, #FFAABB
`description`	string	teks tambahan ditampilkan di samping setiap mandat
`logo`	displayCredentialLogo	logo yang akan digunakan untuk mandat

jenis displayCredentialLogo

Properti	Tipe	Deskripsi
`uri`	string (uri)	uri logo. Jika ini adalah URL, url harus dapat dijangkau melalui internet publik secara anonim.
`description`	string	deskripsi logo

jenis displayConsent

Properti	Tipe	Deskripsi
`title`	string	judul persetujuan
`instructions`	string	teks tambahan yang akan digunakan saat menampilkan persetujuan

jenis displayClaims

Properti	Tipe	Deskripsi
`label`	string	label klaim dalam tampilan
`claim`	string	nama klaim yang diterapkan label
`type`	string	jenis klaim
`description`	string (opsional)	deskripsi dari pekerjaan

contoh:

{
  "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"
                }
            ]
        }
    ]
}

Cantumkan kontrak

API ini mencantumkan semua kontrak yang dikonfigurasi di penyewa saat ini untuk otoritas yang ditentukan.

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

contoh pesan:

{
    "value":
    [
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
            "name": "test1",
            "authorityId": "ffea7eb3-0000-1111-2222-000000000000",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
            "name": "test2",
            "authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        }
    ]
}

Buat kontrak

Saat membuat kontrak, nama harus unik di penyewa. Jika Anda telah membuat beberapa otoritas, nama kontrak harus unik di semua otoritas. Nama kontrak akan menjadi bagian dari URL kontrak, yang digunakan dalam permintaan penerbitan.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Contoh permintaan

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

Pesan respons

Contoh pesan:

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://..."
}

Perbarui kontrak

API ini memungkinkan Anda memperbarui kontrak.

PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid

Contoh permintaan:

{
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],}
    "availableInVcDirectory": true
    "allowOverrideValidityIntervalOnIssuance": true
}

Pesan respons

Contoh pesan:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": true,
    "manifestUrl": "https://...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": rulesModel,
    "displays": displayModel[],
    "allowOverrideValidityIntervalOnIssuance": true
}

Informasi Masuk

Titik akhir ini memungkinkan Anda mencari kredensial yang dapat diverifikasi yang dikeluarkan, memeriksa status pencabutan, dan mencabut kredensial.

Metode

Metode	Jenis Hasil	Deskripsi
Dapatkan kredensial	Kredensial	Baca properti Kredensial
Telusuri kredensial	Kumpulan kredensial	Mencari daftar kredensial dengan nilai klaim tertentu
Mencabut kredensial		Mencabut kredensial tertentu

Dapatkan kredensial

API ini memungkinkan Anda mengambil kredensial tertentu dan memeriksa statusnya untuk melihat apakah kredensial itu dicabut atau tidak.

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Pesan respons

Contoh pesan

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
    "contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
    "status": "valid",
    "issuedAt": "2017-09-13T21:59:23.9868631Z"
}

Mencari kredensial

Anda dapat menelusuri kredensial yang dapat diverifikasi dengan klaim indeks tertentu. Karena hanya hash yang disimpan, Anda perlu mencari nilai yang dihitung secara spesifik. Algoritme yang perlu Anda gunakan adalah: Base64Encode(SHA256(contractid + claim value)) Contoh dalam C# terlihat seperti ini:

  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 );
  }

Permintaan berikut menunjukkan cara menambahkan nilai terhitung ke parameter filter permintaan. Saat ini hanya format eq filter=indexclaimhash yang didukung.

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

Contoh pesan

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"
        }
    ]
}

Mencabut kredensial

API ini memungkinkan Anda mencabut kredensial tertentu, setelah Anda mencari kredensial dengan menggunakan API penelusuran, kredensial dapat dicabut dengan menentukan ID kredensial tertentu.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

HTTP/1.1 204 No Content
Content-type: application/json

Penolakan

Metode ini akan sepenuhnya menghapus semua contoh layanan kredensial yang dapat diverifikasi di penyewa ini. Metode tersebut menghapus semua kontrak yang dikonfigurasi. Setiap kredensial yang dapat diverifikasi yang dikeluarkan tidak dapat diperiksa untuk pencabutan. Tindakan ini tidak dapat diurungkan.

Peringatan

Tindakan ini tidak dapat diurungkan dan akan membatalkan semua kredensial yang dapat diverifikasi dan kontrak yang dibuat.

Permintaan HTTP

POST /v1.0/verifiableCredentials/optout

Header permintaan

Header	Nilai
Authorization	Token pembawa (token). Diperlukan
Content-Type	application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini

Pesan respons

Contoh pesan respons

HTTP/1.1 200 OK
Content-type: application/json

OK

Komentar

Catatan

Jika Anda tidak memiliki izin penghapusan di Key Vault, kami akan memunculkan pesan kesalahan dan tetap menolaknya

Share via

API admin kredensial yang dapat diverifikasi

URL Dasar

Autentikasi

Token pembawa pengguna

Token pembawa aplikasi

Onboarding

Permintaan HTTP

Header permintaan

Isi permintaan

Mengembalikan pesan

Otoritas

Metode

Mendapatkan otoritas

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Jenis otoritas

jenis didModel

Web

jenis keyVaultMetadata

Mencantumkan otoritas

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Membuat otoritas

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Keterangan

Perbarui otoritas

Permintaan HTTP

Header permintaan

Isi permintaan

Menghapus otoritas

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Kojnfigurasi DID yang terkenal

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Keterangan

Membuat dokumen DID

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Komentar

Validasi konfigurasi DID yang terkenal

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Memutar kunci penandatanganan

Permintaan HTTP

Header permintaan

Isi Permintaan

Pesan respons

Menyinkronkan dengan Dokumen DID

Permintaan HTTP

Header permintaan

Isi Permintaan

Pesan respons

Kontrak

Metode

Mendapatkan kontrak

Permintaan HTTP

Header permintaan

Isi permintaan

Pesan respons

Jenis kontrak

Jenis rulesModel

jenis pengesahan

jenis idTokenAttestation