Airflow 3.0.2集成Keycloak SSO角色映射异常及500错误排查

背景概述 #

通过Terraform在K8s部署Airflow 3.0.2（官方Helm Chart 1.17.0），集成Keycloak SSO时遇到两个核心问题：

1. 默认配置下，Keycloak的Admin角色用户登录Airflow后被映射为Viewer角色，AUTH_ROLES_MAPPING未生效
2. 自定义SecurityManager重写get_oauth_user_info后角色映射正常，但UI的Security、Manage页面频繁500错误

疑问解答 #

1. role_keys传递或AUTH_ROLES_MAPPING与CustomSecurityManager的交互是否存在遗漏？ #

是的，核心问题在于自定义SecurityManager时未正确处理角色的完整权限上下文，或角色提取逻辑有误：

• 若Keycloak返回的角色嵌套在realm_access.roles或resource_access.<client_id>.roles中，自定义方法需确保正确提取目标角色集合，而非仅读取顶层字段
• 重写get_oauth_user_info后，返回的role_keys必须与AUTH_ROLES_MAPPING的Key完全匹配（大小写敏感）
• 自定义SecurityManager时，不要覆盖Flask-AppBuilder中与角色权限同步相关的核心方法（如sync_roles），否则会破坏Airflow内置的角色-权限关联逻辑

2. 该方案是否与Airflow 3.0.2/Flask-AppBuilder不兼容？ #

Airflow 3.x基于Flask-AppBuilder（FAB）4.x版本，与旧版本的自定义SecurityManager逻辑存在适配差异：

• FAB 4.x对OAuth用户信息的处理流程有调整，旧版本的get_oauth_user_info重写逻辑未适配新的权限同步机制
• Airflow 3.x默认启用了角色权限的严格校验，自定义SecurityManager若未正确传递用户的完整权限集合，会触发管理页面的权限校验失败，导致500错误

3. Airflow 3.x是否需要手动声明额外的角色-权限绑定？ #

不需要手动声明内置角色（Admin、User、Viewer等）的权限绑定，但需注意：

• Airflow 3.x的内置角色权限集合有更新，若自定义新角色，需通过FAB权限API或Airflow CLI手动绑定权限
• 使用自定义SecurityManager时，需确保同步用户角色时，Airflow能正确识别内置角色的权限，不要修改内置角色的默认权限配置

Airflow 3.0+ Keycloak SSO 可行配置示例 #

以下是webserver_config.py的完整配置，无需自定义SecurityManager即可实现正确的角色映射：

import os
from flask_appbuilder.security.manager import AUTH_OAUTH
from airflow.www.security import AirflowSecurityManager

# 基础认证配置
AUTH_TYPE = AUTH_OAUTH
AUTH_ROLES_SYNC_AT_LOGIN = True  # 登录时同步Keycloak角色到Airflow
AUTH_USER_REGISTRATION = True  # 自动注册新用户
AUTH_USER_REGISTRATION_ROLE = "Viewer"  # 未匹配到映射角色时的默认角色

# Keycloak OAuth提供商配置
OAUTH_PROVIDERS = [
    {
        "name": "keycloak",
        "token_key": "access_token",
        "icon": "fa-key",
        "remote_app": {
            "client_id": os.getenv("KEYCLOAK_CLIENT_ID"),
            "client_secret": os.getenv("KEYCLOAK_CLIENT_SECRET"),
            "client_kwargs": {
                "scope": "openid email profile roles"
            },
            "access_token_url": f"{os.getenv('KEYCLOAK_BASE_URL')}/realms/{os.getenv('KEYCLOAK_REALM')}/protocol/openid-connect/token",
            "authorize_url": f"{os.getenv('KEYCLOAK_BASE_URL')}/realms/{os.getenv('KEYCLOAK_REALM')}/protocol/openid-connect/auth",
            "api_base_url": f"{os.getenv('KEYCLOAK_BASE_URL')}/realms/{os.getenv('KEYCLOAK_REALM')}/protocol/openid-connect/userinfo",
        }
    }
]

# Keycloak角色到Airflow内置角色的映射（需与Keycloak中角色名称完全匹配）
AUTH_ROLES_MAPPING = {
    "airflow-admin": "Admin",
    "airflow-user": "User",
    "airflow-viewer": "Viewer"
}

# 自定义用户信息映射器：从Keycloak返回的userinfo中提取角色
def keycloak_user_info_mapper(data, provider):
    # 若使用Keycloak客户端角色，替换为下方注释的逻辑
    roles = data.get("realm_access", {}).get("roles", [])
    # roles = data.get("resource_access", {}).get(os.getenv("KEYCLOAK_CLIENT_ID"), {}).get("roles", [])
    return {
        "username": data.get("preferred_username"),
        "email": data.get("email"),
        "first_name": data.get("given_name"),
        "last_name": data.get("family_name"),
        "role_keys": roles
    }

# 绑定用户信息映射器到Keycloak提供商
OAUTH_USER_INFO_MAPPERS = {
    "keycloak": keycloak_user_info_mapper
}

# 使用Airflow默认的SecurityManager，避免自定义导致的权限逻辑破坏
SECURITY_MANAGER_CLASS = AirflowSecurityManager

关键配置说明 #

1. AUTH_ROLES_SYNC_AT_LOGIN: 开启后，每次登录都会同步Keycloak角色到Airflow，确保映射关系实时生效
2. OAUTH_USER_INFO_MAPPERS: Airflow 3.x推荐使用该方式提取用户角色，无需重写SecurityManager，避免破坏内置权限逻辑
3. 角色提取逻辑: 根据Keycloak的实际返回结构调整（ realm角色/客户端角色），确保role_keys包含的角色与AUTH_ROLES_MAPPING的Key完全匹配

Helm部署配置传递 #

在Helm values.yaml中，通过webserver.extraEnv传递Keycloak环境变量，通过webserver.webserverConfig挂载上述配置文件：

webserver:
  extraEnv:
    - name: KEYCLOAK_BASE_URL
      value: "https://your-keycloak-domain"
    - name: KEYCLOAK_REALM
      value: "your-realm"
    - name: KEYCLOAK_CLIENT_ID
      value: "airflow-client"
    - name: KEYCLOAK_CLIENT_SECRET
      value: "your-client-secret"
  webserverConfig: |
    # 粘贴上述webserver_config.py内容

500错误排查要点 #

若仍出现管理页面500错误，可按以下步骤排查：

• 查看Airflow webserver日志，确认错误类型是否为PermissionDenied或RoleNotFound
• 检查Keycloak返回的角色是否与AUTH_ROLES_MAPPING完全匹配（大小写、拼写）
• 通过airflow roles list命令确认Airflow内置角色未被修改
• 临时禁用自定义SecurityManager，使用上述默认配置验证是否解决问题

内容的提问来源于stack exchange，提问作者Ravindra Gupta