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

Makale
04/10/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. OnAttributeCollectionSubmit olayı, kullanıcı öznitelikleri girip gönderdikten sonra gerçekleşir ve kullanıcı tarafından sağlanan bilgileri doğrulamak için kullanılabilir. Örneğin, davet kodunu veya iş ortağı numarasını doğrulayabilir, adres biçimini değiştirebilir, kullanıcının devam etmesine izin verebilir veya doğrulama veya engelleme sayfası gösterebilirsiniz. Aşağıdaki eylemler yapılandırılabilir:

continueWithDefaultBehavior - Kaydolma akışıyla devam edin.
modifyAttributeValues - Kullanıcının kaydolma formunda gönderdiği değerlerin üzerine yazın.
showValidationError - Gönderilen değerlere göre bir hata döndürür.
showBlockPage - Bir hata iletisi gösterin ve kullanıcının kaydolmasını engelleyin.

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

İpucu

Bu özelliği denemek için Woodgrove Groceries tanıtımına gidin ve "Kaydolma özniteliklerini doğrula" kullanım örneğini veya "Kullanıcının kaydolma işlemini sürdürmesini engelle" kullanım örneğini başlatın.

REST API şeması

Öznitelik koleksiyonu gönderme 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. Birden çok değere sahip öznitelikler için değerler virgülle ayrılmış bir dize olarak gönderilir.

JSON

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

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionSubmit",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitCalloutData",
    "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

modifyAttributeValues eylemi, dış REST API'nizin öznitelikler toplandıktan sonra varsayılan değerlerle öznitelikleri değiştirmek ve geçersiz kılmak için bir 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

showValidationError eylemi, REST API'nizin bir doğrulama hatası ve uygun bir ileti ve durum kodu döndürdüğünü belirtir.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showValidationError",
        "message": "Please fix the below errors to proceed.",
        "attributeErrors": {
          "city": "City cannot contain any numbers",
          "extension_<appid>_graduationYear": "Graduation year must be at least 4 digits"
        }
      }
    ]
  }
}

Aracılığıyla paylaş