OAuth 2 인증
Destination SDK은 대상에 대한 여러 인증 방법을 지원합니다. 이러한 옵션 중 하나는 OAuth 2 인증 프레임워크를 사용하여 대상을 인증하는 옵션입니다.
이 페이지에서는 Destination SDK에서 지원하는 다양한 OAuth 2 인증 흐름에 대해 설명하고 대상에 대한 OAuth 2 인증을 설정하는 지침을 제공합니다.
지원되는 통합 유형 supported-integration-types
이 페이지에 설명된 기능을 지원하는 통합 유형에 대한 자세한 내용은 아래 표를 참조하십시오.
대상 구성에 OAuth 2 인증 세부 사항을 추가하는 방법 how-to-setup
시스템의 필수 구성 요소 prerequisites
첫 번째 단계로, Adobe Experience Platform용 시스템에서 앱을 만들거나 시스템에 Experience Platform을 등록해야 합니다. 목표는 대상에 대한 Experience Platform을 인증하는 데 필요한 클라이언트 ID와 클라이언트 암호를 생성하는 것입니다.
시스템에서 이 구성의 일부로 아래 목록에서 가져올 수 있는 Adobe Experience Platform OAuth 2 리디렉션/콜백 URL이 필요합니다.
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
이 단계를 마치면 다음과 같은 작업을 수행할 수 있습니다.
- 클라이언트 ID;
- 클라이언트 암호
- Adobe의 콜백 URL(인증 코드 부여용).
Destination SDK에서 수행해야 하는 작업 to-do-in-destination-sdk
Experience Platform에서 대상에 대한 OAuth 2 인증을 설정하려면 customerAuthenticationConfigurations 매개 변수 아래의 대상 구성에 OAuth 2 세부 사항을 추가해야 합니다. 자세한 예제는 고객 인증을 참조하십시오. OAuth 2 권한 부여 유형에 따라 구성 템플릿에 추가해야 하는 필드에 대한 특정 지침은 이 페이지의 아래에 나와 있습니다.
지원되는 OAuth 2 부여 유형 oauth2-grant-types
Experience Platform은 아래 표에서 세 가지 OAuth 2 부여 유형을 지원합니다. 사용자 지정 OAuth 2 설정이 있는 경우 Adobe은 통합의 사용자 지정 필드의 도움을 받아 이를 지원할 수 있습니다. 자세한 내용은 각 권한 유형에 대한 섹션을 참조하십시오.
- 아래 섹션에 설명된 대로 입력 매개 변수를 제공합니다. Adobe 내부 시스템은 플랫폼의 인증 시스템에 연결되고 출력 매개 변수를 가져오며, 이 매개 변수는 사용자를 인증하고 대상에 대한 인증을 유지 관리하는 데 사용됩니다.
- 표에서 굵게 강조 표시된 입력 매개 변수는 OAuth 2 인증 흐름의 필수 매개 변수입니다. 다른 매개 변수는 선택 사항입니다. 여기에는 표시되지 않지만 OAuth 2 구성 사용자 지정 및 액세스 토큰 새로 고침 섹션에 자세히 설명되어 있는 다른 사용자 지정 입력 매개 변수가 있습니다.
- clientId
- clientSecret
- 범위
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- 범위
- accessTokenUrl
- 사용자 이름
- 암호
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- 범위
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
위의 표에는 표준 OAuth 2 흐름에 사용되는 필드가 나열되어 있습니다. 이러한 표준 필드 외에도 다양한 파트너 통합은 추가 입력 및 출력이 필요할 수 있습니다. Adobe은 만료된 액세스 토큰과 같은 잘못된 출력을 자동으로 재생성하는 메커니즘을 지원하면서 위의 표준 필드 패턴에 대한 변형을 처리할 수 있는 유연한 Destination SDK용 OAuth 2 인증 프레임워크를 설계했습니다.
모든 경우에 출력에는 액세스 토큰이 포함되며, 이 액세스 토큰은 Experience Platform에서 대상에 대한 인증을 인증하고 유지 관리하는 데 사용됩니다.
Adobe이 OAuth 2 인증을 위해 디자인한 시스템:
- 는 추가 데이터 필드, 비표준 API 호출 등과 같은 다양한 변형을 고려하면서 세 가지 OAuth 2 권한 모두를 지원합니다.
- 90일, 30분 또는 지정한 다른 모든 라이프타임 값을 포함하여 다양한 라이프타임 값으로 액세스 토큰을 지원합니다.
- 새로 고침 토큰이 있거나 없는 OAuth 2 인증 흐름을 지원합니다.
인증 코드가 있는 OAuth 2 authorization-code
대상이 표준 OAuth 2.0 인증 코드 흐름(RFC 표준 사양 읽기) 또는 그 변형을 지원하는 경우 아래의 필수 및 옵션 필드를 참조하십시오.
- clientId
- clientSecret
- 범위
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
대상에 대해 이 인증 방법을 설정하려면 대상 구성을 만들 때 구성에 다음 줄을 추가하십시오.
{
//...
"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은(는) accessTokenUrl과(와) 같습니다.clientIdclientSecretscope암호 부여가 있는 OAuth 2
OAuth 2 암호 부여(RFC 표준 사양 읽기)의 경우 Experience Platform에 사용자의 사용자 이름과 암호가 필요합니다. 인증 흐름에서 Experience Platform은 액세스 토큰 및 선택적으로 새로 고침 토큰에 대해 이러한 자격 증명을 교환합니다.
Adobe은 아래의 표준 입력을 사용하여 값을 재정의하는 기능으로 대상 구성을 단순화합니다.
- clientId
- clientSecret
- 범위
- accessTokenUrl
- 사용자 이름
- 암호
- accessToken
- expiresIn
- refreshToken
- tokenType
username 및 password에 대한 매개 변수를 추가할 필요가 없습니다. 대상 구성에 "grant": "OAUTH2_PASSWORD"을(를) 추가하면 대상 인증 시 시스템에서 Experience Platform UI에 사용자 이름과 암호를 입력하도록 사용자에게 요청합니다.대상에 대해 이 인증 방법을 설정하려면 대상 구성을 만들 때 구성에 다음 줄을 추가하십시오.
{
//...
"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"]
}
]
authTypegrantaccessTokenUrlclientIdclientSecretscope클라이언트 자격 증명 부여가 있는 OAuth 2
아래 나열된 표준 입력 및 출력을 지원하는 OAuth 2 클라이언트 자격 증명(RFC 표준 사양 읽기) 대상을 구성할 수 있습니다. 값을 사용자 지정할 수 있습니다. 자세한 내용은 OAuth 2 구성 사용자 지정을 참조하십시오.
- clientId
- clientSecret
- 범위
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
대상에 대해 이 인증 방법을 설정하려면 대상 구성을 만들 때 구성에 다음 줄을 추가하십시오.
{
//...
"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은(는) accessTokenUrl과(와) 같습니다.clientIdclientSecretscopeOAuth 2 구성 사용자 지정 customize-configuration
위 섹션에 설명된 구성은 표준 OAuth 2 부여에 대해 설명합니다. 그러나 Adobe에서 디자인한 시스템은 유연성을 제공하므로 OAuth 2 부여에 있는 모든 변형에 대해 사용자 지정 매개 변수를 사용할 수 있습니다. 표준 OAuth 2 설정을 사용자 지정하려면 아래 예제와 같이 authenticationDataFields 매개 변수를 사용하십시오.
예제 1: authenticationDataFields을(를) 사용하여 권한 부여 응답에서 오는 정보를 캡처합니다. example-1
이 예에서 대상 플랫폼에는 특정 시간 후에 만료되는 새로 고침 토큰이 있습니다. 이 경우 파트너는 API 응답의 refresh_token_expires_in 필드에서 새로 고침 토큰 만료를 가져오도록 refreshTokenExpiration 사용자 지정 필드를 설정합니다.
{
"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"
}
]
}
]
}
예제 2: authenticationDataFields을(를) 사용하여 특수 새로 고침 토큰을 제공합니다. example-2
이 예에서 파트너는 특별한 새로 고침 토큰을 제공하기 위해 대상을 설정합니다. 또한 액세스 토큰의 만료 날짜는 API 응답에 반환되지 않으므로 기본값인 3600초를 하드코딩할 수 있습니다.
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
예제 3: 사용자가 대상을 구성할 때 클라이언트 ID 및 클라이언트 암호를 입력합니다 example-3
이 예제에서는 시스템의 필수 구성 요소 섹션에 표시된 대로 전역 클라이언트 ID와 클라이언트 암호를 만드는 대신 고객이 클라이언트 ID, 클라이언트 암호 및 계정 ID(고객이 대상에 로그인하는 데 사용하는 ID)를 입력해야 합니다
{
//...
"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"
}
]
}
}
]
//...
}
authenticationDataFields에서 다음 매개 변수를 사용하여 OAuth 2 구성을 사용자 지정할 수 있습니다.
authenticationDataFields.nameauthenticationDataFields.titleauthenticationDataFields.descriptionauthenticationDataFields.type허용되는 값:
string, boolean, integerauthenticationDataFields.isRequiredauthenticationDataFields.format"format":"password"을(를) 선택하면 Adobe이 권한 부여 데이터 필드의 값을 암호화합니다. "fieldType": "CUSTOMER"과(와) 함께 사용하는 경우 사용자가 필드에 입력할 때 UI의 입력도 숨깁니다.authenticationDataFields.fieldTypeauthenticationDataFields.valueauthenticationDataFields.type에서 선택한 형식과 일치합니다.authenticationDataFields.authenticationResponsePath액세스 토큰 새로 고침 access-token-refresh
Adobe은 사용자가 플랫폼에 다시 로그인할 필요 없이 만료된 액세스 토큰을 새로 고치는 시스템을 디자인했습니다. 시스템은 대상에 대한 활성화가 고객을 위해 원활하게 계속되도록 새 토큰을 생성할 수 있습니다.
액세스 토큰 새로 고침을 설정하려면 Adobe이 새로 고침 토큰을 사용하여 새 액세스 토큰을 가져올 수 있도록 해주는 템플릿화된 HTTP 요청을 구성해야 할 수 있습니다. 액세스 토큰이 만료된 경우 Adobe은 사용자가 제공한 템플릿 요청을 수락하고 제공한 매개 변수를 추가합니다. accessTokenRequest 매개 변수를 사용하여 액세스 토큰 새로 고침 메커니즘을 구성하십시오.
{
"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"
}
}
]
}
}
]
}
accessTokenRequest에서 다음 매개 변수를 사용하여 토큰 새로 고침 프로세스를 사용자 지정할 수 있습니다.
accessTokenRequest.destinationServerTypeURL_BASED 사용.accessTokenRequest.urlBasedDestination.url.templatingStrategyaccessTokenRequest.urlBasedDestination.url.value의 값에 템플릿을 사용하는 경우PEBBLE_V1을(를) 사용합니다.accessTokenRequest.urlBasedDestination.url.value필드의 값이 상수인 경우NONE을(를) 사용합니다.
accessTokenRequest.urlBasedDestination.url.valueaccessTokenRequest.httpTemplate.requestBody.templatingStrategyaccessTokenRequest.httpTemplate.requestBody.value의 값에 템플릿을 사용하는 경우PEBBLE_V1을(를) 사용합니다.accessTokenRequest.httpTemplate.requestBody.value필드의 값이 상수인 경우NONE을(를) 사용합니다.
accessTokenRequest.httpTemplate.requestBody.valueaccessTokenRequest.httpTemplate.httpMethodPOST입니다.accessTokenRequest.httpTemplate.contentType예:
application/x-www-form-urlencoded 또는 application/json.accessTokenRequest.httpTemplate.headersaccessTokenRequest.responseFields.templatingStrategyaccessTokenRequest.responseFields.value의 값에 템플릿을 사용하는 경우PEBBLE_V1을(를) 사용합니다.accessTokenRequest.responseFields.value필드의 값이 상수인 경우NONE을(를) 사용합니다.
accessTokenRequest.responseFields.valueaccessTokenRequest.validations.nameaccessTokenRequest.validations.actualValue.templatingStrategyaccessTokenRequest.validations.actualValue.value의 값에 템플릿을 사용하는 경우PEBBLE_V1을(를) 사용합니다.accessTokenRequest.validations.actualValue.value필드의 값이 상수인 경우NONE을(를) 사용합니다.
accessTokenRequest.validations.actualValue.valueaccessTokenRequest.validations.expectedValue.templatingStrategyaccessTokenRequest.validations.expectedValue.value의 값에 템플릿을 사용하는 경우PEBBLE_V1을(를) 사용합니다.accessTokenRequest.validations.expectedValue.value필드의 값이 상수인 경우NONE을(를) 사용합니다.
accessTokenRequest.validations.expectedValue.value템플릿 규칙 templating-conventions
인증 사용자 지정에 따라 이전 섹션에 표시된 대로 인증 응답의 데이터 필드에 액세스해야 할 수 있습니다. 이렇게 하려면 Adobe에서 사용하는 페블 템플릿 언어를 숙지하고 아래 템플릿 규칙을 참조하여 OAuth 2 구현을 사용자 지정하십시오.
{{ 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
다음 단계 next-steps
이 문서를 읽으면 이제 Adobe Experience Platform에서 지원하는 OAuth 2 인증 패턴에 대해 이해하고 OAuth 2 인증 지원을 통해 대상을 구성하는 방법을 알 수 있습니다. 다음으로, Destination SDK을 사용하여 OAuth 2 지원 대상을 설정할 수 있습니다. 다음 단계를 위해 Destination SDK을 사용하여 대상을 구성을 읽어 보세요.