Flux de serveur Web hybride OAuth 2.0
Utilisez le flux serveur Web hybride OAuth 2.0 pour confier à des applications hybrides la gestion directe des sessions Web. Lorsque le serveur d'autorisation accorde un jeton accès, il inclut dans sa réponse les ID de session (SID) des domaines demandés. L'application hybride peut ainsi définir des cookies Lightning, Visualforce et de domaine de contenu pour connecter un jeton d'accès à une session Web afin de fournir un service ininterrompu.
Éditions requises
| Disponible avec : Salesforce Classic (pas disponible dans toutes les organisations) et Lightning Experience |
| Disponible avec : Toutes les éditions |
Le flux de serveur Web hybride suit les mêmes étapes d'autorisation que celles utilisées dans le flux OAuth 2.0 User-Agent pour l'intégration d'applications de bureau ou mobiles, à l'exception du flux de serveur Web hybride qui utilise un hybrid_auth_code comme type d'autorisation. Par exemple, vous élaborez une application hybride afin de permettre à votre service commercial d'accéder à des informations embarquées, notamment à un tableau de bord qui suit les principaux prospects. Cette application implémente le flux de jeton utilisateur-agent hybride, qui suit les étapes ci-dessous.
- Pour intégrer l'application hybride à l'API Salesforce, créez une application cliente externe. Activez les paramètres OAuth et attribuez ces étendues OAuth à l'application cliente externe.
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- L'utilisateur ouvre l'application et est dirigé vers Salesforce pour authentifier et autoriser l'application.
- Lorsque l'utilisateur approuve l'accès pour ce flux d'autorisation, l'application reçoit le rappel de Salesforce vers l'URL de redirection, qui extrait les jetons d'accès et d'actualisation. Les SID Visualforce, Lightning et contenu des domaines respectifs sont également inclus, ainsi que des cookies de session permettant à l'application de connecter directement une session Web.
Remarque Ce flux prend en charge les jetons d'accès basés sur JWT uniquement si la rotation des jetons d'actualisation n'est pas activée dans l'application cliente externe. Si la rotation du jeton d'actualisation est activée, la requête de jeton renvoie une erreur deinvalid_grant. - L'application définit les cookies des domaines Lightning, Visualforce et de contenu, et connecte par pont un jeton d'accès à une session Web.
- L'utilisateur peut accéder au tableau de bord des principaux prospects sans interrompre les sessions.
Demander un code d'autorisation
Pour initier le flux de serveur Web hybride OAuth 2.0, le service Web externe publie, via l'application cliente externe, une demande de code d'autorisation en utilisant le type 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 est fourni sous forme d'une redirection HTTP, comme dans cet exemple.
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'application cliente externe, recherchez l'application cliente externe, puis sélectionnez Modifier les paramètres dans la liste déroulante. Agrandissez ensuite la section Paramètres OAuth, puis cliquez sur Clé et secret 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. |
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é headless, 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 du uvid_hint |
Une valeur Au lieu de transmettre l’UVID dans le corps de la requête, vous pouvez également le transmettre dans un jeton basé sur 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=hybrid_auth_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 hybride, la valeur doit être hybrid_auth_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'application cliente externe, recherchez l'application cliente externe, puis sélectionnez Modifier les paramètres dans la liste déroulante. Agrandissez ensuite la section Paramètres OAuth, puis cliquez sur Clé et secret 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'application cliente externe, recherchez l'application cliente externe, puis sélectionnez Modifier les paramètres dans la liste déroulante. Agrandissez ensuite la section Paramètres OAuth, puis cliquez sur Clé et secret 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 de client_secret n'est fourni, Salesforce vérifie la client_assertion et la 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_secretSi 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=hybrid_auth_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
Après avoir validé les identifiants de l'application connectée, Salesforce renvoie une réponse contenant le jeton 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 du jeton 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 concaténé et issued_at value, que vous pouvez utiliser pour vérifier que l'URL d'identité n'a pas changé depuis que le serveur l'a envoyé. |
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. |
content_domain
|
Le domaine de la session de contenu, qui est mappé avec le SID de contenu : MyDomainName.file.force.com →
content_sid.
|
content_sid
|
Le SID associé au domaine de la session de contenu. Salesforce renvoie un SID unique que l'application hybride définit directement dans le cookie de session du domaine. |
lightning_domain
|
Le domaine de la session Lightning, qui est mappé avec le SID Lightning : <MyDomainName or
instance>.lightning.force.com → lightning_sid.
|
lightning_sid
|
Le SID associé au domaine de la session Lightning. Salesforce renvoie un SID unique que l'application hybride définit directement dans le cookie de session du domaine. |
visualforce_domain
|
Le domaine de la session Visualforce, qui est mappé avec le SID Visualforce : MyDomainName.vf.force.com →
visualforce_sid.
|
visualforce_sid
|
Le SID associé au domaine de la session Visualforce. Salesforce renvoie un SID unique que l'application hybride définit directement dans le cookie de session du domaine. |
csrf_token
|
Le jeton CSRF (falsification de requête intersites) pour empêcher les attaques pendant les sessions enfants. |
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. |
sidCookieName
|
Le nom du cookie de session que l'application hybride utilise pour connecter directement une session Web. La valeur par défaut est sid. |
cookie-sid_Client
|
Un cookie de session qui détecte et empêche l'altération de la session. Ce cookie de session permet à l'application hybride de connecter directement une session Web. |
cookie-clientSrc
|
Un cookie de session utilisé pour la protection de sécurité. Ce cookie de session permet à l'application hybride de connecter directement une session Web. |
La réponse du jeton peut également contenir les paramètres ci-dessous.
