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
Temel URL
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
.
Kimlik Doğrulaması
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.
Kullanıcı taşıyıcı belirteçleri
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, Kimlik Doğrulama İlkesi Yöneticisi rolüne sahip bir kullanıcı için olmalıdır.
Genel Yönetici rolü de bu izinlere sahiptir, ancak yalnızca gereksinimlerinizi karşılayan başka bir rol bileşimi yoksa kullanılmalıdır. Rol genel okuyucusu olan bir kullanıcı salt okunur API çağrıları gerçekleştirebilir.
Uygulama taşıyıcı belirteçleri
Hizmet Verifiable Credentials Service Admin
aşağıdaki uygulama izinlerini destekler.
İzin | Açıklama |
---|---|
VerifiableCredential.Authority.ReadWrite | Yetkili nesnelerini okuma/yazma izni |
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ının Verifiable Credentials Service Admin
için API İznine ve tablodan gereken izinlere sahip olması gerekir. Bir uygulama erişim belirteci edindiğinde, istemci kimlik bilgileri akışıaracılığıyla uygulama 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
kapsam 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.
Ekleme
Bu API, yeni yetkililerin ayarlanabilmesi için yeni bir ortam oluşturulmasına yardımcı olur. Bu işlem, 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.
HTTP isteği
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.
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
dönüş iletisi
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.
Yetkili
Bu uç nokta, Doğrulanabilir Kimlik Bilgileri hizmet örneğini oluşturmak veya güncelleştirmek için kullanılabilir.
Yöntemler
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 |
DID Belgesi Oluştur | ||
İmzalama Anahtarını Döndür | Yetkili | İmzalama anahtarını döndürme |
İmzalama Anahtarı oluşturma |
Yetkili | İmzalama anahtarı oluşturma |
DID Belgesi ile eşitle | Yetkili | DID belgesini yeni imzalama anahtarıyla eşitleme |
İyi Bilinen DID Yapılandırması Oluşturma | ||
İyi bilinen DID yapılandırmasını doğrulama |
Yetki alma
Yapılandırılmış bir yetkilinin veya doğrulanabilir kimlik bilgisi hizmeti örneğinin özelliklerini alın.
HTTP isteği
GET /v1.0/verifiableCredentials/authorities/<authorityId>
öğesini <authorityId>
yapılandırılan yetkililerden birinin değeriyle değiştirin.
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için istek gövdesi sağlama
Yanıt iletisi
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.
Yetkili türü
Özellik | Türü | Açıklama |
---|---|---|
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 | hizmetin durumu, bu değer her zaman enabled |
didModel | didModel | DID ve anahtarlar hakkında bilgi |
keyVaultMetadata | keyVaultMeta verileri | Kullanılan Key Vault hakkında bilgi |
didModel türü
Web
Özellik | Türü | Açıklama |
---|---|---|
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 |
keyVaultMetadata türü
Özellik | Türü | Açıklama |
---|---|---|
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 |
Liste yetkilileri
Bu kiracı için tüm yapılandırılmış yetkilileri veya doğrulanabilir kimlik bilgileri hizmetlerini alma
HTTP isteği
GET /v1.0/verifiableCredentials/authorities
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
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/"
}
}
]
}
Yetkili oluşturma
Bu çağrı yeni bir özel anahtar oluşturur ve anahtarı 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 DID oluşturur.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
İstek gövdesinde aşağıdakilerin bir JSON gösterimini sağlayın
Özellik | Türü | Açıklama |
---|---|---|
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/"
}
}
Yanıt iletisi
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/"
}
}
Açıklamalar
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.
Güncelleştirme yetkilisi
Bu yöntem, doğrulanabilir kimlik bilgisi hizmetinin bu özel örneğinin görünen adını güncelleştirmek için kullanılabilir.
HTTP isteği
PATCH /v1.0/verifiableCredentials/authorities/<authorityId>
değerini <authorityId>
güncelleştirmek istediğiniz yetkili kimliğinin değeriyle değiştirin.
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
İstek gövdesinde aşağıdakilerin bir JSON gösterimini sağlayın.
Özellik | Türü | Açıklama |
---|---|---|
name |
Dize | Hizmetin bu örneğinin görünen adı |
Örnek ileti
{
"name":"ExampleIssuerName"
}
Yetkiliyi silme
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.
HTTP isteği
DELETE /beta/verifiableCredentials/authorities/<authorityId>
değerini <authorityId>
silmek istediğiniz yetkili kimliğinin değeriyle değiştirin.
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
İstek gövdesi yok
Yanıt iletisi
Örnek yanıt iletisi:
Başarılı silme yetkilisi yanıtı.
HTTP/1.1 200 OK
Bir yetkilinin silinmesi başarılı olsa da Azure Key Vault anahtarlarını temizleme işlemi başarısız olursa bu 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"
}
}
İyi bilinen DID yapılandırması
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.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/generateWellknownDidConfiguration
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Belirtilen yetkilinin linkedDomains içindeki etki alanlarından birini belirtmeniz gerekir.
{
"domainUrl":"https://atest/"
}
Yanıt iletisi
Ö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/"
}
}
Açıklamalar
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>..."
]
}
DID belgesi oluşturma
Bu çağrı, DID:WEB tanımlayıcıları için kullanılan DID Belgesini oluşturur. Hizmet DID Belgesini oluşturduktan sonra, yöneticinin dosyayı https://domain/.well-known/did.json konuma yerleştirmesi gerekir.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/generateDidDocument
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
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çıklama
Çağıranın hedef anahtar kasasında ANAHTAR Listesi izinlerine sahip olmasını gerektirir.
İyi bilinen DID yapılandırmasını doğrulama
Bu çağrı, DID kurulumunuzu denetler. İyi bilinen DID yapılandırmasını indirir ve DID'yi ve imzayı doğrular.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/validateWellKnownDidConfiguration
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
HTTP/1.1 204 No Content
Content-type: application/json
İmzalama anahtarını döndürme
Döndürme imzalama anahtarı did:web yetkilisi için yeni bir özel anahtar oluşturur. DID belgesi, güncelleştirmeyi yansıtacak şekilde yeniden kaydedilmelidir. Yeniden kayıt tamamlandığında, synchronizeWithDidDocument sisteme imzalama için yeni anahtarı kullanmaya başlamasını söyler.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/didInfo/signingKeys/rotate
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek Gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
didDocumentStatus
outOfSync
olarak 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": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
İmzalama anahtarı oluşturma
Oluşturma imzalama anahtarı, did:web yetkilisi için zaten var olan Key Vault'ta yeni bir özel anahtar oluşturur. Yetkilinin didDocumentStatus
outOfSync
olarak değiştirildiğinden DID belgesi güncelleştirmeyi yansıtacak şekilde yeniden kaydedilmelidir. DID belgesi yeniden kaydedildiğinde, sisteme imzalama için yeni anahtarı kullanmaya başlamasını synchronizeWithDidDocument
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek Gövdesi
{
"signingKeyCurve": "P-256"
}
Yanıt iletisi
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"
}
DID Belgesi ile eşitle
İmzalama anahtarı döndürüldikten sonra, DID belgesi güncelleştirmeyi yansıtacak şekilde yeniden kaydedilmelidir. İşlem tamamlandığında synchronizeWithDidDocument sisteme imzalama için yeni anahtarı kullanmaya başlamasını söyler.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/didInfo/synchronizeWithDidDocument
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek Gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
didDocumentStatus
, başarılı bir çağrıda outOfSync
published
olarak 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
}
Sözleşmeler
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 kullanıcı OIDC uyumlu bir kimlik sağlayıcısında oturum açtığında alınan kimlik belirteci gibi kanıtlamaların nasıl toplanıp toplandığına ilişkin bilgileri içerir.
Yöntemler
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 |
Sözleşme alma
HTTP isteği
GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractId>
ve <authorityId>
değerini <contractId>
yetkilinin ve sözleşmenin doğru değeriyle değiştirin.
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
Ö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
Sözleşme türü
Özellik | Türü | Açıklama |
---|---|---|
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 bildirilmesi için true olarak ayarlanmış bu VC, verilmeye hazır |
issueNotificationAllowedToGroupOids |
groupId dizeleri dizisi | bu kimlik bilgilerinin kullanılabilmesi için 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. |
rulesModel türü
Ö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.
Kanıtlama tü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 |
idTokenAttestation türü
Ö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 |
idTokenHintAttestation türü
Ö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 |
verifiablePresentationAttestation türü
Ö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 |
selfIssuedAttestation türü
Ö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 |
accessTokenAttestation türü
Ö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:mappings
,givenName
,displayName
,preferredLanguage
, ,userPrincipalName
,surname
,jobTitle
.photo
claimMapping türü
Özellik | Türü | Açıklama |
---|---|---|
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şmede yalnızca bir clientMapping nesnesi dizine eklenebilir |
required |
boole (varsayılan yanlış) | bu eşlemenin gerekli olup olmadığını gösterir |
type |
dize (isteğe bağlı) | talep türü |
customStatusEndpoint 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"
]
}
}
displayModel türü
Özellik | Türü | Açıklama |
---|---|---|
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 |
displayCredential türü
Özellik | Türü | Açıklama |
---|---|---|
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 |
displayCredentialLogo türü
Özellik | Türü | Açıklama |
---|---|---|
uri |
dize (uri) | logonun uri'sini seçin. Değer bir URL ise, genel İnternet üzerinden anonim olarak erişilebilir olmalıdır. |
description |
Dize | logo açıklaması |
displayConsent türü
Özellik | Türü | Açıklama |
---|---|---|
title |
Dize | onayın başlığı |
instructions |
Dize | onay görüntülenirken kullanılacak ek metin |
displayClaims türü
Özellik | Türü | Açıklama |
---|---|---|
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"
}
]
}
]
}
Sözleşmeleri listeleme
Bu API, belirtilen yetkili için geçerli kiracıda yapılandırılan tüm sözleşmeleri listeler.
HTTP isteği
GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
Ö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şturma
Bir sözleşme oluşturduğunuzda, kullandığınız adın kiracıda benzersiz olması gerekir. Birden çok yetkili oluşturmanı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ıdır.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/contracts
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Örnek istek
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Yanıt iletisi
Ö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://..."
}
Sözleşmeyi güncelleştirme
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
}
Yanıt iletisi
Ö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
}
Referans
Bu uç nokta verilen doğrulanabilir kimlik bilgilerini aramanıza, iptal durumunu denetlemenize ve kimlik bilgilerini iptal etmenizi sağlar.
Yöntemler
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 |
Kimlik bilgilerini alma
Bu API, belirli bir kimlik bilgilerini almanıza ve iptal edilip iptal edilmediğini görmek için durumu denetlemenize olanak tanır.
HTTP İsteği
GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials/:credentialId
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
Yanıt iletisi
Ö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"
}
Arama kimlik bilgileri
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.
HTTP isteği
GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
Ö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"
}
]
}
Kimlik bilgilerini iptal etme
Bu API, arama API'sini kullanarak kimlik bilgilerini aradıktan sonra belirli bir kimlik bilgisi kimliğini belirterek kimlik bilgilerini iptal etmenizi sağlar.
HTTP isteği
POST /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials/:credentialid/revoke
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için bir istek gövdesi sağlamayın.
Yanıt iletisi
HTTP/1.1 204 No Content
Content-type: application/json
Geri çevirme
Bu yöntem, bu kiracıdaki doğrulanabilir kimlik bilgisi hizmetinin tüm örneklerini 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ılabilir.
HTTP İsteği
POST /v1.0/verifiableCredentials/optout
İstek üst bilgileri
Üst bilgi | Değer |
---|---|
Yetkilendirme | Taşıyıcı (belirteç). Zorunlu |
İçerik Türü | application/json |
İstek gövdesi
Bu yöntem için istek gövdesi sağlama
Yanıt iletisi
Örnek yanıt iletisi
HTTP/1.1 200 OK
Content-type: application/json
OK
Açıklama
Not
Key Vault'ta silme izinleriniz yoksa bir hata iletisi döndürerek geri çevirmeye devam ediyoruz