breadcrumbDescription
Opsæt tokenudvekslingsforløbet
Nogle anvendelsessituationer kræver, at du integrerer Salesforce med en ekstern identitetsudbyder sammen med flere apps og mikroservices. Hvis du vil forenkle disse integrationer, skal du bruge OAuth 2.0-tokenudvekslingsforløbet. Med dette forløb skal du udveksle tokener fra en ekstern identitetsudbyder for Salesforce-tokener.
EditionsHeading
| Tilgængelig i: Enterprise, Performance, Unlimited og Developer Edition |
Du hoster f.eks. en kundeportal uden for Salesforce-platformen. Hvis du vil give dine kunder login og registrering, skal du bruge en identitetsudbyder. Når dine kunder er logget ind, får de adgang til data fra en række virksomhedstjenester, herunder webapps og mikroservices. Hvis du vil godkende din portal til at tildele brugere adgang til deres data, accepterer alle disse virksomhedstjenester adgangstokener fra din identitetsudbyder.
Du bruger Salesforce til at spore kundernes supportsager, og du ønsker at give brugere en måde til at få adgang til deres sager i din portal. Ved at konfigurere Salesforce til at acceptere tokener fra din identitetsudbyder kan du nemt passe Salesforce ind i dit integrationsmønster. Ved at bruge tokenudvekslingsforløbet validerer Salesforce identitetsudbyderens tokener, knytter dem til en Salesforce-bruger og udsteder Salesforce-tokener og giver brugere adgang til deres data i din portal.
Her er en trinvis oversigt over tokenudvekslingsforløbet.
Slutbruger anmoder om adgang til Salesforce-data (1)
En slutbruger logges på din app. De anmoder om adgang til beskyttede Salesforce-ressourcer. De klikker f.eks. på en knap for at få vist deres sager.
App har et gyldigt token (2)
Da slutbrugeren loggede ind, modtog vedkommende et eller flere tokener fra din identitetsudbyder. De modtog f.eks. et adgangstoken og et opdateringstoken. For at få adgang til Salesforce-data kan din app udveksle et af disse tokener. Salesforce accepterer disse tokentyper.
- Adgangstokener
- Opdatere tokener
- JSON-webtokener (JWT'er)
- SAML-påstande
- Id-tokener
App anmoder om en udveksling for et Salesforce-token (3)
Hvis du vil hente et Salesforce-token, sender din app en POST-anmodning til slutpunktet /services/oauth2/token på din login-URL til Mit domæne eller din Experience Cloud-lokalitets-URL.
Anmodningen understøtter et sidehoved.
| Sidehoved | Påkrævet? | Beskrivelse |
|---|---|---|
Uvid-Hint
|
Nej. Hvis du implementerer gæstebrugerforløbet på din app, kan du eventuelt bruge dette sidehoved til at overføre et entydigt besøgs-id (UVID), der er knyttet til en gæstebrugers identitet. Brug UVID til at overføre kontekstoplysninger fra en gæstebrugersession, f.eks. brugerens cookiepræferencer, til en navngivet brugersession. | Indeholder UVID, et universelt entydigt id (UUID) i version 4, der identificerer ukendte besøgende. Send UVID som en almindelig værdi, eller send et JWT-baseret adgangstoken med et UVID indbygget i det. Hvis du vil sende UVID som en almindelig værdi, skal du inkludere et UVID-præfiks, så anmodningen er formateret som Hvis du vil sende et JWT-baseret adgangstoken med et UVID, skal du inkludere et JWT-præfiks før værdien, f.eks. |
Medtag disse parametre i anmodningen.
| Parameter | Påkrævet? | Beskrivelse |
|---|---|---|
grant_type
|
Ja. | Den OAuth 2.0-metode, som appen bruger til at anmode om adgangstokenet. Tokenudvekslingsforløbet understøtter disse værdier.
|
subject_token
|
Ja. | Det token, der er udstedt af identitetsudbyderen. Den maksimale længde er 10.000 tegn. |
subject_token_type
|
Ja. | Typen af token, der er udstedt af identitetsudbyderen. Forløbet understøtter disse tokentyper.
|
client_id
|
Ja. | Forbrugernøglen for den tilsluttede app eller den eksterne klientapp. |
client_secret
|
Det afhænger af indstillingerne for din tilsluttede app eller eksterne klientapp. Hvis du vil kræve en For eksterne klientapps skal du indstille |
Forbrugerhemmeligheden for den tilsluttede app eller den eksterne klientapp. Vi anbefaler, at du kun sender en forbrugerhemmelighed, hvis din app har en privat klientafside, hvor den kan bevare hemmeligheden sikker. For offentlige klienter, der ikke har en privat back-end, f.eks. mobilapps og apps med en enkelt side, anbefaler vi ikke, at du sender en hemmelighed, da den kan blive lækket gennem browseren. |
scope
|
Nej. | Tilladelser, der definerer typen af beskyttede ressourcer, som en tilsluttet app har adgang til. De værdier, som du sender i denne anmodning, skal matche eller være et undersæt af de omfang, der er tildelt til din tilsluttede app eller ekstern klientapp. Hvis du ønsker flere oplysninger om hvert omfang og dets formål, kan du se OAuth-tokener og -omfang. |
token_handler
|
Nej, men det anbefales på det kraftigste. Hvis du ikke inkluderer denne parameter, bruger Salesforce din standardhåndtering. Du definerer en standardhandler ved brug af feltet isDefault på OauthTokenExchHandlerApp-metadatatypen. Du skal have mindst en standardhåndtering. | Navnet på den Apex, der bruges til at validere tokenet og tilknytte det til en Salesforce-bruger. |
Her er der en eksempeltokenanmodning, der indeholder et adgangstoken.
POST /services/oauth2/token? HTTP 1.1
Host: MyDomainName.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=*************&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
client_id=***********&
client_secret=************&
scope=web&
token_handler=MyTokenHandler
Salesforce OAuth-kørsel fuldfører indledende validering (4)
Salesforces OAuth-kørsel modtager anmodningen og kører den gennem en indledende validering. Valideringen er baseret på disse krav.
- Den tilsluttede app eller den eksterne klientapp skal være aktiveret for tokenudvekslingsforløbet. Se Integrer en app for tokenudvekslingsforløbet.
subject_token_typei anmodningen skal være aktiveret for tokenudvekslingshandleren. Hvis du vil aktivere en handler for en tokentype, skal du indstille det tilsvarende felt i handlerens OauthTokenExchangeHandler-metadatadefinition tiltrue.subject_token_typeOauthTokenExchangeHandler-felt urn:ietf:params:oauth:token-type:access_tokenisAccessTokenSupported urn:ietf:params:oauth:token-type:refresh_tokenisRefreshTokenSupported urn:ietf:params:oauth:token-type:id_tokenisIdTokenSupported urn:ietf:params:oauth:token-type:saml2isSaml2Supported urn:ietf:params:oauth:token-type:jwtisJwtSupported - Hvis anmodningen indeholder en
client_secret, skal den matche forbrugerhemmeligheden for den tilsluttede app eller den eksterne klientapp. - Hvis anmodningen indeholder en
token_handler, skal organisationen have en understøttet Apex-tokenudvekslingshandler, der matcher navnet i anmodningen. - Tokenudvekslingshandleren skal være aktiveret, hvilket betyder, at feltet isEnabled på dens OauthTokenExchangeHandler-metadatadefinition skal indstilles til
true.
Hvis anmodningen opfylder disse indledende krav, sender Salesforce tokenet fra den eksterne identitetsudbyder til Apex.
Apex validerer tokenet (5)
Apex modtager identitetsudbydertokenet og validerer det ved brug af din tilpassede valideringslogik. Hvordan du vil validere tokenet, er helt op til dig.
(Valgfrit) Apex ringer ud til identitetsudbyderen til validering (6)
Afhængig af dine valideringskrav kan du eventuelt konfigurere din handler til at ringe til identitetsudbyderen. Hvis tokenet er uigennemsigtigt, eller hvis du ønsker at validere det i realtid, kan du ringe til tokenintrospektionen eller slutpunktet Brugeroplysninger på den eksterne identitetsudbyder.
Apex tilknytter tokenet til et Salesforce-emne (7)
Apex identificerer tokenens emne, som er den slutbruger, som det blev udstedt til, og tilknytter det til et Salesforce-emne.
(Valgfrit) Apex ringer ud til identitetsudbyderen for brugeroplysninger (8)
Hvis du ønsker at få nok oplysninger til at oprette et emne eller for at få yderligere oplysninger om et indgående emne, kan du eventuelt konfigurere din handler til at ringe til identitetsudbyderen eller til et andet eksternt system.
Apex finder eller opsætter en bruger (9)
Hvis handleren finder en bruger baseret på data fra tokenet eller fra et eksternt udkald, returnerer den brugeren.
Hvis feltet isUserCreationAllowed er indstillet til true på handlerens OauthTokenExchangeHandler-metadatadefinition, opsætter handleren et nyt brugerobjekt og returnerer det til Salesforce. Denne handling opretter faktisk ikke brugeren – i stedet for returneres brugerobjektet til Salesforce til automatisk indsættelse.
Hvis du ønsker flere oplysninger om tilpasning af din handler til validering af tokener og tilknytning af emner, kan du se Validering af tokenudvekslingshandler og emnetilknytning i Apex Developer Guide.
Salesforce OAuth-kørsel fuldfører brugertilknytning (10)
Salesforce OAuth-kørselskontrollerer for at se, om handleren returnerede en bruger. Hvis det er tilfældet, bekræfter det, om brugeren findes og fuldfører tilknytningen. Hvis brugeren ikke findes, og hvis handleren er konfigureret til at opsætte brugere, indsætter Salesforce automatisk brugeren på vegne af tokenudvekslingshandleren.
Salesforce OAuth-kørsel returnerer tokensvar (11)
Salesforce returnerer et svar, der indeholder et Salesforce-adgangstoken og eventuelle andre tokener eller parametre, som du har anmodet om, herunder opdateringstokener, id-tokener og hybridtokener. Adgangstokenet kan være uigennemsigtigt eller JWT-baseret, afhængigt af indstillingerne for din tilsluttede app eller eksterne klientapp.
Hvis du overførte et UVID i tokenanmodningen, overføres det også gennem forløbet. For et uigennemsigtigt tokensvar vises UVID på slutpunktet services/oauth2/userinfo på din login-URL til Mit domæne eller på Experience Cloud-lokalitets-URL'en. For et JWT-baseret tokensvar sættes UVID'et i det nye adgangstoken.
App Modtager svar (12)
Din app modtager tokensvaret, herunder adgangstokenet og andre tokener og parametre. Her er der et eksempeltokensvar.
{
"access_token":"*******************",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://MyDomainName.my.salesforce.com",
"id":"https://MyDomainName.my.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}Slutpunkt for appopkald - brugeroplysninger (13)
Hvis det er nødvendigt for at fuldføre brugerlogin, kan din app kalde slutpunktet /services/oauth2/userinfo på din login-URL til Mit domæne eller på Experience Cloud-lokalitets-URL'en. Hvis du f.eks. overførte et UVID i din tokenanmodning, og Salesforce returnerede et svar med et uigennemsigtigt adgangstoken, skal du kalde slutpunktet Brugeroplysninger for at få UVID'et.
App anmoder om adgang til Salesforce-data (14)
Nu da din app har et Salesforce-adgangstoken, opretter den en godkendt anmodning til en beskyttet Salesforce-ressource for at hente brugeren deres data.
Slutbruger får adgang til Salesforce-data (15)
Hvis anmodningen lykkes, kan slutbrugeren få adgang til sine Salesforce-data i din app. Fra brugerens perspektiv klikkede de blot på en knap og så deres data uden at blive bedt om at logge ind eller godkende adgang.
