Skip to main content

Azure AD

Extracting DataHub Users​

Usernames​

Usernames serve as unique identifiers for users on DataHub. This connector extracts usernames using the "userPrincipalName" field of an Azure AD User Response, which is the unique identifier for your Azure AD users.

If this is not how you wish to map to DataHub usernames, you can provide a custom mapping using the configurations options detailed below. Namely, azure_ad_response_to_username_attr and azure_ad_response_to_username_regex.

Responses​

This connector also extracts basic user response information from Azure. The following fields of the Azure User Response are extracted and mapped to the DataHub CorpUserInfo aspect:

  • display name
  • first name
  • last name
  • email
  • title
  • country

Extracting DataHub Groups​

Group Names​

Group names serve as unique identifiers for groups on DataHub. This connector extracts group names using the "name" attribute of an Azure Group Response. By default, a URL-encoded version of the full group name is used as the unique identifier (CorpGroupKey) and the raw "name" attribute is mapped as the display name that will appear in DataHub's UI.

If this is not how you wish to map to DataHub group names, you can provide a custom mapping using the configurations options detailed below. Namely, azure_ad_response_to_groupname_attr and azure_ad_response_to_groupname_regex.

Responses​

This connector also extracts basic group information from Azure. The following fields of the Azure AD Group Response are extracted and mapped to the DataHub CorpGroupInfo aspect:

  • name
  • description

Extracting Group Membership​

This connector additional extracts the edges between Users and Groups that are stored in Azure AD. It maps them to the GroupMembership aspect associated with DataHub users (CorpUsers). Today this has the unfortunate side effect of overwriting any Group Membership information that was created outside of the connector. That means if you've used the DataHub REST API to assign users to groups, this information will be overridden when the Azure AD Source is executed. If you intend to always pull users, groups, and their relationships from your Identity Provider, then this should not matter.

This is a known limitation in our data model that is being tracked by this ticket.Certified

Important Capabilities​

CapabilityStatusNotes
Detect Deleted Entities✅Optionally enabled via stateful_ingestion

This plugin extracts the following:

  • Users
  • Groups
  • Group Membership

from your Azure AD instance.

Note that any users ingested from this connector will not be able to log into DataHub unless you have Azure AD OIDC SSO enabled. You can, however, have these users ingested into DataHub before they log in for the first time if you would like to take actions like adding them to a group or assigning them a role.

For instructions on how to do configure Azure AD OIDC SSO, please read the documentation here.

Extracting DataHub Users​

Usernames​

Usernames serve as unique identifiers for users on DataHub. This connector extracts usernames using the "userPrincipalName" field of an Azure AD User Response, which is the unique identifier for your Azure AD users.

If this is not how you wish to map to DataHub usernames, you can provide a custom mapping using the configurations options detailed below. Namely, azure_ad_response_to_username_attr and azure_ad_response_to_username_regex.

Responses​

This connector also extracts basic user response information from Azure. The following fields of the Azure User Response are extracted and mapped to the DataHub CorpUserInfo aspect:

  • display name
  • first name
  • last name
  • email
  • title
  • country

Extracting DataHub Groups​

Group Names​

Group names serve as unique identifiers for groups on DataHub. This connector extracts group names using the "name" attribute of an Azure Group Response. By default, a URL-encoded version of the full group name is used as the unique identifier (CorpGroupKey) and the raw "name" attribute is mapped as the display name that will appear in DataHub's UI.

If this is not how you wish to map to DataHub group names, you can provide a custom mapping using the configurations options detailed below. Namely, azure_ad_response_to_groupname_attr and azure_ad_response_to_groupname_regex.

Responses​

This connector also extracts basic group information from Azure. The following fields of the Azure AD Group Response are extracted and mapped to the DataHub CorpGroupInfo aspect:

  • name
  • description

Extracting Group Membership​

This connector additional extracts the edges between Users and Groups that are stored in Azure AD. It maps them to the GroupMembership aspect associated with DataHub users (CorpUsers).

Prerequisite​

Create a DataHub Application within the Azure AD Portal with the permissions to read your organization's Users and Groups. The following permissions are required, with the Application permission type:

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

CLI based Ingestion​

Install the Plugin​

pip install 'acryl-datahub[azure-ad]'

Starter Recipe​

Check out the following recipe to get started with ingestion! See below for full configuration options.

For general pointers on writing and running a recipe, see our main recipe guide.

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

Config Details​

Note that a . is used to denote nested fields in the YAML recipe.

FieldDescription
authority ✅
string
The authority (https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-client-application-configuration) is a URL that indicates a directory that MSAL can request tokens from.
client_id ✅
string
Application ID. Found in your app registration on Azure AD Portal
client_secret ✅
string
Client secret. Found in your app registration on Azure AD Portal
tenant_id ✅
string
Directory ID. Found in your app registration on Azure AD Portal
token_url ✅
string
The token URL that acquires a token from Azure AD for authorizing requests. This source will only work with v1.0 endpoint.
azure_ad_response_to_groupname_attr
string
Which Azure AD Group Response attribute to use as input to DataHub group name mapping.
Default: displayName
azure_ad_response_to_groupname_regex
string
A regex used to parse the DataHub group name from the attribute specified in azure_ad_response_to_groupname_attr.
Default: (.*)
azure_ad_response_to_username_attr
string
Which Azure AD User Response attribute to use as input to DataHub username mapping.
Default: userPrincipalName
azure_ad_response_to_username_regex
string
A regex used to parse the DataHub username from the attribute specified in azure_ad_response_to_username_attr.
Default: (.*)
filtered_tracking
boolean
If enabled, report will contain names of filtered users and groups.
Default: True
graph_url
string
Microsoft Graph API endpoint
Default: https://graph.microsoft.com/v1.0
ingest_group_membership
boolean
Whether group membership should be ingested into DataHub. ingest_groups must be True if this is True.
Default: True
ingest_groups
boolean
Whether groups should be ingested into DataHub.
Default: True
ingest_groups_users
boolean
This option is useful only when ingest_users is set to False and ingest_group_membership to True. As effect, only the users which belongs to the selected groups will be ingested.
Default: True
ingest_users
boolean
Whether users should be ingested into DataHub.
Default: True
mask_group_id
boolean
Whether workunit ID's for groups should be masked to avoid leaking sensitive information.
Default: True
mask_user_id
boolean
Whether workunit ID's for users should be masked to avoid leaking sensitive information.
Default: True
platform_instance
string
The instance of the platform that all assets produced by this recipe belong to
redirect
string
Redirect URI. Found in your app registration on Azure AD Portal.
Default: https://login.microsoftonline.com/common/oauth2/na...
env
string
The environment that all assets produced by this connector belong to
Default: PROD
groups_pattern
AllowDenyPattern
regex patterns for groups to include in ingestion.
Default: {'allow': ['.*'], 'deny': [], 'ignoreCase': True}
groups_pattern.allow
array(string)
groups_pattern.deny
array(string)
groups_pattern.ignoreCase
boolean
Whether to ignore case sensitivity during pattern matching.
Default: True
users_pattern
AllowDenyPattern
regex patterns for users to filter in ingestion.
Default: {'allow': ['.*'], 'deny': [], 'ignoreCase': True}
users_pattern.allow
array(string)
users_pattern.deny
array(string)
users_pattern.ignoreCase
boolean
Whether to ignore case sensitivity during pattern matching.
Default: True
stateful_ingestion
StatefulStaleMetadataRemovalConfig
Azure AD Stateful Ingestion Config.
stateful_ingestion.enabled
boolean
The type of the ingestion state provider registered with datahub.
Default: False
stateful_ingestion.remove_stale_metadata
boolean
Soft-deletes the entities present in the last successful run but missing in the current run with stateful_ingestion enabled.
Default: True

As a prerequisite, you should create a DataHub Application within the Azure AD Portal with the permissions to read your organization's Users and Groups. The following permissions are required, with the Application permission type:

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

You can add a permission by navigating to the permissions tab in your DataHub application on the Azure AD portal. Azure AD API Permissions

You can view the necessary endpoints to configure by clicking on the Endpoints button in the Overview tab. Azure AD Endpoints

Code Coordinates​

  • Class Name: datahub.ingestion.source.identity.azure_ad.AzureADSource
  • Browse on GitHub

Questions

If you've got any questions on configuring ingestion for Azure AD, feel free to ping us on our Slack.