Récupérer et retourner des données à partir d’un événement OnAttributeCollectionStart

S’applique à : Locataires externes (en savoir plus)

Pour modifier l’expérience d’inscription pour vos flux d’utilisateurs d’inscription en libre-service client, vous pouvez créer une extension d’authentification personnalisée et l’appeler à des points spécifiques dans le flux utilisateur. L’événement OnAttributeCollectionStart se produit au début de l’étape de collecte d’attributs, avant le rendu de la page de collection d’attributs. Cet événement vous permet de définir des actions avant que les attributs ne soient collectés auprès de l’utilisateur. Par exemple, vous pouvez empêcher un utilisateur de poursuivre le flux d’inscription en fonction de son identité fédérée ou de son adresse e-mail, ou préremplir les attributs avec des valeurs spécifiées. Les actions suivantes peuvent être configurées :

• continueWithDefaultBehavior : rendre la page de collection d’attributs comme d’habitude.
• setPreFillValues : préremplir les attributs dans le formulaire d’inscription.
• showBlockPage : afficher un message d’erreur et empêcher l’utilisateur de s’inscrire.

Cet article décrit le schéma d’API REST pour l’événement OnAttributeCollectionStart. (Voir aussi l’article connexe Extension personnalisée pour l’événement OnAttributeCollectionSubmit.)

Schéma de l’API REST

Pour développer votre propre API REST pour l’événement de début de la collection d’attributs, utilisez le contrat de données d’API REST suivant. Le schéma décrit le contrat pour concevoir le gestionnaire de demande et de réponse.

Votre extension d’authentification personnalisée dans Microsoft Entra ID effectue un appel HTTP à votre API REST avec une charge utile JSON. La charge utile JSON contient des données de profil utilisateur, des attributs de contexte d’authentification et des informations sur l’application à laquelle l’utilisateur souhaite se connecter. Les attributs JSON peuvent être utilisés pour effectuer une logique supplémentaire par votre API.

Demande à l'API REST externe

La requête adressée à votre API REST est au format indiqué ci-dessous. Dans cet exemple, la requête inclut des informations sur les identités utilisateur, ainsi que les attributs intégrés (givenName et companyName) et les attributs personnalisés (universityGroups, graduationYear et onMailingList).

La demande contient les attributs utilisateur qui sont sélectionnés dans le flux d’utilisateurs pour la collecte lors de l’inscription en libre-service, y compris les attributs intégrés (par exemple, givenName et companyName) et les attributs personnalisés qui ont déjà été définis (par exemple, universityGroups, graduationYear et onMailingList). Votre API REST ne peut pas ajouter de nouveaux attributs.

La demande contient également des identités utilisateur, y compris l’e-mail de l’utilisateur s’il a été utilisé comme informations d’identification vérifiées pour s’inscrire. Le mot de passe n’est pas envoyé.

Les attributs de la demande de démarrage contiennent leurs valeurs par défaut. Pour les attributs avec plusieurs valeurs, les valeurs sont envoyées sous forme de chaîne délimitée par des virgules. Étant donné que les attributs n’ont pas encore été collectés auprès de l’utilisateur, la plupart des attributs n’auront pas de valeur attribuée. La requête HTTP suivante montre comment Microsoft Entra appelle votre API REST.

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

Content-Type: application/json

[Request payload]

Le document JSON suivant fournit un exemple de charge utile de requête :

{
  "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"
        }
      ]
    }
  }
}

Réponse de l’API REST externe

Les types de valeur de réponse correspondent aux types de valeur de requête, par exemple :

• Si la requête contient un attribut graduationYear avec une valeur @odata.type de int64DirectoryAttributeValue, la réponse doit inclure un attribut graduationYear avec une valeur entière, par exemple 2010.
• Si la requête contient un attribut avec plusieurs valeurs spécifiées en tant que chaîne délimitée par des virgules, la réponse doit contenir les valeurs d’une chaîne délimitée par des virgules.

Microsoft Entra ID attend une réponse d’API REST au format suivant.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Dans la réponse HTTP, fournissez l’un des documents JSON suivants. L’action continueWithDefaultBehavior spécifie que votre API REST externe retourne une réponse de continuation.

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

L’action setPrefillValues spécifie que l’API REST externe renvoie une réponse pour préremplir les attributs avec des valeurs par défaut. Votre API REST ne peut pas ajouter de nouveaux attributs. Tous les attributs supplémentaires retournés, mais qui ne font pas partie de la collection d’attributs sont ignorés.

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

L’action showBlockPage spécifie que votre API REST externe retourne une réponse bloquante.

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