Informations de référence sur l’événement Custom Extension pour OnAttributeCollectionStart (préversion)

S’applique à : Locataires de main-d’œuvre Locataires externes (en savoir plus)

Pour modifier l’expérience d’inscription pour vos flux d’utilisateurs d’inscription en libre-service clients, vous pouvez créer une extension d’authentification personnalisée et l’appeler à des points spécifiques dans le flux d’utilisateur. L’événement OnAttributeCollectionStart se produit au début de l’étape de collection 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 e-mail, ou de préremplir des attributs avec des valeurs spécifiées. Les actions suivantes peuvent être configurées :

• continueWithDefaultBehavior : afficher 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 de l’API REST pour l’événement OnAttributeCollectionStart. (Voir également l’article connexe Extension personnalisée pour l’événement OnAttributeCollectionSubmit.)

Conseil

Pour essayer cette fonctionnalité, accédez à la version de démonstration Woodgrove Groceries et démarrez le cas d’utilisation « Préremplir les attributs d’inscription ».

Schéma API REST

Pour développer votre propre API REST pour l’événement de démarrage de collection d’attributs, utilisez le contrat de données API REST suivant. Le schéma décrit le contrat qui permet de concevoir le gestionnaire de requêtes et de réponses.

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 par votre API pour effectuer une logique supplémentaire.

Requête adressée à 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 requête contient les attributs utilisateur sélectionnés dans le flux d’utilisateur pour la collecte pendant 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 requête contient également des identités utilisateur, y compris l’adresse e-mail de l’utilisateur si elle a été utilisée 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’ont pas de valeurs attribuées.

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

Réponse de l’API REST externe

Microsoft Entra ID attend une réponse de l’API REST au format suivant. Les types de valeur de la réponse correspondent aux types de valeur de la requête, par exemple :

• Si la requête contient un attribut graduationYear avec une valeur @odata.type sur 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.

L’action continueWithDefaultBehavior spécifie que votre API REST externe retourne une réponse de continuation.

HTTP/1.1 200 OK

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

L’action setPrefillValues spécifie que l’API REST externe retourne une réponse aux préremplissage des 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.

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

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

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