Flux du serveur Web OAuth 2.0 pour l'intégration de l'application Web
Pour intégrer une application Web externe à l'API Salesforce, utilisez le flux du serveur Web OAuth 2.0, qui implémente le type d'autorisation d'accès du code d'autorisation OAuth 2.0. Avec ce flux, le serveur qui héberge l'application Web doit pouvoir protéger l'identité de l'application cliente externe, définie par l'ID client et le secret client.
Éditions requises
| Disponible avec : Salesforce Classic (pas disponible dans toutes les organisations) et Lightning Experience |
| Disponible avec : toutes les éditions |
Nous recommandons d'utiliser le flux du serveur Web avec la Clé de vérification pour l'échange de code (PKCE, prononcée « pixy ») à la place du flux utilisateur-agent ou du flux nom d'utilisateur-mot de passe pour des scénarios spéciaux. Utilisez les paramètres code_challenge et code_verifier pour implémenter PKCE avec le flux serveur Web. Pour plus d'informations sur PKCE, consultez Internet Engineering Task Force (IETF). Nous recommandons également d'empêcher toutes les applications clientes externes d'utiliser le flux utilisateur-agent ou le flux nom d'utilisateur-mot de passe. Les étapes sont présentées dans Blocage des flux d'autorisation pour renforcer la sécurité.
Voici un exemple de cas d'implémentation du flux du serveur Web. Vous avez récemment développé un service Web qui permet un accès sécurisé au statut de commande des clients. Les données de statut de commande sont stockées en toute sécurité sur votre plate-forme Salesforce CRM. Pour autoriser les utilisateurs du centre d'assistance à afficher le statut de commande d'un client, vous développez une application Statut de commande et la configurez en tant qu'application cliente externe avec le flux serveur Web.
- Un utilisateur du Help Desk clique sur l'application Web Statut de la commande.
- L'application cliente externe publie une demande de code d'autorisation au point de terminaison d'autorisation Salesforce.
- L'utilisateur est redirigé vers la page de connexion de Salesforce. Une fois connecté avec succès, il est invité à approuver l'accès de l'application aux données de statut de la commande.
- Si l'utilisateur approuve l'accès de l'application Statut de la commande aux données, Salesforce envoie un rappel à l'application Statut de la commande avec un code d'autorisation.
- L'application Statut de la commande transmet le code d'autorisation au point de terminaison de jeton Salesforce, en demandant un jeton d'accès.
- Salesforce valide le code d'autorisation, puis renvoie un jeton d'accès qui inclut les autorisations associées sous forme d'étendues.
- L'application Statut de la commande renvoie une demande à Salesforce pour accéder aux données de statut de la commande. La demande contient le jeton d'accès avec les étendues associées.
- Salesforce valide le jeton d'accès et les étendues associées.
- L'application Statut de la commande peut accéder aux données protégées, et le statut de la commande du client est affiché dans l'application.
Remarque Si le jeton d'accès n'est plus valide, l'application cliente externe peut utiliser un jeton d'actualisation pour obtenir un nouveau jeton d'accès.
Examinons de plus près chaque étape de ce flux d'autorisation.
- Demander un code d'autorisation
- Authentification de l'utilisateur et autorisation d'accès
- Salesforce accorde un code d'autorisation
- Demander un jeton d'accès
- Salesforce accorde un jeton accès
Demander un code d'autorisation
Pour initier le flux de serveur Web OAuth 2.0, le service Web externe publie, via l'application cliente externe, une demande de code d'autorisation en utilisant le type d'autorisation d'octroi de code d'autorisation au point de terminaison d'autorisation Salesforce. Avec un code d'autorisation, l'application cliente externe peut prouver qu'elle a été autorisée en tant que visiteur sûr du site et qu'elle est autorisée à demander un jeton d'accès.
Le code d'autorisation se présente sous forme d'une redirection HTTP.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeInsérez les paramètres ci-dessous dans une demande de code d'autorisation.
| Paramètre | Description |
|---|---|
Request Header
|
Le point de terminaison d'autorisation OAuth 2.0 de Salesforce. Les applications clientes externes envoient des demandes d'autorisation OAuth à ce point de terminaison. |
client_id
|
La clé consommateur de l'application cliente externe. Pour accéder à la clé consommateur, dans le Gestionnaire d'applications, recherchez l'application cliente externe, puis sélectionnez Afficher dans la liste déroulante. Cliquez ensuite sur Gérer les détails du consommateur. Vous pouvez être invité à confirmer votre identité avant d'être autorisé à afficher la clé consommateur. |
redirect_uri
|
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 cliente externe. Sinon, l'approbation échoue. Vous trouverez l'URI de redirection dans la page Paramètres OAuth de l'application cliente externe. Cette valeur doit être codée en URL. |
response_type
|
Le type d'octroi OAuth 2.0 demandé par l'application cliente externe. La valeur de ce flux doit être code pour indiquer que l'application cliente externe demande un code d'autorisation. |
Vous pouvez également inclure les paramètres ci-dessous dans une demande de code d'autorisation.
| Paramètre | Description |
|---|---|
scope
|
Autorisations qui définissent le type de ressources protégées auxquelles une application cliente externe peut accéder. Vous attribuez des étendues à une application cliente externe lors de son élaboration, et elles sont incluses avec les jetons OAuth pendant le flux d'autorisation. Si vous n'incluez pas ce paramètre, toutes les étendues attribuées à l'application cliente externe sont demandées. Les étendues transmises dans ce paramètre doivent être un sous-ensemble des étendues enregistrées. Pour les paramètres valides, consultez Jetons OAuth et étendues. |
sso_provider
|
Le nom d’un développeur d’un fournisseur d’identité par authentification unique (SSO) configuré pour un Mon domaine ou un site Experience Cloud. Vous pouvez utiliser ce paramètre pour créer une expérience d’authentification unique dans laquelle le fournisseur d’authentification unique semble intégré à votre application. Vous pouvez par exemple utiliser ce paramètre pour offrir l’authentification unique dans une implémentation Identité headless. Pour plus d'informations, consultez Création d'une expérience d’authentification unique native dans votre application. |
state
|
Tout état envoyé à l'URL de rappel à la demande du service Web externe. Cette valeur doit être codée en URL. |
immediate
|
Une valeur booléenne qui détermine si l'utilisateur est invité à se connecter et à approuver. La valeur par défaut est
L'option |
code_challenge
|
Spécifie la valeur de hachage SHA256 de la valeur Ce paramètre est requis si
|
display
|
Change le type d'affichage des pages de connexion et d'authentification. Salesforce prend en charge les valeurs suivantes :
|
login_hint
|
Saisissez une valeur de nom d'utilisateur valide pour préremplir la page de connexion avec le nom d'utilisateur, par exemple Pour transmettre le paramètre |
nonce
|
Utilisez-le avec l'étendue openid pour demander un jeton d'identification utilisateur. Le jeton d'identification utilisateur est renvoyé dans la réponse. Ce paramètre est facultatif, mais il aide à détecter les attaques en relecture.
|
prompt
|
Spécifie comment le serveur d'autorisation invite l'utilisateur à se réauthentifier et à obtenir une nouvelle approbation. Salesforce prend en charge les valeurs suivantes :
Pour demander à l'utilisateur de se connecter et de procéder à une nouvelle authentification, vous pouvez transmettre les valeurs |
En-tête Uvid-Hint |
Si vous souhaitez connecter ce flux au flux invité sans interface graphique, incluez un en-tête Si vous implémentez le flux utilisateur invité dans votre application, vous pouvez également utiliser cet en-tête pour transmettre dans un jeton d'accès basé sur JWT contenant un ID de visiteur unique (UVID) lié à l'identité d'un utilisateur invité. En transmettant l’UVID dans un flux utilisateur nommé, vous pouvez transmettre des informations contextuelles à une session utilisateur nommé depuis une session utilisateur invité, par exemple les préférences de cookie de l’utilisateur. |
Paramètre du corps uvid_hint |
Une valeur Au lieu de transmettre l’UVID dans le corps de la demande, vous pouvez également le transmettre dans un jeton JWT avec un UVID via l’en-tête |
Authentification de l'utilisateur et autorisation d'accès
Avant que Salesforce fournisse des codes d'autorisation à des applications clientes externes, les utilisateurs qui s'authentifient sont invités à se connecter à Salesforce.
Après une connexion réussie, Salesforce redirige les utilisateurs vers la page d'approbation pour recevoir l'accès à l'application.
Si les utilisateurs ont déjà approuvé l'accès, Il n'est pas nécessaire de l'approuver une nouvelle fois.
Salesforce accorde un code d'autorisation
Lorsque les utilisateurs approuvent l'accès à une application cliente externe, Salesforce les redirige vers l'URL de rappel, où ils peuvent afficher le rappel avec un code d'autorisation.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- La première partie du rappel est l'URL de rappel de l'application cliente externe :
https://www.mycustomerorderstatus.com/oauth2/callback. - La deuxième partie est le code d'autorisation que l'application cliente externe utilise pour obtenir un jeton d'accès :
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==Le code d'autorisation expire au bout de 15 minutes.
Si le paramètre state est inclus dans la chaîne de la requête d'origine, l'état spécifié est transmis à l'étape d'approbation.
Demander un jeton d'accès
Pour demander un jeton d'accès, l'application cliente externe transmet le code d'autorisation au point de terminaison de jeton Salesforce en tant que POST HTTP.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
La requête POST de l'exemple contient les paramètres ci-dessous.
| Paramètre | Description |
|---|---|
Request Header
|
L'en-tête de la requête doit contenir les paramètres ci-dessous.
L'en-tête de la requête prend également en charge les paramètres ci-dessous.
Le paramètre |
grant_type
|
Le type de validation que l'application cliente externe peut fournir pour prouver qu'elle est un visiteur sûr. Pour le flux serveur Web, la valeur doit être authorization_code. |
code
|
Un code d'autorisation temporaire reçu du serveur d'autorisation. L'application cliente externe utilise ce code en échange d'un jeton d'accès. Ce type de flux OAuth 2.0 est une méthode sécurisée pour renvoyer le jeton d'accès à l'application. |
client_id
|
La clé consommateur de l'application cliente externe. Pour accéder à la clé consommateur, dans le Gestionnaire d'applications, recherchez l'application cliente externe, puis sélectionnez Afficher dans la liste déroulante. Cliquez ensuite sur Gérer les détails du consommateur. Vous pouvez être invité à confirmer votre identité avant d'être autorisé à afficher la clé consommateur. |
client_secret
|
Le secret consommateur de l'application cliente externe. Pour accéder au secret consommateur, dans le Gestionnaire d'applications, recherchez l'application cliente externe, puis sélectionnez Afficher dans la liste déroulante. Cliquez ensuite sur Gérer les détails du consommateur. Vous pouvez être invité à confirmer votre identité avant d'être autorisé à afficher le secret consommateur. Ce paramètre est requis, sauf si l'application cliente externe n'a pas activé Secret requis pour le flux serveur Web. Si une |
redirect_uri
|
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 cliente externe. Sinon, l'approbation échoue. Vous trouverez l'URI de redirection dans la page Paramètres OAuth de l'application cliente externe ou dans la définition de l'application cliente externe. Cette valeur doit être codée en URL. |
Vous pouvez également inclure les paramètres ci-dessous.
| Paramètre | Description |
|---|---|
client_assertion
|
Au lieu de passer un client_secret, vous pouvez fournir un client_assertion et un client_assertion_type. Si aucun paramètre client_secret n'est fourni, Salesforce vérifie client_assertion et client_assertion_type. Consultez Utilisation de client_assertion au lieu de client_secret. |
client_assertion_type
|
Saisissez cette valeur en utilisant le paramètre La valeur de |
code_verifier
|
Requis uniquement si un paramètre code_challenge est spécifié dans la requête d'autorisation. Spécifie 128 octets de données aléatoires avec une entropie élevée pour rendre la valeur
|
format
|
S'il n'est pas inclus dans l'en-tête de la requête, vous pouvez spécifier le format de retour attendu. Le paramètre
|
client_assertion au lieu de client_secret.Si vous saisissez un client_assertion au lieu d'un client_secret, la valeur de client_assertion doit inclure les paramètres ci-dessous.
iss: leclient_idde la définition de l'application cliente externe.sub: leclient_idde la définition de l'application cliente externe.aud: l'URL du servlet de jeton : https://hostname/services/oauth2/token.expexp : l'heure d'expiration de l'assertion, à cinq minutes près, exprimée en nombre de secondes depuis 1970-01-01T0:0:0Z en heure UTC.
La client_assertion doit également être signée avec la clé privée associée au certificat chargé du consommateur OAuth. Seul l'algorithme RS256 est pris en charge. Pour la méthode d'authentification client private_key_jwt, consultez Spécifications OpenID Connect.
Au lieu d'envoyer les identifiants client en tant que paramètres dans le corps de la requête POST, Salesforce prend en charge le schéma d'authentification de base HTTP. Le format de ce schéma nécessite client_id et client_secret dans l'en-tête d'autorisation de la requête POST, comme suit :
Authorization: Basic64Encode(client_id:secret)
Les client_id et les client_secret sont séparés par deux points (:). Pour plus d’informations, consultez le document OAuth 2.0 Authorization Framework.
Cet exemple présent une requête POST de jeton d'accès qui utilise le schéma d'authentification de base HTTP, plutôt que d'envoyer les identifiants client dans le corps de la requête POST.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id et les client_secret sont envoyés dans le corps du POST, l'en-tête d'autorisation est ignoré.Salesforce accorde un jeton accès
Lorsque Salesforce valide les identifiants de l'application cliente externe, elle renvoie une réponse avec le jeton d'accès. Dans cet exemple, la réponse utilise le format JSON.
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
La réponse inclut les paramètres ci-dessous.
| Paramètre | Description |
|---|---|
access_token
|
Jeton OAuth qu'une application cliente externe utilise pour demander l'accès à une ressource protégée au nom de l'application cliente. Des autorisations supplémentaires sous forme d'étendues peuvent accompagner le jeton d'accès. |
signature
|
La signature HMAC-SHA256 codée en Base64 signée par le client_secret. La signature peut inclure l'ID et issued_at value concaténés, que vous pouvez utiliser afin de vérifier si l'URL d'identité a changé depuis que le serveur l'a envoyée. |
scope
|
Les étendues associées au jeton d'accès. Les étendues définissent les types de ressource protégée auxquels le client peut accéder. Vous attribuez des étendues à une application cliente externe lors de son élaboration, et elles sont incluses avec les jetons OAuth pendant le flux d'autorisation. Pour les paramètres valides, consultez Jetons OAuth et étendues. |
id_token
|
Une structure de données signée qui contient les attributs de l'utilisateur authentifié, notamment l'identifiant unique de l'utilisateur et la date d'émission du jeton. Il identifie également l'application cliente à l'origine de la demande. Consultez Spécifications OpenID Connect. Ce paramètre est renvoyé si le paramètre scope inclut |
instance_url
|
Une URL indiquant l'instance de l'organisation de l'utilisateur. Par exemple : https://yourInstance.salesforce.com/.
|
id
|
Une URL d'identité qui peut être utilisée pour identifier l'utilisateur et pour demander plus d'informations sur l'utilisateur. Consultez URL d'identité. |
token_type
|
Un type de jeton Bearer, utilisé pour toutes les réponses qui incluent un jeton d'accès.
|
issued_at
|
Horodatage indiquant à quel moment la signature a été créée, en millisecondes. |
La réponse peut également contenir les paramètres ci-dessous.
