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

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

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

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:

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

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:

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 , saltve alg özelliklerini tanımlamanız iterationsgerekir. pin aşağıdaki özellikleri içerir:

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.

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:

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.