From 51d639a391b38aaaa14e2c074810bbc271ed5d6f Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 10:19:07 +0100 Subject: [PATCH 01/12] Create directories, oauth, scim and overview docs --- .../sources/social-logins/entra-id/index.mdx | 98 +++-------------- .../social-logins/entra-id/oauth/index.mdx | 100 ++++++++++++++++++ .../social-logins/entra-id/scim/index.mdx | 81 ++++++++++++++ 3 files changed, 196 insertions(+), 83 deletions(-) create mode 100644 website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx create mode 100644 website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index 7a0b29d5f8f8..291521391400 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -1,99 +1,31 @@ --- -title: Entra ID -support_level: community +title: Entra ID Identity Providers +sidebar_label: Entra ID tags: - source - entra - azure - active-directory + - scim + - oauth --- -## Preparation - -The following placeholders are used in this guide: - -- `authentik.company` is the FQDN of the authentik install. - -## Entra ID configuration - -1. Log in to [Entra ID](https://entra.microsoft.com) using a [global administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) account. -2. Navigate to **Applications** > **App registrations**. -3. Click **New registration** and set the following required configurations: - - **Name**: provide a descriptive name (e.g. `authentik`). - - Under **Supported account types**: select the account type that applies to your use-case (e.g. `Accounts in this organizational directory only (Default Directory only - Single tenant)`). - - Under **Redirect URI**: - - **Platform**: `Web` - - **URI**: `https://authentik.company/source/oauth/callback/entra-id/ - -4. Click **Register**. Once the registration is complete, the **Overview** tab of the newly created authentik app will open. Take note of the `Application (client) ID`. If you selected `Accounts in this organizational directory only (Default Directory only - Single tenant)` as the **Supported account types**, also note the `Directory (tenant) ID`. These values will be needed later when configuring authentik. -5. In the leftmost sidebar, navigate to **Certificates & secrets**. -6. Select the **Client secrets** tab and click **New Secret**. Configure the following required settings: - - **Description**: provide a description for the secret (e.g. `authentik secret`. - - **Expires**: choose an expiration period. As authentik does not yet support automatic secret rotation, either manual rotation or API-based updates are required. As a result, a duration of at least 12 months is recommended. -7. Copy the secret's value from the **Value** column. - -:::info -The secret value is only displayed once at the time of creation. Make sure to copy and store it securely, as it cannot be retrieved later. -::: - -8. In the sidebar, navigate to **API Permissions**, then click **Add a permission** and select **Microsoft Graph** as the API. -9. Select **Delegated permissions** as the permission type and assign the following permissions: - - Under **OpenID Permissions**: select `email`, `profile`, and `openid`. - - Under **Group Member** _(optional)_: if you need authentik to sync group membership information from Entra ID, select the `GroupMember.Read.All` permission. -10. Click **Add permissions**. -11. _(optional)_ If the `GroupMember.Read.All` permission has been selected, under **Configured permissions**, click **Grant admin consent for default directory**. - -## authentik configuration - -To support the integration of Entra ID with authentik, you need to create an Entra ID OAuth source in authentik. - -### Create Entra ID OAuth source - -1. Log in to authentik as an administrator and open the authentik Admin interface. -2. Navigate to **Directory** > **Federation and Social login**, click **Create**, and then configure the following settings: - - **Select type**: select **Entra ID OAuth Source** as the source type. - - **Create Entra ID OAuth Source**: provide a name, a slug which must match the slug used in the Entra ID `Redirect URI`, and the following required configurations: - - Under **Protocol Settings**: - - **Consumer key**: `Application (client) ID` from Entra ID. - - **Consumer secret**: value of the secret created in Entra ID. - - **Scopes**_(optional)_: if you need authentik to sync group membership information from Entra ID, add the `https://graph.microsoft.com/GroupMember.Read.All` scope. - - Under **URL Settings**: - - For **Single tenant** Entra ID applications: - - **Authorization URL**: `https://login.microsoftonline.com//oauth2/v2.0/authorize` - - **Access token URL**: `https://login.microsoftonline.com//oauth2/v2.0/token` - - **Profile URL**: `https://graph.microsoft.com/v1.0/me` - - **OIDC JWKS URL**: `https://login.microsoftonline.com//discovery/v2.0/keys` - - For **Multi tenant** Entra ID applications: - - **Authorization URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` - - **Access token URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/token` - - **Profile URL**: `https://graph.microsoft.com/v1.0/me` - - **OIDC JWKS URL**: `https://login.microsoftonline.com/common/discovery/v2.0/keys` - -3. Click **Save**. +--- -:::info -When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. -::: +Entra ID provides several services that can be integrated with authentik: -:::info -For instructions on how to display the new source on the authentik login page, refer to the [Add sources to default login page documentation](../../index.md#add-sources-to-default-login-page). -::: + - OAuth integration allows users to sign into authentik using their Entra ID credentials. Accounts and groups are created upon first login. + - SCIM integration provisions users and groups from Entra ID to authentik. + - Optionally, both integrations can be used in conjunction so that users and groups are provisioned before a user signs in. -### Machine-to-machine authentication :ak-version[2024.12] +## OAuth -If using [Machine-to-Machine](../../../../add-secure-apps/providers/oauth2/client_credentials.mdx#jwt-authentication) authentication, some specific steps need to be considered. +Entra ID provides OAuth 2.0 as a federated identity provider. This guide covers how to set up OAuth 2.0 as an authentication method between Entra ID and authentik. -When getting the JWT token from Entra ID, set the scope to the **Application ID URI**, and _not_ the Graph URL; otherwise the JWT will be in an invalid format. +[Configure Entra ID OAuth with authentik](./oauth/index.mdx) -```http -POST //oauth2/v2.0/token/ HTTP/1.1 -Host: login.microsoftonline.com -Content-Type: application/x-www-form-urlencoded +## SCIM -grant_type=client_credentials& -client_id=& -scope=api:///.default& -client_secret= -``` +This guide covers how to provision users and groups via SCIM from Entra ID into authentik. -The JWT returned from the request above can be used in authentik and exchanged for an authentik JWT. +[Configure Entra ID SCIM with authentik](./scim/index.mdx) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx new file mode 100644 index 000000000000..b5e0c0f0712a --- /dev/null +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -0,0 +1,100 @@ +--- +title: Entra ID +support_level: community +tags: + - source + - entra + - azure + - active-directory + - oauth +--- + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik install. + +## Entra ID configuration + +1. Log in to [Entra ID](https://entra.microsoft.com) using a [global administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) account. +2. Navigate to **Applications** > **App registrations**. +3. Click **New registration** and set the following required configurations: + - **Name**: provide a descriptive name (e.g. `authentik`). + - Under **Supported account types**: select the account type that applies to your use-case (e.g. `Accounts in this organizational directory only (Default Directory only - Single tenant)`). + - Under **Redirect URI**: + - **Platform**: `Web` + - **URI**: `https://authentik.company/source/oauth/callback/entra-id/ + +4. Click **Register**. Once the registration is complete, the **Overview** tab of the newly created authentik app will open. Take note of the `Application (client) ID`. If you selected `Accounts in this organizational directory only (Default Directory only - Single tenant)` as the **Supported account types**, also note the `Directory (tenant) ID`. These values will be needed later when configuring authentik. +5. In the leftmost sidebar, navigate to **Certificates & secrets**. +6. Select the **Client secrets** tab and click **New Secret**. Configure the following required settings: + - **Description**: provide a description for the secret (e.g. `authentik secret`. + - **Expires**: choose an expiration period. As authentik does not yet support automatic secret rotation, either manual rotation or API-based updates are required. As a result, a duration of at least 12 months is recommended. +7. Copy the secret's value from the **Value** column. + +:::info +The secret value is only displayed once at the time of creation. Make sure to copy and store it securely, as it cannot be retrieved later. +::: + +8. In the sidebar, navigate to **API Permissions**, then click **Add a permission** and select **Microsoft Graph** as the API. +9. Select **Delegated permissions** as the permission type and assign the following permissions: + - Under **OpenID Permissions**: select `email`, `profile`, and `openid`. + - Under **Group Member** _(optional)_: if you need authentik to sync group membership information from Entra ID, select the `GroupMember.Read.All` permission. +10. Click **Add permissions**. +11. _(optional)_ If the `GroupMember.Read.All` permission has been selected, under **Configured permissions**, click **Grant admin consent for default directory**. + +## authentik configuration + +To support the integration of Entra ID with authentik, you need to create an Entra ID OAuth source in authentik. + +### Create Entra ID OAuth source + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Directory** > **Federation and Social login**, click **Create**, and then configure the following settings: + - **Select type**: select **Entra ID OAuth Source** as the source type. + - **Create Entra ID OAuth Source**: provide a name, a slug which must match the slug used in the Entra ID `Redirect URI`, and the following required configurations: + - Under **Protocol Settings**: + - **Consumer key**: `Application (client) ID` from Entra ID. + - **Consumer secret**: value of the secret created in Entra ID. + - **Scopes**_(optional)_: if you need authentik to sync group membership information from Entra ID, add the `https://graph.microsoft.com/GroupMember.Read.All` scope. + - Under **URL Settings**: + - For **Single tenant** Entra ID applications: + - **Authorization URL**: `https://login.microsoftonline.com//oauth2/v2.0/authorize` + - **Access token URL**: `https://login.microsoftonline.com//oauth2/v2.0/token` + - **Profile URL**: `https://graph.microsoft.com/v1.0/me` + - **OIDC JWKS URL**: `https://login.microsoftonline.com//discovery/v2.0/keys` + - For **Multi tenant** Entra ID applications: + - **Authorization URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` + - **Access token URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/token` + - **Profile URL**: `https://graph.microsoft.com/v1.0/me` + - **OIDC JWKS URL**: `https://login.microsoftonline.com/common/discovery/v2.0/keys` + +3. Click **Save**. + +:::info +When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. +::: + +:::info +For instructions on how to display the new source on the authentik login page, refer to the [Add sources to default login page documentation](../../../index.md#add-sources-to-default-login-page). +::: + +### Machine-to-machine authentication :ak-version[2024.12] + +If using [Machine-to-Machine](../../../../../add-secure-apps/providers/oauth2/client_credentials.mdx#jwt-authentication) authentication, some specific steps need to be considered. + +When getting the JWT token from Entra ID, set the scope to the **Application ID URI**, and _not_ the Graph URL; otherwise the JWT will be in an invalid format. + +```http +POST //oauth2/v2.0/token/ HTTP/1.1 +Host: login.microsoftonline.com +Content-Type: application/x-www-form-urlencoded + +grant_type=client_credentials& +client_id=& +scope=api:///.default& +client_secret= +``` + +The JWT returned from the request above can be used in authentik and exchanged for an authentik JWT. diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx new file mode 100644 index 000000000000..d6641ab7dd33 --- /dev/null +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -0,0 +1,81 @@ +--- +title: Entra ID +support_level: community +tags: + - source + - entra + - azure + - scim +--- + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik install. + +## authentik configuration + +To integrate authentik with Entra ID via SCIM you will first need to create a SCIM source in authentik. + +### Create SCIM source + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Directory** > **Federation and Social login**, click **Create**, and then configure the following settings: + - **Select type**: select **SCIM Source**. + - **Create SCIM Source**: provide a name and a slug. All other configurations are optional. +3. Click **Finish**. +4. On the **Federation and Social login** page, click on the name of the newly created SCIM source. +5. Take note of the **SCIM Base URL**. This value will be required in the next section. +6. Under **Token**, click **Click to copy token** and securely store the value. This value will also be required in the next section. + +:::note Copying the token +If authentik has the required browser permissions, the token will be copied into your clipboard after clicking **Click to copy token** button. However, some browsers don't allow this, in those cases a notification will appear in the bottom right corner with the token and you will need to manually copy it. +::: + +## Entra ID configuration + +### Create a custom enterprise application + +1. Log in to [Entra ID](https://entra.microsoft.com) using a [global administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) account. +2. Navigate to **Enterprise apps**, click **Create your own application** and then configure the following fields: + - **Name**: provide a name for the application (e.g. `authentik-scim`). + - Select `Integrate any other application you don't find in the gallery (Non-gallery)`. +3. Click **Create**. + +### Configure provisioning + +4. Navigate to **Provisioning**, click **New Configuration** and then configure the following fields: + - **Tenant URL**: Set to the **SCIM Base URL** from authentik. + - **Secret Token**: Set to the **Token** from authentik. +5. Click **Test connection** to validate that Entra ID can communicate with authentik. +6. If the connection is successful, click **Create** and **Save**. If the connection fails, ensure that your authentik **SCIM Base URL** is accessible from the internet. +7. In the left sidebar, under **Manage**, click **Provisioning**. + +There are three options to determine which users and groups are provisioned to authentik: + + - Set Entra ID to sync all users and groups + - Set Entra ID to sync all users and groups with scopes to determine which users and groups are synced + - Set Entra ID to sync only assigned users and groups (Group assignment is only available to Microsoft Entra Suite, Microsoft Entra ID Governance and Microsoft Entra ID P2 customers) + +#### Sync all users and groups + +1. On the **Provisioning** page, expand the **Settings** section and then set **Scope** to `Sync all users and groups`. +2. Toggle **Provisioning status** to `On`. +3. At the top of the screen, click **Save**. + +#### Sync all users and groups with scopes + +1. On the **Provisioning** page, expand the **Settings** section and then set **Scope** to `Sync all users and groups`. +2. At the top of the screen, click **Save**. +3. Expand the **Mappings** section and then click **Provision Microsoft Entra ID Users**. +4. Under **Source Object Scope** + +5. On the **Provisioning** page, toggle **Provisioning status** to `On`. +6. At the top of the screen, click **Save**. + +#### Sync only assigned users and groups + +:::note +Group assignment is only available to Microsoft Entra Suite, Microsoft Entra ID Governance and Microsoft Entra ID P2 customers +::: From 99da2390c1bc0549714bfdc108bcb2c969b17b18 Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 11:06:46 +0100 Subject: [PATCH 02/12] Minor changes to overview --- .../users-sources/sources/social-logins/entra-id/index.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index 291521391400..fd742e5471c8 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -10,8 +10,6 @@ tags: - oauth --- ---- - Entra ID provides several services that can be integrated with authentik: - OAuth integration allows users to sign into authentik using their Entra ID credentials. Accounts and groups are created upon first login. @@ -26,6 +24,6 @@ Entra ID provides OAuth 2.0 as a federated identity provider. This guide covers ## SCIM -This guide covers how to provision users and groups via SCIM from Entra ID into authentik. +This guide covers how to provision users and groups from Entra ID into authentik via SCIM. [Configure Entra ID SCIM with authentik](./scim/index.mdx) From edeb5b7a230ae493dba7e5e8e0e15c071c83db2b Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 13:15:21 +0100 Subject: [PATCH 03/12] Update sidebar and complete docs --- website/docs/sidebar.mjs | 13 +++- .../sources/social-logins/entra-id/index.mdx | 14 ++--- .../social-logins/entra-id/oauth/index.mdx | 36 ++++++++--- .../social-logins/entra-id/scim/index.mdx | 61 +++++++++++++------ 4 files changed, 86 insertions(+), 38 deletions(-) diff --git a/website/docs/sidebar.mjs b/website/docs/sidebar.mjs index f0d934b8bff0..6279df4bd15f 100644 --- a/website/docs/sidebar.mjs +++ b/website/docs/sidebar.mjs @@ -553,8 +553,19 @@ const items = [ }, items: [ "users-sources/sources/social-logins/apple/index", - "users-sources/sources/social-logins/entra-id/index", "users-sources/sources/social-logins/discord/index", + { + type: "category", + label: "Entra ID", + link: { + type: "doc", + id: "users-sources/sources/social-logins/entra-id/index", + }, + items: [ + "users-sources/sources/social-logins/entra-id/oauth/index", + "users-sources/sources/social-logins/entra-id/scim/index", + ], + }, "users-sources/sources/social-logins/facebook/index", "users-sources/sources/social-logins/github/index", { diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index fd742e5471c8..062d6b782efe 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -12,18 +12,14 @@ tags: Entra ID provides several services that can be integrated with authentik: - - OAuth integration allows users to sign into authentik using their Entra ID credentials. Accounts and groups are created upon first login. - - SCIM integration provisions users and groups from Entra ID to authentik. - - Optionally, both integrations can be used in conjunction so that users and groups are provisioned before a user signs in. + - **OAuth integration** allows users to sign into authentik using their Entra ID credentials. Accounts and groups are created upon first login. + - **SCIM integration** provisions users and groups from Entra ID to authentik. + - Optionally, both integrations can be used in conjunction so that users and groups are provisioned before a user signs in using their Entra ID credentials. This is the recommended setup for organizations with large numbers of users and groups. ## OAuth -Entra ID provides OAuth 2.0 as a federated identity provider. This guide covers how to set up OAuth 2.0 as an authentication method between Entra ID and authentik. - -[Configure Entra ID OAuth with authentik](./oauth/index.mdx) +The [Entra ID OAuth](./oauth/index.mdx) guide explains how to set up OAuth 2.0 as an authentication method between Entra ID and authentik. ## SCIM -This guide covers how to provision users and groups from Entra ID into authentik via SCIM. - -[Configure Entra ID SCIM with authentik](./scim/index.mdx) +The [Entra ID SCIM](./scim/index.mdx) guide explains how you can provision users and groups from Entra ID into authentik via SCIM. diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx index b5e0c0f0712a..857df8050432 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -1,6 +1,5 @@ --- -title: Entra ID -support_level: community +title: Entra ID OAuth tags: - source - entra @@ -9,6 +8,8 @@ tags: - oauth --- +Allows users to authenticate using their Entra ID credentials. + ## Preparation The following placeholders are used in this guide: @@ -17,6 +18,8 @@ The following placeholders are used in this guide: ## Entra ID configuration +To integrate Entra ID with authentik you will need to create an App Registration in the Entra ID portal. + 1. Log in to [Entra ID](https://entra.microsoft.com) using a [global administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) account. 2. Navigate to **Applications** > **App registrations**. 3. Click **New registration** and set the following required configurations: @@ -24,12 +27,12 @@ The following placeholders are used in this guide: - Under **Supported account types**: select the account type that applies to your use-case (e.g. `Accounts in this organizational directory only (Default Directory only - Single tenant)`). - Under **Redirect URI**: - **Platform**: `Web` - - **URI**: `https://authentik.company/source/oauth/callback/entra-id/ + - **URI**: `https://authentik.company/source/oauth/callback/entra-id/` 4. Click **Register**. Once the registration is complete, the **Overview** tab of the newly created authentik app will open. Take note of the `Application (client) ID`. If you selected `Accounts in this organizational directory only (Default Directory only - Single tenant)` as the **Supported account types**, also note the `Directory (tenant) ID`. These values will be needed later when configuring authentik. 5. In the leftmost sidebar, navigate to **Certificates & secrets**. 6. Select the **Client secrets** tab and click **New Secret**. Configure the following required settings: - - **Description**: provide a description for the secret (e.g. `authentik secret`. + - **Description**: provide a description for the secret (e.g. `authentik secret`). - **Expires**: choose an expiration period. As authentik does not yet support automatic secret rotation, either manual rotation or API-based updates are required. As a result, a duration of at least 12 months is recommended. 7. Copy the secret's value from the **Value** column. @@ -40,9 +43,10 @@ The secret value is only displayed once at the time of creation. Make sure to co 8. In the sidebar, navigate to **API Permissions**, then click **Add a permission** and select **Microsoft Graph** as the API. 9. Select **Delegated permissions** as the permission type and assign the following permissions: - Under **OpenID Permissions**: select `email`, `profile`, and `openid`. + - Under **User**: select `User.Read`. - Under **Group Member** _(optional)_: if you need authentik to sync group membership information from Entra ID, select the `GroupMember.Read.All` permission. 10. Click **Add permissions**. -11. _(optional)_ If the `GroupMember.Read.All` permission has been selected, under **Configured permissions**, click **Grant admin consent for default directory**. +11. Under **Configured permissions**, click **Grant admin consent for default directory**. ## authentik configuration @@ -57,7 +61,7 @@ To support the integration of Entra ID with authentik, you need to create an Ent - Under **Protocol Settings**: - **Consumer key**: `Application (client) ID` from Entra ID. - **Consumer secret**: value of the secret created in Entra ID. - - **Scopes**_(optional)_: if you need authentik to sync group membership information from Entra ID, add the `https://graph.microsoft.com/GroupMember.Read.All` scope. + - **Scopes** _(optional)_: if you need authentik to sync group membership information from Entra ID, add the `https://graph.microsoft.com/GroupMember.Read.All` scope. - Under **URL Settings**: - For **Single tenant** Entra ID applications: - **Authorization URL**: `https://login.microsoftonline.com//oauth2/v2.0/authorize` @@ -72,14 +76,20 @@ To support the integration of Entra ID with authentik, you need to create an Ent 3. Click **Save**. -:::info -When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. +:::info Group Membership +When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. This sync process is carried out upon each user login which can cause login delays for organizations with large numbers of groups. + +For organizations with larger numbers of users and groups, we recommend using the [Entra ID SCIM integration](../oauth/) to provision users and groups. These users are then automatically linked to matching users logging in via this Entra ID OAuth source. ::: -:::info +:::info Display new source on login screen For instructions on how to display the new source on the authentik login page, refer to the [Add sources to default login page documentation](../../../index.md#add-sources-to-default-login-page). ::: +:::info Embed new source in flow :ak-enterprise +For instructions on embedding the new source within a flow, such as an authorization flow, refer to the [Source Stage documentation](../../../../../../add-secure-apps/flows-stages/stages/source). +::: + ### Machine-to-machine authentication :ak-version[2024.12] If using [Machine-to-Machine](../../../../../add-secure-apps/providers/oauth2/client_credentials.mdx#jwt-authentication) authentication, some specific steps need to be considered. @@ -98,3 +108,11 @@ client_secret= ``` The JWT returned from the request above can be used in authentik and exchanged for an authentik JWT. + +## Source property mappings + +Source property mappings allow you to modify or gather extra information from sources. See the [overview](../../../property-mappings/index.md) for more information. + +## Resources + +- [Entra ID Documentation - Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx index d6641ab7dd33..df9099130c9d 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -1,13 +1,15 @@ --- -title: Entra ID -support_level: community +title: Entra ID SCIM tags: - source - entra - azure + - active-directory - scim --- +Allows provisioning users and groups from Entra ID to authentik. + ## Preparation The following placeholders are used in this guide: @@ -16,20 +18,21 @@ The following placeholders are used in this guide: ## authentik configuration -To integrate authentik with Entra ID via SCIM you will first need to create a SCIM source in authentik. +To integrate authentik with Entra ID via SCIM you will need to create a SCIM source in authentik. ### Create SCIM source 1. Log in to authentik as an administrator and open the authentik Admin interface. 2. Navigate to **Directory** > **Federation and Social login**, click **Create**, and then configure the following settings: - **Select type**: select **SCIM Source**. - - **Create SCIM Source**: provide a name and a slug. All other configurations are optional. + - **Create SCIM Source**: provide a name and a slug. + - All other configurations are optional. 3. Click **Finish**. 4. On the **Federation and Social login** page, click on the name of the newly created SCIM source. 5. Take note of the **SCIM Base URL**. This value will be required in the next section. 6. Under **Token**, click **Click to copy token** and securely store the value. This value will also be required in the next section. -:::note Copying the token +:::warning Copying the token If authentik has the required browser permissions, the token will be copied into your clipboard after clicking **Click to copy token** button. However, some browsers don't allow this, in those cases a notification will appear in the bottom right corner with the token and you will need to manually copy it. ::: @@ -38,15 +41,15 @@ If authentik has the required browser permissions, the token will be copied into ### Create a custom enterprise application 1. Log in to [Entra ID](https://entra.microsoft.com) using a [global administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator) account. -2. Navigate to **Enterprise apps**, click **Create your own application** and then configure the following fields: +2. Navigate to **Enterprise apps**, click **Create your own application**, and configure the following fields: - **Name**: provide a name for the application (e.g. `authentik-scim`). - Select `Integrate any other application you don't find in the gallery (Non-gallery)`. 3. Click **Create**. ### Configure provisioning -4. Navigate to **Provisioning**, click **New Configuration** and then configure the following fields: - - **Tenant URL**: Set to the **SCIM Base URL** from authentik. +4. Navigate to **Provisioning**, click **New Configuration**, and configure the following fields: + - **Tenant URL**: Set to the **SCIM Base URL** from authentik (e.g. `https://authentik.company/source/scim/entra-scim/v2`). - **Secret Token**: Set to the **Token** from authentik. 5. Click **Test connection** to validate that Entra ID can communicate with authentik. 6. If the connection is successful, click **Create** and **Save**. If the connection fails, ensure that your authentik **SCIM Base URL** is accessible from the internet. @@ -55,27 +58,47 @@ If authentik has the required browser permissions, the token will be copied into There are three options to determine which users and groups are provisioned to authentik: - Set Entra ID to sync all users and groups - - Set Entra ID to sync all users and groups with scopes to determine which users and groups are synced + - Set Entra ID to sync all users and groups with scopes to limit which users and groups are synced - Set Entra ID to sync only assigned users and groups (Group assignment is only available to Microsoft Entra Suite, Microsoft Entra ID Governance and Microsoft Entra ID P2 customers) #### Sync all users and groups -1. On the **Provisioning** page, expand the **Settings** section and then set **Scope** to `Sync all users and groups`. +1. On the **Provisioning** page, expand the **Settings** section, and set **Scope** to `Sync all users and groups`. 2. Toggle **Provisioning status** to `On`. -3. At the top of the screen, click **Save**. +3. At the top of the page, click **Save**. +4. Track provisioning progress via the **Overview** page. #### Sync all users and groups with scopes -1. On the **Provisioning** page, expand the **Settings** section and then set **Scope** to `Sync all users and groups`. -2. At the top of the screen, click **Save**. +1. On the **Provisioning** page, expand the **Settings** section, and set **Scope** to `Sync all users and groups`. +2. At the top of the page, click **Save**. 3. Expand the **Mappings** section and then click **Provision Microsoft Entra ID Users**. -4. Under **Source Object Scope** - -5. On the **Provisioning** page, toggle **Provisioning status** to `On`. -6. At the top of the screen, click **Save**. +4. Under **Source Object Scope**, click **All records**. +5. Click **Add new filter group**, design the filters that you want applied to synced users and click **Apply**. +6. Optionally, configure **Target object actions** and modify the **Attribute Mappings**. +7. At the top of the page, click **Save**. +8. On the **Provisioning** page, Expand the **Mappings** section and then click **Provision Microsoft Entra ID Groups** and repeat steps 4-7. +9. Back on the **Provisioning** page, toggle **Provisioning status** to `On`. +10. At the top of the page, click **Save**. +11. Track provisioning progress via the **Overview** page. #### Sync only assigned users and groups -:::note -Group assignment is only available to Microsoft Entra Suite, Microsoft Entra ID Governance and Microsoft Entra ID P2 customers +1. On the **Provisioning** page, expand the **Settings** section, and set **Scope** to `Sync only assigned users and groups`. +2. At the top of the page, click **Save**. +3. Under **Manage**, click **Users and groups** and then click **Add user/group**. +4. Select the users and groups that you want synced to authentik. +5. Click **Assign**. +6. On the **Provisioning** page, toggle **Provisioning status** to `On`. +7. At the top of the page, click **Save**. +8. Track provisioning progress via the **Overview** page. + +:::note Group assignment +Group assignment is only available for Microsoft Entra Suite, Microsoft Entra ID Governance and Microsoft Entra ID P2 subscribers. ::: + +## Confirm provisioning in authentik + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Directory** > **Federation and Social login** and click on the name of the SCIM source. +3. Open the **Provisioned Users** and **Provisioned Groups** tabs to confirm whether the correct users and groups have been provisioned from Entra ID. From 597288cd57c5009b02dc32687da22c425873d924 Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 9 Oct 2025 14:16:35 +0100 Subject: [PATCH 04/12] Update website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx Co-authored-by: Tana M Berry Signed-off-by: Dewi Roberts --- .../users-sources/sources/social-logins/entra-id/scim/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx index df9099130c9d..76a1e25a48ae 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -8,7 +8,7 @@ tags: - scim --- -Allows provisioning users and groups from Entra ID to authentik. +Allows provisioning users and groups from Entra ID to authentik using a SCIM source. ## Preparation From 1072635caa4f52d9298e6ea4e0a448191d43f2d7 Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 9 Oct 2025 14:16:47 +0100 Subject: [PATCH 05/12] Update website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx Co-authored-by: Tana M Berry Signed-off-by: Dewi Roberts --- .../users-sources/sources/social-logins/entra-id/scim/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx index 76a1e25a48ae..6b579da7179f 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -77,7 +77,7 @@ There are three options to determine which users and groups are provisioned to a 5. Click **Add new filter group**, design the filters that you want applied to synced users and click **Apply**. 6. Optionally, configure **Target object actions** and modify the **Attribute Mappings**. 7. At the top of the page, click **Save**. -8. On the **Provisioning** page, Expand the **Mappings** section and then click **Provision Microsoft Entra ID Groups** and repeat steps 4-7. +8. On the **Provisioning** page, expand the **Mappings** section and then click **Provision Microsoft Entra ID Groups** and repeat steps 4-7. 9. Back on the **Provisioning** page, toggle **Provisioning status** to `On`. 10. At the top of the page, click **Save**. 11. Track provisioning progress via the **Overview** page. From c75b020d076a2f0e1263ccc99c885cd8c75828d0 Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 15:15:49 +0100 Subject: [PATCH 06/12] Apply suggestions --- .../sources/social-logins/entra-id/index.mdx | 14 ++++++++------ .../sources/social-logins/entra-id/oauth/index.mdx | 8 +++++--- .../sources/social-logins/entra-id/scim/index.mdx | 4 +++- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index 062d6b782efe..b4a7334aed90 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -12,14 +12,16 @@ tags: Entra ID provides several services that can be integrated with authentik: - - **OAuth integration** allows users to sign into authentik using their Entra ID credentials. Accounts and groups are created upon first login. - - **SCIM integration** provisions users and groups from Entra ID to authentik. - - Optionally, both integrations can be used in conjunction so that users and groups are provisioned before a user signs in using their Entra ID credentials. This is the recommended setup for organizations with large numbers of users and groups. - ## OAuth -The [Entra ID OAuth](./oauth/index.mdx) guide explains how to set up OAuth 2.0 as an authentication method between Entra ID and authentik. +The [Entra ID OAuth](./oauth/index.mdx) guide explains how to set up Entra ID as a federated OAuth identity provider for authentik. + +This enables users to sign into authentik using their Entra ID credentials. User accounts are created in authentik upon first login and updated on each subsequent login. + +Alternatively, Entra ID authentication can be embedded into a flow via a [Source stage](../../../../../add-secure-apps/flows-stages/stages/source). ## SCIM -The [Entra ID SCIM](./scim/index.mdx) guide explains how you can provision users and groups from Entra ID into authentik via SCIM. +The [Entra ID SCIM](./scim/index.mdx) guide explains how you can provision users and groups from Entra ID into authentik via the SCIM protocol. + +Optionally, both the OAuth and SCIM integrations can be used in conjunction so that users and groups are provisioned before a user signs in using their Entra ID credentials. This is the recommended setup for organizations with large numbers of users and groups. diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx index 857df8050432..8ec9008ed9a5 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -1,5 +1,7 @@ --- -title: Entra ID OAuth +title: Entra ID OAuth authentication +sidebar_label: Entra ID OAuth +description: Authenticating to authentik using Entra ID credentials via OAuth2 protocol tags: - source - entra @@ -8,7 +10,7 @@ tags: - oauth --- -Allows users to authenticate using their Entra ID credentials. +Allows users to authenticate to authentik using their Entra ID credentials, by configuring Entra ID as a federated identity provider via OAuth2. ## Preparation @@ -107,7 +109,7 @@ scope=api:///.default& client_secret= ``` -The JWT returned from the request above can be used in authentik and exchanged for an authentik JWT. +The JWT returned from the request above can be used in authentik and exchanged for an [authentik JWT](../../../../../../add-secure-apps/providers/oauth2/client_credentials/#authentik-issued-jwts). ## Source property mappings diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx index 6b579da7179f..ab93de76e26b 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -1,5 +1,7 @@ --- -title: Entra ID SCIM +title: Entra ID SCIM user and group provisioning +sidebar_label: Entra ID SCIM +description: Provisioning users and groups from Entra ID to authentik via SCIM protocol tags: - source - entra From 7e05cb10a2d1133e5fb6f89bec4a07c0b7acc122 Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 15:20:07 +0100 Subject: [PATCH 07/12] Fix table of contents --- .../users-sources/sources/social-logins/entra-id/scim/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx index ab93de76e26b..b2b1c19e2a71 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -2,6 +2,7 @@ title: Entra ID SCIM user and group provisioning sidebar_label: Entra ID SCIM description: Provisioning users and groups from Entra ID to authentik via SCIM protocol +toc_max_heading_level: 4 tags: - source - entra From 77735d8f8d6377d7b01f2ff52741a6eef54cd9ef Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 15:39:24 +0100 Subject: [PATCH 08/12] Language change --- .../docs/users-sources/sources/social-logins/entra-id/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index b4a7334aed90..b4c032a7dad6 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -10,7 +10,7 @@ tags: - oauth --- -Entra ID provides several services that can be integrated with authentik: +Entra ID provides several methods by which it can be integrated with authentik: ## OAuth From 921ffcdc04d0c7fe0fdbf6b0b1d380096375d91b Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 15:43:02 +0100 Subject: [PATCH 09/12] Language change --- .../docs/users-sources/sources/social-logins/entra-id/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index b4c032a7dad6..d03cb9eb6f02 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -10,7 +10,7 @@ tags: - oauth --- -Entra ID provides several methods by which it can be integrated with authentik: +There are several ways that Entra ID can be integrated with authentik, to allow for provisioning and authenticating with Entra ID user credentials. ## OAuth From 38676fb51688b76fdb664d756650f384accb8949 Mon Sep 17 00:00:00 2001 From: dewi-tik Date: Thu, 9 Oct 2025 15:45:41 +0100 Subject: [PATCH 10/12] Apply dominic's suggestions --- .../users-sources/sources/social-logins/entra-id/index.mdx | 5 ++--- .../sources/social-logins/entra-id/oauth/index.mdx | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx index d03cb9eb6f02..138640bfafea 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/index.mdx @@ -1,6 +1,5 @@ --- -title: Entra ID Identity Providers -sidebar_label: Entra ID +title: Entra ID tags: - source - entra @@ -16,7 +15,7 @@ There are several ways that Entra ID can be integrated with authentik, to allow The [Entra ID OAuth](./oauth/index.mdx) guide explains how to set up Entra ID as a federated OAuth identity provider for authentik. -This enables users to sign into authentik using their Entra ID credentials. User accounts are created in authentik upon first login and updated on each subsequent login. +This enables users to sign in to authentik using their Entra ID credentials. User accounts are created in authentik upon first login and updated on each subsequent login. Alternatively, Entra ID authentication can be embedded into a flow via a [Source stage](../../../../../add-secure-apps/flows-stages/stages/source). diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx index 8ec9008ed9a5..331a1d57ba2b 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -1,7 +1,7 @@ --- title: Entra ID OAuth authentication sidebar_label: Entra ID OAuth -description: Authenticating to authentik using Entra ID credentials via OAuth2 protocol +description: Authenticating to authentik with Entra ID credentials via the OAuth 2.0 protocol tags: - source - entra @@ -16,7 +16,7 @@ Allows users to authenticate to authentik using their Entra ID credentials, by c The following placeholders are used in this guide: -- `authentik.company` is the FQDN of the authentik install. +- `authentik.company` is the FQDN of the authentik installation. ## Entra ID configuration From b2de9b8a0017f4e222b6991c6c365d5e6b1540da Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 9 Oct 2025 15:46:42 +0100 Subject: [PATCH 11/12] Update website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts --- .../sources/social-logins/entra-id/oauth/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx index 331a1d57ba2b..0334e7db70fc 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -81,7 +81,7 @@ To support the integration of Entra ID with authentik, you need to create an Ent :::info Group Membership When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. This sync process is carried out upon each user login which can cause login delays for organizations with large numbers of groups. -For organizations with larger numbers of users and groups, we recommend using the [Entra ID SCIM integration](../oauth/) to provision users and groups. These users are then automatically linked to matching users logging in via this Entra ID OAuth source. +For organizations with larger numbers of users and groups, we recommend using the [Entra ID SCIM integration](../scim/) to provision users and groups. These users are then automatically linked to matching users logging in via this Entra ID OAuth source. ::: :::info Display new source on login screen From ca2f9e81a82ce67319f327ed5b57e6dbaf51d97e Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 9 Oct 2025 15:48:45 +0100 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: Dominic R Signed-off-by: Dewi Roberts --- .../sources/social-logins/entra-id/oauth/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx index 0334e7db70fc..e966a0bffc05 100644 --- a/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -79,7 +79,7 @@ To support the integration of Entra ID with authentik, you need to create an Ent 3. Click **Save**. :::info Group Membership -When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. This sync process is carried out upon each user login which can cause login delays for organizations with large numbers of groups. +When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. This sync process is carried out upon each user login, which can cause login delays for organizations with large numbers of groups. For organizations with larger numbers of users and groups, we recommend using the [Entra ID SCIM integration](../scim/) to provision users and groups. These users are then automatically linked to matching users logging in via this Entra ID OAuth source. :::