Aracılığıyla paylaş


İstek Hizmeti REST API'sini çağırma

Microsoft Entra Doğrulanmış Kimliği İstek Hizmeti REST API'sini içerir. Bu API, kimlik bilgilerini vermenizi ve doğrulamanızı sağlar. Bu makalede İstek Hizmeti REST API'sini kullanmaya nasıl başlayacağınız gösterilmektedir.

API erişim belirteci

Uygulamanızın İstek Hizmeti REST API'sine erişebilmesi için gerekli izinlere sahip geçerli bir erişim belirteci içermesi gerekir. Microsoft kimlik platformu tarafından verilen erişim belirteçleri, İstek Hizmeti REST API'sinin çağıranı doğrulamak için kullandığı bilgileri (kapsamları) içerir. Erişim belirteci, çağıranın istediği işlemi gerçekleştirmek için uygun izinlere sahip olmasını sağlar.

Erişim belirteci almak için uygulamanızın Microsoft kimlik platformuna kayıtlı olması ve İstek Hizmeti REST API'sine erişim için bir yönetici tarafından yetkilendirilmiş olması gerekir. verifiable-credentials-app uygulamasını kaydetmediyseniz, uygulamayı nasıl kaydedeceğinizi görmek için bkz. ve ardından bir uygulama gizli anahtarı oluşturun.

Erişim belirteci alma

Microsoft kimlik platformunu kullanarak erişim belirtecini almak için OAuth 2.0 istemci kimlik bilgileri verme akışı kullanın. Bu amaçla güvenilen bir kitaplık kullanın. Bu öğreticide, Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanacağız. MSAL, güvenli bir web API'sini çağırabilen bir uygulamaya kimlik doğrulaması ve yetkilendirme eklemeyi kolaylaştırır.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Yukarıdaki kodda aşağıdaki parametreleri sağlayın:

Parametre Koşul Açıklama
Otorite Gerekli Uygulamanın üzerinde çalışmak üzere planladığı dizin kiracısı. Örneğin: https://login.microsoftonline.com/{your-tenant}. (your-tenant ile kiracı kimliğinizi veya adınızıdeğiştirin.)
İstemci Kimliği Gerekli Uygulamanıza atanan uygulama kimliği. Bu bilgileri uygulamanızı kaydettiğiniz Azure portalında bulabilirsiniz.
İstemci sırrı Gerekli Uygulamanız için oluşturduğunuz istemci gizli anahtarı.
Kapsam Gerekli 3db474b9-6a0c-4840-96ac-1fceb342124f/.defaultolarak ayarlanmalıdır. Bu ayar, talebi rolleri olan bir erişim belirteci oluşturur.

Konsol uygulamasının kimliğini kullanarak erişim belirteci alma hakkında daha fazla bilgi için aşağıdaki makalelerden birine bakın:

Ayrıca istemci gizli anahtarı yerine bir sertifika ile belirteç isteğine erişebilirsiniz.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

API'yi çağırma

Doğrulanabilir bir kimlik belgesi vermek veya doğrulamasını yapmak için:

  1. İstek Hizmeti REST API'sine bir HTTP POST isteği oluşturun. Erişim belirtecinde talep olarak bulunduğundan artık URL'de kiracı kimliği gerekli değildir.

    Sorun

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
    

    Doğrula

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Erişim belirtecini bir HTTP isteğindeki yetkilendirme üst bilgisine taşıyıcı belirteç olarak ekleyin.

    Authorization: Bearer <token>
    
  3. Content-Type üst bilgisini Application/jsonolarak ayarlayın.

  4. İstek gövdesine verme veya sunu talep yükünü hazırlayın ve ekleyin.

  5. İsteği İstek Hizmeti REST API'sine gönderin.

İstek Hizmeti API'si, başarılı bir çağrıda bir HTTP Durum Kodu 201 Created döndürür. API çağrısı bir hata döndürürse,hata başvurusu belgelerine bakın.

Belge verme talebi örneği

Aşağıdaki örnekte doğrulanabilir kimlik bilgileri verme isteği gösterilmektedir. Yük hakkında bilgi için bkz. İstek Hizmeti REST API'nin yayımlama belirtimi.

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

{...JSON payload...}

idTokenHint kanıtlama akışını kullanarak talep oluşturma isteği:

{
    "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",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Kodun tamamı için aşağıdaki kod örneklerinden birine bakın:

Sunu isteği örneği

Aşağıdaki örnekte doğrulanabilir kimlik bilgileri sunu isteği gösterilmektedir. Yük hakkında daha fazla bilgi için bkz. İstek Hizmeti REST API sunum belirtimi.

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

{...JSON payload...}

Belirli bir tür ve verene sahip bir kimlik bilgisi için sunum talebi:

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

Kodun tamamı için aşağıdaki kod örneklerinden birine bakın:

Geri arama olayları

İstek yükü, oluşturma ve sunum geri çağırma uç noktasını içerir. Uç nokta web uygulamanızın bir parçasıdır ve HTTPS protokolü aracılığıyla genel kullanıma açık olmalıdır. İstek Hizmeti API'si, uygulamanızı belirli olaylar hakkında bilgilendirmek için uç noktanızı çağırır. Örneğin, bu tür olaylar bir kullanıcı QR kodunu taradığında, doğrulayıcı uygulamasının derin bağlantısını kullandığında veya sunu işlemini tamamladığında olabilir.

Aşağıdaki diyagramda uygulamanızın İstek Hizmeti REST API'sine yaptığı çağrı ve uygulamanıza yapılan geri çağırmalar açıklanmaktadır.

API'ye çağrıyı ve geri çağırma olaylarını gösteren Diyagramı.

Uç noktanızı gelen HTTP POST isteklerini dinleyecek şekilde yapılandırın. Aşağıdaki kod parçacığı, verme geri çağırma HTTP isteğinin nasıl işleneceğini ve kullanıcı arabiriminin buna göre nasıl güncelleştirileceklerini gösterir:

Uygulanamaz. Diğer programlama dillerinden birini seçin.

Sonraki adımlar

Bu belirtimler hakkında daha fazla bilgi edinin: