스트리밍 SDK 커넥터에 대한 인증 구성
스트리밍 SDK으로 빌드된 모든 커넥터에 인증이 필요합니다. 커넥터를 제출하거나 릴리스하기 전에 지원되는 인증 메커니즘 하나을 구성하십시오.
커넥터의 통합 모델과 일치하는 메커니즘을 구성합니다.
시작하기에 앞서
다음을 수행해야 합니다.
- 스트리밍 SDK 커넥터 구현이 완료되었습니다.
- 스트리밍 수집 API 엔드포인트 스테이징 또는 테스트.
- Adobe 조직 및 샌드박스를 테스트합니다.
- 테스트 이벤트 페이로드.
- 자격 증명을 안전하게 저장 및 순환하기 위한 계획입니다.
- 비밀을 노출하지 않고 요청 및 응답 세부 정보를 캡처하는 방법입니다.
추가 OAuth 요구 사항
OAuth 2.0을 사용하는 경우 다음 사항이 있는지 확인하십시오.
- Adobe Developer Console 액세스.
- 커넥터에 필요한 API 또는 제품 프로필입니다.
- 선택한 자격 증명의 클라이언트 ID 및 클라이언트 암호입니다.
- 필요한 범위입니다.
- 커넥터에 필요한 OAuth 흐름 및 토큰 종단점입니다.
적절한 Adobe 자격 증명 유형 및 구현에 대한 자세한 내용은 다음을 참조하십시오.
추가 HMAC 요구 사항
HMAC를 사용하는 경우 다음 사항이 있는지 확인하십시오.
- 웹후크 또는 커넥터에 대해 구성된 공유 암호.
- 보안을 저장하기 위한 안전한 위치입니다.
- HMAC-SHA256 서명을 계산할 수 있는 코드입니다.
- Adobe으로 전송될 정확한 직렬화된 이벤트 본문입니다.
- 유효하고 유효하지 않으며 누락되고 회전된 비밀에 대한 테스트 절차입니다.
OAuth 2.0 구성
1. Adobe 자격 증명 만들기 또는 선택
먼저 커넥터에 필요한 Adobe Developer Console 자격 증명을 만들거나 선택해야 합니다.
Configure:
- 자격 증명 유형.
- 필수 Adobe API 또는 제품 프로필.
- 필요한 범위입니다.
- 리디렉션 또는 동의 설정(선택한 OAuth 흐름에 적용되는 경우).
커넥터의 통합 모델에서 지원하지 않는 자격 증명 유형을 사용하지 마십시오.
2. OAuth 구성을 안전하게 저장
다음 값을 안전하게 저장:
- 클라이언트 ID.
- 클라이언트 암호.
- 필수 범위.
- 토큰 엔드포인트.
- 모든 커넥터별 테넌트, 조직 또는 환경 값.
소스 제어에 클라이언트 암호를 커밋하거나 로그, 오류 메시지, 스크린샷 또는 테스트 결과에 포함시키지 마십시오.
3. 커넥터에 OAuth 구성 추가
커넥터의 자체 구성 또는 서비스에 OAuth 구성 값을 저장합니다. 스트리밍 SDK은 커넥터가 스트리밍 수집 API를 호출하는 방법을 지배하는 것이지 Experience Platform이 소스에 연결하는 방법을 지배하는 것이 아니기 때문에 이 인증 단계에 대한 연결 사양 필드를 정의하지 않습니다.
커넥터의 구성에는 다음이 포함되어야 합니다.
- 인증 유형.
- 클라이언트 ID.
- 클라이언트 암호.
- 범위.
- 토큰 엔드포인트.
- 자격 증명 유형에 필요한 추가 테넌트 또는 조직 값입니다.
4. 액세스 토큰 가져오기
자격 증명 유형에 대해 문서화된 OAuth 플로우를 구현합니다.
커넥터는 다음 작업을 수행해야 합니다.
- 구성된 OAuth 자격 증명을 사용하여 인증합니다.
- 스트리밍 SDK 통합에 필요한 범위를 요청합니다.
- 액세스 토큰을 메모리 또는 다른 보안 위치에 저장합니다.
- 토큰 수명에 따라 토큰을 새로 고치거나 다시 얻습니다.
- 토큰 또는 클라이언트 암호를 기록하지 마십시오.
5. 요청에 액세스 토큰 추가
커넥터가 보낸 요청에 대한 전달자 토큰으로 액세스 토큰을 포함합니다.
Authorization: Bearer {ACCESS_TOKEN}
모든 요청에 HTTPS를 사용합니다.
6. 토큰 오류 처리
커넥터는 다음을 포함한 인증 오류를 감지하고 처리해야 합니다.
- 액세스 토큰 누락.
- 만료된 액세스 토큰입니다.
- 잘못된 클라이언트 자격 증명입니다.
- 범위가 부족합니다.
- 자격 증명이 해지되었거나 비활성화되었습니다.
토큰이 만료되면 문서화된 OAuth 플로우를 사용하여 새 토큰을 얻은 다음 작업을 다시 시도할 수 있는 안전한 경우에만 다시 시도하십시오.
HMAC 기반 인증 구성
1. 공유 암호 구성
커넥터에 필요한 공유 암호를 만들거나 가져와 커넥터 또는 웹후크 설정에서 구성합니다.
암호는 다음과 같아야 합니다.
- 안전하게 저장됨.
- 런타임 시 서명 코드에 사용할 수 있습니다.
- 소스 제어 및 로그에서 제외됩니다.
- 보안 정책에 따라 회전되었습니다.
2. 이벤트 직렬화
서명을 계산하기 전에 이벤트를 직렬화합니다.
이 서명은 커넥터가 요청 본문에서 보내는 것과 동일한 직렬화된 메시지에서 계산되어야 합니다.
serializedMessage = serialize(event)
이벤트의 한 표현에서 서명을 계산하고 다른 표현을 보내지 마십시오. 공백, 속성 순서, 이스케이프, 인코딩 또는 줄 끝을 변경하면 서명 유효성 검사가 실패할 수 있습니다.
3. HMAC-SHA256 서명 계산
다음을 사용하여 HMAC-SHA256 값 계산:
- 키: 구성된 공유 암호입니다.
- 메시지: 직렬화된 요청 본문입니다.
signature = HMAC-SHA256(secret, serializedMessage)
4. HMAC 헤더 추가
요청에 계산된 서명을 x-hmac-sha256 헤더로 추가합니다.
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
예를 들어 헤더는 다음과 유사한 값으로 확인됩니다.
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
헤더 값은 Adobe에 전송된 정확한 요청 본문에 대한 HMAC-SHA256 계산을 나타내야 합니다.
5. 요청 보내기
HTTPS를 통해 서명된 요청을 스트리밍 수집 API 끝점으로 보냅니다.
스트리밍 수집 API는 이벤트를 처리하기 전에 서명을 확인합니다. 서명이 없거나 잘못된 요청은 거부됩니다.
6. 암호를 안전하게 회전합니다.
암호를 회전할 때 다음 순서를 따르십시오.
- 자격 증명 관리 시스템에 새 암호를 만드십시오.
- 겹치는 비밀이 지원되는 경우 새 비밀을 배포하는 동안 기존 비밀을 활성 상태로 유지합니다.
- 새 암호로 커넥터 구성을 업데이트합니다.
- 구성을 배포하거나 저장합니다.
- 테스트 요청을 보내고 인증이 성공했는지 확인합니다.
- 인증 실패를 모니터링한 다음 모든 커넥터 인스턴스가 새 암호를 사용한 후 이전 암호를 취소합니다.
커넥터 확인
성공 및 실패 인증 시나리오를 모두 사용하여 커넥터를 테스트합니다.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| 테스트 | 예상 결과 |
| 유효한 액세스 토큰이 있는 요청 | 이벤트가 수락되고 처리됩니다. |
| 액세스 토큰 없이 요청 | 요청이 거부되었습니다. |
| 만료된 액세스 토큰으로 요청 | 요청이 거부되거나 커넥터가 새 토큰을 가져와 다시 시도 정책에 따라 다시 시도합니다. |
| 잘못된 액세스 토큰이 있는 요청 | 요청이 거부되었습니다. |
| 범위가 부족한 요청 | 요청이 거부되었습니다. |
| 자격 증명 회전 후 요청 | 커넥터가 새 자격 증명을 가져와서 사용합니다. |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| 테스트 | 예상 결과 |
| 유효한 서명 및 현재 비밀이 포함된 요청 | 이벤트가 수락되고 처리됩니다. |
x-hmac-sha256 없이 요청 |
요청이 거부되었습니다. |
| 잘못된 서명이 있는 요청 | 요청이 거부되었습니다. |
| 잘못된 암호로 서명된 요청 | 요청이 거부되었습니다. |
| 서명 생성 후 요청 본문이 수정됨 | 요청이 거부되었습니다. |
| 순환 중 유효한 이전 암호로 서명된 요청 | 그 결과는 문서화된 비밀 회전 동작을 따릅니다. |
| 제거된 암호로 서명된 요청 | 요청이 거부되었습니다. |
각 테스트에 대해 다음을 기록합니다.
- 요청 메서드 및 끝점입니다.
- 비밀 및 토큰이 편집된 요청 헤더입니다.
- 직렬화된 요청 본문입니다.
- 인증 메커니즘이 사용되었습니다.
- 응답 상태 및 본문.
- 타임스탬프 및 상관 관계 또는 추적 식별자(사용 가능한 경우).
- 이벤트가 성공적으로 수집되었는지 여부.
문제 해결
OAuth 인증 실패
다음을 확인하십시오.
- 올바른 Adobe 조직 및 환경에 대해 액세스 토큰이 생성되었습니다.
- 클라이언트 ID 및 클라이언트 암호가 구성된 자격 증명에 속합니다.
- 요청한 범위가 올바릅니다.
- 액세스 토큰이 만료되지 않았습니다.
- 토큰은 Authorization: Bearer 스키마를 사용하여 전송됩니다.
- 커넥터가 올바른 토큰 끝점을 사용하고 있습니다.
- 자격 증명은 필요한 API 또는 제품 프로필에 액세스할 수 있습니다.
HMAC 인증 실패
다음을 확인하십시오.
x-hmac-sha256헤더가 있습니다.- 헤더 이름과 값의 맞춤법이 올바른지 확인하십시오.
- 커넥터가 올바른 암호를 사용하고 있습니다.
- 서명은 HMAC-SHA256으로 계산됩니다.
- 서명은 정확히 직렬화된 요청 본문을 통해 계산됩니다.
- 서명이 계산된 후에는 요청 본문의 형식이 다시 지정되지 않습니다.
- 필요한 서명 인코딩과 문자 대/소문자가 올바릅니다.
- 커넥터가 회전 중에 올바른 현재 또는 이전 암호를 사용하고 있습니다.
- 이 암호는 런타임에 사용할 수 있으며 잘리거나 변경되지 않았습니다.
제출 요구 사항
커넥터를 제출하거나 릴리스하기 전에 다음을 확인하십시오.
- 커넥터는 스트리밍 수집 API에 대한 모든 요청에 대해 OAuth 2.0 또는 HMAC 기반 인증을 사용합니다.
- 커넥터 확인에서 시나리오를 테스트하고 결과를 기록했습니다.
- 커넥터가 인증되지 않은 요청과 잘못 인증된 요청을 거부합니다.
- 비밀과 토큰은 소스 제어, 로그, 오류 메시지 또는 스크린샷에 커밋되지 않습니다.
다음 단계
인증이 구성 및 확인된 상태에서 계속 소스 테스트 및 제출을 계속하십시오. 소스에 대한 인증 요구 사항을 문서화하는 방법에 대해 알아보려면 소스 문서화(SDK 스트리밍)을 참조하십시오.