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

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

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

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.

RequestRegistration türü

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

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.

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:

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:

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:

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.

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.

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:

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.

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.