API Headless Identity: Flusso di registrazione headless per i client privati
Per le app che possono mantenere informazioni riservate, ad esempio le app Web con un'architettura client-server, è possibile impostare la registrazione headless per clienti e partner utilizzando il flusso Registrazione headless. Il flusso Registrazione headless estende il flusso Codice di autorizzazione e credenziali, creato in base al tipo di grant Codice di autorizzazione OAuth 2.0. Con questo flusso si controlla l'esperienza di registrazione degli utenti front-end in un'applicazione di terze parti. È possibile chiamare l'API registrazione headless Salesforce tramite il sito Experience Cloud per creare utenti, accedere e concedere l'accesso alle risorse Salesforce. Separando questi due processi, gli utenti possono registrarsi per l'applicazione e accedere ai dati Salesforce senza uscire dall'applicazione.
Versioni (Edition) richieste
| Disponibile in: Salesforce Classic (non in tutte le organizzazioni) e Lightning Experience |
| Disponibile nelle versioni: Enterprise Edition, Unlimited Edition e Developer Edition |
Ecco un esempio di caso d'uso per il flusso Registrazione headless. Si supponga di lavorare per un'agenzia di viaggi che gestisce le informazioni dei clienti in Salesforce. È importante avere un controllo completo sull'esperienza utente nell'app. Si desidera anche mantenere un numero maggiore di clienti incoraggiandoli a registrarsi per l'app, che richiede i servizi di identità. Poiché la società utilizza già Salesforce, l'identità headless è l'opzione migliore. Si crea un'app client-server tradizionale e si configura il flusso Registrazione headless. Quando i nuovi utenti si iscrivono all'applicazione, viene aperta l'esperienza di registrazione personalizzata. Si registrano, verificano la loro identità e accedono ai dati di Salesforce senza interagire direttamente con Salesforce.
Per espandere le opzioni del modello di email per l'email con password singola (OTP) inviata agli utenti finali durante il flusso, accettare l'inserimento nell'elenco consentiti dei modelli di email e creare un elenco consentiti con modelli personalizzati. Vedere Utilizzo di più modelli di email per flussi headless.
Prima di impostare questo flusso, configurare le impostazioni e i criteri di accesso necessari per l'applicazione connessa o l'app client esterna Vedere Configurazione di un'applicazione connessa per il flusso Codice di autorizzazione e credenziali o Configurazione di un'app client esterna per il flusso Codice di autorizzazione e credenziali
Di seguito è riportata una panoramica del flusso.
- Un utente apre l'applicazione e fa clic su Registra. (1)
- Nell'app, viene visualizzato in modo nativo un modulo di registrazione per la raccolta dei dati degli utenti. L'utente progetta il modulo e personalizza le informazioni da raccogliere. (2)
- L'utente inserisce le proprie informazioni nell'app. Ad esempio, immette il nuovo nome utente, la password e il nome. (3)
- L'app invia le informazioni utente all'endpoint /services/auth/headless/init/registration dell'API registrazione headless sul sito Experience Cloud. (4)
- Salesforce riceve i dati dell'utente e li mette in area di attesa per elaborarli in un secondo momento. Salesforce restituisce un messaggio di esito positivo che include un ID richiesta di registrazione all'app. (5a)
- Salesforce invia quindi un messaggio email o un messaggio SMS contenente una password singola (OTP) all'utente. (5b)
- Nell'app, viene visualizzato in modo nativo un modulo di verifica della password singola. L'utente sceglie come visualizzare il modulo. (6)
- L'utente riceve la password singola e la inserisce nel modulo di verifica. (7)
- L'applicazione inizializza il flusso Codice di autorizzazione e credenziali con una richiesta di codice di autorizzazione all'API accesso headless. La richiesta contiene la password singola e un ID richiesta, insieme ad altri parametri. (8)
- Salesforce verifica l'ID richiesta e la password. Recupera i dati dell'utente in area di attesa memorizzati in precedenza e chiama l'handler di registrazione headless. L'handler di registrazione headless crea un utente in Salesforce. (9)
- Salesforce restituisce un reindirizzamento 302 a un URL preconfigurato contenente il codice di autorizzazione. Il reindirizzamento 302 viene elaborato nel browser e la risposta viene consegnata in modalità headless all'handler di richiamata preconfigurato sul server. (10)
- L'handler di richiamata lato server estrae il codice e altri parametri dal reindirizzamento 302. Quindi avvia lo scambio di codice tramite una richiesta POST all'endpoint token. (11)
- Dall'endpoint token, Salesforce restituisce una risposta con token di accesso all'handler di richiamata lato server. (12)
- L'handler di richiamata lato server elabora la risposta del token e restituisce lo stato di accesso all'applicazione. questa risposta può includere i dettagli della sessione, le informazioni sull'utente e probabilmente il token di accesso, a seconda della progettazione dell'app e del comportamento di sicurezza. (13)
- Il browser riceve la risposta di accesso e crea la sessione dell'utente. (14)
- Ora l'utente è connesso ed esegue un'azione nell'app personalizzata che avvia una richiesta di dati Salesforce. Ad esempio, può fare clic su un pulsante per accedere alla cronologia delle prenotazioni dei viaggi, archiviata nel sito Salesforce Experience Cloud. (15)
- L'app personalizzata invia una richiesta autenticata a un endpoint Salesforce protetto, ad esempio a un'API Salesforce. (16)
- Ora il cliente può accedere ai propri dati protetti nell'app personalizzata. Ad esempio, può visualizzare la cronologia delle prenotazioni dei viaggi. (17)
L'utente apre l'app di terze parti e fa clic su Registra
L'utente apre l'applicazione e fa clic su un link alla registrazione oppure fa clic su un link per accedere a una risorsa che richiede la registrazione.
L'app visualizza un modulo di registrazione
Nell'app, viene visualizzato in modo nativo un modulo di registrazione per la raccolta dei dati degli utenti. È possibile controllare tutto ciò che riguarda il modulo, inclusi l'aspetto, il funzionamento e le informazioni utente da raccogliere.
Ecco alcune considerazioni sulle informazioni da raccogliere dagli utenti. Quando l'app invia le informazioni utente all'API registrazione headless, Salesforce verifica la presenza di un indirizzo email, un nome utente, un cognome e una password. È possibile raccogliere queste informazioni dagli utenti o generarle automaticamente, ma le informazioni devono essere incluse nella richiesta POST. Per stabilire quali informazioni includere, assicurarsi di raccogliere un indirizzo email o un numero di telefono in modo che l'utente possa verificare la propria identità.
L'utente inserisce le proprie informazioni
Nell'app, l'utente inserisce le proprie informazioni nel modulo di registrazione.
L'app invia i dati utente dall'intestazione all'API registrazione headless
Dal browser, l'app invia una richiesta POST all'endpoint di registrazione headless (/services/auth/headless/init/registration) sul sito Experience Cloud utilizzando Java e XML asincroni ( AJAX).
Includere le seguenti intestazioni nella richiesta di registrazione.
| Intestazione | Obbligatorio? | Descrizione |
|---|---|---|
Authorization: Bearer
|
Questa intestazione è obbligatoria se si abilita Richiedi l'autenticazione per accedere a questa API nella pagina Accesso e registrazione di Experience Cloud. Si consiglia vivamente di abilitare sempre questa impostazione per i client privati. | Contiene un token di accesso generato per un utente integrazione interno. Per ottenere il token di accesso, si può utilizzare qualsiasi flusso OAuth standard supportato da Salesforce. Assicurarsi di assegnare l'ambito user_registration_api all'applicazione connessa o all'app client esterna o di trasmetterlo come parametro durante il flusso. |
Content-Type
|
No. Se si utilizza Postman per creare e testare il flusso, a volte viene aggiunta questa intestazione. Verificare che sia corretto controllando le intestazioni nascoste. | Specifica il formato della richiesta, ad esempio application/json. |
Includere questi parametri nel corpo della richiesta.
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
password
|
Sì. | La password dell'utente. La password è soggetta a tutti i criteri relativi alle password configurati per il profilo o l'organizzazione. |
userdata
|
Sì. Anche se non si raccolgono queste informazioni dall'utente, è necessario generarle automaticamente e trasmetterle nel parametro userdata. |
Contiene tutte le informazioni richieste sull'utente. Salesforce richiede almeno queste informazioni nel parametro
|
recaptcha
|
Obbligatorio se si applicano queste condizioni.
|
Token crittografato emesso dall'API reCAPTCHA di Google quando un utente completa una richiesta di verifica reCAPTCHA. |
recaptchaevent
|
Obbligatorio se si applicano le seguenti condizioni:
|
Oggetto JSON contenente i seguenti sottoparametri.
Per ulteriori informazioni, vedere la documentazione reCAPTCHA. |
verificationmethod
|
No. Se non si include questo parametro, Salesforce visualizza per impostazione predefinita la verifica dell'identità dell'utente tramite email. Se si include questo parametro, includere un'intestazione |
Il metodo utilizzato per verificare l'identità dell'utente. Salesforce supporta due valori per il metodo di verifica: email e sms. |
customdata
|
No. | Contiene tutte le informazioni personalizzate raccolte sull'utente. Ad esempio, è possibile includere l'indirizzo della via dell'utente. |
emailtemplate
|
Obbligatorio per specificare più modelli di email se è abilitato l'inserimento nell'elenco consentiti dei modelli di email. Se non si è abilitato l'inserimento nell'elenco consentiti dei modelli di email, non è possibile includere questo parametro. Se non si include questo parametro, Salesforce utilizza il modello di email predefinito configurato nelle impostazioni di Experience Cloud, indipendentemente dal fatto che l'inserimento nell'elenco consentiti sia abilitato o meno. Se non è disponibile alcun modello configurato, Salesforce utilizza un modello di email con OTP predefinito. |
Il nome dello sviluppatore del modello di email personalizzato. Questo parametro può includere solo un modello di email dell'elenco consentiti. |
Di seguito è riportato un esempio di richiesta POST. In questo esempio, le impostazioni di Experience Cloud sono configurate per richiedere autenticazione e reCAPTCHA, in modo che la richiesta contenga un token di accesso e un token reCAPTCHA.
POST /services/auth/headless/init/registration? HTTP 1.1
Host: MyDomainName.my.site.com
Content-Type: application/json
Authorization: Bearer **************
{
“userdata”: {
“firstName”: “Janice”
“lastName”: “Edwards”
“email”: “janice.edwards@example.com”
“username”: “jedwards@myapp.com”
}
“customdata”: {
{”mobilePhone”=”<mobile phone number>”
}
“password”: “*******”
“recaptcha”:”***********”
“verificationmethod”: “email”
“emailtemplate”: “unfiled$public/SalesNewCustomerEmail”
}Salesforce riceve le informazioni e restituisce un identificativo richiesta
Salesforce riceve le informazioni sull'utente. Salesforce non ha verificato l'identità dell'utente e quindi inserisce nelle aree di attesa queste informazioni per elaborarle in un secondo momento.
Se le informazioni nella richiesta POST sono valide, Salesforce restituisce un messaggio di esito positivo all'app. Questo messaggio include un identificativo di richiesta di registrazione, che sarà importante in seguito nel flusso. Di seguito è riportato un esempio di messaggio di operazione riuscita.
{
"status": "success",
"email": “jedwards@myapp.com”
"identifier": “0RXXXXXXXX”
}Salesforce invia una password singola all'utente
Subito dopo che Salesforce ha ricevuto i dati dell'utente e ha inviato un messaggio di esito positivo all'app, invia una password singola (OTP) tramite email o SMS, a seconda del metodo di verifica dell'utente.
L'app visualizza in modo nativo un modulo di verifica
Quando si riceve il messaggio di esito positivo, si visualizza in modo nativo un modulo di verifica OTP nell'app. Anche in questo caso, l'aspetto e lo stile dell'esperienza di verifica sono a scelta dell'utente.
L'utente immette un codice OTP nel modulo di verifica
L'utente riceve il codice OTP tramite email o SMS e lo inserisce nel modulo di verifica.
L'app inizializza il flusso Codice di autorizzazione e credenziali
Quando l'utente conferma la propria identità, l'applicazione inizializza immediatamente il flusso Codice di autorizzazione e credenziali con una richiesta all'API accesso headless.
Includere le seguenti intestazioni nella richiesta di autorizzazione
| Intestazione | Obbligatorio? | Descrizione |
|---|---|---|
Auth-Request-Type
|
Sì. | Specifica il tipo di richiesta che si desidera inviare a Salesforce. Per la registrazione headless, questo valore deve essere impostato su user-registration. |
Authorization
|
Sì. | Un'intestazione di base che Identifica la richiesta di registrazione in modo che Salesforce possa collegare la richiesta ai dati memorizzati dell'utente. È necessario includere l'identificatore della richiesta fornito da Salesforce e l'accesso con password singola utilizzato per verificare l'identità dell'utente. Aggiungere questi valori nel formato |
Content-Type
|
No. Se si utilizza Postman per creare e testare il flusso, a volte viene aggiunta questa intestazione. Verificare che sia corretto controllando le intestazioni nascoste. | Specifica il formato della richiesta, ad esempio application/x-www-form-urlencoded. |
Auth-Verification-Type
|
Obbligatorio se si è specificato un metodo di verifica dell'identità nella richiesta di registrazione iniziale. Il valore di questa intestazione deve corrispondere al valore del parametro del corpo del verificationmethod dalla richiesta all'endpoint /services/auth/headless/init/registration. |
Specifica il metodo utilizzato per verificare l'identità dell'utente. Salesforce supporta due valori per il metodo di verifica: email e sms. |
Uvid-Hint
|
No. 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. Anziché passare un token basato su JWT con un UVID in un'intestazione, è anche possibile passare il valore UVID normale nel corpo della richiesta. |
Token di accesso basato su JWT contenente un valore UVID, ovvero un identificativo univoco universale (UUID) versione 4 generato e gestito interamente dall'app. Per ottenere un token di accesso con un UVID, è necessario abilitare l'applicazione connessa o l'app client esterna per l'emissione di token di accesso basati su JWT e implementare il flusso guest headless nell'app. |
Includere questi parametri nel corpo della richiesta.
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
client_id
|
Sì. | Segreto consumatore dell'applicazione connessa o dell'applicazione client esterna. |
response_type
|
Sì. | Tipo di grant OAuth 2.0 richiesto dall'applicazione connessa o dall'applicazione client esterna. Per il flusso Codice di autorizzazione e credenziali, il valore deve essere code_credentials. |
redirect_uri
|
Sì. | URL a cui vengono reindirizzati gli utenti quando l'autenticazione ha esito positivo. L'URI di reindirizzamento deve corrispondere a uno dei valori presenti nel campo URL di richiamata dell'applicazione connessa o client esterna. In caso contrario, l'approvazione non riesce. Questo valore deve essere codificato nell'URL. |
uvid_hint
|
No. Se si implementa il flusso utente guest nell'app, è possibile, se si desidera, utilizzare questo parametro per passare un valore UVID associato all'identità di un utente guest, inserendo informazioni contestuali da una sessione utente guest in una sessione utente denominata. Anziché passare l'UVID nel corpo della richiesta, è anche possibile passarlo in un token basato su JWT con un UVID tramite l'intestazione |
Valore UVID normale, ovvero un UUID versione 4 generato e gestito dall'app. Per ottenere un UVID, è necessario abilitare l'applicazione connessa o l'app client esterna per l'emissione di token di accesso basati su JWT e implementare il flusso guest headless nell'app. |
code_challenge
|
Solo se si utilizza PKCE. | Obbligatorio se si utilizza l'estensione PKCE. Specifica il valore hash SHA256 del valore Questo parametro è obbligatorio se nella richiesta di token è specificato un
|
Di seguito è riportato un esempio di richiesta all'API accesso headless, con PKCE.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: user-registration
Auth-Verification-Type: email
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64-encoded request ID:OTP>
response_type=code_credentials&
client_id=******&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=Y29kZ*******
Salesforce verifica la richiesta, recupera i dati dell'utente e crea l'utente
Salesforce riceve la richiesta di autorizzazione e verifica l'ID richiesta e la password singola. Salesforce utilizza queste informazioni per recuperare i dati dell'utente in area di attesa e chiamare l'handler di registrazione headless configurato nel sito Experience Cloud. L'handler Apex crea l'utente in Salesforce e lo collega a un account.
Salesforce restituisce un reindirizzamento 302 a un URL preconfigurato contenente il codice
Salesforce restituisce un reindirizzamento HTTP 302 a un URL preconfigurato contenente il codice di autorizzazione. Il reindirizzamento 302 viene elaborato nel browser e la risposta viene consegnata in modalità headless all'endpoint di richiamata preconfigurato sul server. Di seguito è riportato un esempio di URL.
https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxxL'handler di richiamata estrae il codice ed esegue lo scambio di codice
L'handler di richiamata lato server estrae il codice di autorizzazione e altri parametri dal reindirizzamento 302. Avvia quindi lo scambio di codice inviando una richiesta POST headless all'endpoint token.
Per la richiesta di token di accesso è possibile utilizzare solo una richiesta POST. Le richieste GET non sono supportate. Non sono presenti intestazioni obbligatorie per questa richiesta, ma è possibile includere un'intestazione Content-Type.
| Intestazione | Obbligatorio? | Descrizione |
|---|---|---|
Content-Type
|
No. Se si utilizza Postman per creare e testare il flusso, a volte viene aggiunta questa intestazione. Verificare che sia corretto controllando le intestazioni nascoste. | Specifica il formato della richiesta, ad esempio application/x-www-form-urlencoded. |
Includere questi parametri nel corpo della richiesta.
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
client_id
|
Sì. | La chiave consumatore dell'applicazione connessa o dell'app client esterna. |
client_secret
|
Sì. | Segreto consumatore dell'applicazione connessa o dell'applicazione client esterna. |
code
|
Sì. | Il server di autorizzazione crea un codice di autorizzazione, ovvero un token di breve durata, e lo passa al client dopo che è stata eseguita correttamente l'autenticazione. Il client invia il codice di autorizzazione al server di autorizzazione per ottenere un token di accesso ed eventualmente un token di aggiornamento. |
code_verifier
|
Obbligatorio se si utilizza l'estensione PKCE. | Specifica 128 byte di dati casuali con entropia elevata per rendere difficile la congettura del valore di
|
format
|
No. | Il formato previsto per la risposta. Salesforce supporta questi formati.
|
grant_type
|
Sì. | Tipo di convalida che l'applicazione connessa o l'app client esterna può fornire per confermare che è un visitatore sicuro. Per il flusso Codice di autorizzazione e credenziali, il valore deve essere authorization_code. |
redirect_uri
|
Sì. | URL a cui vengono reindirizzati gli utenti quando l'autenticazione ha esito positivo. L'URI di reindirizzamento deve corrispondere a uno dei valori presenti nel campo URL di richiamata dell'applicazione connessa o client esterna. Questo valore deve essere codificato nell'URL. |
Di seguito è riportato un esempio di richiesta token.
POST /services/oauth2/token HTTP 1.1
Host: MyDomainName.my.site.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxC1*******&
client_id=******&
client_secret=******&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/apexrest/code/exchange&
code_verifier=Y29kZ*******
Salesforce concede un token di accesso
Salesforce convalida la richiesta di token e restituisce una risposta con token di accesso all'handler di richiamata lato server. Di seguito è riportato un esempio di risposta con token di accesso in formato JSON.
{
"access_token":"*******************",
"sfdc_community_url":"https://MyDomainName.my.site.com",
"sfdc_community_id":"0DBxxxxxxxxxxxx",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://yourInstance.salesforce.com",
"id":"https://yourInstance.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}La risposta con token di accesso contiene i seguenti parametri.
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
access_token
|
Sì. | Token OAuth utilizzato da un'applicazione connessa o da un'applicazione 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. |
id
|
Sì. | URL identità che può essere utilizzato per identificare l'utente e per chiedere più informazioni sull'utente. Vedere URL identità. |
id_token
|
No. | |
instance_url
|
Sì. | URL che indica l'istanza dell'organizzazione dell'utente. Ad esempio: https://yourInstance.salesforce.com/. |
issued_at
|
Sì. | Indicazione oraria del momento in cui la firma è stata creata, espressa come numero di millisecondi da 1970-01-01T0:0:0Z UTC |
refresh_token
|
No. | Token ottenuto dal flusso del token del server Web, utente-agente o dell'app ibrida. Questo valore è segreto. Adottare le misure appropriate per proteggerlo. Questo parametro viene restituito solo se l'applicazione connessa o l'app client esterna è impostata con un ambito refresh_token. |
signature
|
Sì. | 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. |
sfdc_community_url
|
Sì. | URL del sito Experience Cloud. |
sfdc_community_id
|
Sì. | ID del sito Experience Cloud dell'utente. |
state
|
No. | Lo stato richiesto dal client. Questo valore è incluso solo se il parametro state è incluso nella stringa di query originale. |
token_type
|
Sì. | Tipo di token di Bearer, utilizzato per tutte le risposte che includono un token di accesso. |
L'handler di richiamata elabora la risposta del token e restituisce i parametri all'app
L'handler di richiamata lato server acquisisce il token di accesso dalla risposta. L'handler di richiamata lato server restituisce quindi il token di accesso e lo stato al browser, insieme ai dati dell'utente, ai token e ai dati della sessione. È consigliabile configurare il server per la memorizzazione del token di accesso, creare una sessione per l'app e restituire la sessione all'app anziché restituire il token di accesso. In qualità di sviluppatore, l'utente ha il controllo completo sulla creazione della sessione, sulla memorizzazione del token di accesso e sulla gestione dello stato di accesso, in modo che l'implementazione specifica sia stabilita dall'utente.
Di seguito è riportato un esempio di risposta riuscita nel registro della console del browser.
{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","errMsg":null,"access_token":"00*******"}L'app elabora la risposta del token e crea la sessione utente
L'app riceve la risposta del token, la elabora e crea la sessione utente.
L'utente è registrato ed esegue un'azione nell'app
Ora l'utente è registrato e connesso. Esegue un'azione nell'app che richiede l'accesso ai dati Salesforce. Ad esempio, fa clic su un pulsante per visualizzare la cronologia delle prenotazioni dei viaggi, archiviata in Salesforce.
L'app effettua una chiamata autenticata a un endpoint Salesforce
Per accedere ai dati Salesforce dell'utente, l'app utilizza il token di accesso per effettuare una chiamata autenticata a un endpoint Salesforce protetto, ad esempio un'API Salesforce.
L'utente può accedere ai dati Salesforce
Ora l'utente può accedere ai dati Salesforce protetti nell'app. Ad esempio, può visualizzare la cronologia delle prenotazioni dei viaggi.
