[Kubernetes] Flask의 AUTH_ROLES_MAPPING 및 AUTH_USER_REGISTRATION_ROLE

Flask의 AUTH_ROLES_MAPPING 및 AUTH_USER_REGISTRATION_ROLE

Flask-AppBuilder(FAB)에서 사용자 등록과 역할(Role) 할당은 매우 중요한 보안·권한 관리 요소임.

FAB는 다양한 인증 방식(DB, LDAP, OAuth 등)을 지원하는데, 새로운 사용자가 등록되거나 OAuth 등 외부 인증 프로바이더로부터 로그인할 때, 어떤 Role을 부여할지 정해야 함.

이때 설정값인 AUTH_ROLES_MAPPING과 AUTH_USER_REGISTRATION_ROLE이 핵심적인 역할을 담당함.

 

AUTH_ROLES_MAPPING: 외부 인증 Role → FAB Role 매핑

AUTH_ROLES_MAPPING은 외부 인증 소스(OAuth Provider, LDAP 등)에서 가져온 사용자 그룹(또는 role) 정보를 Flask-AppBuilder 내부의 Role로 자동 변환(매핑) 해줄 때 사용됨.

 

 

AUTH_ROLES_MAPPING - 동작 시나리오

사용자가 OAuth나 LDAP 등을 통해 로그인할 때, 해당 사용자에 대한 그룹/역할/권한 목록이 외부 시스템에서 제공됨.

예를 들어, LDAP 그룹, OAuth(또는 OIDC) Claims, “role” 속성, 혹은 “department” 정보 등.

Flask-AppBuilder SecurityManager는 “외부에서 넘어온 그룹/권한”에 대응되는 FAB 내부의 Role을 찾으려고 함.

AUTH_ROLES_MAPPING에 정의된 딕셔너리를 참조하여, 외부의 그룹(또는 role) 문자열을 어떤 FAB Role로 매핑할지 결정함.

만약 적절한 매핑이 없으면 기본값(예: AUTH_USER_REGISTRATION_ROLE)으로 지정될 수 있음.

 

AUTH_ROLES_MAPPING - 예시 코드

AUTH_ROLES_MAPPING = {
    "GitHub_org_admin": ["Admin"],
    "GitHub_org_user": ["Public"],
    "GitHub_team_data": ["Analytics"]
}

예를 들어, GitHub OAuth 로그인 시, 사용자가 GitHub_org_admin이라는 외부 그룹(또는 team)을 가지고 있다고 하면, FAB 내부에서 “Admin” Role을 부여함.

사용자가 여러 외부 그룹을 가지고 있을 수 있으며, FAB는 해당 매핑에 따라 “중첩”해서 여러 Role을 부여하기도 함.

단, 보안 전략에 따라 달라질 수 있음.

 

AUTH_ROLES_MAPPING - 활용 사례

1. LDAP

LDAP 서버에서 CN=admins 그룹에 속한 사용자라면 FAB “Admin” 역할을, CN=managers 그룹에 속한 사용자라면 FAB “Manager” 역할을 부여하는 식으로 구성 가능함.

 

2. OAuth / OIDC: JWT Claims(예: realm_access.roles, groups)에 따라 FAB Role 매핑.

 

AUTH_ROLES_MAPPING - 주의 사항

외부 Role(또는 그룹) 이름과 FAB Role 이름이 직접 1:1 대응되어야 하는 것은 아님.

AUTH_ROLES_MAPPING에서 임의로 원하는 이름으로 매핑 가능.

매핑에 없는 외부 Role이 들어오면, FAB가 이를 무시하거나 기본 Role로만 처리할 수 있음.

외부 정보가 신뢰할 수 있는 출처인지(인증된 Provider인지) 반드시 확인 필요.

 

AUTH_USER_REGISTRATION_ROLE: 신규 사용자 등록 시 기본 할당 Role

AUTH_USER_REGISTRATION_ROLE은 “처음으로” FAB에 등록되는 사용자(= DB에 존재하지 않는 사용자)에게 어떤 Role을 부여할지 기본값을 설정해주는 옵션임.

 

AUTH_USER_REGISTRATION_ROLE - 동작 시나리오

사용자가 FAB에 처음 로그인 시도(예: OAuth, LDAP 또는 자체 인증(DB))

FAB는 내부 DB(User 모델)에 해당 이메일/사용자명이 이미 있는지 확인

존재하지 않으면, 새 사용자로 등록 (User 레코드 생성)

AUTH_USER_REGISTRATION_ROLE에 설정된 FAB Role을 부여

AUTH_ROLES_MAPPING이 사용 중이라면, 그 매핑 규칙에 따라 추가 Role이 붙을 수도 있음

 

AUTH_USER_REGISTRATION_ROLE - 예시 코드

# default로 "Public" 역할을 부여
AUTH_USER_REGISTRATION_ROLE = "Public"

사용자가 신규 가입할 때, 최소한 “Public” 역할을 가지도록 설정

“Public” 역할은 FAB 기본 제공 역할 중 하나이며, 보통 제한적인 권한만 부여

 

AUTH_USER_REGISTRATION_ROLE - 더 복잡한 시나리오

어떤 서비스에서는 AUTH_ROLES_MAPPING으로 사용자 그룹이 명시되지 않은 경우, 혹은 외부 인증에서 Role/Group 정보를 주지 않는 경우에는 “기본 Role”만 부여하고, 이후 관리자가 별도로 권한을 승급할 수 있게 함.

반대로, 외부 인증에서 아주 세분화된 Role 정보가 들어온다면, AUTH_ROLES_MAPPING에서 매핑한 뒤에 굳이 기본 Role이 필요 없을 수도 있음.

 

AUTH_USER_REGISTRATION_ROLE - 주의 사항

“기본 Role”은 보안상 권한이 매우 제한된 역할로 설정하는 것이 바람직함 (원칙적으로 최소 권한).

AUTH_USER_REGISTRATION_ROLE가 None이거나 잘못 설정되어 있으면, 신규 사용자가 아무 Role 없이 등록될 수 있으므로 권한 관리 혼선이 생길 수 있음.

OAuth 등 외부 Provider에서 이미 ‘관리자’에 해당되는 사용자라도, 매핑 설정이 없으면 기본 Role만 부여되므로, 실제 권한이 기대와 다를 수 있음.

 

보안 전략

1. 최소 권한 원칙(Principle of Least Privilege) 준수

새로운 사용자가 들어오면 일단 최소한의 권한만 부여(예: “Public” 또는 “Viewer” 역할)

외부 인증에 의해 ‘admin’임이 확인된 사용자만 Admin 권한을 얻도록 AUTH_ROLES_MAPPING을 조정

 

2. 외부 Role 신뢰성 검증

OAuth/JWT Claims나 LDAP 그룹 정보가 변조되지 않았는지, 인증 서버가 신뢰할 수 있는지 반드시 확인

JWT 서명 검증, LDAP 연결 시 TLS/SSL 사용 등 보안 필수

 

3. Role 부여 로깅 및 감사(Auditing)

어떤 외부 인증 정보에 의해, 어떤 시점에, 어떤 Role이 부여되었는지 추적 가능하도록 로깅

Role 변경/승급은 관리자가 별도 승인 과정을 거칠 수도 있음

 

4. 정교한 권한 분류

Flask-AppBuilder에서 Role별 권한(권한-뷰, 권한-메뉴 접근 등)을 섬세하게 분배

관리자(Role “Admin”), 일반 사용자(“Public”, “User”), 분석가(“Analytics”) 등 서비스 목적에 맞춰 확장 가능

 

요약

1. AUTH_ROLES_MAPPING

외부 인증에서 넘어오는 Role/Group을 Flask-AppBuilder 내부의 Role로 변환하는 딕셔너리 설정

여러 외부 그룹을 각각 다른 FAB Role로 매핑 가능

LDAP, OAuth, OpenID Connect 등에서 Role/Group 정보를 받아 활용 가능

 

2. AUTH_USER_REGISTRATION_ROLE

FAB에서 “신규 사용자 등록” 시, 기본적으로 부여할 Role

외부 인증에 Role/Group 정보가 없거나, 매핑되지 않았을 때도 최소한의 Role을 부여

일반적으로 권한이 제한적인 Role(예: “Public”)을 지정

 

두 설정을 적절히 조합하면, 외부 인증 소스와 연동된 자동 사용자 등록 & 자동 Role 할당 절차를 편리하게 구현할 수 있음.

실제 서비스에서는 최소 권한 원칙과 보안 모범사례를 준수하면서, 필요에 따라 Role 정의(권한 범위, 뷰 접근 범위) 및 매핑 로직을 세부적으로 튜닝하여 사용자의 권한을 일관성 있게 관리할 수 있음.