Doğrulanabilir kimlik bilgileri yönetici API'si
Microsoft Entra Kimlik Doğrulama Yönetici API'si, Doğrulanabilir Kimlik Bilgileri hizmetinin tüm yönlerini yönetmenize olanak tanır. Yepyeni bir hizmet ayarlamak, Doğrulanabilir Kimlik Bilgileri sözleşmelerini yönetmek ve oluşturmak, Doğrulanabilir Kimlik Bilgilerini iptal etmek ve hizmeti tamamen geri çevirmek için bir yol sunar.
API, RESTful API'leri ve hizmeti etkinleştirmek için Microsoft Entra kiracısı üzerinde yeterli izinlere sahip geliştiricilere yöneliktir
Yönetici API'si HTTPS üzerinden sunucudur. Belgelerde başvuruda bulunılan tüm URL'ler aşağıdaki temele sahiptir: https://verifiedid.did.msidentity.com
.
API, Microsoft Entra Kimliği ile korunur ve OAuth2 taşıyıcı belirteçlerini kullanır. Erişim belirteci bir kullanıcı veya uygulama için olabilir.
Uygulama kaydı için Verifiable Credentials Service Admin
API İznine sahip olması ve erişim belirtecini alırken uygulamanın kapsamı 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
kullanması gerekir. Erişim belirteci Genel Yönetici veya kimlik doğrulama ilkesi yönetici rolüne sahip bir kullanıcı için olmalıdır. Rol genel okuyucusu olan bir kullanıcı salt okunur API çağrıları gerçekleştirebilir.
Hizmet Verifiable Credentials Service Admin
aşağıdaki uygulama izinlerini destekler.
İzin | Açıklama |
---|---|
VerifiableCredential.Authority.ReadWrite | Okuma/yazma yetkilisi nesneleri için izin |
VerifiableCredential.Contract.ReadWrite | Sözleşme nesnelerini okuma/yazma izni |
VerifiableCredential.Credential.Search | İptal etmek için kimlik bilgisi arama izni |
VerifiableCredential.Credential.Revoke | Daha önce verilen bir kimlik bilgilerini iptal etme izni |
VerifiableCredential.Network.Read | Doğrulanmış Kimlik Ağı'ndan girdileri okuma izni |
Uygulama kaydı için Verifiable Credentials Service Admin
API İznine ve yukarıdaki tablodan gerekli izinlere sahip olması gerekir. Erişim belirtecini alırken, istemci kimlik bilgileri akışı aracılığıyla uygulama kapsamını 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
kullanmalıdır.
Uygulama yeni bir yetkili oluşturmayı planlıyorsa iki şeye ihtiyacı vardır. İlk olarak, uygulama kaydının izne VerifiableCredential.Authority.ReadWrite
ihtiyacı vardır. İkinci olarak, uygulamanın Key Vaults Erişim İlkeleri'nde izni olması Create Key
gerekir. Uygulama yalnızca mevcut yetkilileri okur/yazarsa Key Vault izni gerekmez.
Bu API, yeni yetkililerin ayarlanabilmesi için yeni bir ortam oluşturulmasına yardımcı olur. Bu, Azure portalındaki Doğrulanabilir Kimlik Bilgileri sayfasına da giderek el ile tetiklenebilir. Bu API'yi yalnızca bir kez ve yalnızca API ile yepyeni bir ortam ayarlamak istiyorsanız çağırmanız gerekir.
POST /v1.0/verifiableCredentials/onboard
Kiracınızda Doğrulanabilir Kimlik Bilgileri hizmetinin sağlanmasını tamamlamak için bu uç noktayı kullanın. Sistem, hizmet sorumlularının geri kalanını henüz sağlanmamışsa oluşturur.
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
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"
}
Bu API'nin tekrar tekrar çağrılması, tam olarak aynı dönüş iletisine neden olur.
Bu uç nokta, Doğrulanabilir Kimlik Bilgileri hizmet örneğini oluşturmak veya güncelleştirmek için kullanılabilir.
Yöntemler | Dönüş Türü | Açıklama |
---|---|---|
YetkiliYi Al | Yetkili | Yetkilinin özelliklerini okuma |
Liste Yetkilisi | Yetkili dizisi | Yapılandırılmış tüm Yetkililerin/doğrulanabilir kimlik bilgisi hizmetlerinin listesini alma |
Yetkili Oluştur | Yetkili | Yeni bir yetkili oluşturma |
Güncelleştirme yetkilisi | Yetkili | Güncelleştirme yetkilisi |
Yetkiliyi silme | Yetkili | Yetkiliyi silme |
İyi Bilinen DID Yapılandırması Oluşturma | ||
DID Belgesi Oluştur | ||
İyi bilinen DID yapılandırmasını doğrulama | ||
İmzalama Anahtarını Döndür | Yetkili | İmzalama anahtarını döndürme |
DID Belgesi ile eşitle | Yetkili | DID belgesini yeni imzalama anahtarıyla eşitleme |
Yapılandırılmış bir yetkilinin veya doğrulanabilir kimlik bilgisi hizmeti örneğinin özelliklerini alın.
GET /v1.0/verifiableCredentials/authorities/:authorityId
öğesini :authorityId
yapılandırılan yetkililerden birinin değeriyle değiştirin.
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için istek gövdesi sağlama
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/"
}
}
Yanıt aşağıdaki özellikleri içerir.
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
Id |
Dize | Doğrulanabilir kimlik bilgisi hizmetinin belirli bir örneğini almak veya güncelleştirmek için kullanılabilen, otomatik olarak oluşturulan benzersiz kimlik |
name |
Dize | Doğrulanabilir kimlik bilgisi hizmetinin bu örneğinin kolay adı |
status |
Dize | durumunda, bu değer her zaman enabled |
didModel | didModel | DID ve anahtarlar hakkında bilgi |
keyVaultMetadata | keyVaultMeta verileri | Kullanılan Key Vault hakkında bilgi |
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
did |
Dize | Bu doğrulanabilir kimlik bilgisi hizmeti örneği için DID |
signingKeys |
dize dizisi | İmzalama anahtarının URL'si |
linkedDomainUrls |
dize dizisi | Bu DID'ye bağlı etki alanları, tek bir giriş bekleniyor |
didModel | didModel | DID ve anahtarlar hakkında bilgi |
didDocumentStatus |
Dize | DID durumu, değer her zaman published bu yöntem içindir |
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
subscriptionId |
Dize | Bu Key Vault'un bulunduğu Azure aboneliği |
resourceGroup |
Dize | bu Key Vault'tan kaynak grubunun adı |
resourceName |
Dize | Key Vault adı |
resourceUrl |
Dize | Bu Key Vault URL'si |
Bu kiracı için tüm yapılandırılmış yetkilileri veya doğrulanabilir kimlik bilgileri hizmetlerini alma
GET /v1.0/verifiableCredentials/authorities
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi bir Yetkili dizisidir
Örnek:
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/"
}
}
]
}
Bu çağrı yeni bir özel anahtar, kurtarma anahtarı ve güncelleştirme anahtarı oluşturur, bu anahtarları belirtilen Azure Key Vault'ta depolar ve doğrulanabilir kimlik bilgisi hizmeti için bu Key Vault izinlerini ayarlar ve ilgili DID Belgesi ile yeni bir DID oluşturur.
POST /v1.0/verifiableCredentials/authorities
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesinde aşağıdakilerin bir JSON gösterimini sağlayın
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
name |
Dize | Hizmetin bu örneğinin görünen adı |
linkedDomainUrl |
Dize | Bu DID'ye bağlı etki alanı |
didMethod |
Dize | Olmalıdır web |
keyVaultMetadata |
keyVaultMetadata | belirli anahtar kasası için meta veriler |
Örnek ileti:
{
"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/"
}
}
Başarılı olduğunda yanıt iletisi yetkilinin adını içerir
did:web için örnek ileti:
{
"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 için örnek ileti:
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/"
}
}
Kendi DID ve özel anahtarlarıyla birden çok yetkili oluşturabilirsiniz, bunlar Azure portalının kullanıcı arabiriminde görünmez. Şu anda yalnızca 1 yetkiliye sahip olmayı destekliyoruz. Oluşturulan birden çok yetkiliye sahip tüm senaryoları tam olarak test etmedik. Bunu deniyorsanız lütfen deneyiminizi bize bildirin.
Bu yöntem, doğrulanabilir kimlik bilgisi hizmetinin bu özel örneğinin görünen adını güncelleştirmek için kullanılabilir.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
değerini :authorityId
güncelleştirmek istediğiniz yetkili kimliğinin değeriyle değiştirin.
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesinde aşağıdakilerin bir JSON gösterimini sağlayın.
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
name |
Dize | Hizmetin bu örneğinin görünen adı |
Örnek ileti
{
"name":"ExampleIssuerName"
}
Bu yöntem bir yetkiliyi silmek için kullanılabilir. Şu anda yalnızca did:ion
yetkililer silinebilir. Bir yetkiliyi sildiğinizde, verilen Doğrulanmış Kimlik kimlik bilgileri geçersiz hale gelir ve veren yetkili gittiği için artık doğrulanamaz.
DELETE /beta/verifiableCredentials/authorities/:authorityId
değerini :authorityId
silmek istediğiniz yetkili kimliğinin değeriyle değiştirin.
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi yok
Örnek yanıt iletisi:
Başarılı silme yetkilisi yanıtı.
HTTP/1.1 200 OK
Yetki silme işlemi başarılı olduysa ancak Azure Key Vault anahtarlarını temizleme işlemi başarısız olduysa aşağıdaki yanıtı alırsınız.
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"
}
}
generateWellknownDidConfiguration
yöntemi, imzalı did-configuration.json dosyasını oluşturur. Dosya, bu doğrulanabilir kimlik bilgisi örneğinin .well-known
bağlı etki alanındaki etki alanı için barındırılan web sitesinin kökündeki klasöre yüklenmelidir. Yönergeleri burada bulabilirsiniz.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Belirtilen yetkilinin linkedDomains içindeki etki alanlarından birini belirtmeniz gerekir.
{
"domainUrl":"https://atest/"
}
Örnek yanıt iletisi:
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>..."
]
}
Bu sonucu did-configuration.json dosya adıyla kaydedin ve bu dosyayı doğru klasöre ve web sitesine yükleyin. Bu DID/DID Belgesine bağlı olmayan bir etki alanı belirtirseniz bir hata alırsınız:
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/"
}
}
Aynı etki alanına birden çok DD işaret edebilirsiniz. Bu yapılandırmayı seçerseniz, oluşturulan belirteçleri birleştirmeniz ve aynı did-configuration.json dosyasına yerleştirmeniz gerekir. Dosya bu belirteçlerden oluşan bir dizi içerir.
Örneğin:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Bu çağrı, DID:WEB tanımlayıcıları için kullanılan DID Belgesini oluşturur. Bu DID Belgesini oluşturdıktan sonra, yöneticinin dosyayı konuma yerleştirmesi https://domain/.well-known/did.json gerekir.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
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"
]
}
Çağıranın hedef anahtar kasasında ANAHTAR Listesi izinlerine sahip olmasını gerektirir.
Bu çağrı, DID kurulumunuzu denetler. İyi bilinen DID yapılandırmasını indirir ve doğru DID'nin kullanılıp kullanılmadığını ve imzanın doğru olup olmadığını doğrular.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
HTTP/1.1 204 No Content
Content-type: application/json
İmzalama anahtarını döndür, did:web yetkilisi için yeni bir özel anahtar oluşturur. DID belgesi, güncelleştirmeyi yansıtacak şekilde yeniden kaydedilmelidir. Bu işlem tamamlandığında synchronizeWithDidDocument sisteme imzalama için yeni anahtarı kullanmaya başlamasını söyler.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
didDocumentStatus
olarak değişiroutOfSync
.
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
}
İmzalama anahtarı döndürüldikten sonra, DID belgesi güncelleştirmeyi yansıtacak şekilde yeniden kaydedilmelidir. Bu işlem tamamlandığında synchronizeWithDidDocument sisteme imzalama için yeni anahtarı kullanmaya başlamasını söyler.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
didDocumentStatus
başarılı bir çağrıda olarak published
outOfSync
değişir.
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
}
Bu uç nokta, yeni sözleşmeler oluşturmanıza ve mevcut sözleşmeleri güncelleştirmenize olanak tanır. Sözleşmeler iki JSON tanımıyla temsil edilen iki bölümden oluşur. El ile sözleşme tasarlama ve oluşturma hakkında bilgileri burada bulabilirsiniz.
- Görüntü tanımı, yöneticiler tarafından doğrulanabilir kimlik bilgilerinin görünümünü denetlemek için kullanılır; örneğin arka plan rengi, logo ve doğrulanabilir kimlik bilgilerinin başlığı. Bu dosya, doğrulanabilir kimlik bilgileri içinde depolanması gereken talepleri de içerir.
- Kural tanımı, kendi kendini doğrulanmış beyanlar, giriş olarak doğrulanabilir başka bir kimlik bilgisi veya bir kullanıcı OIDC uyumlu bir kimlik sağlayıcısında oturum açtıktan sonra alınan kimlik belirteci gibi kanıtlamaların nasıl toplanıp toplandığına ilişkin bilgileri içerir.
Yöntemler | Dönüş Türü | Açıklama |
---|---|---|
Sözleşme alma | Contract | Sözleşmenin özelliklerini okuma |
Sözleşmeleri listeleme | Sözleşme koleksiyonu | Yapılandırılmış tüm sözleşmelerin listesini alma |
Sözleşme oluşturma | Contract | Yeni sözleşme oluşturma |
Sözleşmeyi güncelleştirme | Contract | Sözleşmeyi güncelleştirme |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
ve :contractId
değerini :authorityId
yetkilinin ve sözleşmenin doğru değeriyle değiştirin.
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
örnek ileti:
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
}
Yanıt aşağıdaki özellikleri içerir
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
Id |
Dize | sözleşme kimliği |
name |
Dize | Bu sözleşmenin kolay adı |
status |
Dize | Her zaman Enabled |
manifestUrl |
Dize | Verme isteğinde kullanılan sözleşmenin URL'si |
issueNotificationEnabled |
boolean | kullanıcılara bildirim gönderilirse true olarak ayarlayın. Bu VC, verilmeye hazır |
issueNotificationAllowedToGroupOids |
groupId dizeleri dizisi | bu kimlik bilgilerinin sunulacağı grup kimlikleri dizisi |
availableInVcDirectory |
boolean | Bu sözleşme Doğrulanabilir Kimlik Bilgileri Ağı'nda mı yayımlandı? |
kurallar | rulesModel | kural tanımı |
Görüntü -ler | displayModel dizisi | tanımları görüntüleme |
allowOverrideValidityIntervalOnIssuance |
boolean | createIssuanceRequest API çağrısının kimlik bilgilerinin süre sonunu geçersiz kılmasına izin veriliyorsa. Bu yalnızca idTokenHint akışları için geçerlidir. |
Özellik | Türü | Açıklama |
---|---|---|
attestations |
kanıtlamalar | kurallar için desteklenen girişleri açıklama |
validityInterval |
Numara | bu değer, kimlik bilgilerinin kullanım ömrünü gösterir |
vc |
vcType dizisi | bu sözleşmenin türleri |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint türü) (isteğe bağlı) | bu sözleşme için doğrulanabilir kimlik bilgilerine eklenecek durum uç noktası |
Özellik customStatusEndpoint
özelliği belirtilmezse durum anonymous
uç noktası kullanılır.
Özellik | Türü | Açıklama |
---|---|---|
idTokens |
idTokenAttestation (dizi) (isteğe bağlı) | kimlik belirteci girişlerini açıklar |
idTokenHints |
idTokenHintAttestation (dizi) (isteğe bağlı) | kimlik belirteci ipucu girişlerini açıklar |
presentations |
verifiablePresentationAttestation (dizi) (isteğe bağlı) | doğrulanabilir sunu girişlerini açıklar |
selfIssued |
selfIssuedAttestation (dizi) (isteğe bağlı) | kendi kendine verilen girişleri açıklar |
accessTokens |
accessTokenAttestation (dizi) (isteğe bağlı) | erişim belirteci girişlerini açıklar |
Özellik | Türü | Açıklama |
---|---|---|
mapping |
claimMapping (isteğe bağlı) | doğrulanabilir kimlik bilgilerindeki çıkış taleplerine giriş beyanlarını eşleme kuralları |
configuration |
dize (url) | kimlik sağlayıcısının yapılandırma belgesinin konumu |
clientId |
Dize | kimlik belirtecini alırken kullanılacak istemci kimliği |
redirectUri |
Dize | kimlik belirtecini alırken kullanılacak yeniden yönlendirme uri'si vcclient://openid/ |
scope |
Dize | kimlik belirtecini alırken kullanılacak kapsamların boşlukla ayrılmış listesi |
required |
boole (varsayılan yanlış) | bu kanıtlamanın gerekli olup olmadığını gösterir |
Özellik | Türü | Açıklama |
---|---|---|
mapping |
claimMapping (isteğe bağlı) | doğrulanabilir kimlik bilgilerindeki çıkış taleplerine giriş beyanlarını eşleme kuralları |
required |
boole (varsayılan yanlış) | bu kanıtlamanın gerekli olup olmadığını gösterir |
trustedIssuers |
dize (dizi) | bu sözleşme için doğrulanabilir kimlik bilgilerini vermesine izin verilen DD'lerin listesi |
Özellik | Türü | Açıklama |
---|---|---|
mapping |
claimMapping (isteğe bağlı) | doğrulanabilir kimlik bilgilerindeki çıkış taleplerine giriş beyanlarını eşleme kuralları |
credentialType |
dize (isteğe bağlı) | girişin gerekli kimlik bilgisi türü |
required |
boole (varsayılan yanlış) | bu kanıtlamanın gerekli olup olmadığını gösterir |
trustedIssuers |
dize (dizi) | bu sözleşme için doğrulanabilir kimlik bilgilerini vermesine izin verilen DD'lerin listesi |
Özellik | Türü | Açıklama |
---|---|---|
mapping |
claimMapping (isteğe bağlı) | doğrulanabilir kimlik bilgilerindeki çıkış taleplerine giriş beyanlarını eşleme kuralları |
required |
boole (varsayılan yanlış) | bu kanıtlamanın gerekli olup olmadığını gösterir |
Özellik | Türü | Açıklama |
---|---|---|
mapping |
claimMapping (isteğe bağlı) | doğrulanabilir kimlik bilgilerindeki çıkış taleplerine giriş beyanlarını eşleme kuralları |
required |
boole (varsayılan yanlış) | bu kanıtlamanın gerekli olup olmadığını gösterir |
özelliği için desteklenen
inputClaim
değerler şunlardır:givenName
,displayName
,preferredLanguage
,userPrincipalName
, ,surname
,jobTitle
photo
.mappings
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
inputClaim |
Dize | girişten kullanılacak talebin adı |
outputClaim |
Dize | doğrulanabilir kimlik bilgilerindeki talebin adı |
indexed |
boole (varsayılan yanlış) | bu talebin değerinin arama için kullanılıp kullanılmadığını gösterir; Belirli bir sözleşme için yalnızca bir clientMapping nesnesinin dizine alınmasına izin verilir |
required |
boole (varsayılan yanlış) | bu eşlemenin gerekli olup olmadığını gösterir |
type |
dize (isteğe bağlı) | talep türü |
Özellik | Türü | Açıklama |
---|---|---|
url |
dize (url) | özel durum uç noktasının URL'si |
type |
Dize | uç noktanın türü |
örnek:
"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"
]
}
}
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
locale |
Dize | bu ekranın yerel ayarı |
credential |
displayCredential | doğrulanabilir kimlik bilgilerinin görüntü özellikleri |
consent |
displayConsent | doğrulanabilir kimlik bilgileri verildiğinde ek veriler |
claims |
displayClaims dizisi | doğrulanabilir kimlik bilgilerine dahil edilen talepler için etiketler |
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
title |
Dize | kimlik bilgilerinin başlığı |
issuedBy |
Dize | kimlik bilgisi verenin adı |
backgroundColor |
sayı (onaltılık) | onaltılık kimlik bilgilerinin arka plan rengi, örneğin, #FFAABB |
textColor |
sayı (onaltılık) | onaltılık kimlik bilgilerinin metin rengi, örneğin, #FFAABB |
description |
Dize | her kimlik bilgisi ile birlikte görüntülenen ek metin |
logo |
displayCredentialLogo | kimlik bilgisi için kullanılacak logo |
Özellik | Türü | Açıklama |
---|---|---|
uri |
dize (uri) | logonun uri'sini seçin. Bu bir URL ise, genel İnternet üzerinden anonim olarak erişilebilir olmalıdır. |
description |
Dize | logo açıklaması |
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
title |
Dize | onayın başlığı |
instructions |
Dize | onay görüntülenirken kullanılacak ek metin |
Özellik | Türü | Veri Akışı Açıklaması |
---|---|---|
label |
Dize | görüntülenen talebin etiketi |
claim |
Dize | etiketin uygulandığı talebin adı |
type |
Dize | talebin türü |
description |
dize (isteğe bağlı) | talebin açıklaması |
örnek:
{
"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"
}
]
}
]
}
Bu API, belirtilen yetkili için geçerli kiracıda yapılandırılan tüm sözleşmeleri listeler.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
örnek ileti:
{
"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}]
}
]
}
Sözleşme oluştururken adın kiracıda benzersiz olması gerekir. Birden çok yetkili oluşturmuş olmanız durumunda, sözleşme adının tüm makamlar arasında benzersiz olması gerekir. Sözleşmenin adı, verme isteklerinde kullanılan sözleşme URL'sinin bir parçası olacaktır.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Örnek istek
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Örnek ileti:
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://..."
}
Bu API Sözleşmeyi güncelleştirmenize olanak tanır.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Örnek istek:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Örnek ileti:
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
}
Bu uç nokta verilen doğrulanabilir kimlik bilgilerini aramanıza, iptal durumunu denetlemenize ve kimlik bilgilerini iptal etmenizi sağlar.
Yöntemler | Dönüş Türü | Açıklama |
---|---|---|
Kimlik bilgilerini alma | Referans | Kimlik Bilgilerinin özelliklerini okuma |
Arama kimlik bilgileri | Kimlik bilgisi koleksiyonu | Belirli bir talep değerine sahip kimlik bilgileri listesinde arama |
Kimlik bilgilerini iptal etme | Belirli kimlik bilgilerini iptal etme |
Bu API, belirli bir kimlik bilgilerini almanıza ve iptal edilip iptal edilmediğini görmek için durumu denetlemenize olanak tanır.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Örnek ileti
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Belirli dizin taleplerine sahip doğrulanabilir kimlik bilgilerini arayabilirsiniz. Yalnızca bir karma depolandığından, belirli bir hesaplanan değeri aramanız gerekir. Kullanmanız gereken algoritma: Base64Encode(SHA256(contractid + talep değeri)) C# dilindeki bir örnek şöyle görünür:
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 );
}
Aşağıdaki istek, hesaplanan değerin isteğin filtre parametresine nasıl ekleneceğini gösterir. Şu anda yalnızca filter=indexclaimhash eq biçimi desteklenir.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
Örnek ileti
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"
}
]
}
Bu API, arama API'sini kullanarak kimlik bilgilerini aradıktan sonra belirli bir kimlik bilgisi kimliğini belirterek kimlik bilgilerini iptal etmenizi sağlar.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için bir istek gövdesi sağlamayın.
HTTP/1.1 204 No Content
Content-type: application/json
Bu yöntem, bu kiracıdaki doğrulanabilir kimlik bilgisi hizmetinin tüm örneklerini tamamen kaldırır. Yapılandırılan tüm sözleşmeleri kaldırır. Verilen her doğrulanabilir kimlik bilgisi iptal için denetlenemez. Bu eylem geri alınamaz.
Uyarı
Bu eylem geri alınamaz ve verilen tüm doğrulanabilir kimlik bilgilerini ve oluşturulan sözleşmeleri geçersiz kılacak.
POST /v1.0/verifiableCredentials/optout
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Bu yöntem için istek gövdesi sağlama
Örnek yanıt iletisi
HTTP/1.1 200 OK
Content-type: application/json
OK
Not
Key Vault'ta silme izinleriniz yoksa bir hata iletisi döndürür ve geri çevirmeye devam ederiz