단일 로그인 관리

2026-11-17

단일 로그인(SSO)을 통해 사용자는 엔터프라이즈 계정으로 DJI FlightHub 2에 로그인할 수 있습니다. 엔터프라이즈 ID 공급자(IdP)가 사용자를 인증하면 FlightHub 2는 반환된 ID 정보와 역할 매핑을 사용하여 로그인 세션을 생성하고 해당 권한을 부여합니다. 엔터프라이즈 계정의 비밀번호는 엔터프라이즈 ID 시스템에서 관리합니다.

이 기능은 퍼블릭 클라우드 엔터프라이즈 패키지와 온프레미스 버전에서 사용할 수 있습니다. 이 가이드는 조직 관리자와 엔터프라이즈 ID 시스템 관리자를 대상으로 하며, ID 소스 설정, 권한 관리, 테스트 및 활성화, 로컬 계정 로그인 관리를 설명합니다.



개요

ID 소스 및 로그인 절차

Realm은 FlightHub 2에서 독립적으로 설정되는 SSO ID 소스입니다. 각 Realm은 하나의 프로토콜을 사용하며 이메일 도메인을 기준으로 로그인 요청을 매칭합니다. 엔터프라이즈 IdP의 해당 애플리케이션과 FlightHub 2의 Realm에서 사용하는 프로토콜, 애플리케이션 자격 증명, 콜백 URL 및 역할 출력 설정은 서로 일치해야 합니다.

사용자가 FlightHub 2에서 SSO 로그인을 시작하면 시스템은 입력한 이메일 주소의 도메인을 기준으로 활성화된 ID 소스를 선택하고, 인증을 위해 사용자를 엔터프라이즈 IdP로 리디렉션합니다. 이후 FlightHub 2는 반환된 ID 정보를 검증하고 사용자의 관리 역할을 매칭합니다. 엔터프라이즈 로그인 세션이 만료되었거나 IdP가 재인증을 요구하는 경우 사용자는 다시 인증해야 합니다.

이메일 도메인은 ID 소스를 선택하는 데만 사용됩니다. 고유 사용자 식별자가 아니며 권한을 직접 부여하지 않습니다. 프로젝트 접근 권한은 SSO 로그인 후 별도로 설정해야 합니다.


프로토콜 선택

FlightHub 2는 OIDC, SAML 2.0 및 OAuth2를 지원합니다.

비교 항목OIDCSAML 2.0OAuth2
ID 정보 소스ID TokenSAML AssertionUser URL에서 반환하는 사용자 정보 JSON
설정 방법Discovery URLIdP Metadata URL 또는 Metadata XML 파일권한 부여, Token 및 사용자 정보 엔드포인트를 수동으로 설정
역할 조회 설정Role PathRole AttributeRole Path (UserInfo)
고유 사용자 식별자issuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
적합한 사용 사례OpenID Connect를 지원하는 엔터프라이즈 ID 시스템이미 SAML을 사용하는 엔터프라이즈 ID 시스템OAuth2 권한 부여 및 사용자 정보 API를 제공하는 시스템

유의 사항:

  • 엔터프라이즈 IdP가 여러 프로토콜을 지원하는 경우 OIDC를 권장합니다. 기업에서 이미 다른 애플리케이션을 연동하는 데 SAML을 사용하고 있다면 SAML을 계속 사용할 수 있습니다.
  • OAuth2는 권한 부여 프로토콜입니다. OAuth2를 선택하기 전에 사용자 정보 API에서 변경되지 않는 사용자 ID, 계정 이름 및 역할 정보를 제공하는 필드가 무엇인지 IdP 관리자와 확인하십시오.
  • OIDC와 OAuth2는 모두 PKCE 검증을 적용한 권한 부여 코드 흐름을 사용합니다. ID 정보를 조회하는 방식은 서로 다릅니다:
    • OIDC: ID Token을 검증하여 사용자의 ID를 확인합니다.
    • OAuth2: Access Token으로 User URL을 호출하여 사용자 정보를 조회하고 파싱합니다. OIDC의 ID Token, Discovery 또는 JWKS ID 검증 메커니즘은 사용하지 않습니다.
  • SAML 2.0은 FlightHub 2에서 시작하는 로그인(SP-Initiated)만 지원하며, 엔터프라이즈 IdP 애플리케이션 포털에서 직접 시작하는 로그인은 지원하지 않습니다.


설정 준비

온프레미스 버전에서 SSO를 사용하려면 먼저 HTTPS를 활성화해야 합니다. SSO ID 소스를 설정하기 전에 배포 환경에서 HTTPS를 설정하고 HTTPS로 FlightHub 2에 접근할 수 있는지 확인하십시오.

조직 관리자로 조직의 SSO 로그인 설정을 열고 Realm 생성 버튼을 클릭한 후 프로토콜을 선택하십시오.

SSO 로그인 설정 및 Realm 생성 버튼

설정 전에 엔터프라이즈 IdP 관리자와 함께 다음 정보를 준비하십시오:

  • 프로토콜 및 해당 애플리케이션의 Client ID, Client Secret 또는 Metadata.
  • ID 소스 매칭에 사용할 이메일 도메인 및 테스트 로그인에 사용할 엔터프라이즈 계정.
  • 엔터프라이즈 ID 정보의 역할 필드와 역할 값 및 할당할 FlightHub 2 관리 역할.
  • IdP의 HTTPS 엔드포인트와 유효한 인증서. FlightHub 2 백엔드가 해당 엔드포인트에 접근하고 인증서를 검증할 수 있는지 확인하십시오.

설정 규칙:

  • 하나의 조직에서 동시에 활성화할 수 있는 Realm은 최대 8개입니다. 활성화되지 않은 설정은 초안으로 저장하거나 비활성화 상태로 유지할 수 있습니다.
  • Realm 이름은 조직 내에서 고유해야 합니다. 표시 이름은 관리 화면에서 Realm을 구분하는 데 사용됩니다.
  • Realm 생성 시 Login routing email에는 완전한 형식의 유효한 이메일 주소 또는 도메인만 입력할 수 있습니다. 예: user@example.com. 시스템은 로그인 라우팅을 위해 도메인을 저장합니다. 조직 내에서 동일한 도메인을 서로 다른 Realm에 할당할 수 없습니다.
  • FlightHub 2 접근 URL 및 SSO 엔드포인트는 HTTPS를 사용해야 합니다. 시스템에서 생성한 콜백 정보를 제공된 그대로 IdP에 등록하십시오. 콜백 URL 대신 설정 페이지 URL을 사용하지 마십시오.


ID 소스 설정

각 Realm 설정 페이지에는 기본 설정, 권한 관리, 테스트 및 활성화, 고급 설정의 네 가지 탭이 있습니다. 먼저 기본 설정을 완료하고 초안을 저장한 다음, 역할 매핑을 설정하고 테스트를 실행한 후 Realm을 활성화하십시오.

OIDC

기본 설정

필드설정 안내
Realm name / Realm display nameID 소스를 구분할 이름을 입력하십시오. 예: Enterprise_OIDC
Login routing email완전한 형식의 이메일 주소를 입력하십시오. 해당 도메인이 ID 소스 선택에 사용됩니다
Discovery URLIdP에서 제공한 완전한 HTTPS Discovery URL을 입력하십시오
Client IDIdP에 등록된 애플리케이션 식별자를 입력하십시오
Client Secret해당 애플리케이션의 시크릿을 입력하십시오. 저장 후에는 평문 값이 표시되지 않습니다
Callback URL초안 저장 후 생성됩니다. 제공된 그대로 IdP에 유효한 리디렉션 URI로 등록하십시오
Web Origin URL시스템에서 생성합니다. IdP의 요구 사항에 따라 Web Origins에 등록하십시오

초안을 저장한 후 배포 환경의 실제 콜백 정보를 복사하여 IdP 애플리케이션 설정을 완료하십시오. 생성 양식의 플레이스홀더 URL은 연동에 사용할 수 없습니다. 일반 로그인과 테스트 로그인은 서로 다른 콜백 URL을 사용할 수 있습니다. 배포 환경에 맞게 각 URL을 등록하십시오.

권한 관리에서 IdP가 반환하는 역할 배열에 맞게 Role Path를 설정하십시오. 예: roles 또는 claims.roles. 역할 매핑 규칙은 아래의 권한 관리 섹션을 참조하십시오.

고급 설정

  • 고유 ID 식별자: issuer + sub로 고정됩니다. 이메일 주소로 대체할 수 없습니다.
  • 사용자 표시 이름 Claim: 기본값은 name입니다. 표시 및 검색에만 사용되며, ID 매칭이나 권한 할당에는 사용되지 않습니다.
  • Discovery 새로 고침: 최초 조회 후에는 기본적으로 자동 새로 고침이 비활성화됩니다. 지금 새로 고침을 사용하여 설정을 다시 조회하십시오. 새로 고침에 실패하면 가장 최근의 유효한 설정이 유지됩니다. 자동 새로 고침 및 간격 설정은 배포 환경에서 제공되는 옵션에 따라 달라집니다.
  • 고급 프로토콜 옵션: Scope를 설정하십시오. 최소한 openid를 포함해야 합니다. Authorization Endpoint, Token Endpoint 및 JWKS URI를 수동으로 재정의할 수 있습니다.
  • 수동 재정의: 재정의된 필드는 Discovery 새로 고침으로 덮어쓰이지 않습니다. 자동 값 복원을 클릭하여 조회된 값으로 복원하십시오. 수동 재정의는 설정 저장 시 수행되는 Discovery 조회 및 검증을 대체하지 않습니다.

SAML 2.0

기본 설정

  1. Realm 이름, 표시 이름 및 로그인 라우팅 이메일을 입력하십시오.
  2. IdP Metadata URL 또는 XML 업로드를 선택하여 엔터프라이즈 IdP Metadata를 가져오십시오. 시스템은 IdP Entity ID, SSO URL, 서명 인증서 및 Binding을 파싱합니다.
  3. 초안을 저장하여 생성된 SP Metadata URL 및 ACS URL을 확인하거나 SP Metadata XML을 다운로드하십시오.
  4. FlightHub 2 SP Metadata를 IdP 관리자에게 제공하여 해당 SAML 애플리케이션을 설정하십시오. 실제로 생성된 SP Metadata에서 SP Entity ID를 확인하십시오. Metadata URL과 같다고 가정하지 마십시오.
  5. 권한 관리에서 역할 속성 이름을 입력하고 관리 역할 매핑을 설정하십시오.

URL로 가져오는 경우 FlightHub 2 백엔드가 HTTPS로 Metadata URL에 접근할 수 있어야 합니다. 파일을 업로드하는 경우 엔터프라이즈 IdP에서 내보낸 실제 Metadata XML을 사용하십시오.

Role Attribute를 SAML Assertion의 <Attribute Name="...">에 있는 이름과 정확히 일치하도록 설정하십시오. 기본값은 roles이며 대소문자를 구분합니다. 여러 역할은 하나의 문자열로 합치지 않고 별도의 AttributeValue 요소로 반환해야 합니다. 예:

<Attribute Name="roles">
  <AttributeValue>fh2-member-org</AttributeValue>
</Attribute>

고급 설정

  • 고유 ID 식별자: IdP Entity ID + persistent NameID로 고정됩니다. IdP에서 persistent NameID를 사용하도록 설정하십시오.
  • 사용자 표시 이름 Attribute: 기본값은 displayName입니다. IdP는 이 속성을 출력해야 합니다.
  • Metadata 업데이트: 최초 조회 후에는 기본적으로 자동 새로 고침이 비활성화됩니다. URL로 가져오는 경우 페이지에서 제공하는 새로 고침 옵션을 사용하십시오. XML을 업로드하는 경우 업데이트된 파일을 다시 업로드하십시오. 자동 새로 고침 및 간격 설정은 배포 환경에서 제공되는 옵션에 따라 달라집니다.
  • 고급 프로토콜 옵션: IdP Entity ID, SSO URL, Binding 및 서명 인증서를 수동으로 재정의하거나 자동 값으로 복원하십시오. Metadata 새로 고침은 수동으로 재정의한 필드를 덮어쓰지 않습니다.
  • 인증서 관리: 가능한 경우 Metadata를 통해 서명 인증서를 가져오고 업데이트하십시오. 인증서 지문은 인증서를 검증하는 데 사용되며 X.509 인증서 내용을 대체할 수 없습니다.

OAuth2

기본 설정

OAuth2는 Discovery를 사용하지 않습니다. IdP API 문서에 따라 엔드포인트 및 사용자 정보 필드 경로를 설정하십시오.

필드설정 안내
Realm name / Realm display nameID 소스 이름을 입력하십시오. 예: Enterprise_OAuth2
Login routing email완전한 형식의 이메일 주소를 입력하십시오. 해당 도메인이 ID 소스 선택에 사용됩니다
Authorization URLIdP에서 제공한 사용자 권한 부여 URL
Token URLIdP에서 제공한 권한 부여 코드 교환 URL
User URLAccess Token으로 사용자 ID 및 역할 JSON을 조회하는 API URL
Client ID / Client Secret해당 IdP 애플리케이션의 식별자 및 시크릿
USER_ID_KEY사용자 정보 응답에서 변경되지 않는 사용자 ID의 필드 경로. 예: id 또는 data.id
USER_ACCOUNT_KEY사용자 정보 응답에서 계정 이름의 필드 경로. 예: username 또는 data.username
ScopesIdP 사용자 정보 API의 권한 요구 사항에 따라 설정하십시오
Callback URL초안 저장 후 생성됩니다. 제공된 그대로 IdP에 등록하십시오

권한 관리에서 Role Path (UserInfo)는 User URL 응답의 역할 문자열 배열을 가리켜야 합니다. 예: roles 또는 data.roles. FlightHub 2는 JWT Access Token이나 별도의 권한 API에서 OAuth2 역할을 조회하지 않습니다.

예를 들어 User URL이 다음 구조를 반환하는 경우 USER_ID_KEY를 id, USER_ACCOUNT_KEY를 username, Role Path를 roles로 설정하십시오:

{
  "id": "user-001",
  "username": "sso-user",
  "roles": ["fh2-member-org"]
}

이 필드는 예시일 뿐입니다. 실제 필드 경로는 IdP 응답과 일치해야 합니다. Scopes는 역할을 결정하지 않으며, openid를 반드시 포함해야 한다는 공통 요구 사항도 없습니다. IdP API 요구 사항을 따르십시오. USER_ID_KEY가 sub이거나 Scopes에 openid가 포함되어 있어도 이 Realm은 OAuth2 사용자 정보 API를 통해 ID와 역할을 파싱합니다.

고급 설정

고급 설정에는 USER_ID_KEY와 연결된 변경되지 않는 ID 식별 규칙 및 사용자 표시 이름 필드 경로가 표시됩니다. 표시 정보에는 USER_ACCOUNT_KEY를 사용하므로 두 번째 필드 경로는 필요하지 않습니다.

OAuth2는 Discovery 또는 Metadata 가져오기나 새로 고침을 제공하지 않습니다. 엔드포인트가 변경되면 수동으로 업데이트하십시오. 새 Realm은 기존의 USE_REDIRECT_URL 또는 SUPER_ACCOUNT 호환성 옵션을 제공하지 않습니다. 마이그레이션된 설정의 권한 호환성 동작은 새 Realm에 적용되지 않습니다.



권한 관리

역할 조회 및 관리 역할 매핑

권한 관리에서 역할 조회 위치를 설정하고 IdP가 반환하는 외부 Role 값을 FlightHub 2 관리 역할에 매핑하십시오.

역할 조회 설정 및 관리 역할 매핑

프로토콜설정요구 사항
OIDCRole PathID 정보의 역할 문자열 배열을 가리킵니다. 예: roles
SAML 2.0Role AttributeAssertion의 Attribute Name과 일치해야 합니다. 예: roles. 여러 역할에는 별도의 AttributeValue 요소를 사용하십시오
OAuth2Role Path (UserInfo)User URL 응답의 역할 문자열 배열을 가리킵니다. 예: data.roles

관리 역할과 기본 매핑은 아래와 같습니다. 각 관리 역할에 하나의 외부 Role 값을 설정하십시오.

FlightHub 2 관리 역할기본 외부 Role 값우선순위
조직 관리자fh2-admin-org1 (가장 높음)
기기 유지 관리 담당자fh2-admin-device2
멤버fh2-member-org3
  • 새로 생성된 SSO Realm을 통해 로그인하려면 사용자가 하나 이상의 관리 역할과 매칭되어야 합니다.
  • 여러 관리 역할이 매칭되면 우선순위가 가장 높은 역할이 사용됩니다. 인식되지 않는 Role 값은 무시됩니다.
  • 외부 SSO 사용자를 슈퍼 관리자에 매핑할 수 없습니다.
  • 현재 권한 부여는 Roles를 기준으로 하며 Groups, Security Groups 또는 기타 속성을 직접 기준으로 하지 않습니다. 기업에서 그룹으로 사용자를 관리하는 경우 그룹 소속 정보를 합의된 역할 목록으로 변환하도록 IdP를 설정하십시오.

프로젝트 권한

SSO 관리 역할과 프로젝트 권한은 서로 독립적입니다. 로그인에 성공한 후에도 관리자는 프로젝트 멤버 관리에서 SSO 사용자를 추가하고 프로젝트 역할을 할당해야 하며, 해당 Realm의 변경되지 않는 고유 식별자로 사용자를 매칭해야 합니다. 프로젝트 역할 설정은 프로젝트 사용자 역할 관리를 참조하십시오.



테스트 및 활성화

테스트 절차

  1. 기본 설정 및 권한 관리를 완료한 후 초안 저장을 클릭하십시오.
  2. 테스트 및 활성화를 열고 연결 테스트를 실행하여 필수 필드, HTTPS, 프로토콜 엔드포인트 및 해당하는 Discovery, Metadata 또는 인증서 설정을 확인하십시오.
  3. 테스트 로그인을 실행하고 열린 IdP 페이지에서 테스트 계정으로 인증한 후 원래 설정 페이지로 돌아오십시오.
  4. 반환된 변경되지 않는 식별자, 표시 이름, 이메일, Role 목록 및 관리 역할을 확인하십시오. 역할 조회 및 매핑이 예상대로 작동하는지 확인하십시오.
  5. 테스트를 통과한 후 저장 및 적용을 클릭하고 ID 소스가 활성화되었는지 확인하십시오.
연결 테스트 및 테스트 로그인 모두 통과

연결 테스트는 설정 및 엔드포인트만 검증하며 실제 사용자 로그인 테스트를 대체하지 않습니다. OIDC는 활성화 전에 연결 테스트를 통과해야 합니다. 테스트 로그인을 통과하지 않은 상태에서 페이지 안내에 따라 위험을 확인하고 Realm을 활성화하더라도 로그인 검증을 통과한 것은 아닙니다. 활성화 전에 두 테스트를 모두 완료하는 것이 좋습니다. SAML 2.0은 두 테스트를 모두 통과한 후 활성화해야 합니다. 새로 생성된 OAuth2 Realm은 두 테스트를 모두 통과해야 합니다. 버튼이 사용 가능하거나 일반적인 확인 메시지가 표시된다고 해서 테스트를 통과한 것은 아닙니다.

Discovery 조회, Metadata 가져오기 또는 Token 교환에 실패하면 FlightHub 2 백엔드 네트워크, TLS 인증서 신뢰, 애플리케이션 자격 증명, 콜백 URL 및 프로토콜 매개변수를 확인하십시오. 설정을 수정한 후 저장하고 다시 테스트하십시오.


ID 소스 유지 관리

목록에서 ID 소스 설정을 편집하거나 계속 진행할 수 있으며, 테스트, 활성화, 비활성화 및 삭제도 할 수 있습니다. 각 상태에 따라 다음과 같이 처리하십시오:

상태작업
초안설정을 완료하고 저장한 후 테스트를 실행하십시오
재테스트 필요주요 설정의 변경 사항을 검토하고 테스트를 다시 실행하십시오
테스트 실패실패 결과를 검토하고 IdP 또는 FlightHub 2 설정을 수정한 후 다시 테스트하십시오
활성화 준비 완료테스트 결과를 확인하고 페이지에 표시된 조건에 따라 Realm을 활성화하십시오
활성화됨로그인에 사용할 수 있습니다. 주요 설정을 변경한 후 안내에 따라 다시 테스트하십시오
비활성화됨설정은 유지되지만 일반 로그인에는 사용할 수 없습니다

IdP 엔드포인트, 인증서 또는 역할 출력 설정을 업데이트한 후 Realm에도 해당 변경 사항을 반영하고 다시 테스트하십시오. 수동으로 재정의한 필드는 자동 조회된 값으로 업데이트되지 않으므로 별도로 확인해야 합니다.



로컬 계정 로그인 관리

SSO 로그인 설정 페이지의 로컬 계정 비밀번호 로그인 허용 스위치는 일반 로컬 계정의 비밀번호 로그인 허용 여부를 제어합니다. 비활성화하면 일반 로컬 계정은 비밀번호 로그인을 사용할 수 없으며, 멤버는 테스트를 통과하고 활성화된 SSO ID 소스를 통해 로그인해야 합니다.

로컬 계정 비밀번호 로그인을 비활성화하려면:

  1. 하나 이상의 Realm을 설정하고 테스트한 후 활성화하여 엔터프라이즈 계정으로 정상적으로 로그인할 수 있는지 확인하십시오.
  2. 비상 슈퍼 관리자 계정과 해당 로컬 비밀번호가 정상적으로 작동하는지 확인하십시오.
  3. 로컬 계정 비밀번호 로그인 허용을 끄고 대화 상자에서 비상 슈퍼 관리자 지정을 선택하십시오.
  4. 영향을 검토하고 확인 체크박스를 선택한 후 비활성화 확인을 클릭하십시오.
로컬 계정 로그인 비활성화 시 비상 슈퍼 관리자 지정

엔터프라이즈 IdP를 사용할 수 없거나 SSO 설정이 잘못된 경우 지정된 비상 슈퍼 관리자는 로컬 비밀번호로 시스템에 접근하여 로컬 계정 로그인을 다시 활성화하거나 SSO 설정을 수정할 수 있습니다. 일반 조직 관리자는 비상 슈퍼 관리자가 아니며, 계정 이름만으로는 비상 로그인 가능 여부를 판단할 수 없습니다.



Keycloak 연동 예시

다음 예시는 Keycloak으로 각 프로토콜을 설정하는 방법을 설명합니다. 예시의 도메인, Realm 이름, Client ID 및 필드 경로를 배포 환경에 맞는 값으로 바꾸십시오. FlightHub 2에서 생성한 콜백 URL 및 SP Metadata 정보를 사용하십시오. 메뉴 위치는 Keycloak 버전에 따라 다를 수 있습니다.

스크린샷은 설정 위치 및 주요 옵션을 보여줍니다. 스크린샷에 표시된 Realm, Client 및 테스트 사용자 이름은 예시입니다. 실제 설정에는 기업의 ID 소스, 애플리케이션 및 사용자 정보를 사용하십시오.


엔터프라이즈 ID 소스, 역할 및 테스트 사용자 생성

  1. Keycloak 관리 콘솔에 로그인하고 Manage realms에서 엔터프라이즈 Realm을 생성하거나 선택하십시오. 예: Enterprise.

    Keycloak Realm 생성, 이름 입력 및 활성화
  2. Realm roles에서 fh2-admin-org, fh2-admin-device 및 fh2-member-org를 생성하거나 FlightHub 2 매핑과 일치하는 역할 값을 생성하십시오.

    Keycloak Realm 역할 목록 및 역할 생성 버튼
  3. Users에서 테스트 사용자를 생성하고 활성화하십시오. Credentials에서 비밀번호를 설정하고 필요한 계정 작업을 완료하십시오.

  4. 사용자의 Role mapping 탭에서 테스트 역할을 할당하십시오. 첫 테스트에서는 결과를 쉽게 확인할 수 있도록 fh2-member-org와 같은 관리 역할을 하나만 할당하십시오.

    Keycloak에서 테스트 사용자에게 멤버 역할 할당

Keycloak의 엔터프라이즈 Realm과 FlightHub 2의 Realm은 서로 다른 설정 단위이며 이름이 같을 필요는 없습니다. 여러 프로토콜을 연동하는 경우 각 프로토콜에 별도의 Client를 설정하고 서로 다른 로그인 라우팅 도메인을 사용하십시오.


OIDC 연동

  1. Keycloak에서 OpenID Connect Client를 생성하십시오. 예: Enterprise_OIDC.

  2. Client authentication 및 Standard flow를 활성화하고 Implicit flow를 비활성화하십시오. 브라우저 기반 SSO에는 Direct access grants가 필요하지 않습니다. Require PKCE를 활성화하고 PKCE Method를 S256으로 설정하십시오. 이 설정은 Settings → Capability config에서 찾을 수 있습니다.

    Keycloak Client 인증 흐름 및 PKCE S256 설정
  3. FlightHub 2에서 OIDC Realm을 생성하고 로그인 라우팅 이메일, Client ID, Client Secret 및 Discovery URL을 입력하십시오. Keycloak Discovery URL의 형식은 다음과 같습니다:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. FlightHub 2 초안을 저장하여 실제 콜백 정보를 확인하십시오. Keycloak Client의 Valid redirect URIs에 일반 로그인 및 테스트 로그인 콜백 URL을 등록하고, FlightHub 2에서 생성한 정보로 Web origins를 설정하십시오. Client의 Credentials 탭에서 Client Secret을 확인하십시오.

  5. Client scopes → 해당 Client의 전용 스코프 → Mappers에서 User Realm Role Mapper를 추가하십시오:

    Client scopes를 열고 현재 Client의 전용 스코프를 선택한 후 매퍼 설정을 여십시오.

    Keycloak Client scopes의 전용 스코프 항목
    설정예시 값
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    Multivalued켜짐
    Add to ID token / Add to access token / Add to userinfo켜짐
    토큰 및 사용자 정보에 다중 값 역할을 출력하는 Keycloak User Realm Role Mapper
  6. FlightHub 2에서 Role Path를 roles로 설정하고 관리 역할 매핑을 설정한 후 연결 테스트 및 테스트 로그인을 실행하십시오. 역할을 확인한 후 설정을 저장하고 적용하십시오.


SAML 2.0 연동

  1. 다음 형식의 URL로 Keycloak에서 IdP Metadata를 조회하십시오. 이 URL이 반환하는 Metadata XML은 파일 업로드에도 사용할 수 있습니다.

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. FlightHub 2에서 SAML 2.0 Realm을 생성하고 IdP Metadata를 가져온 후 초안을 저장하고 생성된 SP Metadata XML을 다운로드하십시오.

  3. Keycloak의 Clients → Import client에서 SP Metadata를 가져오거나 SAML Client를 수동으로 생성하고 다음 필드를 확인하십시오:

    설정예시 값
    Client IDFlightHub 2 SP Metadata의 Entity ID
    Name애플리케이션을 구분할 이름. 예: Enterprise_SAML
    Valid redirect URIsFlightHub 2 ACS URL
    Name ID formatpersistent
    Force name ID format켜짐
    Force POST binding켜짐. POST로 SAML 응답을 반환합니다
    Sign documents / Sign assertions켜짐
    Signature algorithmRSA_SHA256
    Client signature required켜짐. FlightHub 2 SP Metadata에서 SP 서명 인증서를 가져오십시오
    IDP-Initiated SSO URL name비워 두십시오. FlightHub 2에서 로그인을 시작하십시오

    아래 스크린샷은 persistent NameID 및 POST Binding을 설정하는 위치를 보여줍니다. 위 표와 비교하여 서명 및 인증서 설정을 확인하십시오.

    Keycloak SAML persistent NameID 및 POST Binding 설정
  4. SAML Client의 전용 스코프에서 역할 및 사용자 정보 Mappers를 설정하십시오:

    매퍼 유형주요 설정
    Role listName 및 Role attribute name: roles; NameFormat: Basic; Single Role Attribute: 켜짐
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    roles 속성과 Single Role Attribute가 활성화된 Keycloak SAML Role list Mapper
  5. 역할 출력이 중복되거나 충돌하지 않도록 Client의 기본 role_list 스코프 및 사용자 지정 역할 Mapper를 확인하십시오. 위의 사용자 지정 roles Mapper를 사용하는 경우 이 Client에서 충돌하는 기본 스코프 할당을 제거하십시오.

  6. FlightHub 2에서 Role Attribute를 roles, 사용자 표시 이름 Attribute를 displayName으로 설정한 후 관리 역할 매핑을 설정하십시오. 두 테스트를 모두 통과한 후 설정을 저장하고 적용하십시오.

Client ID에는 애플리케이션 표시 이름이 아닌 실제 SP Entity ID를 사용해야 합니다. FlightHub 2 AuthnRequest는 Redirect Binding을 사용하고 IdP 응답은 POST Binding을 사용할 수 있습니다. 이 바인딩은 용도가 서로 다릅니다. FlightHub 2 SAML Realm을 다시 생성한 후 새 SP Metadata를 조회하고 IdP의 Entity ID, ACS 및 인증서 설정을 확인하여 업데이트하십시오.


OAuth2 연동

Keycloak은 OpenID Connect Client를 통해 OAuth2 엔드포인트를 제공합니다. FlightHub 2에서는 OAuth2 프로토콜을 선택하십시오.

  1. Keycloak에서 별도의 Client를 생성하십시오. 예: Enterprise_OAuth2. 위의 OIDC 예시에 따라 Client authentication, Standard flow, PKCE 및 일반 로그인과 테스트 로그인 콜백 URL을 설정하고 이 Client의 고유한 Secret을 확인하십시오.

  2. Client의 전용 스코프에 User Realm Role Mapper를 추가하십시오. Token Claim Name을 roles, Multivalued를 켜짐으로 설정하고 Add to userinfo가 켜짐인지 확인하십시오.

  3. FlightHub 2에서 OAuth2 Realm을 생성하고 해당 애플리케이션 자격 증명, 로그인 라우팅 이메일 및 다음 설정을 입력하십시오:

    FlightHub 2 필드Keycloak 예시
    Authorization URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/auth
    Token URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/token
    User URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfo
    USER_ID_KEYsub
    USER_ACCOUNT_KEYpreferred_username
    Scopesopenid profile email, 이 예시의 Keycloak 사용자 정보 API에 사용
    Role Path (UserInfo)roles
  4. 초안을 저장하고 관리 역할 매핑을 설정하십시오. 연결 테스트와 테스트 로그인을 모두 통과하고 사용자 정보 및 관리 역할이 예상 결과와 일치하는 경우에만 설정을 저장하고 적용하십시오.

예시의 Scopes 및 사용자 필드는 위에서 설명한 Keycloak 설정에 적용됩니다. 다른 IdP와 연동하는 경우 API 문서에 따라 조정하십시오.



자주 묻는 질문

연결 테스트를 통과했는데도 사용자가 로그인할 수 없는 이유는 무엇인가요?

연결 테스트는 설정 및 엔드포인트를 확인합니다. 테스트 로그인은 실제 ID 정보, 역할 조회 및 관리 역할 매핑을 검증합니다. 테스트 로그인을 실행하고 변경되지 않는 사용자 ID, 역할 필드, 매핑 결과, 콜백 URL 및 서명 검증 결과를 확인하십시오.

콜백 URL 불일치는 어떻게 해결하나요?

실제 요청의 redirect_uri와 해당 IdP 애플리케이션에 등록된 콜백 URL을 비교하십시오. 프로토콜, 도메인, 포트 및 경로까지 정확히 일치해야 합니다. 배포 환경에 맞게 일반 로그인 및 테스트 로그인 콜백을 모두 등록하십시오. 프런트엔드 설정 페이지 URL이나 저장하지 않은 양식의 플레이스홀더 값을 사용하지 마십시오.

로그인 라우팅 이메일은 IdP의 사용자 이메일과 일치해야 하나요?

로그인 라우팅 이메일은 ID 소스를 선택하는 데 사용되며, IdP 사용자 이메일은 사용자 프로필의 일부입니다. 두 이메일은 용도가 서로 다릅니다. 계정 및 이메일 주소에 대한 IdP 설정 요구 사항을 따르십시오. 로그인 라우팅 도메인은 이메일 형식 요구 사항을 충족해야 하며 밑줄을 포함해서는 안 됩니다. Realm 생성 시 완전한 형식의 이메일 주소를 입력하십시오.

FlightHub 2가 IdP에서 반환한 역할을 조회할 수 없는 이유는 무엇인가요?

OIDC의 경우 ID 정보의 배열 구조와 Role Path를 비교하여 확인하십시오. OAuth2의 경우 User URL이 반환하는 역할 배열을 확인하십시오. SAML의 경우 Attribute Name의 대소문자를 확인하고 여러 역할에 별도의 AttributeValue 요소가 사용되는지 확인하십시오. 또한 IdP의 기본 Mappers와 사용자 지정 Mappers 간에 충돌이 없는지 확인하고, 반환된 Role 값이 관리 역할 매핑과 일치하는지 확인하십시오.

로그인에 성공했는데 프로젝트가 표시되지 않는 이유는 무엇인가요?

SSO 관리 역할은 프로젝트 권한을 자동으로 부여하지 않습니다. 관리자는 프로젝트 멤버 관리에서 사용자를 추가하고 프로젝트 역할을 할당해야 하며, 사용자 Realm의 변경되지 않는 고유 식별자로 사용자를 매칭해야 합니다.

이메일 주소를 고유 사용자 식별자로 사용할 수 있나요?

아니요. 이메일 주소는 변경되거나 재사용될 수 있습니다. OIDC는 issuer + sub, SAML은 IdP Entity ID + persistent NameID, OAuth2는 Realm + stable user ID를 사용합니다. 표시 이름 및 계정 이름도 변경되지 않는 고유 식별자를 대체할 수 없습니다.

Discovery 또는 Metadata 조회 실패는 어떻게 해결하나요?

URL이 올바른지, FlightHub 2 백엔드가 HTTPS로 해당 URL에 접근할 수 있는지, 백엔드가 IdP 인증서를 신뢰하는지 확인하십시오. 브라우저에서 접근하거나 인증서를 수락할 수 있다고 해서 FlightHub 2 백엔드에서도 접근하거나 신뢰할 수 있는 것은 아닙니다. SAML의 경우 IdP에서 내보낸 실제 Metadata XML을 업로드할 수도 있습니다. 문제를 해결한 후 저장하고 다시 테스트하십시오.

IdP 인증 후 토큰 교환 실패는 어떻게 해결하나요?

FlightHub 2 백엔드와 Token URL 간의 네트워크 연결 및 TLS 인증서 신뢰를 확인하십시오. 해당 Client ID, Client Secret, 실제 콜백 URL 및 PKCE 매개변수를 확인하십시오. 문제를 해결한 후 다시 테스트하고 사용자 정보 및 관리 역할이 정상적으로 조회되는지 확인하십시오.

인증서 또는 엔드포인트는 어떻게 업데이트하나요?

OIDC의 경우 Discovery를 새로 고치십시오. SAML에서 URL로 가져온 경우 Metadata를 새로 고치고, XML을 업로드한 경우 업데이트된 파일을 다시 업로드하십시오. 수동으로 재정의한 필드를 확인하고 필요에 따라 업데이트하거나 자동 값으로 복원하십시오. OAuth2의 경우 엔드포인트를 수동으로 업데이트하십시오. 변경 후 테스트를 다시 실행하십시오.

FlightHub 2에서 로그아웃하면 엔터프라이즈 IdP에서도 로그아웃되나요?

로그아웃하면 FlightHub 2 세션만 종료됩니다. 엔터프라이즈 IdP에서는 로그아웃되지 않습니다. 다음 로그인 시 엔터프라이즈 세션이 여전히 활성 상태일 수 있으며, 테스트 로그인에서는 재인증이 필요할 수 있습니다.

로컬 비밀번호 로그인을 비활성화한 후 IdP에 장애가 발생하면 어떻게 접근을 복구하나요?

로컬 계정 로그인 비활성화 시 지정한 비상 슈퍼 관리자는 로컬 비밀번호로 시스템에 접근하여 로컬 계정 로그인을 다시 활성화하거나 SSO 설정을 수정할 수 있습니다. 로컬 계정 로그인을 비활성화하기 전에 이 계정과 비밀번호가 정상적으로 작동하는지 확인하십시오.

ID 소스를 활성화할 수 없는 경우 무엇을 확인해야 하나요?

초안이 저장되었는지, 필수 필드가 유효한지, 재테스트가 요청되었는지, 활성화된 Realm이 한도인 8개에 도달했는지 확인하십시오. 새로 생성된 OAuth2 Realm의 경우 두 테스트를 모두 통과했는지도 확인하십시오.

Last Updated: