DataHub 集成 Microsoft Entra IDAzure AD身份元数据摄取指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubMicrosoft 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 ConceptDataHub ConceptNotesOwnership 与协作主体Ownership and collaboration principalsCorpUser, CorpGroup由支持所有权与身份元数据的模块发出从源码可以进一步确认用户在 DataHub 中映射为CorpUserSnapshot组映射为CorpGroupSnapshot并额外发出OriginClass(OriginTypeClass.EXTERNAL, AZURE_AD)标记数据来源为外部系统见 azure_ad.py 与 azure_ad.py。Prerequisites前置条件在运行摄取之前需要确保网络连通性DataHub 摄取执行环境能够访问 Microsoft Graph API 端点有效认证凭证Azure AD 应用注册App Registration的 Application ID、Directory ID租户 ID与 Client Secret元数据 API 的读取权限授予应用注册读取身份元数据所需的 API 权限。必需的 Azure AD 应用权限Application 权限在 Azure AD 门户中为 DataHub 创建一个应用注册并授予以下Application类型权限应用权限而非委派权限Group.Read.AllGroupMember.Read.AllUser.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.ymlsource: 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必填无授权机构 URLMSAL 据此向目录请求令牌token_url必填无获取令牌的 Token URL。该 Source 仅支持 v1.0 端点redirect可选https://login.microsoftonline.com/common/oauth2/nativeclient重定向 URI可在应用注册中找到graph_url可选https://graph.microsoft.com/v1.0Microsoft Graph API 端点ingest_users可选True是否摄取用户到 DataHubingest_groups可选True是否摄取组到 DataHubingest_group_membership可选True是否摄取组成员关系若为True则ingest_groups必须为Trueingest_groups_users可选True仅在ingest_usersFalse且ingest_group_membershipTrue时有用只摄取属于所选组的用户users_pattern可选允许全部摄取用户的 regex 过滤模式AllowDenyPatterngroups_pattern可选允许全部摄取组的 regex 过滤模式AllowDenyPatternazure_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组的工作单元WorkUnitID 是否脱敏避免泄漏敏感信息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 的CorpUserInfoaspectdisplay name显示名first name名last name姓emailtitle职位country国家/地区对应源码映射见 azure_ad.pyCorpUserInfoClass( activecorp_user_info_active_from_status(user_status), displayNameazure_ad_user.get(displayName, full_name), firstNameazure_ad_user.get(givenName, None), lastNameazure_ad_user.get(surname, None), fullNamefull_name, # givenName surname emailazure_ad_user.get(mail), titleazure_ad_user.get(jobTitle, None), countryCodeazure_ad_user.get(mobilePhone, None), )用户状态User Status连接器为每个用户同时发出两个 aspectcorpUserInfo.activecorpUserStatus状态推导规则见 corp_user_status.pyAzure ADaccountEnabled: false→ DataHubSUSPENDED且active: falseaccountEnabled为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默认displayNameazure_ad_response_to_groupname_regex默认(.*)。注意文档正文描述默认使用name属性而AzureADConfig中该配置项的默认值为displayName见 azure_ad.py。从源码结构看实际生效的属性名以azure_ad_response_to_groupname_attr的默认值displayName为准建议在使用前结合目标租户的响应结构确认。组信息Responses连接器提取 Azure AD Group Response 中的以下字段并映射到 DataHub 的CorpGroupInfoaspectname组名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。从源码看该过程有两个值得注意的设计点嵌套组展开Azure 支持嵌套组但 DataHub 不支持。源码在遍历组成员时遇到odata.type #microsoft.graph.group的成员会递归展开其成员并归并到父组而不是嵌套组名下见 azure_ad.py其他对象类型跳过既非用户也非组的成员类型会被记录 warning 并跳过见 azure_ad.py。摄取执行流程与底层实现从 azure_ad.py 的get_workunits_internal可以看出摄取逻辑严格按如下顺序执行源码注释也明确提示了这一点先摄取组Groups拉取/groups数据逐批映射为CorpGroupSnapshot并发出OriginClass与StatusClass(removedFalse)两个 MCP再摄取组成员关系Membership遍历已选中的组调用/groups/{id}/members把用户归并到各自的GroupMembershipaspect 中最后摄取用户Users拉取/users数据映射为CorpUserSnapshot并把第 2 步累积的成员关系 aspect 附加到对应用户上同时发出 origin 与 status MCP。分页与重试_get_azure_ad_data通过响应中的odata.nextLink持续翻页直至取完所有数据HTTP 会话配置了Retry(total5, backoff_factor1, 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_typeclient_credentials、client_id、client_secret、resourcehttps://graph.microsoft.com、scopehttps://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如果摄取失败请按以下顺序排查验证凭证client_id、tenant_id、client_secret是否正确密钥是否过期验证权限是否已为应用注册授予Group.Read.All、GroupMember.Read.All、User.Read.All三项 Application 权限且租户管理员已完成同意admin consent验证连通性执行环境能否访问graph_url与token_url核对过滤范围groups_pattern/users_pattern是否误过滤掉了目标实体被过滤实体记录在报告的 filtered 列表而非 failures 中可据此区分是配置问题还是数据问题查看摄取日志关注报告中 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考