OAuth 2.0 신뢰를 사용하여 연결된 앱 구성
Tableau Server 관리자는 하나 이상의 EAS(외부 권한 부여 서버)를 등록하여 Tableau Server와 EAS 간의 신뢰 관계를 OAuth 2.0 표준 프로토콜을 사용하여 설정할 수 있습니다.
중요:
- 이 항목의 일부 절차에는 타사 소프트웨어 및 서비스를 사용한 구성이 필요합니다. Tableau는 Tableau Server에서 EAS 기능을 사용하도록 설정하는 절차를 확인하기 위해 최선을 다했습니다. 그러나 타사 소프트웨어 및 서비스에서 변경되었거나 조직에 따라 다를 수 있습니다. 문제가 발생하는 경우 신뢰할 수 있는 구성 세부 정보 및 지원은 타사 설명서를 참조하십시오.
- EAS를 통한 내장 기능을 사용하려면 HTTP 트래픽에 SSL을 사용하도록 Tableau Server를 구성해야 합니다.
- 세션 토큰이 유효하려면 외부 응용 프로그램의 시계와 외부 응용 프로그램을 호스트하는 서버의 시계가 UTC(협정 세계시)로 설정되어야 합니다. 두 클록이 다른 표준 시간대를 사용하는 경우 연결된 앱을 신뢰할 수 없게 됩니다.
OAuth 2.0 신뢰와 Tableau 연결된 앱이 작동하는 방식
Tableau Server 사이트와 외부 응용 프로그램 간의 신뢰 관계는 JWT(JSON 웹 토큰) 표준의 인증 토큰을 통해 설정되고 검증됩니다.
내장된 Tableau 콘텐츠를 외부 응용 프로그램에 로드하면 인증 코드 흐름인 OAuth 흐름이 사용됩니다. 사용자가 IdP에 로그인하면 자동으로 Tableau Server에 로그인됩니다. 아래에 설명된 단계에 따라 EAS를Tableau Server 에 등록합니다.
연결된 앱의 주요 구성 요소
연결된 앱의 다음 구성 요소는 외부 응용 프로그램의 JWT와 함께 작동하여 사용자를 인증하고 내장된 콘텐츠를 표시합니다.
EAS(외부 권한 부여 서버): 일반적으로 사용자와 외부 응용 프로그램 간의 인터페이스 역할을 하는 서버로, 주로 IdP가 이 역할을 수행합니다. 서버는 보호된 Tableau 콘텐츠에 대한 사용자 액세스를 인증하고 권한을 부여합니다.
발급자 URL: EAS 인스턴스를 고유하게 식별하는 URL입니다.
연결된 앱 워크플로우
내장 워크플로우
아래의 다이어그램은 EAS(외부 권한 부여 서버), 외부 응용 프로그램(웹 서버 및 웹 페이지), Tableau 연결 앱 간의 인증이 작동하는 방식을 보여 줍니다.
사용자가 웹 페이지를 방문: 사용자가 웹 페이지의 내장된 콘텐츠를 방문하면 웹 페이지가 외부 응용 프로그램으로 GET 요청을 보냅니다.
외부 응용 프로그램이 요청을 EAS로 리디렉션: 외부 응용 프로그램은 EAS(외부 권한 부여 서버)로 리디렉션되는 웹 페이지로 응답합니다.
EAS로 사용자 인증: EAS를 통해 사용자를 인증하고 권한을 부여합니다.
EAS는 인증 코드로 웹 페이지에 응답: EAS는 인증 코드로 페이지에 응답하고 웹 페이지로 다시 리디렉션합니다.
EAS가 인증 코드를 JWT로 변환: 웹 페이지가 EAS를 호출하여 인증 코드를 JWT로 변환하고, 웹 페이지는 이를 내장된 콘텐츠의 URL에 삽입합니다.
웹 페이지가 Tableau의 콘텐츠를 요청: 웹 페이지가 iFrame을 로드하고 Tableau에 GET 요청을 보냅니다.
Tableau가 토큰 검증: Tableau는 서명이 있는 URL의 JWT 유효성을 검사하고 콘텐츠로 응답하며 JWT에 정의된 내장 범위를 준수합니다.
연결된 앱 만들기
1단계: 시작하기 전에
EAS를 Tableau Server 에 등록하려면 EAS가 이미 구성되어 있어야 합니다. 또한 EAS에서 아래 표에 나열된 등록된 클레임 및 헤더가 포함된 유효한 JWT(JSON Web Token)를 전송해야 합니다.
| 클레임 | 이름 | 설명 또는 필요한 값 |
"kid" | Key ID | 필수입니다(헤더에 필요). ID 공급자의 고유 키 식별자입니다. |
"iss" | Issuer | 필수입니다(헤더 또는 클레임에 필요). 신뢰할 수 있는 연결된 앱 및 서명 키를 식별하는 고유한 발급자 URI입니다. |
"alg" | Algorithm | 필수입니다(헤더에 필요). JWT 서명 알고리즘입니다. 지원되는 알고리즘 이름은 javadoc.io 설명서의 JWSAlgorithm 클래스(영문)(링크가 새 창에서 열림) 페이지에 나열되어 있습니다. |
"sub" | Subject | 인증된 Tableau Server 사용자의 사용자 이름입니다. |
"aud" | Audience | 값은 " |
"exp" | Expiration Time | |
"jti" | JWT ID | JWT ID 클레임은 JWT의 고유 식별자를 제공하며 대/소문자를 구분합니다. |
"scp" | Scope | 내장 워크플로우의 경우 지원되는 값은 다음과 같습니다. " 참고:
REST API 권한 부여 워크플로우의 경우 JWT 권한 부여를 지원하는 REST API 메서드를 참조하십시오. 인증을 위해 REST API를 사용하는 메타데이터 API 워크플로우의 경우 유일하게 지원되는 범위는 |
https://tableau.com/groups | 동적 그룹 멤버십 | 내장 워크플로우만 해당합니다. 값은 Tableau Server에 있는 하나 이상의 그룹 이름과 일치해야 합니다. 자세한 내용은 아래의 동적 그룹 멤버십(내장 워크플로만 해당) 섹션을 참조하십시오. |
참고: 위의 JWT 클레임은 IETF(Internet Engineering Task Force) 조직에서 배포한 설명서의 등록된 클레임 이름(영문)(링크가 새 창에서 열림) 섹션에 문서화되어 있습니다.
2단계: Tableau Server에 EAS 등록
Tableau Server에 EAS를 등록하면 EAS와 Tableau Server 간의 신뢰 관계가 설정됩니다. 즉, 사용자가 외부 응용 프로그램에 내장된 Tableau 콘텐츠에 액세스하면 IdP를 통한 인증을 위해 리디렉션됩니다. EAS에서 인증 토큰이 생성되고 확인을 위해 Tableau Server로 전달됩니다. 신뢰 관계가 확인되면 내장된 콘텐츠에 대한 액세스 권한이 사용자에게 부여됩니다.
참고: 일부 EAS는 Tableau 콘텐츠에 대한 응용 프로그램 액세스에 대해 사용자의 승인을 구하는 동의 대화 상자를 표시하는 옵션을 지원합니다. 최상의 사용자 경험을 보장하려면 외부 응용 프로그램의 요청에 사용자 대신 자동으로 동의하도록 EAS를 구성하는 것이 좋습니다.
사이트 수준 EAS 정보
Tableau Server 2024.2부터 사이트 수준 EAS를 구성할 수 있습니다. 사이트 수준에서 EAS를 등록하려면 TSM(Tableau Server Manager)에서 연결된 앱을 사용하도록 설정해야 합니다.
서버 전체 EAS를 등록하는 방법에는 TSM 웹 UI를 사용하거나 TSM CLI를 사용하는 두 가지 방법이 있습니다.
EAS를 등록한 후 설정된 신뢰 관계는 Tableau Server의 모든 사이트에 적용됩니다.
옵션 1: TSM 웹 UI 사용
Tableau Server 관리자로 TSM(Tableau 서비스 관리자) 웹 UI에 로그인합니다. 자세한 내용은 Tableau 서비스 관리자 웹 UI에 로그인을 참조하십시오.
다음 작업 중 하나를 수행합니다.
Tableau Server 2024.2 이상에서는 사용자 ID 및 액세스 페이지 > 연결된 앱 탭으로 이동합니다.
Tableau Server 2023.3 이하에서는 사용자 ID 및 액세스 페이지 > 권한 부여 서버 탭으로 이동합니다.
- 다음 작업 중 하나를 수행합니다.
Tableau Server 2024.2 이상:
연결된 앱 사용 확인란을 선택합니다.
두 번째 라디오 버튼인 연결된 앱 허용(사이트 수준에서 구성) 및 서버 전체 OAuth 2.0 신뢰(그 아래 구성)를 선택합니다.
발급자 URL 텍스트 상자에 EAS의 발급자 URL을 붙여 넣습니다.
보류 중인 변경 내용 저장 단추를 클릭합니다.
Tableau Server 2023.3 이하:
내장된 콘텐츠에 OAuth 액세스 사용 확인란을 선택합니다.
발급자 URL 텍스트 상자에 EAS의 발급자 URL을 붙여 넣습니다.
보류 중인 변경 내용 저장 단추를 클릭합니다.
- 작업을 마치면 다음을 수행합니다.
페이지의 오른쪽 위에서 보류 중인 변경 내용 단추를 클릭합니다.
페이지의 오른쪽 아래에서 변경 내용 적용 후 다시 시작 단추를 클릭하여 Tableau Server를 중지했다가 다시 시작합니다.
옵션 2: TSM CLI 사용
- 클러스터의 초기 노드(TSM이 설치된 노드)에서 관리자로 명령 프롬프트를 엽니다.
다음 명령을 실행합니다.
tsm configuration set -k vizportal.oauth.external_authorization.enabled -v true tsm configuration set -k vizportal.oauth.external_authorization_server.issuer -v "<issuer_url_of_EAS>" tsm restart
Tableau Server 2024.2부터 사이트에 하나 이상의 EAS를 등록할 수 있습니다. 사이트 수준에서 EAS를 등록하면 설정된 신뢰 관계가 해당 사이트에만 적용됩니다.
참고: 사이트 수준 EAS를 구성하려면 먼저 TSM에서 연결된 앱을 사용하도록 설정해야 합니다.
1단계: 연결된 앱 사용
Tableau Server 관리자로 TSM(Tableau 서비스 관리자) 웹 UI에 로그인합니다. 자세한 내용은 Tableau 서비스 관리자 웹 UI에 로그인을 참조하십시오.
사용자 ID 및 액세스 페이지 > 연결된 앱 탭으로 이동합니다.
연결된 앱 사용 확인란을 선택합니다.
다음 작업 중 하나를 수행합니다.
첫 번째 라디오 버튼 연결된 앱 허용(사이트 수준에서 구성)을 선택하고 사이트 수준에서만 EAS 등록을 사용하도록 설정합니다.
(기본값) 두 번째 라디오 버튼인 연결된 앱 허용(사이트 수준에서 구성) 및 서버 전체 OAuth 2.0 신뢰(그 아래 구성)를 선택하여 사이트 수준과 서버 전체에서 EAS 등록을 사용하도록 설정합니다. 이 옵션을 선택하는 경우 사이트 수준에서 지정된 발급자 URL이 서버 전체 발급자 URL과 달라야 합니다.
보류 중인 변경 내용 저장 단추를 클릭합니다.
- 작업을 마치면 다음을 수행합니다.
페이지의 오른쪽 위에서 보류 중인 변경 내용 단추를 클릭합니다.
페이지의 오른쪽 아래에서 변경 내용 적용 후 다시 시작 단추를 클릭하여 Tableau Server를 중지했다가 다시 시작합니다.
2단계: EAS 등록
Tableau Server 관리자로 Tableau Server에 로그인합니다.
왼쪽 패널에서 설정 > 연결된 앱을 선택합니다.
새 연결된 앱 단추 드롭다운 화살표를 클릭하고 OAuth 2.0 신뢰를 선택합니다.
- 연결된 앱 만들기 대화 상자에서 다음을 수행합니다.
이름 텍스트 상자에 연결된 앱의 이름을 입력합니다.
발급자 URL 텍스트 상자에 EAS의 발급자 URL을 붙여 넣습니다.
연결된 앱 사용을 선택합니다. 연결된 앱은 보안을 위해 앱을 만들 때 기본적으로 사용되지 않도록 설정됩니다.
작업을 마치면 만들기 단추를 클릭합니다.
연결된 앱이 만들어지면 연결된 앱의 사이트 ID를 복사합니다. 사이트 ID는 위의 1단계에서 설명한 JWT의 “aud”(Audience) 클레임에 사용됩니다.
3단계: 다음 단계
내장 워크플로우의 경우
EAS를 사용하도록 Tableau Server 를 구성한 후에는 내장 코드를 외부 응용 프로그램에 추가해야 합니다. 위의 1단계에 설명된 대로 EAS를 통해 생성된 유효한 JWT를 외부 응용 프로그램에서 호출하는 웹 구성 요소에 포함해야 합니다.
Tableau 콘텐츠 내장에 대한 자세한 내용은 다음을 참조하십시오.
- 메트릭을 포함하려면 Tableau 도움말에서 웹 페이지에 메트릭 내장(링크가 새 창에서 열림) 항목을 참조하십시오. (
- Tableau Embedding API v3(링크가 새 창에서 열림)를 사용하여 Tableau 뷰와 메트릭을 내장합니다.
참고: 사용자가 내장된 콘텐츠에 액세스할 때 성공적으로 인증하려면, 타사 쿠키를 허용하도록 브라우저를 구성해야 합니다.
도메인 허용 목록을 사용하여 콘텐츠를 내장할 수 있는 위치 제어
기본적으로 내장에 대한 unrestrictedEmbedding 사이트 설정이 true로 설정되면 무제한 내장이 허용됩니다. 또는 false로 설정하고 allowList 매개 변수를 사용하여 외부 응용 프로그램의 Tableau 콘텐츠를 내장할 수 있는 도메인을 지정할 수 있습니다.
자세한 내용은 다음 중 하나 또는 둘 모두를 참조하십시오.
- 사이트의 내장 설정 업데이트(영문)(링크가 새 창에서 열림) - Tableau REST API 도움말
- 내장 관련 Tableau 사이트 설정(영문)(링크가 새 창에서 열림) - Tableau Embedding API v3 도움말
REST API 권한 부여 워크플로우의 경우
JWT를 구성한 후에는 유효한 JWT를 REST API 로그인 요청에 추가해야 액세스 권한이 부여됩니다. 자세한 내용은 연결된 앱의 액세스 범위를 참조하십시오.
메타데이터 API 워크플로우의 경우
JWT를 구성한 후에는 유효한 JWT를 REST API 로그인 요청에 추가해야 합니다. 자세한 내용은 연결된 앱의 액세스 범위를 참조하십시오.
연결된 앱 관리
동적 그룹 멤버십(내장 워크플로만 해당)
구성된 경우 사용자 인증 중에 외부 응용 프로그램은 사용자를 어설션할 그룹((https://tableau.com/groups)과 그룹 이름(예: "Group1" 및 "Group2")이라는 두 개의 사용자 지정 그룹 멤버십 클레임이 포함된 JWT를 전송합니다. Tableau는 JWT의 유효성을 검사한 다음 그룹 및 콘텐츠(사용 권한이 해당 그룹에 따라 달라짐)에 대한 액세스를 허용합니다.
알려진 문제(내장 워크플로우만 해당)
연결된 앱을 사용하는 경우 몇 가지 알려진 문제가 있으며, 이는 향후 릴리스에서 해결될 예정입니다.
툴바 기능: 내장된 콘텐츠에 툴바 매개 변수가 정의되어 있으면 일부 툴바 기능이 작동하지 않습니다. 이 문제를 해결하려면 아래 예와 같이 툴바 매개 변수를 숨기는 것이 좋습니다.
<tableau-viz id='tab-viz' src='https://<your_server>/t/<your_site>/...' toolbar='hidden'> </tableau-viz>
게시된 데이터 원본: 데이터베이스 자격 증명이 사용자에게 확인으로 설정된 경우 게시된 데이터 원본이 표시되지 않습니다. 이 문제를 해결하려면 가능한 경우 데이터 원본 소유자가 대신 데이터베이스 자격 증명을 내장하는 것이 좋습니다.
- 여러 사이트에 내장된 뷰: Tableau Server 2023.1 이하 버전에서 동일한 브라우저에서 다른 사이트의 뷰 간에 전환하면 1008: 연결된 앱의 암호를 가져올 수 없습니다 오류가 발생합니다. 이 문제를 해결하려면 Tableau Server 2023.3 이상으로 업그레이드하십시오.
문제 해결
내장된 콘텐츠가 외부 응용 프로그램에 표시되지 않거나 Tableau REST API 권한 부여가 실패하면 브라우저의 개발자 도구를 사용하여 Tableau Server 에서 사용되는 EAS 기능과 관련되었을 수 있는 오류 코드를 검사하고 식별할 수 있습니다.
아래의 표를 참조하여 오류 코드 설명 및 가능한 해결 방법을 검토하십시오.
| 오류 코드 | 요약 | 설명 | 잠재적 해결 방법 또는 설명 |
| 5 | SYSTEM_USER_NOT_FOUND | Tableau 사용자를 찾을 수 없음 | sub'(Subject) 클레임 값이 인증된 Tableau Server의 "username"인지 확인합니다. 이 값은 대/소문자를 구분합니다. |
| 16 | LOGIN_FAILED | 로그인 실패 | 이 오류는 일반적으로 JWT의 다음 클레임 문제 중 하나로 인해 발생합니다.
|
| 67 | FEATURE_NOT_ENABLED | 주문형 액세스가 지원되지 않음 | 주문형 액세스는 라이선스가 부여된 Tableau Cloud 사이트를 통해서만 사용할 수 있습니다. |
| 10081 | COULD_NOT_RETRIEVE_IDP_METADATA | EAS 메타데이터 끝점이 없음 | 이 문제를 해결하려면 EAS가 올바르게 구성되어 있고 올바른 발급자가 호출되는지 확인하십시오. |
| 10082 | AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED | 발급자가 없음 | 이 문제를 해결하려면 올바른 발급자가 호출되는지 확인하십시오. |
| 10083 | BAD_JWT | JWT 헤더에 문제가 있음 | JWT 헤더에서 'kid'(Secret ID) 또는 'clientId'(Issuer) 클레임이 누락되었습니다. 이 문제를 해결하려면 해당 정보가 포함되어 있는지 확인하십시오. |
| 10084 | JWT_PARSE_ERROR | JWT에 문제가 있음 | 이 문제를 해결하려면 다음을 확인합니다.
|
| 10085 | COULD_NOT_FETCH_JWT_KEYS | JWT에서 키를 찾을 수 없음 | 암호를 찾을 수 없습니다. 이 문제를 해결하려면 올바른 발급자가 호출되는지 확인하십시오. |
| 10087 | BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN | JWT 서명 알고리즘에 문제가 있음 | 이 문제를 해결하려면 서명 알고리즘을 제거하면 됩니다. |
| 10088 | RSA_KEY_SIZE_INVALID | JWT 서명 요구 사항에 문제가 있음 | 이 문제를 해결하려면 EAS 또는 IdP에서 JWT가 2048의 RSA 키 크기로 서명되고 있는지 확인합니다. |
| 10091 | JTI_ALREADY_USED | 고유한 JWT가 필요함 | JWT가 이미 인증 프로세스에서 사용되었습니다. 이 문제를 해결하려면 EAS 또는 IdP에서 새 JWT를 생성해야 합니다. |
| 10092 | NOT_IN_DOMAIN_ALLOW_LIST | 내장된 콘텐츠의 도메인이 지정되지 않음 | 이 문제를 해결하려면 unrestrictedEmbedding 설정이 true로 설정되거나, 사이트의 내장 설정 업데이트(영문)(링크가 새 창에서 열림) 방법을 사용하여 Tableau REST API에서 Tableau 콘텐츠를 내장할 도메인을 domainAllowlist 매개 변수에 포함해야 합니다. |
| 10094 | MISSING_REQUIRED_JTI | JWT ID 누락 | 이 문제를 해결하려면 'jti'(JWT ID)가 JWT에 포함되어 있는지 확인합니다. |
| 10096 | JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD | exp'(Expiration Time)가 기본 최대 유효 기간을 초과합니다. 이 문제를 해결하려면 유효한 JWT에 필요한 등록 클레임(링크가 새 창에서 열림)을 검토하고 올바른 값이 사용되는지 확인하십시오. 최대 유효 기간을 변경하려면 vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes 명령을 사용하면 됩니다. | |
| 10097 | SCOPES_MALFORMED | Scope 클레임 관련 문제 | 이 오류는 'scp'(Scope) 클레임이 JWT에서 누락되었거나 목록 유형으로 전달되지 않은 경우 발생할 수 있습니다. 이 문제를 해결하려면 'scp'가 JWT에 포함되었고 목록 유형으로 전달되었는지 확인하십시오. JWT 관련 문제 해결 도움말은 auth0 사이트에서 디버거(영문)(링크가 새 창에서 열림)를 참조하십시오. |
| 10098 | JWT_UNSIGNED_OR_ENCRYPTED | JWT가 서명되지 않았거나 암호화되어 있음 | Tableau는 서명되지 않았거나 암호화된 JWT를 지원하지 않습니다. |
| 10099 | SCOPES_MISSING_IN_JWT | Scope 클레임 누락 | JWT에서 필수 'scp'(Scope) 클레임이 누락되었습니다. 이 문제를 해결하려면 'scp'가 JWT에 포함되어 있는지 확인합니다. JWT 관련 문제 해결 도움말은 auth0 사이트에서 디버거(영문)(링크가 새 창에서 열림)를 참조하십시오. |
| 10100 | JTI_PERSISTENCE_FAILED | 예기치 않은 JWT ID 오류 | 'jti'(JWT ID)에 예기치 않은 오류가 있습니다. 이 문제를 해결하려면 새 'jti'를 사용하여 새 JWT를 생성해야 합니다. |
| 10103 | JWT_MAX_SIZE_EXCEEDED | JWT가 최대 크기를 초과함 | 이 오류는 JWT 크기가 8000바이트를 초과하는 경우에 발생할 수 있습니다. 이 문제를 해결하려면 필요한 클레임만 Tableau Server에 전달되는지 확인하십시오. |