Bagikan melalui

API admin kredensial yang dapat diverifikasi

  • Artikel

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 Kebijakan Autentikasi. Peran Administrator Global juga memiliki izin ini tetapi hanya boleh digunakan jika tidak ada kombinasi peran lain yang memenuhi kebutuhan Anda. 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. Saat aplikasi 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. Proses ini dapat dipicu secara manual dengan menavigasi 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). Wajib
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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
    "verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
    "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 Dokumen DID
Kunci Penandatanganan Rotasi Otoritas Memutar kunci penandatanganan
Buat Kunci Penandatanganan Otoritas Membuat kunci penandatanganan
Menyinkronkan dengan Dokumen DID Otoritas Menyinkronkan dokumen DID dengan kunci penandatanganan baru
Buat Konfigurasi DID yang Terkenal
Memvalidasi konfigurasi DID yang Terkenal

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

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 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). Wajib
Content-Type application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

Pesan respons adalah array Otoritas

Contoh:

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

Membuat otoritas

Panggilan ini membuat kunci privat baru dan menyimpan kunci 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). Wajib
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). Wajib
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). Wajib
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 gagal, Anda mendapatkan respons 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). Wajib
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 layanan menghasilkan Dokumen DID, administrator harus menempatkan 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). Wajib
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. Ini mengunduh konfigurasi DID yang terkenal dan memvalidasi DID, dan tanda tangan.

Permintaan HTTP

POST /v1.0/verifiableCredentials/authorities/<authorityId>/validateWellKnownDidConfiguration

Header permintaan

Header Nilai
Authorization Token pembawa (token). Wajib
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 reregistrasi selesai, menyinkronkanWithDidDocument 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). Wajib
Content-Type application/json

Isi Permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

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
}

Membuat kunci penandatanganan

Kunci penandatanganan Create membuat kunci privat baru di Key Vault yang sudah ada untuk did:web authority. Dokumen DID harus didaftarkan ulang untuk mencerminkan pembaruan karena didDocumentStatus otoritas diubah menjadi outOfSync. Ketika dokumen DID didaftarkan ulang, panggil synchronizeWithDidDocument memberi tahu sistem untuk mulai menggunakan kunci baru untuk penandatanganan.

Permintaan HTTP

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

Header permintaan

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

Isi Permintaan

{
	"signingKeyCurve": "P-256"
}

Pesan respons

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

{
	"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
	"keyUrl": "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407",
	"curve": "P-256"
}

Menyinkronkan dengan Dokumen DID

Setelah memutar kunci penandatanganan, dokumen DID harus didaftarkan kembali untuk mencerminkan pembaruan. Ketika proses 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). Wajib
Content-Type application/json

Isi Permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

didDocumentStatus berubah dari outOfSync menjadi 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 input atau 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). Wajib
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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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 diatur ke true agar pengguna diberi tahu bahwa VC ini siap untuk dikeluarkan
issueNotificationAllowedToGroupOids array string groupId array ID grup tempat kredensial ini tersedia untuk
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 dapat diindeks per kontrak yang diberikan
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 nilainya adalah URL, nilai tersebut 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.z13.web.core.windows.net/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). Wajib
Content-Type application/json

Isi permintaan

Jangan sediakan isi permintaan untuk metode ini.

Pesan respons

Contoh pesan:

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

Buat kontrak

Saat Anda membuat kontrak, nama yang Anda gunakan harus unik di penyewa. Jika Anda membuat beberapa otoritas, nama kontrak harus unik di semua otoritas. Nama kontrak adalah 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). Wajib
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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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). Wajib
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.

Permintaan HTTP

GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

Header permintaan

Header Nilai
Authorization Token pembawa (token). Wajib
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). Wajib
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 menghapus semua instans 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 dibatalkan dan membatalkan semua kredensial yang dapat diverifikasi yang dikeluarkan dan kontrak yang dibuat.

Permintaan HTTP

POST /v1.0/verifiableCredentials/optout

Header permintaan

Header Nilai
Authorization Token pembawa (token). Wajib
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 mengembalikan pesan kesalahan dan masih menolak

Langkah berikutnya