Flusso server Web OAuth 2.0 per l'integrazione delle app Web
Per integrare un'app Web esterna con l'API Salesforce, utilizzare il flusso server Web OAuth 2.0, che implementa il tipo di grant codice di autorizzazione OAuth 2.0. Con questo flusso, il server che ospita l'app Web deve essere in grado di proteggere l'identità dell'app client esterna, definita dall'ID client e dal segreto client.
Versioni (Edition) richieste
| Disponibile in: Salesforce Classic (non in tutte le organizzazioni) e Lightning Experience |
| Disponibile in tutte le versioni. |
si consiglia di utilizzare il flusso server Web con Proof Key for Code for Exchange (PKCE, pronunciato pixy) al posto del flusso utente-agente o del flusso nome utente-password per scenari speciali. Utilizzare i parametri code_challenge e code_verifier per implementare PKCE con il flusso server Web. Per maggiori informazioni su PKCE, vedere la Internet Engineering Task Force (IETF.) Si consiglia inoltre di impedire a tutte le app client esterne di utilizzare il flusso utente-agente o il flusso nome utente-password. Per istruzioni, vedere Blocco dei flussi di autorizzazione per migliorare la sicurezza.
Ecco un esempio di caso d'uso per l'implementazione del flusso server Web. Si è sviluppato di recente un servizio Web che consente di accedere in sicurezza allo stato degli ordini dei clienti. I dati relativi allo stato degli ordini è archiviato in modo sicuro sulla piattaforma CRM Salesforce. Per autorizzare gli utenti dell'help desk a visualizzare lo stato degli ordini di un cliente, sviluppare un'app Stato ordine e configurarla come app client esterna con il flusso server Web.
- Un utente dell'help desk fa clic sull'app Web Stato ordine.
- L'app client esterna invia una richiesta di codice di autorizzazione all'endpoint di autorizzazione Salesforce.
- L'utente viene reindirizzato alla pagina di accesso di Salesforce. Eseguito l'accesso, all'utente viene chiesto di approvare l'accesso da parte dell'app ai dati relativi allo stato degli ordini.
- Quando l'utente approva l'accesso ai dati per l'app Stato ordine, Salesforce invia una richiamata all'app Stato ordine con un codice di autorizzazione.
- L'app Stato ordine passa il codice di autorizzazione all'endpoint token di Salesforce richiedendo un token di accesso.
- Salesforce convalida il codice di autorizzazione e rimanda un token di accesso che include le autorizzazioni associate sotto forma di ambiti.
- L'app Stato ordine invia di nuovo una richiesta a Salesforce per accedere ai dati relativi allo stato degli ordini. La richiesta include il token di accesso con gli ambiti associati.
- Salesforce convalida il token di accesso e gli ambiti associati.
- L'app Stato ordine può accedere ai dati protetti e lo stato degli ordini del cliente viene visualizzato nell'app.
Nota Se il token di accesso diventa non valido, l'app client esterna può utilizzare un token di aggiornamento per ottenere un nuovo token di accesso.
Di seguito sono riportate in dettaglio le fasi di questo flusso di autorizzazione.
- Richiesta di un codice di autorizzazione
- L'utente autentica e autorizza l'accesso
- Salesforce concede il codice di autorizzazione
- Richiesta di un token di accesso
- Salesforce concede un token di accesso
Richiesta di un codice di autorizzazione
Per avviare il flusso server Web 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.
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, trovare l'app client esterna dal Gestore app e selezionare Visualizza dall'elenco a discesa. Quindi fare clic su Gestisci dettagli consumatore. 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. |
sso_provider
|
Il nome sviluppatore di un provider di identità Single Sign-On (SSO) configurato con un URL di accesso di Dominio personale o un URL di sito Experience Cloud. È possibile utilizzare questo parametro per creare un'esperienza SSO che risulti come se l'app fosse integrata con il provider SSO. Ad esempio, è possibile utilizzare questo parametro per offrire SSO in un'implementazione Headless Identity. Per ulteriori informazioni, vedere Creazione di un'esperienza Single Sign-On nativa nell'app. |
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=authorization_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, il valore deve essere authorization_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, trovare l'app client esterna dal Gestore app e selezionare Visualizza dall'elenco a discesa. Quindi fare clic su Gestisci dettagli 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 e selezionare Visualizza dall'elenco a discesa. Quindi fare clic su Gestisci dettagli 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_secret.Se 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=authorization_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
Quando Salesforce convalida le credenziali dell'app client esterna, restituisce 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 contiene 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. |
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. |
La risposta può anche contenere questi parametri.
