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 7a0b29d5f8f8..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,99 +1,26 @@ --- title: Entra ID -support_level: community tags: - source - entra - azure - active-directory + - scim + - oauth --- -## Preparation +There are several ways that Entra ID can be integrated with authentik, to allow for provisioning and authenticating with Entra ID user credentials. -The following placeholders are used in this guide: +## OAuth -- `authentik.company` is the FQDN of the authentik install. +The [Entra ID OAuth](./oauth/index.mdx) guide explains how to set up Entra ID as a federated OAuth identity provider for authentik. -## Entra ID configuration +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. -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/ +Alternatively, Entra ID authentication can be embedded into a flow via a [Source stage](../../../../../add-secure-apps/flows-stages/stages/source). -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. +## SCIM -:::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. -::: +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. -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. +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 new file mode 100644 index 000000000000..e966a0bffc05 --- /dev/null +++ b/website/docs/users-sources/sources/social-logins/entra-id/oauth/index.mdx @@ -0,0 +1,120 @@ +--- +title: Entra ID OAuth authentication +sidebar_label: Entra ID OAuth +description: Authenticating to authentik with Entra ID credentials via the OAuth 2.0 protocol +tags: + - source + - entra + - azure + - active-directory + - oauth +--- + +Allows users to authenticate to authentik using their Entra ID credentials, by configuring Entra ID as a federated identity provider via OAuth2. + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik installation. + +## 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: + - **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 **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. 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 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](../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 +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. + +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](../../../../../../add-secure-apps/providers/oauth2/client_credentials/#authentik-issued-jwts). + +## 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 new file mode 100644 index 000000000000..b2b1c19e2a71 --- /dev/null +++ b/website/docs/users-sources/sources/social-logins/entra-id/scim/index.mdx @@ -0,0 +1,107 @@ +--- +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 + - azure + - active-directory + - scim +--- + +Allows provisioning users and groups from Entra ID to authentik using a SCIM source. + +## 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 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. + +:::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. +::: + +## 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 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 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. +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 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 set **Scope** to `Sync all users and groups`. +2. Toggle **Provisioning status** to `On`. +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 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**, 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 + +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.