OAuth 2-auktorisering
Destinationen SDK har stöd för flera åtkomstmetoder till ditt mål. Detta är bland annat alternativet att autentisera till ditt mål med hjälp av OAuth 2-auktoriseringsramverket.
Den här sidan beskriver de olika OAuth 2-auktoriseringsflöden som stöds av Destinationen SDK och innehåller anvisningar om hur du ställer in OAuth 2-auktorisering för ditt mål.
Integrationstyper som stöds supported-integration-types
Se tabellen nedan för mer ingående information om vilka typer av integreringar som stöder de funktioner som beskrivs på den här sidan.
Så här lägger du till OAuth 2-auktoriseringsinformation i målkonfigurationen how-to-setup
Förutsättningar i systemet prerequisites
Som ett första steg måste du skapa en app i ditt system för Adobe Experience Platform, eller på annat sätt registrera Experience Platform i ditt system. Målet är att generera ett klient-ID och en klienthemlighet som behövs för att autentisera Experience Platform mot målet.
Som en del av den här konfigurationen i ditt system behöver du omdirigerings-/återanrops-URL:erna för Adobe Experience Platform OAuth 2, som du kan hämta från listan nedan.
https://platform-va7.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-can2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-gbr9.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform.adobe.io/data/core/activation/oauth/api/v1/callback
I slutet av det här steget bör du ha:
- Ett klient-ID.
- En klienthemlighet;
- AdobeCallback-URL (för auktoriseringskodens medgivande).
Vad du behöver göra i Destinationen SDK to-do-in-destination-sdk
Om du vill konfigurera OAuth 2-auktorisering för ditt mål i Experience Platform måste du lägga till din OAuth 2-information i målkonfigurationen, under parametern customerAuthenticationConfigurations. Se kundautentisering för detaljerade exempel. Specifika anvisningar om vilka fält du måste lägga till i konfigurationsmallen, beroende på din OAuth 2-auktoriseringstyp, finns längre ned på den här sidan.
OAuth 2-anslagstyper som stöds oauth2-grant-types
Experience Platform stöder de tre OAuth 2-anslagstyperna i tabellen nedan. Om du har en anpassad OAuth 2-konfiguration kan Adobe stödja den med hjälp av anpassade fält i din integrering. Mer information finns i avsnitten för respektive anslagstyp.
- Du anger indataparametrarna enligt instruktionerna i avsnitten nedan. Adobe-interna system ansluter till din plattforms auktoriseringssystem och hämtar utdataparametrar, som används för att autentisera användaren och upprätthålla auktoriseringen till din destination.
- Indataparametrarna som markeras med fet stil i tabellen är obligatoriska parametrar i OAuth 2-auktoriseringsflödet. De andra parametrarna är valfria. Det finns andra anpassade indataparametrar som inte visas här, men som beskrivs i detalj i avsnitten Anpassa din OAuth 2-konfiguration och Uppdatera åtkomsttoken.
- clientId
- clientSecret
- omfång
- authenticationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expirresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- omfång
- accessTokenUrl
- användarnamn
- lösenord
- accessToken
- expirresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- omfång
- accessTokenUrl
- accessToken
- expirresIn
- refreshToken
- tokenType
Tabellen ovan visar de fält som används i OAuth 2-standardflöden. Förutom dessa standardfält kan olika partnerintegreringar kräva ytterligare indata och utdata. Adobe har utformat ett flexibelt ramverk för OAuth 2-auktorisering för Destination SDK som kan hantera variationer av det ovanstående standardfältmönstret och samtidigt ha stöd för en mekanism som automatiskt återskapar ogiltiga utdata, som utgångna åtkomsttoken.
Utdata innehåller alltid en åtkomsttoken som används av Experience Platform för att autentisera och upprätthålla behörigheten till ditt mål.
Det system som Adobe har utformat för OAuth 2-auktorisering:
- Stöder alla tre OAuth 2-stipendiaterna samtidigt som de redovisar eventuella variationer i dem, som extra datafält, icke-standard-API-anrop med mera.
- Stöder åtkomsttoken med varierande livstidsvärden, oavsett om det är 90 dagar, 30 minuter eller något annat livstidsvärde som du anger.
- Stöder OAuth 2-auktoriseringsflöden med eller utan uppdateringstoken.
OAuth 2 med auktoriseringskod authorization-code
Om målet har stöd för ett vanligt OAuth 2.0 Authorization Code-flöde (läs RFC-standardsspecifikationer) eller en variant av det, kan du läsa de obligatoriska och valfria fälten nedan:
- clientId
- clientSecret
- omfång
- authenticationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expirresIn
- refreshToken
- tokenType
Om du vill konfigurera den här auktoriseringsmetoden för målet lägger du till följande rader i konfigurationen när du skapar en målkonfiguration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"authorizationUrl": "https://www.moviestar.com/dialog/OAuth",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
authTypegrantaccessTokenUrlauthorizationUrlrefreshTokenUrlrefreshTokenUrl samma som accessTokenUrl.clientIdclientSecretscopeOAuth 2 med lösenordsbeviljande
För OAuth 2-lösenordsbeviljande (läs RFC-standardspecifikationerna) kräver Experience Platform användarens användarnamn och lösenord. I auktoriseringsflödet utbyter Experience Platform dessa autentiseringsuppgifter för en åtkomsttoken och, om så önskas, en uppdateringstoken.
Adobe använder standardindata nedan för att förenkla destinationskonfigurationen, med möjlighet att åsidosätta värden:
- clientId
- clientSecret
- omfång
- accessTokenUrl
- användarnamn
- lösenord
- accessToken
- expirresIn
- refreshToken
- tokenType
username och password i konfigurationen nedan. När du lägger till "grant": "OAUTH2_PASSWORD" i målkonfigurationen kommer systemet att begära att användaren anger ett användarnamn och lösenord i användargränssnittet för Experience Platform när de autentiseras mot målet.Om du vill konfigurera den här auktoriseringsmetoden för målet lägger du till följande rader i konfigurationen när du skapar en målkonfiguration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_PASSWORD",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
authTypegrantaccessTokenUrlclientIdclientSecretscopeOAuth 2 med klientautentiseringsuppgifter
Du kan konfigurera en OAuth 2-klientautentiseringsuppgifter (läs RFC-standardsspecifikationer) som stöder standardindata och standardutdata som listas nedan. Du kan anpassa värdena. Mer information finns i Anpassa OAuth 2-konfigurationen.
- clientId
- clientSecret
- omfång
- accessTokenUrl
- accessToken
- expirresIn
- refreshToken
- tokenType
Om du vill konfigurera den här auktoriseringsmetoden för målet lägger du till följande rader i konfigurationen när du skapar en målkonfiguration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
authTypegrantaccessTokenUrlrefreshTokenUrlrefreshTokenUrl samma som accessTokenUrl.clientIdclientSecretscopeAnpassa din OAuth 2-konfiguration customize-configuration
De konfigurationer som beskrivs i avsnitten ovan beskriver OAuth 2-standardstipendier. Det system som Adobe har utformat ger dock flexibilitet så att du kan använda anpassade parametrar för alla variationer i OAuth 2-anslaget. Om du vill anpassa OAuth 2-standardinställningarna använder du parametrarna authenticationDataFields, som visas i exemplen nedan.
Exempel 1: authenticationDataFields används för att hämta information från auktoriseringssvaret example-1
I det här exemplet har en målplattform uppdateringstoken som upphör att gälla efter en viss tid. I det här fallet konfigurerar partnern det anpassade fältet refreshTokenExpiration så att uppdateringstoken upphör att gälla från fältet refresh_token_expires_in i API-svaret.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"options":{
},
"grant":"OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl":"https://api.moviestar.com/OAuth/access_token",
"authorizationUrl":"https://api.moviestar.com/OAuth/authorization",
"scope":[
"read",
"write",
"delete"
],
"refreshTokenUrl":"https://api.moviestar.com/OAuth/accessToken",
"clientSecret":"client-secret-here",
"authenticationDataFields":[
{
"name":"refreshTokenExpiration",
"title":"Refresh Token Expires In",
"description":"Time in seconds when the refresh token will expire",
"type":"string",
"isRequired":false,
"source":"CUSTOMER",
"authenticationResponsePath":"refresh_token_expires_in"
}
]
}
]
}
Exempel 2: authenticationDataFields används för att tillhandahålla en särskild uppdateringstoken example-2
I det här exemplet ställer en partner in sitt mål för att tillhandahålla en särskild uppdateringstoken. Dessutom returneras inte förfallodatumet för åtkomsttoken i API-svaret, vilket innebär att de kan hårdkoda ett standardvärde, i det här fallet 3 600 sekunder.
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
Exempel 3: Användaren anger klient-ID och klienthemlighet när han/hon konfigurerar målet example-3
I det här exemplet måste kunden, i stället för att skapa ett globalt klient-ID och en klienthemlighet, som visas i avsnittet Krav i systemet, ange klient-ID, klienthemlighet och konto-ID (det ID som kunden använder för att logga in på målet)
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"authenticationDataFields": [
{
"name": "clientId",
"title": "Client ID",
"description": "Client ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
},
{
"name": "clientSecret",
"title": "Client Secret",
"description": "Client Secret",
"type": "string",
"isRequired": true,
"format": "password",
"source": "CUSTOMER"
},
{
"name": "moviestarId",
"title": "Moviestar ID",
"description": "Moviestar ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
}
],
"accessTokenRequest": {
"destinationServerType": "URL_BASED",
"urlBasedDestination": {
"url": {
"templatingStrategy": "PEBBLE_V1",
"value": "https://{{ authData.moviestarId }}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate": {
"requestBody": {
"templatingStrategy": "PEBBLE_V1",
"value": "{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod": "POST",
"contentType": "application/x-www-form-urlencoded"
},
"responseFields": [
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.access_token }}",
"name": "accessToken"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.scope }}",
"name": "scope"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.token_type }}",
"name": "tokenType"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.expires_in }}",
"name": "expiresIn"
}
]
}
}
]
//...
}
Du kan använda följande parametrar i authenticationDataFields för att anpassa OAuth 2-konfigurationen:
authenticationDataFields.nameauthenticationDataFields.titleauthenticationDataFields.descriptionauthenticationDataFields.typeGodkända värden:
string, boolean, integerauthenticationDataFields.isRequiredauthenticationDataFields.format"format":"password" krypterar Adobe värdet för auktoriseringsdatafältet. När det används med "fieldType": "CUSTOMER" döljs även indata i användargränssnittet när användaren skriver i fältet.authenticationDataFields.fieldTypeauthenticationDataFields.valueauthenticationDataFields.type.authenticationDataFields.authenticationResponsePathUppdatera åtkomsttoken access-token-refresh
Adobe har utformat ett system som uppdaterar utgångna åtkomsttoken utan att användaren behöver logga in på din plattform igen. Systemet kan generera en ny token så att aktiveringen till destinationen kan fortsätta utan problem för kunden.
Om du vill konfigurera uppdatering av åtkomsttoken kan du behöva konfigurera en mallad HTTP-begäran som tillåter att Adobe får en ny åtkomsttoken med hjälp av en uppdateringstoken. Om åtkomsttoken har upphört att gälla, tar Adobe den mallbaserade begäran som du har angett och lägger till de parametrar som du har angett. Använd parametern accessTokenRequest för att konfigurera en uppdateringsmekanism för åtkomsttoken.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"grant":"OAUTH2_CLIENT_CREDENTIALS",
"accessTokenRequest":{
"destinationServerType":"URL_BASED",
"urlBasedDestination":{
"url":{
"templatingStrategy":"PEBBLE_V1",
"value":"https://{{authData.customerId}}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate":{
"requestBody":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod":"POST",
"contentType":"application/x-www-form-urlencoded",
"headers":[
]
},
"responseFields":[
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.expires_in }}",
"name":"expiresIn"
},
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.access_token }}",
"name":"accessToken"
}
],
"validations":[
{
"name":"access_token validation",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{response.body.access_token is empty }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"false"
}
},
{
"name":"response status",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.status }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"200"
}
}
]
}
}
]
}
Du kan använda följande parametrar i accessTokenRequest för att anpassa din tokenuppdateringsprocess:
accessTokenRequest.destinationServerTypeURL_BASED.accessTokenRequest.urlBasedDestination.url.templatingStrategy- Använd
PEBBLE_V1om du använder mallar för värdet iaccessTokenRequest.urlBasedDestination.url.value. - Använd
NONEom värdet i fältetaccessTokenRequest.urlBasedDestination.url.valueär en konstant.
accessTokenRequest.urlBasedDestination.url.valueaccessTokenRequest.httpTemplate.requestBody.templatingStrategy- Använd
PEBBLE_V1om du använder mallar för värdena iaccessTokenRequest.httpTemplate.requestBody.value. - Använd
NONEom värdet i fältetaccessTokenRequest.httpTemplate.requestBody.valueär en konstant.
accessTokenRequest.httpTemplate.requestBody.valueaccessTokenRequest.httpTemplate.httpMethodPOST.accessTokenRequest.httpTemplate.contentTypeTill exempel:
application/x-www-form-urlencoded eller application/json.accessTokenRequest.httpTemplate.headersaccessTokenRequest.responseFields.templatingStrategy- Använd
PEBBLE_V1om du använder mallar för värdena iaccessTokenRequest.responseFields.value. - Använd
NONEom värdet i fältetaccessTokenRequest.responseFields.valueär en konstant.
accessTokenRequest.responseFields.valueaccessTokenRequest.validations.nameaccessTokenRequest.validations.actualValue.templatingStrategy- Använd
PEBBLE_V1om du använder mallar för värdena iaccessTokenRequest.validations.actualValue.value. - Använd
NONEom värdet i fältetaccessTokenRequest.validations.actualValue.valueär en konstant.
accessTokenRequest.validations.actualValue.valueaccessTokenRequest.validations.expectedValue.templatingStrategy- Använd
PEBBLE_V1om du använder mallar för värdena iaccessTokenRequest.validations.expectedValue.value. - Använd
NONEom värdet i fältetaccessTokenRequest.validations.expectedValue.valueär en konstant.
accessTokenRequest.validations.expectedValue.valueMallkonventioner templating-conventions
Beroende på hur du anpassar din behörighet kan du behöva komma åt datafält i auktoriseringssvaret, vilket visas i föregående avsnitt. Det gör du genom att bekanta dig med det Pebble-mallspråk som används av Adobe och se mallkonventionerna nedan för att anpassa OAuth 2-implementeringen.
{{ authData.accessToken }}{{ response.body.access_token }}{{ response.status }}{{ response.headers.server[0] }}{{ userContext.sandboxName }}{{ userContext.sandboxId }}{{ userContext.imsOrgId }}{{ userContext.client }} // the client executing the authorization attempt
Nästa steg next-steps
Genom att läsa den här artikeln får du nu en förståelse för de OAuth 2-autentiseringsmönster som stöds av Adobe Experience Platform och veta hur du konfigurerar ditt mål med OAuth 2-auktoriseringsstöd. Sedan kan du konfigurera ditt mål som stöds av OAuth 2 med Destination SDK. Läs Använd Destination SDK för att konfigurera ditt mål för nästa steg.