Configuration du flux d'échange de jetons
Certains cas d'utilisation nécessitent d'intégrer Salesforce à un fournisseur d'identité externe avec plusieurs applications et microservices. Pour simplifier ces intégrations, utilisez le flux d'échange de jetons OAuth 2.0. Ce flux permet d’échanger des jetons d’un fournisseur d'identité externe contre des jetons Salesforce.
Éditions requises
| Disponible avec : Enterprise Edition, Performance Edition, Unlimited Edition et Developer Edition |
Par exemple, vous hébergez un portail client hors de la plate-forme Salesforce. Pour fournir la connexion et l’inscription à vos clients, vous utilisez un fournisseur d'identité. Lorsque vos clients sont connectés, ils accèdent aux données de divers services d’entreprise, notamment des applications Web et des microservices. Pour autoriser votre portail à accorder aux utilisateurs l'accès à leurs données, tous ces services d'entreprise acceptent les jetons d'accès de votre fournisseur d'identité.
Vous utilisez Salesforce pour suivre les requêtes de support des clients et souhaitez accorder aux utilisateurs l’accès à leurs requêtes dans votre portail. En configurant Salesforce pour accepter les jetons de votre fournisseur d’identité, vous pouvez aisément ajuster Salesforce à votre modèle d’intégration. À l’aide du flux d’échange de jetons, Salesforce valide les jetons du fournisseur d’identité, les mappe avec un utilisateur Salesforce, puis émet des jetons Salesforce afin d’accorder aux utilisateurs l’accès à leurs données dans votre portail.
Vue d'ensemble pas à pas du flux d'échange de jetons.
L'utilisateur demande l'accès aux données Salesforce (1)
Un utilisateur est connecté à votre application. Il demande l'accès aux ressources Salesforce protégées. Il clique par exemple sur un bouton pour afficher ses requêtes.
L’application a un jeton valide (2)
Lorsque l’utilisateur est connecté, il reçoit un ou plusieurs jetons de votre fournisseur d’identité. Il reçoit par exemple un jeton d'accès et un jeton d'actualisation. Pour accéder aux données Salesforce, votre application peut échanger l'un de ces jetons. Salesforce accepte les types de jeton suivants :
- Jetons d’accès
- Jetons d'actualisation
- Jetons Web JSON (JWT)
- Assertions SAML
- Jetons d'identification
L’application demande l’échange d’un jeton Salesforce (3)
Pour obtenir un jeton Salesforce, votre application envoie une requête POST au point de terminaison /services/oauth2/token de votre URL de connexion Mon domaine ou site Experience Cloud.
La demande accepte un seul en-tête.
| En-tête | Obligatoire ? | Description |
|---|---|---|
Uvid-Hint
|
Non. Si vous implémentez le flux utilisateur invité dans votre application, vous pouvez également utiliser cet en-tête pour transmettre un ID de visiteur unique (UVID) lié à l'identité d'un utilisateur invité. Utilisez l'UVID pour transmettre des informations contextuelles depuis une session utilisateur invité, par exemple les préférences de cookie de l'utilisateur, dans une session utilisateur nommée. | Contient l'UVID, un identificateur unique universel (UUID) version 4 qui identifie les visiteurs inconnus. Envoyez l'UVID en valeur brute ou envoyez un jeton d’accès basé sur JWT contenant un UVID. Pour envoyer l'UVID en valeur brute, insérez un préfixe UVID qui met la demande en forme comme suit : Pour envoyer un jeton d'accès basé sur JWT contenant un UVID, insérez un préfixe JWT avant la valeur, par exemple |
Insérez les paramètres ci-dessous dans la demande.
| Paramètre | Obligatoire ? | Description |
|---|---|---|
grant_type
|
Oui. | La méthode OAuth 2.0 que l'application utilise pour demander le jeton d'accès. Le flux d'échange de jetons prend en charge les valeurs ci-dessous.
|
subject_token
|
Oui. | Le jeton émis par le fournisseur d'identité. La longueur maximale est de 10,000 caractères. |
subject_token_type
|
Oui. | Le type de jeton émis par le fournisseur d'identité. Le flux prend en charge les types de jeton suivants :
|
client_id
|
Oui. | La clé consommateur de l'application connectée ou de l'application cliente externe. |
client_secret
|
Dépend des paramètres de votre application connectée ou application cliente externe. Avec des applications connectées, pour demander un Avec des applications clientes externes, définissez le champ |
Le secret consommateur de l'application connectée ou de l'application cliente externe. Nous recommandons d'envoyer un secret consommateur uniquement si votre application a un back-end client privé dans lequel elle peut conserver le secret en toute sécurité. Pour les clients publics qui n'ont pas de back-end privé, par exemple les applications mobiles et les applications à page unique, nous recommandons de ne pas envoyer de secret, car il peut être révélé dans le navigateur. |
scope
|
Non. | Les autorisations qui définissent les types de ressource protégée auxquels l'application connectée peut accéder. Les valeurs que vous envoyez dans cette requête doivent correspondre aux ou être les étendues attribuées à votre application connectée ou application cliente externe. Pour plus d'informations sur chaque étendue et son objet, consultez Jetons OAuth et étendues. |
token_handler
|
Non, mais vivement recommandé. Si vous n'incluez pas ce paramètre, Salesforce utilise votre gestionnaire par défaut. Vous définissez un gestionnaire par défaut en utilisant le champ isDefault dans le type de métadonnées OauthTokenExchHandlerApp. Un gestionnaire par défaut minimum est requis. | Le nom du gestionnaire d'échange de jetons Apex utilisé pour valider le jeton et le mapper avec un utilisateur Salesforce. |
Voici un exemple de demande de jeton qui contient un jeton d'accès.
POST /services/oauth2/token? HTTP 1.1
Host: MyDomainName.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=*************&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
client_id=***********&
client_secret=************&
scope=web&
token_handler=MyTokenHandler
L’exécution OAuth Salesforce effectue la validation initiale (4)
L'exécution OAuth de Salesforce reçoit la demande et l'exécute via une validation initiale. La validation est basée sur les exigences ci-dessous.
- L'application connectée ou l'application cliente externe doit être activée pour le flux d'échange de jetons. Consultez Intégration d'une application pour le flux d'échange de jetons.
- Le
subject_token_typede la demande doit être activé pour le gestionnaire d'échange de jetons. Pour activer un gestionnaire pour un type de jeton, définissez le champ correspondant surtruedans la définition des métadonnées OauthTokenExchangeHandler du gestionnaire.subject_token_typeValeurChamp OauthTokenExchangeHandler urn:ietf:params:oauth:token-type:access_tokenisAccessTokenSupported urn:ietf:params:oauth:token-type:refresh_tokenisRefreshTokenSupported urn:ietf:params:oauth:token-type:id_tokenisIdTokenSupported urn:ietf:params:oauth:token-type:saml2isSaml2Supported urn:ietf:params:oauth:token-type:jwtisJwtSupported - Si la demande contient un
client_secret, elle doit correspondre au secret consommateur de l'application connectée ou de l'application cliente externe. - Si la demande contient un
token_handler, l'organisation doit avoir un gestionnaire d'échange de jetons Apex pris en charge correspondant au nom de la demande. - Le gestionnaire d'échange de jetons doit être activé, ce qui signifie que le champ isEnabled de sa définition de métadonnées OauthTokenExchangeHandler doit être défini sur
true.
Si la demande remplit ces exigences initiales, Salesforce envoie le jeton depuis le fournisseur d'identité externe vers le gestionnaire d'échange de jetons Apex.
Le gestionnaire Apex valide le jeton (5)
Le gestionnaire Apex reçoit le jeton du fournisseur d’identité et le valide en utilisant votre logique de validation personnalisée. Vous choisissez la méthode de validation du jeton.
(Facultatif) Le gestionnaire Apex appelle le fournisseur d'identité pour validation (6)
Selon vos exigences de validation, vous pouvez configurer votre gestionnaire pour qu’il appelle le fournisseur d’identité. Si le jeton est opaque ou si vous souhaitez le valider en temps réel, appelez le point de terminaison d'introspection du jeton ou Informations utilisateur du fournisseur d'identité externe.
Mappage du jeton avec un objet Salesforce par le gestionnaire Apex (7)
Le gestionnaire Apex identifie l'objet du jeton, qui correspond à l'utilisateur pour lequel il a été émis, puis le mappe avec un objet Salesforce.
(Facultatif) Le gestionnaire Apex appelle le fournisseur d'identité pour obtenir des informations sur les utilisateurs (8)
Pour recueillir suffisamment d'informations avant de créer un objet, ou des informations supplémentaires sur un objet entrant, vous pouvez configurer votre gestionnaire pour appeler le fournisseur d'identité ou un autre système externe.
Recherche ou configuration d'un utilisateur par le gestionnaire Apex (9)
Si le gestionnaire trouve un utilisateur à partir des données du jeton ou d'un appel externe, il renvoie l'utilisateur.
Si le champ isUserCreationAllowed est défini sur true dans la définition des métadonnées OauthTokenExchangeHandler du gestionnaire, le gestionnaire configure un nouvel objet Utilisateur et le renvoie à Salesforce. Cette action ne crée pas l'utilisateur. À la place, l'objet Utilisateur est renvoyé à Salesforce pour insertion automatique.
Pour plus d'informations sur la personnalisation de votre gestionnaire afin de valider des jetons et de mapper des objets, consultez Token Exchange Handler Validation and Subject Mapping dans Apex Developer Guide.
Exécution OAuth de Salesforce du mappage utilisateur (10)
L'exécution OAuth Salesforce vérifie si le gestionnaire a renvoyé un utilisateur. Dans la positive, il vérifie si l'utilisateur existe et effectue le mappage. Si l'utilisateur n'existe pas et que le gestionnaire est défini pour configurer des utilisateurs, Salesforce insère automatiquement l'utilisateur au nom du gestionnaire d'échange de jetons.
Renvoi d’une réponse avec jeton par l’exécution OAuth Salesforce (11)
Salesforce renvoie une réponse qui contient un jeton d'accès Salesforce et les autres jetons ou paramètres que vous avez demandés, notamment des jetons d'actualisation, des jetons d'identification et des jetons hybrides. Le jeton d'accès peut être opaque ou basé sur JWT, selon les paramètres de votre application connectée ou application cliente externe.
Si vous transmettez un UVID dans la demande de jeton, il est aussi transmis dans le flux. Pour une réponse de jeton opaque, l’UVID est exposé dans le point de terminaison services/oauth2/userinfo de votre URL de connexion Mon domaine ou site Experience Cloud. Pour une réponse de jeton basée sur JWT, l'UVID est inclus dans le nouveau jeton d'accès.
L’application reçoit la réponse (12)
Votre application reçoit la réponse de jeton, contenant le jeton d'accès et les autres jetons et paramètres. Exemple de réponse de jeton.
{
"access_token":"*******************",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://MyDomainName.my.salesforce.com",
"id":"https://MyDomainName.my.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}L’application appelle le point de terminaison Information utilisateur (13)
Pour terminer la procédure de connexion de l’utilisateur, votre application peut appeler le point de terminaison /services/oauth2/userinfo de votre Mon domaine ou site Experience Cloud. Par exemple, si vous avez transmis un UVID dans votre demande de jeton et que Salesforce a renvoyé une réponse avec un jeton d’accès opaque, appelez le point de terminaison Information utilisateur pour obtenir l’UVID.
L’application demande l’accès aux données Salesforce (14)
Votre application possède maintenant un jeton d’accès Salesforce. Elle soumet une requête authentifiée à une ressource Salesforce protégée pour obtenir les données de l’utilisateur.
L’utilisateur accède aux données Salesforce (15)
Si la demande réussit, l'utilisateur peut accéder à ses données Salesforce dans votre application. Il a suffi à l’utilisateur de cliquer sur un bouton et de consulter ses données, sans être invité à se connecter ou à approuver l'accès.
