Aracılığıyla paylaş


İstek Hizmeti REST API sunu belirtimi

Microsoft Entra Kimlik Doğrulama İstek Hizmeti REST API'sini içerir. Bu API, bir kimlik bilgisi vermenizi ve doğrulamanızı sağlar. Bu makalede, sunu isteği için İstek Hizmeti REST API'sini belirtir. Sunu isteği, kullanıcıdan doğrulanabilir bir kimlik bilgisi sunmasını ve ardından kimlik bilgilerini doğrulamasını ister. Başka bir makalede İstek Hizmeti REST API'sinin nasıl çağrıldığı açıklanır.

HTTP isteği

İstek Hizmeti REST API sunu isteği aşağıdaki HTTP yöntemini destekler:

Metot Notlar
POST Bu makalede belirtildiği gibi JSON yükü ile.

İstek Hizmeti REST API sunu isteği aşağıdaki HTTP üst bilgilerini gerektirir:

Metot Değer
Authorization Erişim belirtecini bir HTTP isteğindeki yetkilendirme üst bilgisine taşıyıcı belirteç olarak ekleyin. Örneğin, Authorization: Bearer <token>.
Content-Type Application/json

İstek Hizmeti REST API'sine bir HTTP POST isteği oluşturun. tenantId url'sinde bir talep olarak bulunduğundan url'de access_tokenartık gerekli değildir.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

Aşağıdaki HTTP isteği İstek Hizmeti REST API'sine yönelik bir sunu isteğini gösterir:

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

İstek Hizmeti REST API'sini çağırmak için aşağıdaki izin gereklidir. Daha fazla bilgi için bkz . Erişim belirteçlerini almak için izin verme.

İzin türü İzin
Uygulama 3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Sunu isteği yükü

Sunu isteği yükü, doğrulanabilir kimlik bilgileri sunu isteğinizle ilgili bilgileri içerir. Aşağıdaki örnekte, belirli bir verenden gelen sunu isteği gösterilmektedir. Bu isteğin sonucu, sunu işlemini başlatmak için bağlantı içeren bir QR kodu döndürür.

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Yük aşağıdaki özellikleri içerir.

Parametre Tür Açıklama
includeQRCode Boolean isteğe bağlı. Bir QR kodunun bu isteğin yanıtına eklenip eklenmeyeceğini belirler. QR kodunu sunun ve kullanıcıdan taramasını isteyin. QR kodunu taramak, bu sunu isteğiyle kimlik doğrulayıcı uygulamasını başlatır. Olası değerler true veya false (varsayılan). değerini falseolarak ayarladığınızda, derin bir bağlantı oluşturmak için return url özelliğini kullanın.
includeReceipt Boolean isteğe bağlı. Bu isteğin yanıtına bir alındı bilgisi eklenip eklenmeyeceğini belirler. Olası değerler true veya false (varsayılan). Alındı bilgisi, doğrulayıcıdan Doğrulanabilir Kimlik Bilgileri hizmetine gönderilen özgün yükü içerir. Makbuz, sorun giderme için veya yükün tüm ayrıntılarını alma gereksiniminiz varsa yararlıdır. Aksi takdirde varsayılan olarak bu değerin true olarak ayarlanması gerekmez. İstekte OpenId Connect SIOP , alındı bilgisi özgün istekteki kimlik belirtecini içerir.
authority Dize Doğrulayıcı Microsoft Entra kiracınızın merkezi olmayan tanımlayıcısı (DID). Daha fazla bilgi için bkz . Örnek uygulamanızı ayarlamak için kiracı ayrıntılarını toplama.
registration requestRegistration Doğrulayıcı hakkında bilgi sağlar.
callback Geri çağırma Zorunlu. Geliştiricinin doğrulanabilir kimlik bilgisi sunu işlemi sırasında kullanıcı arabirimini güncelleştirmesine izin verir. Kullanıcı işlemi tamamladığında, sonuçlar uygulamaya döndürüldükten sonra işleme devam edin.
requestedCredentials koleksiyonu RequestCredential nesneleri koleksiyonu.

RequestRegistration türü

Türü RequestRegistration , veren için bilgi kaydı sağlar. Türü RequestRegistration aşağıdaki özellikleri içerir:

Özellik Tür Açıklama
clientName Dize Doğrulanabilir kimlik bilgilerinin doğrulayıcının görünen adı. Bu ad, kimlik doğrulayıcı uygulamasında kullanıcıya sunulur.
purpose Dize isteğe bağlı. Kullanıcıya doğrulanabilir kimlik bilgilerinin neden istendiğini bildirmek için görüntülenen dize.
logoUrl URL isteğe bağlı. Doğrulayıcının logo türünün URL'si. Bu değer Authenticator uygulaması tarafından kullanılmaz.
termsOfServiceUrl URL isteğe bağlı. Doğrulayıcı için hizmet koşullarının URL'si. Bu değer Authenticator uygulaması tarafından kullanılmaz.

Aşağıdaki ekran görüntüsünde, sunu isteğindeki clientName özelliği ve görünen adı authority (doğrulayıcı) gösterilmektedir.

Sunu isteğinin nasıl onaylandığını gösteren ekran görüntüsü.

Geri arama türü

İstek Hizmeti REST API'si, geri çağırma uç noktasına birkaç olay oluşturur. Bu olaylar, kullanıcı arabirimini güncelleştirmenize ve sonuçlar uygulamaya döndürüldükten sonra işleme devam etmenizi sağlar. Türü Callback aşağıdaki özellikleri içerir:

Özellik Tür Açıklama
url Dize Uygulamanızın geri çağırma uç noktasına URI. URI' nin İnternet'te erişilebilir bir uç noktaya işaret etmesi gerekir, aksi takdirde hizmet bir geri çağırma URL'si okunamaz hatası oluşturur. Kabul edilen girişler IPv4, IPv6 veya DNS çözümlenebilir ana bilgisayar adı. Ağınızı sağlamlaştırmak için bkz . SSS.
state Dize Geri çağırma olayını özgün yükte geçirilen durumla ilişkilendirir.
headers Dize isteğe bağlı. POST iletisinin alıcı sonu için gereken HTTP üst bilgilerinden oluşan bir koleksiyon ekleyebilirsiniz. Desteklenen geçerli üst bilgi değerleri veya api-key üst bilgileridirAuthorization. Diğer üst bilgiler geçersiz bir geri çağırma üst bilgisi hatası oluşturur.

RequestCredential türü

, RequestCredential kullanıcının sağlaması gereken istenen kimlik bilgileri hakkında bilgi sağlar. RequestCredential aşağıdaki özellikleri içerir:

Özellik Tür Açıklama
type Dize Doğrulanabilir kimlik bilgisi türü. , type doğrulanabilir kimlik bilgisi bildiriminde issuer tanımlanan türle eşleşmelidir (örneğin, VerifiedCredentialExpert). Veren bildirimini almak için bkz . Örnek uygulamanızı ayarlamak için kimlik bilgilerini ve ortam ayrıntılarını toplama. Sorun kimlik bilgisi URL'sini kopyalayın, web tarayıcısında açın ve id özelliğini denetleyin.
purpose Dize isteğe bağlı. Bu doğrulanabilir kimlik bilgilerini istemenin amacı hakkında bilgi sağlayın. Bu veriler Authenticator uygulaması tarafından kullanılmaz.
acceptedIssuers dize koleksiyonu isteğe bağlı. Konuların sunabileceği doğrulanabilir kimlik bilgisi türünü verebilecek verenlerin DD'lerinden oluşan bir koleksiyon. VerenIN DID'sini almak için bkz. Örnek uygulamanızı ayarlamak için kimlik bilgilerini ve ortam ayrıntılarını toplama ve Merkezi Olmayan tanımlayıcının (DID) değerini kopyalama. acceptedIssuers koleksiyonu boşsa veya yoksa, sunu isteği herhangi bir veren tarafından verilen bir kimlik bilgisi türünü kabul eder.
configuration.validation Configuration.Validation Sunu doğrulaması için isteğe bağlı ayarlar.
constraints Kısıtlamalar isteğe bağlı. Talep kısıtlamaları koleksiyonu.

Configuration.Validation türü

, Configuration.Validation sunulan kimlik bilgilerinin nasıl doğrulanması gerektiği hakkında bilgi sağlar. Aşağıdaki özelliklerde oluşur:

Özellik Tür Açıklama
allowRevoked Boolean isteğe bağlı. İptal edilen kimlik bilgilerinin kabul edilmesi gerekip gerekmediğini belirler. Varsayılan değerdir false (kabul edilmemelidir).
validateLinkedDomain Boolean isteğe bağlı. Bağlı etki alanının doğrulanıp doğrulanmadığını belirler. Varsayılan false değeridir. Bu bayrağı olarak ayarlamak false , Bağlı Olan Taraf uygulaması olarak, doğrulamamış bir bağlı etki alanından kimlik bilgilerini kabul ettiğiniz anlamına gelir. Bu bayrağın true olarak ayarlanması, bağlı etki alanının doğrulanacağı ve yalnızca doğrulanan etki alanlarının kabul edildiği anlamına gelir.
faceCheck faceCheck isteğe bağlı. Sunu sırasında canlılık denetimi istemeye izin verir.

Kısıtlama türü

Bu tür, constraints bir cüzdan aday kimlik bilgilerini seçtiğinde karşılanması gereken talep kısıtlamaları koleksiyonu içerir. Bu, belirli talep değerine sahip bir kimlik bilgisi istemenizi sağlar. Belirtilen kısıtlamalar AND mantığını kullanır, yani üç kısıtlama belirtirseniz, bunların tümünün karşılanması gerekir. Koleksiyondaki her kısıtlama için bir değer işleneni seçmelisiniz, içerir veya startsWith. Değerler normal ifadeler olamaz. Tüm karşılaştırmalar büyük/küçük harfe duyarlı değildir.

Özellik Tür Açıklama
claimName Dize Zorunlu. Kısıtlama için talebin adı. Bu değer, doğrulanabilir kimlik bilgilerindeki talep adıdır. Bkz . outputClaim in claimMapping type.
values dize koleksiyonu Talep değeriyle eşleşmesi gereken değerler kümesi. ["kırmızı", "yeşil", "mavi"] gibi birden çok değer belirtirseniz, kimlik bilgilerindeki talep değeri koleksiyondaki değerlerden herhangi birine sahipse eşleşme olur.
contains Dize Talep değeri belirtilen değeri içeriyorsa kısıtlama true olarak değerlendirilir.
startsWith Dize Talep değeri belirtilen değerle başlıyorsa kısıtlama true olarak değerlendirilir.

faceCheck türü

faceCheck türü, kimlik bilgilerinin sunulması sırasında canlılık denetimi gerçekleştirmeye yönelik bilgiler içerir. İstenen kimlik bilgisi sourcePhotoClaimName tarafından adlandırılan talepte sahibin fotoğrafını içermelidir. Canlılık denetimi matchConfidenceThreshold özelliğinde belirtilen değere eşit veya daha yüksek bir güvenilirlik düzeyine ulaşırsa sunu başarılı olur. Eşik karşılanmazsa sununun tamamı başarısız olur.

Özellik Tür Açıklama
sourcePhotoClaimName Dize Zorunlu. Fotoğrafı içeren kimlik bilgilerindeki talebin adı. Bkz . outputClaim in claimMapping type.
matchConfidenceThreshold integer isteğe bağlı. Fotoğraf ve canlılık verileri arasında başarılı bir denetim için gizli eşik. 50 ile 100 arasında bir tamsayı olmalıdır. Varsayılan değer 70'tir.

Başarılı yanıt

Başarılı olursa, bu yöntem yanıt kodu (HTTP 201 Oluşturuldu) ve yanıt gövdesindeki olay nesneleri koleksiyonunu döndürür. Aşağıdaki JSON başarılı bir yanıtı gösterir:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

Yanıt aşağıdaki özellikleri içerir:

Özellik Tür Açıklama
requestId Dize Otomatik oluşturulan istek kimliği. Geri arama aynı isteği kullanarak sunu isteğini ve geri çağrılarını izlemenizi sağlar.
url Dize Kimlik doğrulayıcı uygulamasını başlatan ve sunu işlemini başlatan bir URL. QR kodunu tarayamıyorsa bu URL'yi kullanıcıya sunabilirsiniz.
expiry integer Yanıtın süresinin ne zaman dolduğunda gösterir.
qrCode Dize Kullanıcının sunu akışını başlatmak için tarayabileceği bir QR kodu.

Uygulamanız yanıtı aldığında, uygulamanın QR kodunu kullanıcıya sunması gerekir. Kullanıcı, kimlik doğrulayıcı uygulamasını açan ve sunu işlemini başlatan QR kodunu tarar.

Hata yanıtı

İstekte bir hata varsa hata yanıtları döndürülür. Uygulamanın hatayı uygun şekilde işlemesi gerekir.

Geri çağırma olayları

Kullanıcı QR kodunu taradığında, kimlik doğrulayıcı uygulamasının derin bağlantısını kullandığında veya sunu işlemini tamamladığında geri çağırma uç noktası çağrılır.

Özellik Tür Açıklama
requestId Dize Yük Doğrulanabilir Kimlik Bilgileri hizmetine gönderildiğinde özgün istekle eşlenir.
requestStatus Dize Kimlik doğrulayıcı uygulaması isteği aldığında döndürülen durum. Olası değerler:
  • request_retrieved: Kullanıcı QR kodunu taradı veya sunu akışını başlatan bağlantıyı seçti.
  • presentation_verified: Doğrulanabilir kimlik bilgisi doğrulaması başarıyla tamamlandı.
  • presentation_error: Sunuda bir hata oluştu.
state Dize Özgün yükte geçirilen durum değerini döndürür.
subject Dize Doğrulanabilir kimlik bilgisi kullanıcısı DID.
verifiedCredentialsData dizi İstenen doğrulanabilir kimlik bilgileri dizisini döndürür. Doğrulanabilir her kimlik bilgisi için şunları sağlar:
  • Doğrulanabilir kimlik bilgisi türleri.
  • Verenin DID'i
  • Alınan talepler.
  • Doğrulanabilir kimlik bilgisi verenin etki alanı.
  • Doğrulanabilir kimlik bilgisi verenin etki alanı doğrulama durumu.
  • receipt Dize isteğe bağlı. Makbuz, cüzdandan Doğrulanabilir Kimlik Bilgileri hizmetine gönderilen özgün yükü içerir. Alındı bilgisi yalnızca sorun giderme/hata ayıklama için kullanılmalıdır. Makbuzdaki biçim düzeltmez ve kullanılan cüzdan ve sürüme göre değişebilir.

    Aşağıdaki örnekte, kimlik doğrulayıcı uygulaması sunu isteğini başlattığında geri çağırma yükü gösterilmektedir:

    {
        "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
        "requestStatus":"request_retrieved",
        "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
    }
    

    Aşağıdaki örnekte, doğrulanabilir kimlik bilgisi sunusu başarıyla tamamlandıktan sonra bir geri çağırma yükü gösterilmektedir:

    {
      "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
      "requestStatus": "presentation_verified",
      "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
      "subject": "did:web:verifiedid.contoso.com",
      "verifiedCredentialsData": [
        {
          "issuer": "did:web:issuer...",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          },
          "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
          "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Sonraki adımlar

    İstek Hizmeti REST API'sini çağırmayı öğrenin.