API Identité headless : Flux Invité headless pour des clients publics
Certains utilisateurs interagissent avec votre application hors plate-forme, mais ne se connectent pas et ne s'inscrivent pas. Vous pouvez émettre des identifiants sous forme d’ID de visiteur unique (UVID) pour ces visiteurs inconnus avec le flux Invité headless. Si l'utilisateur décide de se connecter ou de s'inscrire, vous pouvez transmettre l'identifiant dans un flux utilisateur nommé, par exemple un flux de connexion headless. Utilisez l'identité utilisateur invité en tant qu'outil pour transférer le contexte des sessions utilisateur invité vers des sessions utilisateur nommé. Ce flux est une variante du flux Code d'autorisation et identifiants.
Éditions requises
| Disponible avec : Salesforce Classic (pas disponible dans toutes les organisations) et Lightning Experience |
| Disponible avec : Enterprise Edition, Unlimited Edition et Developer Edition |
Avant de configurer ce flux, procédez comme suit.
- Prérequis à Identité headless
- Intégrez votre application hors plate-forme à Salesforce en utilisant l'une des options ci-dessous. Assurez-vous de configurer des stratégies supplémentaires pour le flux invité.
Par exemple, vous hébergez une application e-commerce hors de la plate-forme Salesforce. Vous souhaitez que les utilisateurs puissent enregistrer des articles dans un panier d'achat sans se connecter. Vous pouvez utiliser le flux utilisateur invité pour générer un UVID pour l’utilisateur, et stocker les informations du panier d’achat de l’utilisateur et l'associer à l’UVID. Lorsque l’utilisateur se connecte ou s’inscrit, vous transmettez l'UVID dans un flux de connexion ou d’inscription headless. Comme vous disposez du contexte du panier d’achat avec l’UVID, vous pouvez enregistrer les articles de l’utilisateur et lui offrir une meilleure expérience.
L’exemple de panier d’achat est l’une des nombreuses possibilités offertes par l'UVID et le flux invité. D'autres possibilités existent, notamment la compréhension des raisons pour lesquelles les utilisateurs s'inscrivent dans votre application et la mémorisation de leurs préférences.
Le flux invité et l'UVID sont pris en charge uniquement pour les jetons d'accès basés sur JWT. Pour connecter l’UVID à un utilisateur nommé, vous devez configurer le flux utilisateur nommé pour qu'il émette aussi des jetons d’accès basés sur JWT.
Ces instructions indiquent comment implémenter le flux pour un client public, par exemple une application à page unique, qui ne peut pas garder les informations confidentielles privées. Les clients publics font l'objet de considérations de sécurité supplémentaires. Par rapport à un client privé, par exemple une application client-serveur, ils n'ont pas de back-end privé pour stocker le secret consommateur, qui agit en tant que mot de passe pour sécuriser l'échange de code. Sans emplacement pour stocker le secret consommateur, l'application ne risque aucune fuite du secret. Pour remplacer le rôle du secret consommateur, vous pouvez utiliser à la place l'extension Clé de vérification pour l'échange de code (PKCE). Cette extension protège votre application avec des paramètres que seuls vous et Salesforce pouvez vérifier. Nous recommandons de toujours implémenter la PKCE pour un client public.
Voici une vue d'ensemble du flux invité. Ces étapes montrent le flux jusqu'à l'identification de l'utilisateur invité, mais pas la connexion.
- Le visiteur inconnu arrive dans l'application ou exécute une action, par exemple cliquer sur un bouton (1).
- L’application recherche un UVID et génère une valeur s'il n'en trouve pas.
- Si vous utilisez l'extension Clé de vérification pour l'échange de code (PKCE), que nous recommandons vivement, l'application génère les paramètres PKCE.
- Pour obtenir un code d'autorisation, votre application envoie l'UVID headless au point de terminaison d'autorisation Salesforce (
services/oauth2/authorize) dans une requête GET ou POST. - Salesforce valide l'UVID et renvoie une redirection HTTP 302 à une URL préconfigurée contenant le code d'autorisation. La redirection est traitée dans le navigateur, et la réponse est livrée au point de terminaison de rappel.
- Le point de terminaison de rappel extrait le code d'autorisation et le renvoie à votre application.
- Votre application reçoit le code d'autorisation et initie un échange de code en l'envoyant avec d'autres paramètres dans une requête POST au point de terminaison de jeton Salesforce (
services/oauth2/token). - Salesforce valide la requête et renvoie un jeton d'accès invité basé sur JWT avec l'UVID dans la réclamation objet.
- Votre application traite la réponse et crée une session invité, en conservant la valeur UVID.
- L’utilisateur a maintenant une session invité incluse dans la valeur UVID renvoyée par le jeton d’accès.
De la même façon que les autres variantes du flux Code d'autorisation et identifiants, pour un client public, ce flux nécessite un point de terminaison de rappel qui peut gérer la redirection 302 et renvoyer le code d'autorisation et d'autres paramètres à votre application. Si vous effectuez l'échange de code dans votre navigateur, vous pouvez utiliser le point de terminaison Salesforce /services/oauth2/echo. Il analyse automatiquement la redirection 302, extrait les paramètres et les renvoie à votre application sous le format JSON. Nous utilisons le point de terminaison echo dans les exemples de code de ce flux.
Arrivée de l'utilisateur inconnu dans votre application
Le flux démarre lorsqu'un utilisateur visite votre application. Vous pouvez également configurer son démarrage lorsque l'utilisateur exécute une action, par exemple enregistrer un article dans un panier d'achat.
Génération d'un UVID par l'application
Votre application recherche un UVID associé à cet utilisateur. Par exemple, elle recherche dans les cookies du navigateur liés aux visites précédentes de l'application. Si l'application ne trouve pas d'UVID, elle en génère un. Salesforce ne joue aucun rôle dans la génération de l'UVID. Sa génération, son stockage et sa maintenance vous reviennent. Une seule exigence, l’UVID doit être un identifiant unique universel version 4 (v4 UUID).
Génération des paramètres PKCE par l'application
Si vous utilisez PKCE, votre application génère les paramètres code_verifier et code_challenge.
La spécification PKCE définie dans RFC 7636 inclut également un paramètre facultatif code_challenge_method que vous pouvez envoyer dans la requête d'autorisation. Salesforce ignore toute valeur que vous envoyez dans ce paramètre et applique par défaut SHA256.
Échange de l’UVID contre un code d’autorisation par l'application
Votre application envoie une requête GET ou POST headless au point de terminaison d'autorisation Salesforce de votre site Experience Cloud. La requête contient l'UVID et d’autres paramètres pour identifier l’application et spécifier le type de requête.
Vous avez deux options pour envoyer l’UVID dans cette requête. Vous pouvez envoyer une valeur UVID brute ou un jeton d’accès basé sur JWT avec l'UVID inclus. Par exemple, si vous avez le jeton d’accès basé sur JWT d’une session précédente, l’envoi du jeton au point de terminaison d’autorisation facilite sa réutilisation sans l’analyse spécifique au UVID.
Insérez les en-têtes ci-dessous dans votre requête.
| En-tête | Obligatoire ? | Description |
|---|---|---|
Uvid-Hint
|
Requis si vous n’envoyez pas l’UVID dans le corps de requête. Vous devez toujours inclure un UVID (que ce soit dans l'en-tête ou dans le corps de la requête). | Contient l'UVID en valeur brute ou un jeton d’accès basé sur JWT avec un UVID inclus. Si vous envoyez l'UVID en valeur brute, insérez un préfixe Si vous envoyez un jeton d'accès basé sur JWT contenant un UVID, insérez un préfixe |
Auth-Request-Type
|
Oui. | Spécifie le type de requête que vous souhaitez envoyer à Salesforce. Pour la connexion sans mot de passe headless, cette valeur doit être définie sur guest. |
Insérez les paramètres ci-dessous dans le corps de la requête.
| Paramètre | Obligatoire ? | Description |
|---|---|---|
uvid_hint
|
Obligatoire si vous n'incluez pas l’UVID dans l’en-tête. | Contient l'UVID en valeur brute ou un jeton d’accès basé sur JWT avec un UVID inclus. Si vous envoyez l'UVID en valeur brute, insérez un préfixe Si vous envoyez un jeton d'accès basé sur JWT contenant un UVID, insérez un préfixe |
client_id
|
Oui. | La clé consommateur de l'application cliente externe ou de l'application connectée. |
response_type
|
Oui. | Le type d'octroi OAuth 2.0 que demande votre application. Comme ce flux est une variante du flux Code d'autorisation et identifiants, cette valeur doit être code_credentials. |
redirect_uri
|
Oui. | L'URL vers laquelle les utilisateurs sont redirigés après la réussite de l'authentification. Pour ce flux, vous pouvez utiliser le point de terminaison echo, |
code_challenge
|
Uniquement si vous utilisez la PKCE, que nous recommandons toujours, particulièrement pour un client public. | Spécifie la valeur de hachage SHA256 de la valeur Si Si |
scope
|
Oui. | Les autorisations qui définissent les types de ressource protégée auxquels l'application cliente externe ou connectée peut accéder. Les valeurs que vous envoyez dans cette requête doivent correspondre aux ou être un sous-ensemble des étendues attribuées à votre application. Pour plus d'informations sur chaque étendue et son objet, consultez Jetons OAuth et étendues. |
Consultez les exemples de requêtes d'autorisation ci-dessous, qui implémentent l’extension PKCE.
Voici un exemple de requête dans laquelle l’UVID est transmis en valeur brute dans l'en-tête de la requête.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
Auth-Request-Type: guest
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
Dans cet exemple, l'UVID est transmis dans un jeton d’accès basé sur JWT dans l'en-tête.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: JWT **************
Auth-Request-Type: guest
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
Voici un exemple de transmission de l’UVID en valeur brute dans le corps de la requête.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: guest
uvid_hint=UVID abcd-1234-efgh&
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
Salesforce renvoie une redirection 302
Salesforce valide l'UVID. Si l'UVID est transmis en valeur brute, Salesforce valide son format. S'il est transmis dans un jeton d'accès basé sur JWT, Salesforce vérifie la validité du jeton.
Salesforce renvoie ensuite une redirection HTTP 302 vers une URL préconfigurée contenant le code d'autorisation. Si le flux se produit dans le navigateur, la redirection 302 est traitée dans le navigateur et Salesforce envoie automatiquement la réponse de redirection à l'URL de redirection, qui est le point de terminaison de rappel. Voici un exemple d'URL préconfigurée.
https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxxEnvoi du code d'autorisation à votre application par le point de terminaison de rappel
Le point de terminaison de rappel extrait le code d'autorisation et le renvoie à votre application. Dans ces exemples de code, l'URL de redirection pointe vers le point de terminaison de rappel /services/oauth2/echo dans le site Experience Cloud. Ce point de terminaison analyse automatiquement la redirection 302, extrait le code d'autorisation et d'autres paramètres et les renvoie à votre application sous le format JSON.
Échange de code initié par l'application
Votre application reçoit la réponse de code avec l'autorisation et d'autres paramètres. Elle échange le code contre un jeton d'accès en envoyant une requête POST headless au point de terminaison /services/oauth2/token.
Insérez un en-tête dans la requête.
| Paramètre | Obligatoire ? | Description |
|---|---|---|
Auth-Request-Type
|
Oui. | Spécifie le type de requête que vous souhaitez envoyer à Salesforce. Pour la connexion sans mot de passe headless, cette valeur doit être définie sur guest. |
Uvid-Hint
|
Oui. | Contient l'UVID en tant que valeur brute ou un jeton d’accès basé sur JWT avec un UVID inclus. Pour l’échange de code, n'incluez pas de préfixe pour l'UVID. Par exemple, si vous transmettez l'UVID en valeur brute, l'en-tête est seulement |
Insérez les paramètres ci-dessous dans le corps de la requête.
| Paramètre | Obligatoire ? | Description |
|---|---|---|
code
|
Oui. | Le serveur d'autorisation crée un code d'autorisation, un jeton éphémère, et le transmet au client une fois l'authentification réussie. Le client envoie le code d'autorisation au serveur d'autorisation pour obtenir le jeton d'accès et éventuellement un jeton d'actualisation. |
client_id
|
Oui. | La clé consommateur de l'application cliente externe ou de l'application connectée. |
redirect_uri
|
Oui. | L'URL vers laquelle les utilisateurs sont redirigés après une authentification réussie. L'URI de redirection doit correspondre à l'une des valeurs du champ URL de rappel de l'application connectée. Sinon, l'approbation échoue. Cette valeur doit être codée en URL. Pour ce flux, vous pouvez utiliser le point de terminaison echo, |
grant_type
|
Oui. | Le type de validation que l'application cliente externe ou connectée peut fournir pour prouver qu'elle est un visiteur de confiance. Comme ce flux est une variante du flux Code d'autorisation et identifiants, la valeur doit être authorization_code. |
code_verifier
|
Uniquement si vous utilisez PKCE. | Spécifie 128 octets de données aléatoires avec une entropie élevée pour rendre la valeur du code difficile à deviner. Définissez ce paramètre pour empêcher les attaques par interception de code d'autorisation. La valeur doit être codée en base64url comme défini dans https://datatracker.ietf.org/doc/html/rfc4648#section-5. Si une valeur Si la valeur |
Voici un exemple de requête de jeton qui implémente la PKCE. Dans cet exemple, l'UVID est envoyé en valeur brute.
POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: abcd-1234-efgh
Auth-Request-Type: guest
code=********&
client_id=**********&
redirect_uri=https://MyExperienceCloudSite.my.site.com/services/oauth2/echo&
grant_type=authorization_code&
code_verifier=*******Octroi d'un jeton d'accès basé sur JWT par Salesforce
Après la validation des identifiants de l'application. Salesforce renvoie un jeton d'accès invité basé sur JWT et un état au navigateur. Le jeton d'accès invité contient l'UVID dans la réclamation objet (sub). Voici un exemple d'extrait d'un jeton d'accès basé sur JWT. Pour rappel, ces jetons contiennent trois composants : un en-tête, une charge de travail et une signature. Cet exemple montre la charge de travail avec l'UVID dans la réclamation sub. Comme vous pouvez le voir, la valeur est précédée de uvid.
{
"tnk": "example/00XXXXXX",
"ver": "1.0",
"kid": "CORE_ATJWT************",
"tty": "sfdc-core-token",
"typ": "JWT",
"alg": "RS256"
}
{
"scp": "open_id",
"aud": [
"https://example.com"
],
"sub": "uvid:abcd-1234-efgh",
"nbf": "1675197036",
"iss": "https://MyExperienceCloudSite.my.site.com",
"exp": "1675198836",
"iat": "1675197036",
jti”: xRb**********”
"client_id": "**********"
}Pour une explication détaillée de chaque réclamation dans un jeton d'accès basé sur JWT, consultez Jetons d'accès basés sur JWT dans l'Aide de Salesforce.
Création d'une session invité par l'application
Votre application traite la réponse du jeton d'accès et crée une session invité, en conservant la valeur UVID.
Identification de l'utilisateur inconnu
L’utilisateur inconnu a maintenant une session invité liée à la valeur UVID renvoyée par le jeton d’accès basé sur JWT. À ce point, vous décidez l'action exécutée avec l’UVID. Pour apprendre à le transmettre dans un flux d'autorisation utilisateur nommé, consultez Headless Identity APIs: Extension du flux Invité headless en un flux Utilisateur nommé.
