İstek Hizmeti REST API'si verme 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, verme isteği için İstek Hizmeti REST API'sini belirtir. Başka bir makalede İstek Hizmeti REST API'sinin nasıl çağrıldığı açıklanır.
HTTP isteği
İstek Hizmeti REST API'sinin verme 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'sinin verme isteği aşağıdaki HTTP üst bilgilerini gerektirir:
Veri Akışı Adı | 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.
https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Aşağıdaki HTTP isteği İstek Hizmeti REST API'sine yönelik bir isteği gösterir:
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>
{
"callback": {
"url": "https://contoso.com/api/issuer/issuanceCallback",
"state": "Aaaabbbb11112222",
"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 |
Verme isteği yükü
Verme isteği yükü, doğrulanabilir kimlik bilgileri verme isteğinizle ilgili bilgileri içerir. Aşağıdaki örnek, ad ve soyadı gibi kullanıcı talepleri ile bir PIN kodu akışı kullanarak verme isteğini gösterir. Bu isteğin sonucu, verme işlemini başlatmak için bağlantı içeren bir QR kodu döndürür.
{
"authority": "did:web:verifiedid.contoso.com",
"callback": {
"url": "https://contoso.com/api/issuer/issuanceCallback",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
"headers": {
"api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
}
},
"registration": {
"clientName": "Verifiable Credential Expert Sample"
},
"type": "VerifiedCredentialExpert",
"manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
"pin": {
"value": "3539",
"length": 4
},
"claims": {
"given_name": "Megan",
"family_name": "Bowen"
},
"expirationDate": "2024-12-31T23:59:59.000Z"
}
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 verme 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. |
callback |
Geri çağırma | Zorunlu. Geliştiricinin doğrulanabilir kimlik bilgisi verme işlemi sırasında akış hakkında zaman uyumsuz olarak bilgi almasına olanak tanır. Örneğin, kullanıcı QR kodunu taradığında veya verme isteği başarılı veya başarısız olduğunda geliştirici bir çağrı isteyebilir. |
authority |
Dize | Verenin merkezi olmayan tanımlayıcısı (DID). Daha fazla bilgi için bkz . Örnek uygulamanızı ayarlamak için kimlik bilgilerini ve ortam ayrıntılarını toplama. |
registration |
requestRegistration | Doğrulayıcı uygulamasında görüntülenebilen veren hakkında bilgi sağlar. |
type |
Dize | Doğrulanabilir kimlik bilgisi türü. Doğrulanabilir kimlik bilgisi bildiriminde tanımlanan türle eşleşmelidir. Örneğin: VerifiedCredentialExpert . Daha fazla bilgi için bkz . Azure'da doğrulanmış kimlik bilgisi uzmanı kartı oluşturma. |
manifest |
Dize | Doğrulanabilir kimlik bilgisi bildirim belgesinin URL'si. Daha fazla bilgi için bkz . Örnek uygulamanızı ayarlamak için kimlik bilgilerini ve ortam ayrıntılarını toplama. |
claims |
Dize | isteğe bağlı. Yalnızca kimlik belirteci ipucu kanıtlama akışı için, doğrulanabilir kimlik bilgilerine konu hakkında yapılan onayların bir koleksiyonunu eklemek için kullanılabilir. |
pin |
İĞNE | isteğe bağlı. PIN kodu yalnızca kimlik belirteci ipucu kanıtlama akışıyla kullanılabilir. Verme sırasında ek güvenlik sağlamak için bir PIN numarası. Bir PIN kodu oluşturur ve bunu uygulamanızdaki kullanıcıya sunarsınız. Kullanıcı, oluşturduğunuz PIN kodunu sağlamalıdır. |
expirationDate |
Dize | isteğe bağlı. expirationDate yalnızca kimlik belirteci ipucu kanıtlama akışıyla kullanılabilir. Belirtilirse, değerin ISO8601 biçiminde ifade edilen bir tarih olması gerekir. Tarih, bu verme isteğinin kimlik bilgileri kuralları tanımındaki geçerlilikInterval geçersiz kılar. Verme süresi ne olursa olsun, kimlik bilgilerinin süresinin ne zaman dolmak üzere olduğunu (gün sonu, ay sonu veya yıl sonu gibi) açıkça denetlemek için bu ayarı kullanın. Tarih UTC biçiminde ifade edilir. Yıl sonu belirtirseniz, saat 23:59:59 olarak ayarlanmışsa (UTC saatinde 1 saniye ile gece yarısı arası) farklı bir saat dilimindeki tüm kullanıcılar Microsoft Authenticator'da yerel saat diliminde sunulan son kullanma tarihini alır. Bu, CET saat dilimindeyseniz 1 Ocak 01:00 olarak sunulacağı anlamına gelir.Kimlik bilgisi sözleşmesinin allowOverrideValidityOnIssuance bayrağının true olarak ayarlanması gerekir. |
Şu anda yükte gönderebileceğiniz dört talep kanıtlama türü vardır. Microsoft Entra Kimlik Doğrulama, talepleri doğrulanabilir bir kimlik bilgilerine eklemek ve bu bilgileri verenin DID'siyle onaylamak için dört yol kullanır. Dört tür şunlardır:
- Kimlik belirteci
- Kimlik belirteci ipucu
- Doğrulanabilir bir sunu aracılığıyla doğrulanabilir kimlik bilgileri
- Kendi kendine tasdikli beyanlar
Giriş türleri hakkında ayrıntılı bilgileri Doğrulanabilir kimlik bilgilerinizi özelleştirme bölümünde bulabilirsiniz.
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 verenin görünen adı. |
logoUrl |
Dize | isteğe bağlı. Veren logosunun URL'si. |
termsOfServiceUrl |
Dize | isteğe bağlı. Oluşturduğunuz doğrulanabilir kimlik bilgilerinin kullanım koşullarının URL'si. |
Not
Şu anda bilgiler Microsoft RequestRegistration
Authenticator uygulamasında verme sırasında sunulmaz. Ancak bu bilgiler yükte kullanılabilir.
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 geri çağırma URL'si okunamaz hatası oluşturur. Kabul edilen biçimler 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 |
Sabitleme türü
Türü, pin
verme işleminin bir parçası olarak görüntülenebilen bir PIN kodu tanımlar.
pin
isteğe bağlıdır ve kullanılırsa her zaman bant dışı gönderilmelidir. KARMA PIN kodu kullanırken , salt
ve alg
özelliklerini tanımlamanız iterations
gerekir.
pin
aşağıdaki özellikleri içerir:
Özellik | Tür | Açıklama |
---|---|---|
value |
Dize | PIN değerini düz metin olarak içerir. Karma PIN kullanırken value özelliği base64 kodlanmış tuzlanmış karmayı içerir. |
type |
Dize | PIN kodunun türü. Olası değer: numeric (varsayılan). |
length |
integer | PIN kodunun uzunluğu. Varsayılan uzunluk 6, minimum 4 ve maksimum 16'dır. |
salt |
Dize | Karma PIN kodunun tuzu. Karma hesaplama sırasında tuza eklenmiştir. Kodlama: UTF-8. |
alg |
Dize | Karma PIN için karma algoritması. Desteklenen algoritma: sha256 . |
iterations |
integer | Karma yineleme sayısı. Olası değer: 1 . |
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": "799f23ea-5241-45af-99ad-cf8e5018814e",
"url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",
"expiry": 1622227690,
"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 verme işlemini başlatan QR kodunu tarar.
Hata yanıtı
İstekte bir hata varsa, hata yanıtı döndürülür. Uygulamanın yanıtı uygun şekilde işlemesi gerekir.
Geri çağırma olayları
Geri çağırma uç noktası, kullanıcı QR kodunu taradığında, doğrulayıcı uygulamasının derin bağlantısını kullandığında veya verme işlemini tamamladığında ç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 | İstek için döndürülen durum. Olası değerler:
|
state |
Dize | Özgün yükte geçirilen durum değerini döndürür. |
error |
hata |
code Özellik değeri olduğunda, issuance_error bu özellik hata hakkında bilgi içerir. |
error.code |
Dize | Dönüş hata kodu. |
error.message |
Dize | Hata iletisi. |
Aşağıdaki örnekte, kimlik doğrulayıcı uygulaması verme isteğini başlattığında bir geri çağırma yükü gösterilmektedir:
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus":"request_retrieved",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}
Aşağıdaki örnekte, kullanıcı verme işlemini başarıyla tamamladıktan sonra bir geri çağırma yükü gösterilmektedir:
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus":"issuance_successful",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}
Geri çağırma hataları
Geri çağırma uç noktası bir hata iletisiyle çağrılabilir. Aşağıdaki tabloda hata kodları listelenmektedir:
İleti | Tanım |
---|---|
fetch_contract_error |
Doğrulanabilir kimlik bilgisi sözleşmesi getirilemiyor. Bu hata genellikle API istek yükü RequestIssuance nesnesinde belirttiğiniz bildirimi getiremezse oluşur. |
issuance_service_error |
Doğrulanabilir Kimlik Bilgileri hizmeti gereksinimleri doğrulayamıyor veya Doğrulanabilir Kimlik Bilgileri'nde bir sorun oluştu. |
unspecified_error |
Bu hata nadirdir, ancak araştırmaya değer. |
Aşağıdaki örnekte bir hata oluştuğunda geri çağırma yükü gösterilmektedir:
{
"requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",
"requestStatus": "issuance_error",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
"error": {
"code":"IssuanceFlowFailed",
"message":"issuance_service_error”,
}
}
Sonraki adımlar
İstek Hizmeti REST API'sini çağırmayı öğrenin.