OnAttributeCollectionStart olay başvurusu (önizleme) için Özel Uzantı

Makale
01/23/2024

Şunlar için geçerlidir: Gri X simgesine sahip beyaz daire. İş gücü kiracıları Beyaz onay işareti simgesi olan yeşil daire. Dış kiracılar (daha fazla bilgi edinin)

Müşteri self servis kaydolma kullanıcı akışlarınızın kaydolma deneyimini değiştirmek için özel bir kimlik doğrulama uzantısı oluşturabilir ve bunu kullanıcı akışının belirli noktalarında çağırabilirsiniz. OnAttributeCollectionStart olayı, öznitelik koleksiyonu sayfasının işlenmesinden önce öznitelik koleksiyonu adımının başında gerçekleşir. Bu olay, öznitelikler kullanıcıdan toplanmadan önce eylemleri tanımlamanızı sağlar. Örneğin, bir kullanıcının federasyon kimliğine veya e-postasına göre kaydolma akışını sürdürmesini veya belirtilen değerlerle öznitelikleri önceden doldurmasını engelleyebilirsiniz. Aşağıdaki eylemler yapılandırılabilir:

continueWithDefaultBehavior - Öznitelik koleksiyonu sayfasını her zamanki gibi işleyin.
setPreFillValues - Kaydolma formunda öznitelikleri önceden doldurun.
showBlockPage - Bir hata iletisi gösterin ve kullanıcının kaydolmasını engelleyin.

Bu makalede, OnAttributeCollectionStart olayının REST API şeması açıklanmaktadır. (Ayrıca ilgili makaleye bakınOnAttributeCollectionSubmit olayı için Özel Uzantı.)

İpucu

Bu özelliği denemek için Woodgrove Market tanıtımına gidin ve "Önceden doldurma kaydolma öznitelikleri" kullanım örneğini başlatın.

REST API şeması

Öznitelik koleksiyonu başlangıç olayı için kendi REST API'nizi geliştirmek için aşağıdaki REST API veri sözleşmesini kullanın. Şema, istek ve yanıt işleyicisini tasarlamaya yönelik sözleşmeyi açıklar.

Microsoft Entra ID'deki özel kimlik doğrulama uzantınız, JSON yüküyle REST API'nize bir HTTP çağrısı yapar. JSON yükü kullanıcı profili verilerini, kimlik doğrulama bağlamı özniteliklerini ve kullanıcının oturum açmak istediği uygulama hakkındaki bilgileri içerir. JSON öznitelikleri, API'niz tarafından ek mantık gerçekleştirmek için kullanılabilir.

Dış REST API'ye istek

REST API'nize gönderilen istek aşağıda gösterilen biçimdedir. Bu örnekte istek, yerleşik öznitelikler (givenName ve companyName) ve özel öznitelikler (universityGroups, graduationYear ve onMailingList) ile birlikte kullanıcı kimlik bilgilerini içerir.

İstek, yerleşik öznitelikler (örneğin, givenName ve companyName) ve önceden tanımlanmış özel öznitelikler (örneğin, universityGroups, graduationYear ve onMailingList) dahil olmak üzere self servis kayıt sırasında koleksiyon için kullanıcı akışında seçilen kullanıcı özniteliklerini içerir. REST API'niz yeni öznitelikler ekleyemez.

İstek, kaydolmak için doğrulanmış bir kimlik bilgisi olarak kullanıldıysa kullanıcının e-postası da dahil olmak üzere kullanıcı kimliklerini de içerir. Parola gönderilmez.

Başlangıç isteğindeki öznitelikler varsayılan değerlerini içerir. Birden çok değere sahip öznitelikler için değerler virgülle ayrılmış bir dize olarak gönderilir. Öznitelikler henüz kullanıcıdan toplanmadığından, özniteliklerin çoğunda değer atanmayacaktır.

JSON

POST https://exampleAzureFunction.azureWebsites.net/api/functionName

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionStart",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartCalloutData",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
    "authenticationContext": {
        "correlationId": "<GUID>",
        "client": {
            "ip": "30.51.176.110",
            "locale": "en-us",
            "market": "en-us"
        },
        "protocol": "OAUTH2.0",
        "clientServicePrincipal": {
            "id": "<Your Test Applications servicePrincipal objectId>",
            "appId": "<Your Test Application App Id>",
            "appDisplayName": "My Test application",
            "displayName": "My Test application"
        },
        "resourceServicePrincipal": {
            "id": "<Your Test Applications servicePrincipal objectId>",
            "appId": "<Your Test Application App Id>",
            "appDisplayName": "My Test application",
            "displayName": "My Test application"
        },
    },
    "userSignUpInfo": {
      "attributes": {
        "givenName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Larissa Price",
          "attributeType": "builtIn"
        },
        "companyName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Contoso University",
          "attributeType": "builtIn"
        },
        "extension_<appid>_universityGroups": {
          "@odata.Type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Alumni,Faculty",
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_graduationYear": {
          "@odata.type": "microsoft.graph.int64DirectoryAttributeValue",
          "value": 2010,
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_onMailingList": {
          "@odata.type": "microsoft.graph.booleanDirectoryAttributeValue",
          "value": false,
          "attributeType": "directorySchemaExtension"
        }
      },
      "identities": [
        {
          "signInType": "email",
          "issuer": "contoso.onmicrosoft.com",
          "issuerAssignedId": "larissa.price@contoso.onmicrosoft.com"
        }
      ]
    }
  }
}

Dış REST API'den yanıt

Microsoft Entra Id, aşağıdaki biçimde bir REST API yanıtı bekler. Yanıt değeri türleri, istek değeri türleriyle eşleşer, örneğin:

İstek ile bir int64DirectoryAttributeValue@odata.type özniteliği graduationYear içeriyorsa, yanıt gibi bir graduationYear tamsayı değerine 2010sahip bir öznitelik içermelidir.
İstekte virgülle ayrılmış dize olarak belirtilen birden çok değer içeren bir öznitelik varsa, yanıt virgülle ayrılmış dizedeki değerleri içermelidir.

continueWithDefaultBehavior eylemi, dış REST API'nizin bir devamlılık yanıtı döndürdüğünü belirtir.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

setPrefillValues eylemi, dış REST API'nin varsayılan değerlerle önceden doldurma özniteliklerine yanıt döndürdüğünü belirtir. REST API'niz yeni öznitelikler ekleyemez. Döndürülen ancak öznitelik koleksiyonunun parçası olmayan ek öznitelikler yoksayılır.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

showBlockPage eylemi, dış REST API'nizin engelleme yanıtı döndürdüğünü belirtir.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.showBlockPage",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

Aracılığıyla paylaş