SAML SSO 설정

이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

이 문서에서는 Braze 계정에 SAML SSO를 활성화하는 방법과 SAML 트레이스를 얻는 방법을 안내합니다.

요구 사항

설정 시 로그온 URL과 어설션 소비자 서비스(ACS) URL을 제공해야 합니다.

요구 사항	세부 사항
어설션 소비자 서비스(ACS) URL	`https://<SUBDOMAIN>.braze.com/auth/saml/callback` 유럽 연합 도메인의 경우 ACS URL은 `https://<SUBDOMAIN>.braze.eu/auth/saml/callback`입니다. 일부 IdP에서는 이를 응답 URL, 로그온 URL, 오디언스 URL 또는 오디언스 URI라고도 합니다.
엔티티 ID	기본값은 `braze_dashboard`입니다. IdP에서 회사별 엔티티 ID를 요구하는 경우, 보안 설정에서 커스텀 엔티티 ID를 활성화하고 `braze_dashboard_<companyID>`를 사용하세요.
RelayState API 키	설정 > 설정 및 테스트 > API 및 식별자로 이동하여 API 키 탭을 열고 `sso.saml.login` 권한이 있는 API 키를 생성하세요. 생성된 API 키를 IdP 내에서 `RelayState` 파라미터로 입력하세요. 자세한 단계는 RelayState 설정을 참조하세요.

SAML SSO 설정하기

1단계: ID 공급자 구성하기

다음 정보를 사용하여 ID 공급자(IdP)에서 Braze를 서비스 공급자(SP)로 설정합니다. 또한 SAML 속성 매핑을 설정합니다.

중요

Okta를 ID 공급자로 사용할 계획이라면 Okta 사이트에서 사전 구축된 통합을 사용해야 합니다.

SAML 속성	필수 여부	허용되는 SAML 속성
`email`	필수	`email` `mail` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email`
`first_name`	선택 사항	`first_name` `firstname` `firstName` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/first_name`
`last_name`	선택 사항	`last_name` `lastname` `lastName` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/last_name`

참고

Braze는 SAML 어설션에서 email만 필수로 요구합니다.

2단계: Braze 구성하기

ID 공급자에서 Braze 설정을 완료하면 ID 공급자가 Braze 계정에 입력할 대상 URL과 x.509 인증서를 제공합니다.

계정 매니저가 계정에 대해 SAML SSO를 활성화한 후 설정 > 회사 설정 > 관리자 설정 > 보안 설정으로 이동하여 SAML SSO 섹션을 ON으로 토글합니다.

같은 페이지에서 다음 정보를 입력합니다:

요구 사항	세부 정보
SAML 이름	로그인 화면에 버튼 텍스트로 표시됩니다. 일반적으로 “Okta”와 같은 ID 공급자의 이름입니다.
대상 URL	IdP 내에서 Braze를 설정한 후 제공됩니다. 일부 IdP에서는 이를 SSO URL 또는 SAML 2.0 엔드포인트라고 합니다.
인증서	ID 공급자가 제공하는 `x.509` 인증서입니다.

커스텀 엔티티 ID

기본적으로 Braze는 braze_dashboard를 엔티티 ID(일부 IdP에서는 Audience 또는 Audience URI라고도 함)로 사용합니다. IdP에서 회사별 엔티티 ID가 필요한 경우:

보안 설정에서 커스텀 엔티티 ID를 켭니다.
생성된 엔티티 ID(braze_dashboard_<companyID>)를 복사합니다.
해당 값을 IdP의 엔티티 ID, Audience 또는 Audience URI 필드에 붙여넣습니다.
로그인을 테스트하기 전에 Braze와 IdP 모두에서 변경 사항을 저장합니다.

중요

엔티티 ID가 Braze와 IdP 양쪽에서 일치하지 않으면 사용자가 로그인할 수 없습니다. 커스텀 엔티티 ID는 ID 공급자에서 추가 구성이 필요합니다.

대시보드에 추가할 때 x.509 인증서가 다음 형식을 따르는지 확인합니다:

-----BEGIN CERTIFICATE-----
<certificate>
-----END CERTIFICATE-----

토글이 선택된 SAML SSO 설정.

3단계: Braze에 로그인하기

보안 설정을 저장하고 로그아웃합니다. 그런 다음 ID 공급자를 사용하여 다시 로그인합니다.

커스텀 엔터티 ID 사용하기

기본적으로, 모든 Braze 대시보드는 공유 엔터티 ID braze_dashboard를 사용합니다. 커스텀 엔터티 ID를 사용하면 대시보드에 고유 식별자가 부여되어, ID 공급자가 로그인 요청이 해당 특정 대시보드를 대상으로 한 것인지 확인할 수 있습니다. 이는 동일한 ID 공급자에서 여러 Braze 회사에 걸쳐 SAML SSO를 설정하는 경우에 유용합니다.

커스텀 엔터티 ID 사용은 선택 사항입니다. 활성화하지 않으면 대시보드는 계속 braze_dashboard를 사용합니다.

경고

사전 구축된 Braze Okta 마켓플레이스 앱은 공유 엔터티 ID braze_dashboard를 강제하며 커스텀 엔터티 ID와 호환되지 않습니다. Braze Okta 마켓플레이스 앱으로 이미 SAML SSO를 설정한 상태에서 커스텀 SAML 앱을 통해 Okta의 엔터티 ID 필드를 업데이트하지 않고 커스텀 엔터티 ID를 켜면, 로그인이 중단되고 사용자가 대시보드에 접근하지 못하게 될 수 있습니다. Okta에서 커스텀 엔터티 ID를 사용하려면 커스텀 SAML 앱을 대신 설정하세요.

1단계: 커스텀 엔터티 ID 켜기

설정 > 관리자 설정 > 보안 설정으로 이동하여 SAML SSO 섹션을 엽니다. 커스텀 엔터티 ID 토글을 켭니다. Braze가 braze_dashboard_<COMPANY_ID> 형식으로 대시보드의 고유 엔터티 ID를 생성합니다. 커스텀 엔터티 ID 옵션이 보이지 않으면 Braze 계정 매니저에게 문의하세요.

2단계: ID 공급자 업데이트하기

생성된 엔터티 ID를 복사하여 ID 공급자의 Braze 애플리케이션에 있는 엔터티 ID 필드에 붙여넣습니다. 공급자에 따라 이 필드는 Entity ID, Audience 또는 Audience URI로 표시될 수 있습니다.

중요

엔터티 ID는 Braze와 ID 공급자 양쪽에서 일치해야 합니다. 양쪽이 동일한 값을 사용할 때까지 사용자는 SAML SSO로 로그인할 수 없습니다. 사용자가 잠기는 것을 방지하려면 이 페이지를 저장하기 전에 ID 공급자를 먼저 업데이트하세요.

3단계: 저장 및 테스트하기

보안 설정을 저장하고, 로그아웃한 다음, ID 공급자를 통해 다시 로그인하여 커스텀 엔터티 ID로 로그인이 정상적으로 작동하는지 확인합니다.

RelayState 설정하기

Braze에서 설정 > 설정 및 테스트 > API 및 식별자로 이동합니다.
API 키 탭에서 API 키 만들기 버튼을 선택합니다.
API 키 이름 필드에 키의 이름을 입력합니다.
권한 아래의 SSO 드롭다운을 확장하고 sso.saml.login을 선택합니다.
API 키 만들기를 선택합니다.
API 키 탭에서 생성한 API 키 옆의 식별자를 복사합니다.
RelayState API 키를 IdP의 RelayState에 붙여넣습니다(IdP에 따라 “Relay State” 또는 “Default Relay State”로 표시될 수도 있습니다).

일부 ID 공급자는 IdP 시작 로그인을 지원하며, 이 경우 사용자는 Braze 로그인 페이지가 아닌 IdP 포털에서 시작합니다. IdP 시작 로그인에는 유효한 RelayState API 키와 올바른 ACS URL 구성이 필요합니다. 공급자별 설정 가이드:

참고

Microsoft Entra SSO IdP 시작 로그인의 경우 Sign-On URL 필드를 비워 두어야 합니다. 자세한 내용은 Microsoft Entra SSO를 참조하세요.

SSO 동작

SSO를 사용하기로 선택한 멤버는 더 이상 비밀번호를 사용할 수 없습니다. 비밀번호를 계속 사용하는 사용자는 다음 설정에 의해 제한되지 않는 한 계속 사용할 수 있습니다.

제한

조직의 구성원이 Google SSO 또는 SAML SSO로만 로그인하도록 제한할 수 있습니다. 제한을 설정하려면 설정 > 회사 설정 > 관리자 설정 > 보안 설정으로 이동하여 Google SSO 전용 로그인 적용 또는 커스텀 SAML SSO 전용 로그인 적용을 선택합니다.

최소 비밀번호 길이 8자, 비밀번호 재사용 횟수 3회로 설정된 '인증 규칙' 섹션의 예시. 비밀번호는 180일 후에 만료되며, 사용자는 1,440분 동안 비활성 상태이면 로그아웃됩니다.

제한을 설정하면 회사의 Braze 사용자는 이전에 비밀번호로 로그인한 적이 있더라도 더 이상 비밀번호로 로그인할 수 없습니다.

중요

SSO가 적용된 후에는 SSO 인증에 실패할 경우 대체 로그인 옵션이 없습니다. SSO 적용을 활성화하기 전에 SSO 구성이 올바른지, 모든 인증서가 최신 상태이고 갱신되었는지, 보안 설정이 적절히 관리되고 있는지 확인하여 로그인 문제를 방지하세요.

SAML 트레이스 가져오기

SSO와 관련된 로그인 문제가 발생하면 SAML 트레이스를 가져와서 SAML 요청에 전송되는 내용을 확인하여 SSO 연결 문제를 해결할 수 있습니다.

사전 요구 사항

SAML 트레이스를 실행하려면 SAML 트레이서가 필요합니다. 브라우저에 따라 다음 두 가지 옵션을 사용할 수 있습니다:

1단계: SAML 트레이서 열기

브라우저 탐색 바에서 SAML 트레이서를 선택합니다. Pause가 선택되어 있지 않은지 확인하세요. 이 옵션이 선택되면 SAML 트레이서가 SAML 요청에서 전송되는 내용을 캡처하지 못합니다. SAML 트레이서가 열리면 트레이스가 채워지는 것을 확인할 수 있습니다.

Google Chrome용 SAML 트레이서.

2단계: SSO를 사용하여 Braze에 로그인

Braze 대시보드로 이동하여 SSO를 사용하여 로그인을 시도합니다. 오류가 발생하면 SAML 트레이서를 열고 다시 시도합니다. https://dashboard-XX.braze.com/auth/saml/callback과 같은 URL이 포함된 행과 주황색 SAML 태그가 표시되면 SAML 트레이스가 성공적으로 수집된 것입니다.

3단계: 내보내기 후 Braze에 전송

Export를 선택합니다. Select cookie-filter profile에서 None을 선택합니다. 그런 다음 Export를 선택합니다. 이렇게 하면 추가 문제 해결을 위해 Braze 지원팀에 보낼 수 있는 JSON 파일이 생성됩니다.

"SAML 트레이스 내보내기 환경설정" 메뉴에서 "None" 옵션이 선택된 화면.

문제 해결

사용자의 이메일 주소가 올바르게 설정되어 있나요?

ERROR_CODE_SSO_INVALID_EMAIL 오류가 발생하는 경우, 사용자의 이메일 주소가 유효하지 않습니다. SAML 트레이스에서 saml2:Attribute Name="email" 필드가 사용자가 로그인에 사용하는 이메일 주소와 일치하는지 확인하세요. Microsoft Entra ID(이전의 Azure 액티브 디렉토리)를 사용하는 경우, 속성 매핑은 email = user.userprincipalname입니다.

이메일 주소는 대소문자를 구분하며, ID 공급자(Okta, OneLogin, Microsoft Entra ID 등)에서 구성한 주소를 포함하여 Braze에 설정된 주소와 정확히 일치해야 합니다.

사용자의 이메일 주소에 문제가 있음을 나타내는 기타 오류는 다음과 같습니다:

ERROR_CODE_SSO_EMAIL_DOES_NOT_EXIST: 사용자의 이메일 주소가 대시보드에 존재하지 않습니다.
ERROR_CODE_SSO_SESSION_SIGN_IN_EMAIL_MISSING: 사용자의 이메일 주소가 비어 있거나 잘못 구성되어 있습니다.
ERROR_CODE_SSO_SESSION_SIGN_IN_EMAIL_MISMATCH 또는 ERROR_CODE_SSO_SIGN_IN_EMAIL_MISMATCH: 사용자의 이메일 주소가 SSO 설정에 사용된 주소와 일치하지 않습니다.

유효한 SAML 인증서(x.509 인증서)를 가지고 있나요?

이 SAML 유효성 검사 도구를 사용하여 SAML 인증서를 검증할 수 있습니다. 만료된 SAML 인증서도 유효하지 않은 SAML 인증서라는 점에 유의하세요.

올바른 SAML 인증서(x.509 인증서)를 업로드했나요?

SAML 트레이스의 ds:X509Certificate 섹션에 있는 인증서가 Braze에 업로드한 인증서와 일치하는지 확인하세요. 여기에는 -----BEGIN CERTIFICATE----- 헤더와 -----END CERTIFICATE----- 푸터가 포함되지 않습니다.

SAML 인증서(x.509 인증서)를 잘못 입력하거나 형식이 올바르지 않나요?

Braze 대시보드에 제출한 인증서에 공백이나 불필요한 문자가 없는지 확인하세요.

Braze에 인증서를 입력할 때는 PEM(Privacy Enhanced Mail) 인코딩으로 올바르게 포맷되어야 합니다(-----BEGIN CERTIFICATE----- 헤더와 -----END CERTIFICATE----- 푸터 포함).

다음은 올바르게 포맷된 인증서 예시입니다:

사용자의 세션 토큰이 유효한가요?

영향을 받는 사용자에게 브라우저의 캐시와 쿠키를 지우도록 한 다음, SAML SSO로 다시 로그인을 시도하세요.

RelayState를 설정했나요?

ERROR_CODE_SSO_INVALID_RELAY_STATE 오류가 발생하는 경우, RelayState가 잘못 구성되었거나 존재하지 않을 수 있습니다. 아직 설정하지 않았다면, IdP 관리 시스템에서 RelayState를 설정해야 합니다. 자세한 단계는 RelayState 설정하기를 참조하세요.

이 문제는 RelayState가 올바르게 구성되지 않은 경우 발생할 수 있습니다. 설정 > 설정 및 테스트 > API 및 식별자에서 IdP 로그인용 API 키를 생성하고, 해당 API 키를 IdP에서 RelayState 파라미터로 설정했는지 확인하세요. RelayState는 로그인하려는 회사 계정을 식별합니다. 단계별 안내는 RelayState 설정하기를 참조하세요.

여전히 로그인할 수 없는 경우, 가능하면 SAML 트레이스를 함께 Braze 지원팀에 문의하세요. 트레이스 캡처에 대한 도움말은 SAML 트레이스 얻기를 참조하세요.

사용자가 Okta SSO와 Braze 대시보드 사이를 반복적으로 순환하여 로그인할 수 없는 경우, Okta로 이동하여 SSO URL 대상을 Braze 인스턴스(예: https://dashboard-07.braze.com)로 설정해야 합니다.

다른 IdP를 사용하는 경우, 회사에서 올바른 SAML 또는 x.509 인증서를 Braze에 업로드했는지 확인하세요.

수동 통합을 사용하고 있나요?

회사에서 IdP의 앱 스토어에서 Braze 앱을 다운로드하지 않은 경우, 사전 구축된 통합을 다운로드해야 합니다. 예를 들어, Okta가 IdP인 경우, 통합 페이지에서 Braze 앱을 다운로드하면 됩니다.

Google SSO

회사에서 커스텀 SAML 대신 Google SSO를 사용하는 경우, Braze 계정 매니저에게 워크스페이스에 대한 Google SSO 활성화를 요청하세요. 활성화된 후 설정 > 회사 설정 > 관리자 설정 > 보안 설정으로 이동하여 Google SSO 전용 로그인 적용을 선택하면 모든 회사 사용자에게 Google 인증을 요구할 수 있습니다.

Google SSO 적용이 활성화되면 사용자는 Google 인증으로 로그인해야 하며 더 이상 Braze 비밀번호를 사용할 수 없습니다. 각 사용자는 Braze 대시보드 이메일 주소와 일치하는 Google 계정으로 로그인해야 합니다. 로그인 시 다른 Google 계정을 선택하면 Braze가 인증 시도를 거부합니다.

일부 사용자가 Google SSO로 로그인할 수 없는 경우 다음을 확인하세요:

사용자의 Google 계정 이메일이 Braze 대시보드 이메일 주소와 정확히 일치하는지 확인합니다.
사용자가 회사 이메일 주소에 대한 Google 계정에 접근할 수 있는지 확인합니다.
사용자가 Braze에서 정지되지 않았는지 확인합니다(설정 > 회사 사용자).

다음 단계

SAML SSO를 설정한 후 다음을 수행할 수 있습니다:

New Stuff!

서비스 공급자(SP) 시작 로그인