İ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_token
artı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 false olarak 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.
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:
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:
|
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: |
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.