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_accesskullanması 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.

Uygulama taşıyıcı belirteçleri

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/.defaultkullanmalı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, 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
İ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

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

Request body

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ü 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

didModel türü

Web

Ö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

keyVaultMetadata türü

Ö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

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, 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.

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

Request body

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

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

Request body

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

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

Request body

İstek gövdesi yok

Yanıt iletisi

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

İ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

Request body

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. Bu DID Belgesini oluşturdıktan sonra, yöneticinin dosyayı konuma yerleştirmesi https://domain/.well-known/did.json 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 doğru DID'nin kullanılıp kullanılmadığını ve imzanın doğru olup olmadığını 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

İ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.

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

DID Belgesi ile eşitle

İ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.

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

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

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 :contractId değerini :authorityId 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ü 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.

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: givenName, displayName, preferredLanguage, userPrincipalName, , surname, mail, jobTitlephoto.mappings

claimMapping türü

Ö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ü

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ü 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

displayCredential türü

Ö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

displayCredentialLogo türü

Ö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ı

displayConsent türü

Özellik Türü Veri Akışı Açıklaması
title Dize onayın başlığı
instructions Dize onay görüntülenirken kullanılacak ek metin

displayClaims türü

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

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

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.

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

Request body

Ö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. Şu anda yalnızca filter=indexclaimhash eq biçimi desteklenir.

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 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.

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

Request body

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ürür ve geri çevirmeye devam ederiz

Sonraki adımlar