Informations de référence sur l’extension personnalisée pour l’événement OnAttributeCollectionSubmit (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 OnAttributeCollectionSubmit se produit une fois que l’utilisateur entre et envoie des attributs et peut être utilisé pour valider les informations fournies par l’utilisateur. Par exemple, vous pouvez valider un code d’invitation ou un numéro de partenaire, modifier un format d’adresse, autoriser l’utilisateur à continuer ou afficher une page de validation ou de blocage. Les actions suivantes peuvent être configurées :

• continueWithDefaultBehavior : continuer avec le flux d’inscription.
• modifyAttributeValues : remplacer les valeurs envoyées par l’utilisateur dans le formulaire d’inscription.
• showValidationError : retourner une erreur en fonction des valeurs envoyées.
• 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 OnAttributeCollectionSubmit. (Voir également l’article connexe Extension personnalisée pour l’événement OnAttributeCollectionStart.)

Conseil

Pour essayer cette fonctionnalité, accédez à la version de démonstration Woodgrove Groceries et démarrez le cas d’utilisation « Valider les attributs d’inscription » ou le cas d’utilisation « Empêcher un utilisateur de poursuivre le processus d’inscription ».

Schéma API REST

Pour développer votre propre API REST pour l’événement d’envoi de collection d’attributs, utilisez le contrat de données d’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é. Pour les attributs avec plusieurs valeurs, les valeurs sont envoyées sous forme de chaîne délimitée par des virgules.

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

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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

L’action modifyAttributeValues spécifie que votre API REST externe retourne une réponse pour modifier et remplacer les attributs par défaut après la collecte des attributs. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

L’action showValidationError spécifie que votre API REST retourne une erreur de validation ainsi qu’un message et un code d’état appropriés.

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