Salesforce 데이터 수집과 커넥터 이관

Salesforce 커넥터는 접근 가능한 표준 객체와 사용자 정의 객체를 Foundry 데이터셋으로 수집합니다. 원천 탐색과 대량 가져오기는 일반 제공 기능입니다. 스키마는 Salesforce에서 동적으로 가져오며 탐색 화면에서 객체 목록과 수집 결과의 미리보기를 확인할 수 있습니다.

기존 소스에는 이전 버전의 커넥터가 남아 있을 수 있습니다. 현재 버전의 설정과 Legacy YAML 설정은 다르므로 마지막의 이관 절차에서 버전을 먼저 확인합니다.

자료형과 API 선택

기본 수집은 Salesforce Bulk API를 사용합니다. 2,000행을 초과하는 데이터 작업에는 Bulk API를 권장합니다. JDBC 속성 UseBulkAPI=false를 지정하면 SOAP API를 사용할 수 있습니다. 두 방식에는 각각 Salesforce의 API 사용량 제한이 적용되므로 원천 조직의 허용량과 작업량을 함께 고려합니다.

소스와 통합 사용자 준비

Data Connection에서 + New Source를 선택한 뒤 Salesforce 소스를 선택합니다. 새 연결에는 Foundry 워커를 사용하고, 기존 에이전트 워커 구성은 Legacy 방식의 제약을 확인합니다.

통합 사용자는 Salesforce API와 수집하거나 수정할 객체에 대한 접근 권한을 가져야 합니다. JWT 인증의 사용자 승인 단계에서도 같은 사용자로 로그인할 수 있어야 합니다.

Salesforce는 Spring '26부터 새 connected app 생성을 제한합니다. 기존 connected app은 계속 사용할 수 있으며 새 통합에는 external client app을 사용합니다. 조직에 external client app이 활성화되어 있어야 하고, 설정 담당자에게 앱 생성과 정책 수정 권한이 필요합니다.

JWT bearer 인증

JWT bearer 흐름은 개인 키로 서명한 토큰으로 통합 사용자를 인증합니다. 요청마다 사용자 로그인을 반복하지 않습니다. X.509 공개 인증서는 Salesforce 앱에 등록하고 대응하는 개인 키는 Foundry 커넥터가 사용할 인증서 저장소에 보관합니다.

인증서 생성

다음 명령은 OpenSSL을 설치한 관리용 컴퓨터에서 2048비트 RSA 개인 키와 X.509 인증서를 만듭니다. 생성 파일 이름은 작업용 예시이며 보호된 디렉터리에서 실행합니다. 첫 개인 키 파일은 암호화되지 않으므로 접근을 제한해야 합니다.

umask 077
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out key.pem -nocrypt
openssl req -new -x509 -key key.pem -out cert.pem -days 3650
openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.pfx
openssl base64 -in certificate.pfx -out certificate.pfx.base64

인증서 생성 시 subject 항목을 입력하고 PFX 내보내기에서는 저장소 비밀번호를 설정합니다. 3650은 예제의 인증서 유효기간을 일 단위로 지정한 값입니다. 조직의 인증서 수명 정책에 맞게 조정합니다. PFX와 Base64 값에는 개인 키가 들어 있으므로 안전한 위치에 보관합니다.

macOS에서 Base64 값을 클립보드로 복사해야 할 때에는 다음 명령을 사용할 수 있습니다. 복사한 값도 비밀 정보로 취급합니다.

openssl base64 -in certificate.pfx | pbcopy

External client app 설정

1. Salesforce Setup의 External Client App Manager에서 앱을 만들거나 기존 앱의 설정을 엽니다.
2. OAuth를 활성화하고 JWT bearer 흐름을 설정합니다. JWT Bearer Flow의 인증서 항목에 공개 인증서 cert.pem을 올립니다. 개인 키 파일은 업로드하지 않습니다.
3. Callback URL을 https://localhost:12345로 설정합니다. JWT 커넥터 자체는 callback을 보내지 않지만 앱 설정과 아래의 일회성 브라우저 승인에서 이 값을 사용합니다.
4. OAuth 범위 api를 부여합니다. 일회성 브라우저 승인 방식을 선택할 때에는 offline_access와 refresh_token도 부여합니다.
5. 앱의 consumer key를 확인하여 안전하게 보관합니다. 숨겨진 키를 표시할 때 이메일 인증 코드를 요구할 수 있습니다.

Consumer key는 서명한 JWT에 들어가며 Foundry 설정의 Consumer key에 입력합니다. 이 커넥터의 JWT 인증에는 함께 발급되는 consumer secret을 입력하지 않습니다.

Issue JSON Web Token (JWT)-based access tokens for named users는 Salesforce가 반환하는 액세스 토큰의 형식을 바꾸는 별도 설정입니다. JWT bearer 인증을 구성한다는 이유만으로 이 항목을 켤 필요는 없습니다.

새 앱이 바로 사용 가능해지지 않을 수 있습니다. 생성 직후 인증이 실패하면 구성을 바꾸기 전에 최대 30분 동안 반영을 기다립니다.

통합 사용자 승인

사전 승인을 권장합니다. 앱의 OAuth 정책에서 Permitted Users를 Admin approved users are pre-authorized로 설정하고, 통합 사용자에게 할당된 Profile 또는 Permission Set을 통해 해당 앱 접근을 허용합니다. 정책 값만 변경하고 사용자 권한 부여를 생략하면 승인되지 않습니다.

브라우저 승인 흐름이 허용된 앱에서는 통합 사용자로 한 번 로그인하여 승인하는 방식도 사용할 수 있습니다. 이때 앱에 api, offline_access, refresh_token 범위와 앞의 callback URL이 설정되어 있어야 합니다.

다음 Python 코드는 승인 URL만 구성합니다. SALESFORCE_ORIGIN과 CONSUMER_KEY는 가상 예시값이므로 실제 Salesforce 인스턴스와 앱의 consumer key로 수정합니다. 요청을 자동 전송하거나 권한을 승인하지 않습니다.

from secrets import token_urlsafe
from urllib.parse import urlencode

SALESFORCE_ORIGIN = "https://example.my.salesforce.com"
CONSUMER_KEY = "example-consumer-key"
CALLBACK_URL = "https://localhost:12345"

query = urlencode({
    "client_id": CONSUMER_KEY,
    "redirect_uri": CALLBACK_URL,
    "scope": "api offline_access refresh_token",
    "response_type": "code",
    "response_mode": "query",
    "nonce": token_urlsafe(24),
})
print(SALESFORCE_ORIGIN + "/services/oauth2/authorize?" + query)

생성한 URL을 브라우저에서 열고 통합 사용자로 로그인하여 범위를 승인합니다. 로그인된 계정이 개인 계정이 아닌지 확인합니다. 다른 사용자를 승인하면 그 사용자의 권한으로 인해 연결이 실패할 수 있습니다.

마지막에는 실제 서버를 두지 않은 https://localhost:12345로 이동하여 연결 오류나 찾을 수 없다는 화면이 나타날 수 있습니다. 이 callback 오류 자체를 커넥터의 성공 증거로 삼지 말고 통합 사용자 승인과 Foundry 연결 상태를 확인합니다. 커넥터는 이 흐름의 authorization code를 교환하지 않고 이후 JWT로 인증합니다.

Foundry의 JWT 설정

사용자명과 비밀번호 인증

이 방식은 커넥터에 서비스 사용자의 사용자명과 비밀번호를 입력합니다. 서비스 사용자에게 필요한 API 및 객체 접근 권한을 준비합니다.

앱 설정에서는 JWT 구성과 달리 인증서가 필요하지 않습니다. OAuth 범위는 api 대신 Full access (full)을 사용하고 Permitted Users는 All users may self-authorize로 설정합니다. full 범위는 활성 사용자가 접근할 수 있는 데이터 범위에서 동작합니다. 새 커넥터의 이 인증 입력에는 consumer key나 consumer secret을 요구하지 않습니다.

Salesforce 사용자의 Login History에 Failed: API security token required가 나타나면 비밀번호 끝에 해당 사용자의 보안 토큰을 붙여 입력합니다. 신뢰되지 않는 네트워크에서 로그인할 때 요구되는 토큰입니다. Salesforce에서는 기존 보안 토큰을 화면에서 조회할 수 없습니다. 통합 사용자로 로그인한 뒤 My Settings > Personal > Reset My Security Token에서 재설정합니다.

네트워크와 일반 설정

직접 연결에는 다음 DNS 외부 통신 정책을 적용합니다.

운영 로그인과 Sandbox 로그인 중 사용하는 쪽을 허용하고 인스턴스 호스트도 허용합니다. TLS 검사나 자체 서명 인증서 때문에 표준 신뢰 체인으로 검증되지 않으면 소스 또는 기존 에이전트에 올바른 서버 인증서를 추가합니다.

동기화, 증분과 행 필터

원천 탐색에서 객체를 선택하여 동기화를 만들고 필요한 고급 설정을 편집합니다.

증분 동기화는 증분 열의 값이 이전에 관측한 최댓값보다 크거나 같은 행을 가져옵니다. 경계값을 다시 읽으므로 출력에 중복 행이 생깁니다. 증분 파이프라인에는 항상 중복 제거 단계를 포함합니다.

행 필터는 조건 트리로 구성합니다. ALL은 하위 조건이 모두 참이어야 하며 ANY는 하위 조건 중 하나 이상이 참이면 됩니다. 조건마다 열을 선택하고 그 자료형에 맞는 연산자와 비교값을 지정합니다. 변경한 구성은 Save로 저장해야 동기화에 적용됩니다.

Legacy 커넥터에서 이관

Connection settings > Connection details에서 Custom YAML에 type: salesforce가 있으면 Legacy 커넥터입니다. 버그 수정 이상의 Palantir 지원을 받으려면 현재 버전으로 이관합니다.

새 Salesforce 소스를 만들고 이전 소스의 auth-method 또는 authentication-method에 맞게 인증을 설정합니다.

새 소스의 원천 탐색에서 기존에 수집하던 객체의 동기화를 다시 만듭니다. 여러 객체를 한 번에 선택하여 새 데이터셋을 만들 수 있습니다. 같은 API 버전을 사용하면 Legacy와 새 커넥터의 스키마는 같습니다.

하위 파이프라인과 애플리케이션의 입력을 새 동기화 데이터셋으로 옮깁니다. Data Lineage로 이전 데이터셋의 소비자를 찾고, 더 이상 필요로 하는 소비자가 없음을 확인한 뒤 이전 데이터셋, 동기화와 연결을 제거합니다.