Skip to main content

Microsoft Entra ID provider

Enterprise

The Entra ID provider allows you to integrate with your Entra ID tenant. It supports syncing users and groups from authentik to Entra ID, allowing authentik to act as a source of truth for all users and groups.

If you also want to authenticate to Entra ID using authentik credentials, refer to our Microsoft 365 SAML or Microsoft 365 WS-Federation integrations guides.

Discovery​

Upon creating the Entra ID provider, it will run a discovery task to query your Entra ID tenant for all users and groups, and attempt to match them with their respective counterparts in authentik.

Users are matched on their email address. Groups are matched based on their names.

This discovery also takes into consideration any User filtering options configured in the provider, such as only linking to authentik users in a specific group or excluding service accounts. This discovery process occurs each time a full sync is initiated.

Synchronization​

There are two types of synchronization: direct sync and full sync.

Direct sync​

A direct sync occurs when a user or group is created, updated or deleted in authentik, or when a user is added to or removed from a group. When any of these events occur, the direct sync automatically syncs those changes to Entra ID.

Full sync​

A full sync occurs when the provider is initially created and when it is saved. During a full sync, all users and groups that match the User filtering settings are processed and created or updated in Entra ID. After the initial sync, authentik automatically performs a full sync every four hours by default to maintain consistency between users and groups.

During the full sync, if a user or group exists in both authentik and Entra ID, authentik will automatically link them.

Additionally, any users or groups present in authentik but absent in Entra ID will be created and linked.

Deletion and offboarding​

The provider's User deletion action and Group deletion action control what happens to the linked Entra ID object when you delete its counterpart in authentik. Both settings default to Delete. Deletion is processed by a background sync task and requires the provider to remain assigned to an application. Dry-run mode prevents changes to the remote directory.

ActionWhen an authentik user is deletedWhen an authentik group is deleted
Delete (delete, default)Deletes the linked Entra ID user account.Deletes the linked Entra ID group.
Suspend (suspend)Keeps the Entra ID account and disables sign-in by setting Microsoft Graph's accountEnabled to false.Unsupported. Treated as Do Nothing, leaving the remote group unchanged.
Do Nothing (do_nothing)Leaves the Entra ID account unchanged, including its enabled or suspended status.Leaves the Entra ID group unchanged.

All three actions remove authentik's connection record for the deleted user or group. Suspend retains the remote user account; it does not retain the deleted authentik user. Do Nothing does not revoke access to the remote account.

In the Admin interface, User deletion action offers Delete, Suspend, and Do Nothing. Suspension applies only to users, so Group deletion action offers Delete and Do Nothing.

Deactivate a user without deleting the account​

Marking an authentik user inactive is an update, so it does not use User deletion action. With the default user property mapping, authentik sets account_enabled to False, which becomes accountEnabled: false in Microsoft Graph. The authentik user and its connection record remain, and reactivating the user allows the default mapping to enable the remote account again.

This requires the user to remain included in synchronization. Custom property mappings can change whether active status is synchronized.

Offboard users and groups​

  • To retain a user's accounts while disabling sign-in, mark the authentik user inactive and verify that synchronization has disabled the Entra ID account before removing the user from synchronization filters.
  • To delete an authentik user while retaining the remote account, select Suspend for User deletion action before deleting the user. Use Do Nothing only if you intend to manage the remote account's access separately.
  • To delete the remote user or group as well, use Delete. Complete any required data retention or ownership transfers in Entra ID before deleting the authentik object.
  • After offboarding, check the provider's sync tasks for errors and verify the account or group state in Entra ID.

Removing a user from the provider's filtering group, changing User filtering to exclude the user, or skipping a user with SkipObject does not itself delete or suspend the remote account. These changes exclude the user from provisioning updates. Removing group membership can also remove that membership in Entra ID, but it does not disable the account.

Do not rely on filtering alone to revoke access. If you later delete a previously linked authentik user, its retained connection record still allows the configured deletion action to run.

Error handling​

Property mappings are evaluated in name order. If a property mapping fails to evaluate, authentik stops the synchronization and does not evaluate the remaining mappings.

To handle network interruptions, authentik detects transient request failures and retries sync tasks.

Property mapping​

There are several considerations regarding how authentik data is mapped to Entra ID user and group data.

Users​

For users, authentik only saves the full display name, not separate first and family names.

By default, authentik maps a user's email address, name, and whether the user is active.

Refer to the Entra ID documentation for further details on which attributes can be mapped: Microsoft Graph - Create User

Groups​

By default, authentik only maps a group's name, mail_enabled status, security_enabled status and mail_nickname (equivalent to name).

Refer to the Entra ID documentation for further details on these attributes and which attributes can be mapped: Microsoft Graph - Create Group

Skip objects during synchronization​

To exclude specific users or groups from Entra ID synchronization, you can create a property mapping that raises the SkipObject exception. When this exception is raised during the evaluation of a property mapping, the object is skipped and the sync continues with the next object.

For more information, refer to Skip objects during synchronization.