Configurer une application pour Universal Portals

Chaque portail repose sur une Application Web classique Auth0. Le serveur du portail utilise les informations d’identification de l’application pour connecter les utilisateurs et obtenir des jetons d’accès pour l’API My Account et l’API My Organization. Une application ne sert qu’un seul portail, et un portail n’utilise qu’une seule application. Le Démarrage rapide Universal Portals crée et configure l’Application Web classique à votre place. Consultez cette page si vous souhaitez associer une application existante, gérer votre configuration sous forme de code ou vérifier les paramètres.

Exigences selon le scénario

Scénario	Exigences
Portail grand public	Accès à l’API My Account avec les permissions de l’API My Account
Portail entreprise	Accès à l’API My Organization avec les permissions de l’API My Organization, ainsi que les paramètres de contexte d’organisation
Application native	L’application accepte les jetons de transfert de session. Consultez Application native
Forms qui mettent à jour les utilisateurs	Une application de communication entre machines distincte pour le coffre-fort de Forms. Consultez Forms qui mettent à jour les utilisateurs

Chaque serveur de ressources appelé par votre portail, soit l’API My Account et l’API My Organization, nécessite deux éléments :

Une autorisation client, qui permet à l’application de demander les permissions.
Une politique de jeton d’actualisation, qui permet au serveur du portail d’échanger le contre un jeton d’accès pour ce serveur de ressources.

S’il manque l’un ou l’autre, les composants échouent et renvoient des erreurs d’API. Pour en savoir plus, consultez Multi-Resource Refresh Token. Les permissions à accorder dépendent des composants qu’utilise votre portail. Les listes suivantes contiennent toutes les permissions requises par les composants pris en charge. Retirez celles des composants que vous n’utilisez pas. Pour connaître les permissions de chaque composant, consultez Référence de la bibliothèque de composants de portail.

Permissions de l’API My Account

Public : https://YOUR_DOMAIN/me/

read:me:factors
read:me:authentication_methods
create:me:authentication_methods
delete:me:authentication_methods

Permissions de l’API My Organization

Public : https://YOUR_DOMAIN/my-org/

read:my_org:details
update:my_org:details
read:my_org:configuration
read:my_org:domains
create:my_org:domains
update:my_org:domains
delete:my_org:domains
read:my_org:identity_providers
create:my_org:identity_providers_domains
delete:my_org:identity_providers_domains

Configuration recommandée

Utilisez ces paramètres pour l’application du portail. Les durées de vie des jetons d’actualisation correspondent à celles de la session du portail : 1 heure d’inactivité et 1 jour au total. N’accordez que les permissions nécessaires aux composants qu’utilise votre Portal, et supprimez la politique et le grant associés à tout serveur de ressources que votre Portal n’appelle pas.

Auth0 Dashboard
Management API

Créer l’application

Accédez à Auth0 Dashboard > Integration > Applications, sélectionnez Create Application, choisissez Regular Web Applications et saisissez un nom.

Définir les URL

Dans l’onglet Settings, réglez Allowed Callback URLs sur https://YOUR_DOMAIN/portals/auth/callback. Réglez Allowed Logout URLs sur l’URL de votre application, c’est-à-dire la page où arrivent les utilisateurs après s’être déconnectés du Portal.

Faire confiance à l’en-tête IP du point de terminaison de jetons

Dans l’onglet Credentials, sous Advanced, activez Trust token endpoint IP header.

Définir les types d’autorisation

Dans Advanced Settings > Grant Types, activez Authorization Code, Refresh Token et MFA. Laissez tous les autres types d’autorisation désactivés.

Définir la durée de vie des jetons d’actualisation

Dans Refresh Token Expiration, activez Set Idle Refresh Token Lifetime et saisissez 3600 secondes. Activez Set Maximum Refresh Token Lifetime et saisissez 86400 secondes. Laissez la rotation des jetons d’actualisation désactivée (paramètre par défaut).

Autoriser les organisations

Dans l’onglet Organizations, réglez Type of Users sur Both et Login Flow sur No Prompt.

Accorder l’accès aux API

Dans l’onglet API Access, autorisez l’API My Account et l’API My Organization pour l’accès utilisateur, avec les permissions indiquées dans Exigences par scénario.

Activer les Multi-Resource Refresh Tokens

Dans Multi-Resource Refresh Token, activez les mêmes API et permissions. Sélectionnez Save Changes.

Créez l’application. La charge utile définit les valeurs qui diffèrent des valeurs par défaut d’une nouvelle Application Web classique, ainsi que les politiques de jeton d’actualisation des deux serveurs de ressources. L’API exige rotation_type chaque fois que vous envoyez refresh_token.

curl --request POST \
  --url "https://YOUR_DOMAIN/api/v2/clients" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "name": "{portalName} (Universal Portals)",
    "app_type": "regular_web",
    "oidc_conformant": true,
    "callbacks": ["https://YOUR_DOMAIN/portals/auth/callback"],
    "allowed_logout_urls": ["{yourApplicationUrl}"],
    "grant_types": [
      "authorization_code",
      "refresh_token",
      "http://auth0.com/oauth/grant-type/mfa-oob",
      "http://auth0.com/oauth/grant-type/mfa-otp",
      "http://auth0.com/oauth/grant-type/mfa-recovery-code"
    ],
    "token_endpoint_auth_method": "client_secret_post",
    "is_token_endpoint_ip_header_trusted": true,
    "organization_usage": "allow",
    "refresh_token": {
      "rotation_type": "non-rotating",
      "expiration_type": "expiring",
      "token_lifetime": 86400,
      "idle_token_lifetime": 3600,
      "policies": [
        {
          "audience": "https://YOUR_DOMAIN/me/",
          "scope": [
            "read:me:factors",
            "read:me:authentication_methods",
            "create:me:authentication_methods",
            "delete:me:authentication_methods"
          ]
        },
        {
          "audience": "https://YOUR_DOMAIN/my-org/",
          "scope": [
            "read:my_org:details",
            "update:my_org:details",
            "read:my_org:configuration",
            "read:my_org:domains",
            "create:my_org:domains",
            "update:my_org:domains",
            "delete:my_org:domains",
            "read:my_org:identity_providers",
            "create:my_org:identity_providers_domains",
            "delete:my_org:identity_providers_domains"
          ]
        }
      ]
    }
  }'

Créez ensuite une autorisation client pour chaque serveur de ressources. L’exemple suivant accorde l’accès à l’API My Account. Refaites la même opération avec le public https://YOUR_DOMAIN/my-org/ et les permissions de l’API My Organization.

curl --request POST \
  --url "https://YOUR_DOMAIN/api/v2/client-grants" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "client_id": "{portalClientId}",
    "audience": "https://YOUR_DOMAIN/me/",
    "subject_type": "user",
    "scope": [
      "read:me:factors",
      "read:me:authentication_methods",
      "create:me:authentication_methods",
      "delete:me:authentication_methods"
    ]
  }'

Paramètres à ne pas modifier

Ces paramètres déterminent le fonctionnement des Portals et ne doivent pas être modifiés.

D’autres paramètres de l’application peuvent également influer sur le comportement du Portal. Testez d’abord toute modification sur un locataire de développement.

N’activez pas DPoP. Le serveur du portail est un client confidentiel et n’utilise pas de jetons liés à l’émetteur.
N’activez pas la rotation des jetons d’actualisation. Les Portals ne la prennent pas en charge.
Ne partagez pas une même application entre plusieurs Portals. Chaque Portal doit avoir sa propre application.
Ne réglez pas la durée de vie d’inactivité du jeton d’actualisation à moins d’une heure. La session du portail expire après une heure d’inactivité. Si la durée de vie du jeton d’actualisation est plus courte, les appels d’API échoueront avant que le Portal ne demande à l’utilisateur de se reconnecter.
N’ajoutez pas de types d’autorisation ni de permissions que le Portal n’utilise pas. Par exemple, n’activez pas le grant client_credentials.
N’ajoutez pas de grant Management API à l’application du portail. Les Forms qui mettent à jour les utilisateurs doivent utiliser une application de communication entre machines distincte.

Paramètres selon le scénario

Certains cas d’utilisation exigent des paramètres supplémentaires dans l’application du portail. Consultez les scénarios de cette section et appliquez les paramètres qui correspondent à la façon dont vos utilisateurs accèdent au Portail.

Application native

Pour ouvrir le portail à partir d’une application native, l’application du portail doit accepter les jetons de transfert de session reçus dans l’URL. Ajoutez le code suivant à l’application du portail :

{
  "session_transfer": {
    "allowed_authentication_methods": ["query"],
    "enforce_device_binding": "ip"
  }
}

Configurez l’application native pour qu’elle crée des jetons de transfert de session. Pour en savoir plus, consultez Configurer et mettre en œuvre l’authentification unique d’une application native à une application Web. Suivez ensuite les instructions de la page Accéder aux portails.

Contexte d’organisation

Pour ouvrir le portail avec le paramètre organization, l’application du portail doit autoriser les Organisations :

{
  "organization_usage": "allow"
}

La configuration recommandée inclut déjà cette valeur, avec le flux de connexion no_prompt par défaut. Avec ces paramètres, envoyez toujours organization chaque fois que vous ouvrez un Portal d’entreprise. Pour en savoir plus, consultez Définir le comportement des organisations et Accéder aux Portals.

Forms qui mettent à jour les utilisateurs

Un formulaire dont le flux met à jour les utilisateurs appelle la Management API au moyen d’une connexion de coffre-fort Forms. Créez une application de communication entre machines distincte pour cette connexion et accordez-lui seulement les permissions nécessaires au flux, comme update:users et update:users_app_metadata. Pour en savoir plus, consultez Connexions de coffre-fort Auth0.

Associer l’application au portail

Auth0 Dashboard
Management API

Accédez à Auth0 Dashboard > Portals et sélectionnez Create Portal, ou ouvrez un portail existant.
Saisissez un Name et un Slug, puis sélectionnez l’application. Le slug sera intégré à l’URL du portail.
Sélectionnez Create.

curl --request POST \
  --url "https://YOUR_DOMAIN/api/v2/portals" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "name": "{portalName}",
    "slug": "{slug}",
    "client": {
      "token_endpoint_auth_method": "client_secret_post",
      "client_id": "{portalClientId}",
      "client_secret": "{portalClientSecret}"
    }
  }'

Le client_secret est accessible en écriture seule : Auth0 ne le renvoie jamais. L’API des portails ne prend en charge que client_secret_post. Un slug en double renvoie une erreur 409 Conflict.

Valider les connexions activées

Les utilisateurs peuvent se connecter au Portal avec n’importe quelle connexion activée pour l’application du portail. Avant de partager le Portal, assurez-vous qu’au moins une des connexions dont vos utilisateurs ont besoin est activée.

Accédez à Auth0 Dashboard > Applications et sélectionnez l’application du portail.
Sélectionnez l’onglet Connexions.
Activez les connexions dont vos utilisateurs ont besoin. Si aucune connexion n’est activée, les utilisateurs ne pourront pas se connecter au Portal.

Pour en savoir plus, consultez Mettre à jour les connexions d’application.

Si le paramètre du locataire Enable Application Connections est activé, l’application du portail reçoit toutes les connexions actuelles du locataire, y compris celle créée par le Démarrage rapide. Pour en savoir plus, consultez Paramètres du tenant.

Vérifier la configuration

Ouvrez https://YOUR_DOMAIN/portals/{slug} et connectez-vous avec un utilisateur test. Ouvrez une page qui contient un composant Universal. Si le composant affiche une erreur, consultez Dépanner les portails Universal.

Prochaines étapes

Dépanner les Universal Portals

Corrigez les erreurs d’API ainsi que les problèmes de connexion et d’organisation.

Accéder aux Portals

Redirigez les utilisateurs de vos applications vers le Portal.

Personnalisation de l’image de marque

Personnalisation du code

Personnalisation par des tiers

Configurer une application pour Universal Portals

Exigences selon le scénario

Configuration recommandée

Paramètres à ne pas modifier

Paramètres selon le scénario

Application native

Contexte d’organisation

Forms qui mettent à jour les utilisateurs

Associer l’application au portail

Valider les connexions activées

Vérifier la configuration

Prochaines étapes

Dépanner les Universal Portals

Accéder aux Portals

​Exigences selon le scénario

​Configuration recommandée

​Paramètres à ne pas modifier

​Paramètres selon le scénario

​Application native

​Contexte d’organisation

​Forms qui mettent à jour les utilisateurs

​Associer l’application au portail

​Valider les connexions activées

​Vérifier la configuration

​Prochaines étapes

Dépanner les Universal Portals

Accéder aux Portals

Exigences selon le scénario

Configuration recommandée

Paramètres à ne pas modifier

Paramètres selon le scénario

Application native

Contexte d’organisation

Forms qui mettent à jour les utilisateurs

Associer l’application au portail

Valider les connexions activées

Vérifier la configuration

Prochaines étapes