Flusso del server Web Ibrido OAuth 2.0
Utilizzare il flusso del server Web ibrido OAuth 2.0 per fornire alle app ibride la gestione diretta delle sessioni Web. Quando il server di autorizzazione concede un token di accesso, il server include gli ID sessione (SID) dei domini richiesti nella risposta. L'app ibrida può quindi impostare i cookie Lightning, Visualforce e di dominio di contenuti e collegare un token di accesso in una sessione Web, offrendo un servizio senza interruzioni.
Versioni (Edition) richieste
| Disponibile in: Salesforce Classic (non in tutte le organizzazioni) e Lightning Experience |
| Disponibile in: tutte le versioni |
Il flusso del server Web ibrido segue gli stessi passaggi di autorizzazione utilizzati nel flusso utente-agente OAuth 2.0, con l'eccezione che il flusso del server Web ibrido utilizza un hybrid_auth_code come tipo di grant. Ad esempio, si compila un'app ibrida per il reparto vendite per accedere alle informazioni mentre si lavora fuori sede, incluso un cruscotto digitale che tiene traccia dei principali clienti potenziali. L'app implementa il flusso del token utente-agente ibrido, che segue queste fasi.
- Per integrare l'app ibrida con l'API Salesforce, creare un'app client esterna. Abilitare le impostazioni OAuth e assegnare questi ambiti OAuth all'app client esterna.
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- L'utente finale apre l'app e viene indirizzato a Salesforce per autenticare e autorizzare l'app.
- Dopo che l'utente ha approvato l'accesso per questo flusso di autorizzazione, l'app riceve la richiamata da Salesforce all'URL di reindirizzamento, che estrae i token di accesso e aggiornamento. Sono inclusi anche i SID Visualforce, Lightning e del contenuto dei rispettivi domini, oltre ai cookie di sessione che consentono all'app di collegare direttamente una sessione Web.
Nota Questo flusso supporta i token di accesso basati su JWT solo se nell'app client esterna non è abilitata la rotazione dei token di aggiornamento. Se è abilitata la rotazione dei token di aggiornamento, la richiesta di token restituisce un errore diinvalid_grant. - L'app imposta i cookie di sessione Lightning, Visualforce e dei domini di contenuti e collega un token di accesso in una sessione Web.
- L'utente può accedere al cruscotto digitale dei principali clienti potenziali senza sessioni interrotte.
Richiesta di un codice di autorizzazione
Per avviare il flusso del server Web ibrido OAuth 2.0, il servizio Web esterno, tramite l'app client esterna, invia una richiesta di codice di autorizzazione utilizzando il tipo di grant codice di autorizzazione all'endpoint di autorizzazione Salesforce. Con un codice di autorizzazione, l'app client esterna può dimostrare di essere stata autorizzata come visitatore sicuro del sito e di essere autorizzata a richiedere un token di accesso.
Il codice di autorizzazione ha il formato di un reindirizzamento HTTP, come indicato nell'esempio.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeIncludere questi parametri in una richiesta di codice di autorizzazione.
| Parametro | Descrizione |
|---|---|
Request Header
|
L'endpoint di autorizzazione OAuth 2.0 di Salesforce. Le app client esterne inviano le richieste di autorizzazione OAuth a questo endpoint. |
client_id
|
Chiave consumatore dell'app client esterna. Per accedere alla chiave consumatore, dal Gestore app client esterne, trovare l'app client esterna e selezionare Modifica impostazioni dall'elenco a discesa. Quindi espandere la sezione Impostazioni OAuth e fare clic su Chiave consumatore e segreto. Talvolta viene richiesto di verificare la propria identità prima di poter visualizzare la chiave consumatore. |
redirect_uri
|
URL a cui vengono reindirizzati gli utenti quando l'autenticazione ha esito positivo. L'URI di reindirizzamento deve corrispondere a uno dei valori del campo URL di richiamata dell'app client esterna. In caso contrario, l'approvazione non riesce. L'URI di reindirizzamento è disponibile nella pagina Impostazioni OAuth dell'app client esterna. Questo valore deve essere codificato nell'URL. |
response_type
|
Tipo di grant OAuth 2.0 richiesto dall'app client esterna. Il valore di questo flusso deve essere code per indicare che l'app client esterna richiede un codice di autorizzazione. |
Anche i seguenti parametri possono essere inclusi in una richiesta di codice di autorizzazione.
| Parametro | Descrizione |
|---|---|
scope
|
Autorizzazioni che definiscono il tipo di risorse protette a cui può accedere un'app client esterna. Gli ambiti vengono assegnati a un'app client esterna quando viene creata e vengono inclusi con i token OAuth durante il flusso di autorizzazione. Se non si include questo parametro, vengono richiesti tutti gli ambiti assegnati all'app client esterna. Gli ambiti passati in questo parametro devono essere un sottoinsieme degli ambiti registrati. Per i parametri validi, vedere Token e ambiti OAuth. |
state
|
Qualsiasi stato di cui il servizio Web esterno richiede l'invio all'URL di richiamata. Questo valore deve essere codificato nell'URL. |
immediate
|
Valore booleano che determina se richiedere all'utente l'accesso e l'approvazione. Il valore predefinito è
L'opzione |
code_challenge
|
Specifica il valore hash SHA256 del valore Questo parametro è obbligatorio se nella richiesta di token è specificato un
|
display
|
Modifica il tipo di visualizzazione delle pagine di accesso e autorizzazione. Salesforce supporta i seguenti valori.
|
login_hint
|
Fornisce un valore di nome utente valido per precompilare la pagina di accesso con il nome utente, ad esempio Per passare il parametro |
nonce
|
Utilizzare con l'ambito openid per richiedere un token ID utente. Il token ID utente viene restituito nella risposta. Questo parametro è facoltativo ma consente di rilevare gli attacchi replay.
|
prompt
|
Specifica in che modo il server di autorizzazione richiede la riautenticazione e la riapprovazione all'utente. Salesforce supporta i seguenti valori.
È possibile passare i valori |
Intestazione Uvid-Hint |
Se si desidera, per connettere questo flusso al flusso guest headless, è possibile includere un'intestazione Se si implementa il flusso utente guest nella propria app, è possibile, facoltativamente, utilizzare questa intestazione per passare un token di accesso basato su JWT contenente un ID visitatore univoco (UVID) legato all'identità di un utente guest. Passando l'UVID in un flusso utente denominato, è possibile inserire in una sessione utente denominata informazioni contestuali da una sessione utente guest, ad esempio le preferenze dei cookie dell'utente. |
Parametro del corpo del uvid_hint |
Valore di Anziché passare l'UVID nel corpo della richiesta, è anche possibile passarlo in un token basato su JWT con un UVID tramite l'intestazione |
L'utente autentica e autorizza l'accesso
Prima che Salesforce fornisca codici di autorizzazione alle app client esterne, agli utenti che eseguono l'autenticazione viene chiesto di accedere a Salesforce.
Eseguito l'accesso, Salesforce reindirizza gli utenti alla pagina di approvazione per concedere l'accesso all'applicazione.
Se gli utenti hanno già approvato l'accesso, non è necessario approvarlo di nuovo.
Salesforce concede il codice di autorizzazione
Dopo che gli utenti hanno approvato l'accesso a un'app client esterna, Salesforce reindirizza gli utenti all'URL di richiamata, dove possono visualizzare la richiamata con un codice di autorizzazione.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- La prima parte della richiamata è l'URL di richiamata dell'app client esterna:
https://www.mycustomerorderstatus.com/oauth2/callback. - La seconda parte è il codice di autorizzazione utilizzato dall'app client esterna per ottenere un token di accesso:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==. Il codice autorizzazione scade dopo 15 minuti.
Se il parametro state è incluso nella stringa di query originale, lo stato specificato viene passato alla fase di approvazione.
Richiesta di un token di accesso
Per richiedere un token di accesso, l'app client esterna passa il codice di autorizzazione all'endpoint token di Salesforce come 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
Il POST dell'esempio contiene i seguenti parametri.
| Parametro | Descrizione |
|---|---|
Request Header
|
L'intestazione della richiesta può contenere i seguenti parametri.
L'intestazione della richiesta supporta anche i seguenti parametri.
Il parametro |
grant_type
|
Tipo di convalida che l'app client esterna può fornire per dimostrare che è un visitatore sicuro. Per il flusso server Web ibrido, il valore deve essere hybrid_auth_code. |
code
|
Codice di autorizzazione temporaneo ricevuto dal server di autorizzazione. L'app client esterna utilizza questo codice in cambio di un token di accesso. Questo tipo di flusso OAuth è un modo sicuro per restituire il token di accesso all'applicazione. |
client_id
|
Chiave consumatore dell'app client esterna. Per accedere alla chiave consumatore, dal Gestore app client esterne, trovare l'app client esterna e selezionare Modifica impostazioni dall'elenco a discesa. Quindi espandere la sezione Impostazioni OAuth e fare clic su Chiave e segreto consumatore. Talvolta viene richiesto di verificare la propria identità prima di poter visualizzare la chiave consumatore. |
client_secret
|
Segreto consumatore dell'app client esterna. Per accedere al segreto consumatore, trovare l'app client esterna dal Gestore app client esterno e selezionare Modifica impostazioni dall'elenco a discesa. Quindi espandere la sezione Impostazioni OAuth e fare clic su Chiave e segreto consumatore. Talvolta viene richiesto di verificare la propria identità prima di poter visualizzare il segreto consumatore. Questo parametro è obbligatorio a meno che nell'app client esterna non sia abilitato Richiedi segreto per il flusso server Web. Se un |
redirect_uri
|
URL a cui vengono reindirizzati gli utenti quando l'autenticazione ha esito positivo. L'URI di reindirizzamento deve corrispondere a uno dei valori del campo URL di richiamata dell'app client esterna. In caso contrario, l'approvazione non riesce. L'URI di reindirizzamento è disponibile nella pagina Impostazioni OAuth dell'app client esterna o nella definizione dell'app client esterna. Questo valore deve essere codificato nell'URL. |
È anche possibile includere questi parametri.
| Parametro | Descrizione |
|---|---|
client_assertion
|
Anziché passare un client_secret, è possibile fornire un client_assertion e un client_assertion_type. Se non viene fornito un parametro client_secret, Salesforce verifica la presenza di client_assertion e client_assertion_type. Vedere Utilizzo di client_assertion anziché client_secret. |
client_assertion_type
|
Specificare questo valore quando si utilizza il parametro Il valore di |
code_verifier
|
Richiesto solo se nella richiesta di autorizzazione è stato specificato il parametro code_challenge. Specifica 128 byte di dati casuali con entropia elevata per rendere difficile la congettura del valore di
|
format
|
Se non è incluso nell'intestazione della richiesta, è possibile specificare il formato previsto della risposta. Il parametro
|
client_assertion anziché client_secretSe si specifica un client_assertion anziché un client_secret, il valore di client_assertion deve includere i seguenti parametri.
iss:client_iddella definizione dell'app client esterna.sub:client_iddella definizione dell'app client esterna.aud: URL del servlet token: https://hostname/services/oauth2/token.exp: l'ora di scadenza dell'asserzione entro 5 minuti, espressa come numero di secondi da 1970-01-01T0:0:0Z misurato in UTC.
Il client_assertion deve anche essere firmato con la chiave privata associata al certificato caricato del consumatore OAuth. È supportato solo l'algoritmo RS256. Per il metodo di autenticazione client private_key_jwt, vedere le specifiche OpenID Connect.
Anziché inviare le credenziali del client come parametri nel corpo del POST, Salesforce supporta lo schema di autenticazione di base HTTP. Il formato di questo schema richiede il client_id e il client_secret nell'intestazione di autorizzazione del post come segue.
Authorization:
Basic64Encode(client_id:secret)
Il client_id e il client_secret sono separati da due punti (:). Per ulteriori informazioni, vedere il documentoFramework di autenticazione OAuth 2.0.
Questo esempio mostra una richiesta POST di token di accesso che utilizza lo schema di autenticazione di base HTTP anziché inviare le credenziali del client nel corpo della richiesta 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 e i client_secret vengono inviati nel corpo del POST, l'intestazione di autorizzazione viene ignorata.Salesforce concede un token di accesso
Dopo aver convalidato le credenziali dell'app, Salesforce invia una risposta con il token di accesso.
In questo esempio la risposta è in formato 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 risposta del token include i seguenti parametri.
| Parametro | Descrizione |
|---|---|
access_token
|
Token OAuth utilizzato da un'app client esterna per richiedere l'accesso a una risorsa protetta per conto dell'applicazione client. Al token di accesso possono essere abbinate altre autorizzazioni sotto forma di ambiti. |
signature
|
Firma HMAC-SHA256 con codifica Base64 firmata con il client_secret. La firma può includere l'ID concatenato e il issued_at value, che è possibile utilizzare per verificare che l'URL identità non sia cambiato da quando il server lo ha inviato. |
scope
|
Ambiti associati al token di accesso. Gli ambiti definiscono ulteriormente i tipi di risorse protette a cui può accedere il client. Gli ambiti vengono assegnati a un'app client esterna quando viene creata e vengono inclusi con i token OAuth durante il flusso di autorizzazione. Per i parametri validi, vedere Token e ambiti OAuth. |
content_domain
|
Il dominio della sessione di contenuti mappato al SID di contenuti: MyDomainName.file.force.com →
content_sid.
|
content_sid
|
SID associati al dominio della sessione dei contenuti. Salesforce restituisce un SID univoco impostato dall'app ibrida direttamente nel cookie di sessione del dominio. |
lightning_domain
|
Dominio della sessione Lightning mappato al SID Lightning: <MyDomainName or
instance>.lightning.force.com → lightning_sid.
|
lightning_sid
|
SID associati al dominio della sessione Lightning. Salesforce restituisce un SID univoco impostato dall'app ibrida direttamente nel cookie di sessione del dominio. |
visualforce_domain
|
Dominio della sessione Visualforce mappato al SID Visualforce: MyDomainName.vf.force.com →
visualforce_sid.
|
visualforce_sid
|
SID associato al dominio della sessione Visualforce. Salesforce restituisce un SID univoco impostato dall'app ibrida direttamente nel cookie di sessione del dominio. |
csrf_token
|
Token CSRF (Cross-site Request Forgery) per impedire gli attacchi durante le sessioni secondarie. |
id_token
|
Struttura di dati firmata che contiene gli attributi dell'utente autenticato, fra cui un identificativo univoco per l'utente e l'indicazione della data e dell'ora di emissione del token. Il token ID identifica inoltre l'app client richiedente. Vedere le specifiche di OpenID Connect. Questo parametro viene restituito se il parametro scope include |
instance_url
|
URL che indica l'istanza dell'organizzazione dell'utente. Ad esempio: https://yourInstance.salesforce.com/.
|
id
|
URL identità che può essere utilizzato per identificare l'utente e per chiedere più informazioni sull'utente. Vedere URL identità. |
token_type
|
Tipo di token Bearer, utilizzato per tutte le risposte che includono un token di accesso.
|
issued_at
|
Indicazione oraria in millisecondi del momento in cui la firma è stata creata. |
sidCookieName
|
Il nome del cookie di sessione utilizzato dall'app ibrida per collegare direttamente una sessione Web. Il valore predefinito è sid. |
cookie-sid_Client
|
Un cookie di sessione che rileva e impedisce la manomissione della sessione. Questo cookie di sessione consente all'app ibrida di collegare direttamente una sessione Web. |
cookie-clientSrc
|
Un cookie di sessione utilizzato per la protezione della sicurezza. Questo cookie di sessione consente all'app ibrida di collegare direttamente una sessione Web. |
La risposta del token può contenere anche i seguenti parametri.
