DataHub 集成 Microsoft Entra ID（Azure AD）身份元数据摄取指南

DataHub 集成 Microsoft Entra ID（Azure AD）身份元数据摄取指南

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

Microsoft Entra ID（原 Azure Active Directory / Azure AD）是企业级的身份与访问管理平台。DataHub 通过azure-ad摄取模块将 Entra ID 中的用户、组以及组成员关系同步为 DataHub 的CorpUser、CorpGroup身份实体，并借助有状态摄取（Stateful Ingestion）实现删除检测。本文基于 metadata-ingestion/docs/sources/azure-ad/README.md 及其配套文档，结合 azure_ad.py 源码，完整讲解前置条件、API 权限配置、Recipe 配置参数、实体映射逻辑与成员关系同步原理，帮助读者在生产环境中完成 Entra ID 身份数据的可靠同步。

Overview：模块定位与能力边界

Microsoft Entra ID 是微软的身份与访问管理平台。DataHub 对其的集成覆盖了三类身份实体：

• 用户（Users）
• 组（Groups）
• 组成员关系（Memberships）

同时通过有状态摄取捕获状态化删除检测（stateful deletion detection）——当 Entra ID 中的用户或组被删除时，DataHub 侧能感知到并从图中移除对应实体。

该模块的实现位于 azure_ad.py，是一个标注为SupportStatus.GA（正式可用）的摄取源，通过 Microsoft Graph REST API v1.0 拉取数据，并使用 OAuth2 客户端凭证流（client credentials flow）完成认证。从源码装饰器可以看到它声明了DELETION_DETECTION能力，默认通过有状态摄取开启（见 azure_ad.py）。

概念映射（Concept Mapping）

官方文档当前对具体概念映射仍在完善中，但通用映射关系如下：

Source Concept	DataHub Concept	Notes
Ownership 与协作主体（Ownership and collaboration principals）	CorpUser, CorpGroup	由支持所有权与身份元数据的模块发出

从源码可以进一步确认：用户在 DataHub 中映射为CorpUserSnapshot，组映射为CorpGroupSnapshot，并额外发出OriginClass(OriginTypeClass.EXTERNAL, "AZURE_AD")标记数据来源为外部系统（见 azure_ad.py 与 azure_ad.py）。

Prerequisites：前置条件

在运行摄取之前，需要确保：

1. 网络连通性：DataHub 摄取执行环境能够访问 Microsoft Graph API 端点；
2. 有效认证凭证：Azure AD 应用注册（App Registration）的 Application ID、Directory ID（租户 ID）与 Client Secret；
3. 元数据 API 的读取权限：授予应用注册读取身份元数据所需的 API 权限。

必需的 Azure AD 应用权限（Application 权限）

在 Azure AD 门户中为 DataHub 创建一个应用注册，并授予以下Application类型权限（应用权限，而非委派权限）：

• Group.Read.All
• GroupMember.Read.All
• User.Read.All

权限可以在应用配置的API permissions选项卡中添加。相关界面示意如下：

注：仓库内置的截图（azure_ad_api_permissions.png）展示的是应用注册中 "API permissions" 页面的实际形态，包含 "Add a permission" 与 "Grant admin consent" 等操作入口。请按上文列出的三个权限名（而不是截图示例中的User.Read）进行配置。

配置完成后，可点击应用概览（Overview）中的Endpoints按钮，核对后续 Recipe 所需的端点值（如 OAuth 2.0 token 端点、Microsoft Graph 端点等）：

SSO 注意事项（SSO Caveat）

通过本连接器摄取的 DataHub 用户，只有在你 DataHub 部署中配置了Okta OIDC SSO时，才能实际登录 DataHub。也就是说：摄取负责把身份同步进来，而登录认证由 OIDC SSO 配置负责，二者需要配合使用。

快速上手：Recipe 配置示例

以下是一个可直接作为基础的摄取 Recipe（完整示例见 azure-ad_recipe.yml）：

source: type: "azure-ad" config: client_id: "00000000-0000-0000-0000-000000000000" tenant_id: "00000000-0000-0000-0000-000000000000" client_secret: "xxxxx" redirect: "https://login.microsoftonline.com/common/oauth2/nativeclient" authority: "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000" token_url: "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/token" graph_url: "https://graph.microsoft.com/v1.0" ingest_users: True ingest_groups: True groups_pattern: allow: - ".*" users_pattern: allow: - ".*" sink: # sink configs

运行摄取：

datahub ingest -c azure-ad_recipe.yml

关键配置参数详解

以下参数均来自 azure_ad.py 中AzureADConfig的字段定义：

参数	是否必填	默认值	说明
client_id	必填	无	Application ID，可在 Azure AD 门户的应用注册中找到
tenant_id	必填	无	Directory ID（目录/租户 ID），可在应用注册中找到
client_secret	必填	无	客户端密钥，在应用注册中创建（源码中以TransparentSecretStr类型保护，避免日志泄漏）
authority	必填	无	授权机构 URL，MSAL 据此向目录请求令牌
token_url	必填	无	获取令牌的 Token URL。该 Source 仅支持 v1.0 端点
redirect	可选	https://login.microsoftonline.com/common/oauth2/nativeclient	重定向 URI，可在应用注册中找到
graph_url	可选	https://graph.microsoft.com/v1.0	Microsoft Graph API 端点
ingest_users	可选	True	是否摄取用户到 DataHub
ingest_groups	可选	True	是否摄取组到 DataHub
ingest_group_membership	可选	True	是否摄取组成员关系；若为True则ingest_groups必须为True
ingest_groups_users	可选	True	仅在ingest_users=False且ingest_group_membership=True时有用：只摄取属于所选组的用户
users_pattern	可选	允许全部	摄取用户的 regex 过滤模式（AllowDenyPattern）
groups_pattern	可选	允许全部	摄取组的 regex 过滤模式（AllowDenyPattern）
azure_ad_response_to_username_attr	可选	userPrincipalName	用于映射 DataHub 用户名的 Azure AD User Response 属性
azure_ad_response_to_username_regex	可选	(.*)	从上述属性解析 DataHub 用户名的正则表达式
azure_ad_response_to_groupname_attr	可选	displayName	用于映射 DataHub 组名的 Azure AD Group Response 属性
azure_ad_response_to_groupname_regex	可选	(.*)	从上述属性解析 DataHub 组名的正则表达式
mask_group_id	可选	True	组的工作单元（WorkUnit）ID 是否脱敏，避免泄漏敏感信息
mask_user_id	可选	True	用户的工作单元 ID 是否脱敏
stateful_ingestion	可选	无	Azure AD 有状态摄取配置（StatefulStaleMetadataRemovalConfig）

能力与使用方式（Capabilities）

官方文档以Important Capabilities表格为能力清单的权威来源（能力表由 integrations_catalog.json 等自动生成），用于判断某项特性是否受支持、是否需要额外配置。以下结合源码说明各项能力的底层实现。

提取 DataHub 用户（Extracting DataHub Users）

用户名（Usernames）

用户名是 DataHub 中用户的唯一标识。本连接器默认使用 Azure AD User Response 中的userPrincipalName字段提取用户名——它正是 Azure AD 用户的唯一标识。

如果你希望自定义用户名的映射方式，可通过两个配置项实现：

• azure_ad_response_to_username_attr：指定使用 Azure AD User Response 的哪个属性作为输入；
• azure_ad_response_to_username_regex：用一个正则表达式从该属性中解析出 DataHub 用户名（默认(.*)表示取整段属性值）。

源码中的实现为：先按azure_ad_response_to_username_attr取值，再通过re.search提取匹配部分，随后用make_user_urn构造urn:li:corpuser:<username>（见 azure_ad.py）。

用户信息（Responses）

连接器还会从 Azure 提取基本的用户信息，并映射到 DataHub 的CorpUserInfoaspect：

• display name（显示名）
• first name（名）
• last name（姓）
• email
• title（职位）
• country（国家/地区）

对应源码映射（见 azure_ad.py）：

CorpUserInfoClass( active=corp_user_info_active_from_status(user_status), displayName=azure_ad_user.get("displayName", full_name), firstName=azure_ad_user.get("givenName", None), lastName=azure_ad_user.get("surname", None), fullName=full_name, # givenName + " " + surname email=azure_ad_user.get("mail"), title=azure_ad_user.get("jobTitle", None), countryCode=azure_ad_user.get("mobilePhone", None), )

用户状态（User Status）

连接器为每个用户同时发出两个 aspect：

• corpUserInfo.active
• corpUserStatus

状态推导规则（见 corp_user_status.py）：

• Azure ADaccountEnabled: false→ DataHubSUSPENDED（且active: false）；
• accountEnabled为true或缺失 → DataHubACTIVE（且active: true）。

其中corpUserStatusaspect 携带lastModified审计戳（时间与 actorurn:li:corpuser:datahub），便于追踪状态变更（见 corp_user_status.py）。

提取 DataHub 组（Extracting DataHub Groups）

组名（Group Names）

组名是 DataHub 中组的唯一标识。连接器默认使用 Azure Group Response 的name属性提取组名。具体地：

• 默认以组全名的 URL 编码版本作为唯一标识（CorpGroupKey）；
• 原始name属性映射为 DataHub UI 中显示的 display name。

源码中通过urllib.parse.quote(group_name)对组名做 URL 编码后调用make_group_urn构造 URN（见 azure_ad.py）。

如需自定义组名映射，同样可用两个配置项：

• azure_ad_response_to_groupname_attr（默认displayName）；
• azure_ad_response_to_groupname_regex（默认(.*)）。

注意：文档正文描述默认使用name属性，而AzureADConfig中该配置项的默认值为displayName（见 azure_ad.py）。从源码结构看，实际生效的属性名以azure_ad_response_to_groupname_attr的默认值displayName为准；建议在使用前结合目标租户的响应结构确认。

组信息（Responses）

连接器提取 Azure AD Group Response 中的以下字段并映射到 DataHub 的CorpGroupInfoaspect：

• name（组名）
• description（描述）

源码映射（见 azure_ad.py）还补充了email（来自mail字段），并预留了members、groups、admins等列表字段。

提取组成员关系（Extracting Group Membership）

连接器额外提取 Azure AD 中存储的用户与组之间的边（edge），映射为与 DataHub 用户（CorpUser）关联的GroupMembershipaspect。底层调用 Microsoft Graph 的组会员列表接口（/groups/{group_id}/members，见 azure_ad.py）。

从源码看，该过程有两个值得注意的设计点：

1. 嵌套组展开：Azure 支持嵌套组，但 DataHub 不支持。源码在遍历组成员时，遇到@odata.type == "#microsoft.graph.group"的成员会递归展开其成员并归并到父组（而不是嵌套组）名下（见 azure_ad.py）；
2. 其他对象类型跳过：既非用户也非组的成员类型会被记录 warning 并跳过（见 azure_ad.py）。

摄取执行流程与底层实现

从 azure_ad.py 的get_workunits_internal可以看出，摄取逻辑严格按如下顺序执行（源码注释也明确提示了这一点）：

1. 先摄取组（Groups）：拉取/groups数据，逐批映射为CorpGroupSnapshot，并发出OriginClass与StatusClass(removed=False)两个 MCP；
2. 再摄取组成员关系（Membership）：遍历已选中的组，调用/groups/{id}/members，把用户归并到各自的GroupMembershipaspect 中；
3. 最后摄取用户（Users）：拉取/users数据，映射为CorpUserSnapshot，并把第 2 步累积的成员关系 aspect 附加到对应用户上，同时发出 origin 与 status MCP。

分页与重试：_get_azure_ad_data通过响应中的@odata.nextLink持续翻页直至取完所有数据；HTTP 会话配置了Retry(total=5, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])，即对限流（429）和常见 5xx 错误自动重试最多 5 次（见 azure_ad.py）。

过滤逻辑：组与用户的过滤在 URN 构造之前进行——正则未匹配或不在groups_pattern/users_pattern允许范围内（或属性缺失）的实体会被记录到报告的filtered列表，而不是被当作失败（见 azure_ad.py）。

令牌获取：get_token使用客户端凭证流，向token_urlPOST 表单数据（grant_type=client_credentials、client_id、client_secret、resource=https://graph.microsoft.com、scope=https://graph.microsoft.com/.default），拿到的access_token用于后续所有 Graph 请求的Authorization: Bearer <token>头（见 azure_ad.py）。注意该 Source 仅支持 v1.0 token 端点。

Limitations 与 Troubleshooting

限制（Limitations）

模块行为受限于源平台的 API、权限与可暴露的元数据。例如：嵌套组会被展开而非保留层级结构；组会员接口中非用户/非组的对象类型会被跳过；登录 DataHub 依赖 OIDC SSO 配置（见上文 SSO Caveat）。

故障排查（Troubleshooting）

如果摄取失败，请按以下顺序排查：

1. 验证凭证：client_id、tenant_id、client_secret是否正确，密钥是否过期；
2. 验证权限：是否已为应用注册授予Group.Read.All、GroupMember.Read.All、User.Read.All三项 Application 权限，且租户管理员已完成同意（admin consent）；
3. 验证连通性：执行环境能否访问graph_url与token_url；
4. 核对过滤范围：groups_pattern/users_pattern是否误过滤掉了目标实体（被过滤实体记录在报告的 filtered 列表而非 failures 中，可据此区分是配置问题还是数据问题）；
5. 查看摄取日志：关注报告中 source-specific 的错误信息（如令牌获取失败、Graph API 返回非 200 等，源码均通过self.report.failure(...)记录上下文），据此调整配置。

小结

DataHub 的azure-ad连接器为生产环境同步 Microsoft Entra ID 身份数据提供了完整链路：从应用注册与 API 权限配置，到 Recipe 中十余个可调参数，再到用户/组/成员关系的实体映射与状态化删除检测。理解AzureADConfig各字段的作用、CorpUserInfo/CorpGroupInfo/GroupMembership/corpUserStatus等 aspect 的映射规则，以及"先组、再成员关系、后用户"的执行顺序，是保障身份数据准确落库的关键。相关文档与源码入口：README.md、azure-ad_pre.md、azure-ad_post.md、azure-ad_recipe.yml、azure_ad.py。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub