diff --git a/website/docs/users-sources/sources/social-logins/apple/index.md b/website/docs/users-sources/sources/social-logins/apple/index.md index 0d36aaa90ddd..5b1fe2750f51 100644 --- a/website/docs/users-sources/sources/social-logins/apple/index.md +++ b/website/docs/users-sources/sources/social-logins/apple/index.md @@ -1,72 +1,83 @@ --- title: Apple -support_level: authentik +tags: + - source + - apple --- -Allows users to authenticate using their Apple ID. +Allows users to authenticate using their Apple ID credentials. ## Preparation -:::caution -An Apple developer account is required. -::: +The following placeholders are used in this guide: -:::caution -Apple mandates the use of a [registered TLD](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains), as such this source will not work with .local and other non-public TLDs. -::: +Apple mandates the use of a [registered top-level domain](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains), therefore this source will not work with `.local` and other non-public TLDs. -The following placeholders are used in this guide: +## Apple configuration -- `authentik.company` is the FQDN of the authentik install. +To integrate Apple with authentik, you will need to create two identifiers and a key in the Apple Developer Portal. -## Apple +### Registering identifiers -1. Log in to your Apple developer account, and navigate to **Certificates, IDs & Profiles**, then click **Identifiers** in the sidebar. -2. Register a new Identifier with the type of **App IDs**, and the subtype **App**. -3. Choose a name that users will recognise for the **Description** field. -4. For your bundle ID, use the reverse domain of authentik, in this case `company.authentik`. +1. Log in to the [Apple Developer Portal](https://developer.apple.com/account/), and navigate to **Account** > **Certificates, IDs & Profiles**, then click **Identifiers** in the sidebar. +2. Register a new identifier with the type of **App IDs**, and the subtype **App**. +3. Choose a name that users will recognize for the **Description** field (e.g. `authentik`). +4. For your **Bundle ID**, use the reverse of your authentik domain, for example: `company.authentik`. 5. Scroll down the list of capabilities, and check the box next to **Sign In with Apple**. 6. At the top, click **Continue** and **Register**. ![](./app_id.png) -7. Register another new Identifier with the type of **Services IDs**. +7. Register another new identifier with the type of **Services IDs**. 8. Again, choose the same name as above for your **Description** field. 9. Use the same identifier as above, but add a suffix like `signin` or `oauth`, as identifiers are unique. 10. At the top, click **Continue** and **Register**. ![](./service_id.png) -11. Once back at the overview list, click on the just-created Identifier. +### Configuring identifier + +11. Once back at the overview list, click on the just-created identifier. 12. Enable the checkbox next to **Sign In with Apple**, and click **Configure** -13. Under domains, enter `authentik.company`. +13. Under **Domains and Subdomains**, enter `authentik.company`. 14. Under **Return URLs**, enter `https://authentik.company/source/oauth/callback/apple/`. ![](./app_service_config.png) -15. Click on **Keys** in the sidebar. Register a new Key with any name, and select **Sign in with Apple**. -16. Click on **Configure**, and select the App ID you've created above. +### Registering a key + +15. Click **Keys** in the sidebar, then register a new key with any name, and select **Sign in with Apple**. +16. Click **Configure**, then select the App ID that you created. 17. At the top, click **Save**, **Continue** and **Register**. 18. Download the Key file and note the **Key ID**. ![](./key.png) -19. Note the Team ID, visible at the top of the page. +19. Take note of the **Team ID** visible at the top of the page. -## authentik +## authentik configuration -20. Under **Directory > Federation & Social login** click **Create Apple OAuth Source** +To support the integration of Apple with authentik, you need to create an Apple OAuth source in authentik. -21. **Name**: `Apple` -22. **Slug**: `apple` -23. **Consumer Key:** The identifier from step 9, then `;`, then your Team ID from step 19, then `;`, then the Key ID from step 18. +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Directory** > **Federation and Social login**, click **Create**, then configure the following settings: + - **Select type**: select **Apple OAuth Source**. + - **Create Apple OAuth Source**: provide a name, a slug which must match the slug used in the Apple `Return URL`, and the following required configurations: + - Under **Protocol Settings**: + - **Consumer key**: The identifier from step 9, then `;`, then your **Team ID** from step 19, then `;`, then the **Key ID** from step 18. (e.g. `company.authentik;JQNH45HN7V;XFBNJ82BV6`). + - **Consumer secret**: Paste the contents of the keyfile you've downloaded. + - **Scopes** _(optional)_: define any further access scopes. - Example: `io.goauthentik.dev-local;JQNH45HN7V;XFBNJ82BV6` +3. Click **Save**. -24. **Consumer Secret:** Paste the contents of the keyfile you've downloaded - -Save, and you now have Apple as a 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). +::: + +## 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. diff --git a/website/docs/users-sources/sources/social-logins/discord/discord1.png b/website/docs/users-sources/sources/social-logins/discord/discord1.png deleted file mode 100644 index 905ac4186ed8..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/discord/discord1.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/discord/discord2.png b/website/docs/users-sources/sources/social-logins/discord/discord2.png deleted file mode 100644 index 1cdc74901d0a..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/discord/discord2.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/discord/discord3.png b/website/docs/users-sources/sources/social-logins/discord/discord3.png deleted file mode 100644 index fee3bd505bf9..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/discord/discord3.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/discord/discord4.png b/website/docs/users-sources/sources/social-logins/discord/discord4.png deleted file mode 100644 index 17ed1e990c64..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/discord/discord4.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/discord/index.md b/website/docs/users-sources/sources/social-logins/discord/index.md index 0387d79586dc..e18d78aa22ed 100644 --- a/website/docs/users-sources/sources/social-logins/discord/index.md +++ b/website/docs/users-sources/sources/social-logins/discord/index.md @@ -1,9 +1,11 @@ --- title: Discord -support_level: authentik +tags: + - source + - discord --- -Allows users to authenticate using their Discord credentials +Allows users to authenticate using their Discord credentials. ## Preparation @@ -11,64 +13,144 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -## Discord +## Discord configuration -1. Create an application in the Discord Developer Portal (This is Free) https://discord.com/developers/applications +To integrate Discord with authentik you will need to create an OAuth application in the Discord Developer Portal. -![New Application Button](./discord1.png) +1. Log in to the [Discord Developer Portal](https://discord.com/developers/applications). +2. Navigate to **Applications** and click **New Application**. +3. Provide a name for the application, accept the terms, and then click **Create**. +4. Select **OAuth2** in the sidebar. +5. Under **Client Secret**, click **Reset Secret** and follow the steps. +6. Take note of the **Client ID** and **Client Secret**. They will be required in the next section. +7. Click **Add Redirect** and enter `https://authentik.company/source/oauth/callback/discord/`. -2. Name the Application +## authentik configuration -![Name App](./discord2.png) +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 **Discord OAuth Source** as the source type. + - **Create Discord OAuth Source**: provide a name, a slug which must match the slug used in the Discord `Redirect URI` (e.g. `discord`), and the following required configurations: + - Under **Protocol Settings**: + - **Consumer key**: set the Client ID from Discord. + - **Consumer secret**: set the Client Secret from Discord. + - **Scopes** _(optional)_: if you need authentik to sync guild membership information from Disord, add the `guilds guilds.members.read` scope. -3. Select **OAuth2** from the left menu +3. Click **Save**. -4. Copy the **Client ID** and _save it for later_ +:::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). +::: -5. **Click to Reveal** the Client Secret and _save it for later_ +:::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). +::: -6. Click **Add Redirect** and add https://authentik.company/source/oauth/callback/discord/ +## Optional additional configuration -Here is an example of a completed OAuth2 screen for Discord. +### Syncing Discord roles and avatars to authentik -![](./discord3.png) +The following property mapping allows you to synchronize roles from a Discord guild to roles in authentik. -## authentik +Whenever a user enrolls in authentik via a Discord source, this property mapping will check the user's Discord roles and update the user's authentik groups accordingly. -8. Under **Directory > Federation & Social login** click **Create Discord OAuth Source** +:::info Group Attribute +Any authentik group that you want to sync with a Discord role needs to have a `discord_role_id` attribute set with the ID of the Discord role. +Example: `discord_role_id: ""` -9. **Name:** Choose a name (For the example I used `Discord`) -10. **Slug:** discord (You can choose a different slug, if you do you will need to update the Discord redirect URL and point it to the correct slug.) -11. **Consumer Key:** Client ID from step 4 -12. **Consumer Secret:** Client Secret from step 5 +This group attribute can be set via **Directory** > **Groups** > **Your_Group** > **Attributes**. +::: -Here is an example of a complete authentik Discord OAuth Source +:::info Required OAuth Scopes +Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings** > **Scopes**. +::: -![](./discord4.png) +:::info Avatar Setting +In order to use the created avatar attribute in authentik you will need to set the [authentik avatar configuration](../../../../sys-mgmt/settings.md#avatars). +::: -Save, and you now have Discord as a source. +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Property Mappings**. +3. Click **Create**, select **OAuth Source Property Mapping** and then **Next**. +4. Provide a name for the mapping and set the following expression: -:::info -For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page). -::: +```python +import base64 +import requests +from authentik.core.models import Group + +# To get the guild ID number for the parameters, open Discord, go to Settings > Advanced and enable developer mode. +# Right-click on the server/guild title and select "Copy ID" to get the guild ID. + +#Set these values +ACCEPTED_GUILD_ID = "123456789123456789" # Discord server id to fetch roles from +AVATAR_SIZE = "64" # Valid avatar size values: 16,32,64,128,256,512,1024. +# Larger values than 64 may cause HTTP error 431 on applications/providers +# due to headers being too large. + +# Generate avatar URL and base64 avatar image +avatar_url = None +avatar_base64 = None + +if info.get("avatar"): + avatar_url = (f"https://cdn.discordapp.com/avatars/{info.get('id')}/" + f"{info.get('avatar')}.png?size={AVATAR_SIZE}") + try: + response = client.do_request("GET", avatar_url) + encoded_image = base64.b64encode(response.content).decode('utf-8') + avatar_base64 = f"data:image/png;base64,{encoded_image}" + except: + avatar_base64 = None + +# Get guild membership +guild_url = f"https://discord.com/api/v10/users/@me/guilds/{ACCEPTED_GUILD_ID}/member" +guild_response = client.do_request("GET", guild_url, token=token) +guild_data = guild_response.json() + +# Get matching groups +user_groups = Group.objects.filter(attributes__discord_role_id__in=guild_data["roles"]) + +# Return user data +return { + "name": info.get("global_name"), + "attributes.discord": { + "id": info.get("id"), + "username": info.get("username"), + "discriminator": info.get("discriminator"), + "email": info.get("email"), + "avatar": info.get("avatar"), + "avatar_url": avatar_url + }, + "groups": [group.name for group in user_groups], + "attributes.avatar": avatar_base64 +} +``` -### Checking for membership of a Discord Guild +5. Click **Finish**. +6. Navigate to **Directory** > **Federation and Social login** and click the **Edit** icon next to your Discord OAuth Source. +7. Under **OAuth Attribute mapping** add the newly create property mapping to **Selected User Property Mappings**. +8. Click **Update**. + +### Checking Discord Guild membership :::info -Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings**. +Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings** > **Scopes**. ::: -Create a new **Expression Policy** with the content below, adjusting the variables where required: +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Policies**. +3. Click **Create**, select **Expression Policy** and then **Next**. +4. Provide a name for the policy and set the following expression: ```python # To get the guild ID number for the parameters, open Discord, go to Settings > Advanced and enable developer mode. # Right-click on the server/guild title and select "Copy ID" to get the guild ID. +# Set these values ACCEPTED_GUILD_ID = "123456789123456789" GUILD_NAME_STRING = "The desired server/guild name in the error message." -# Only change below here if you know what you are doing. - +# The following sections should not need to be edited # Ensure flow is only run during OAuth logins via Discord if not isinstance(context['source'], OAuthSource) or context['source'].provider_type != "discord": return True @@ -92,31 +174,39 @@ if not user_matched: return user_matched ``` -Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source. +5. Click **Finish**. You can now bind this policy to the chosen enrollment and/or authentication flow of the Discord OAuth source. +6. Navigate to **Flows and Stages** > **Flows** and click the name of the flow in question. +7. Open the **Policy/Group/User Bindings** tab and click **Bind existing Policy/Group/User**. +8. Select the policy that you previously created and click **Create**. +9. Optionally, repeat the process for any other flows that you want the policy applied to. -### Checking for membership of a Discord Guild role +### Checking Discord Guild role membership :::info -Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings**. +Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings** > **Scopes**. ::: -Create a new **Expression Policy** with the content below, adjusting the variables where required: +To check if the user is member of a Discord Guild role, you can use the following policy on your flows: + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Policies**. +3. Click **Create**, select **Expression Policy** and then **Next**. +4. Provide a name for the policy and set the following expression: ```python -# To get the role and guild ID numbers for the parameters, open Discord, go to Settings > Advanced and -# enable developer mode. +# To get the guild ID number for the parameters, open Discord, go to Settings > Advanced and enable developer mode. # Right-click on the server/guild title and select "Copy ID" to get the guild ID. -# Right-click on the server/guild title and select server settings > roles, right click on the role and click -# "Copy ID" to get the role ID. +# Right-click on the server/guild title and select server settings > roles, right click on the role and click "Copy ID" to get the role ID. -ACCEPTED_ROLE_ID = "123456789123456789" +#Set these values ACCEPTED_GUILD_ID = "123456789123456789" GUILD_NAME_STRING = "The desired server/guild name in the error message." +ACCEPTED_ROLE_ID = "123456789123456789" ROLE_NAME_STRING = "The desired role name in the error message." -# Only change below here if you know what you are doing. GUILD_API_URL = f"https://discord.com/api/users/@me/guilds/{ACCEPTED_GUILD_ID}/member" +# The following sections should not need to be edited # Ensure flow is only run during OAuth logins via Discord if not isinstance(context['source'], OAuthSource) or context['source'].provider_type != "discord": return True @@ -152,235 +242,13 @@ if not user_matched: return user_matched ``` -Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source. - -### Syncing Discord roles to authentik groups - -:::info -Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds.members.read` scopes added under **Protocol settings**. -::: - -:::info -Any authentik role that you want to sync with a Discord role needs to have the **attribute** `discord_role_id` with a value of the Discord role's ID set. -This setting can be found under `Authentik > Admin Interface > Directory > Groups > YOUR_GROUP > Attributes` -Example: `discord_role_id: ""` -::: - -The following two policies allow you to synchronize roles in a Discord guild with roles in authentik. -Whenever a user enrolls or signs in to authentik via a Discord source, these policies will check the user's Discord roles and apply the user's authentik roles accordingly. -All roles with the attribute `discord_role_id` defined will be added or removed depending on whether the user is a member of the defined Discord role. - -Create a new **Expression Policy** with the content below, adjusting the variables where required. - -#### Sync on enrollment - -The following policy will apply the above behaviour when a user enrolls. - -```python -from authentik.core.models import Group -GUILD_API_URL = "https://discord.com/api/users/@me/guilds/{guild_id}/member" - -### CONFIG ### -guild_id = "" -############## - -# Ensure flow is only run during OAuth logins via Discord -if not isinstance(context['source'], OAuthSource) or context['source'].provider_type != "discord": - return True - -# Get the user-source connection object from the context, and get the access token -connection = context.get("goauthentik.io/sources/connection") -if not connection: - return False -access_token = connection.access_token - -guild_member_request = requests.get( - GUILD_API_URL.format(guild_id=guild_id), - headers={ - "Authorization": f"Bearer {access_token}", - }, -) -guild_member_info = guild_member_request.json() - -# Ensure we are not being ratelimited -if guild_member_request.status_code == 429: - ak_message(f"Discord is throttling this connection. Retry in {int(guild_member_info['retry_after'])}s") - return False - -# Ensure user is a member of the guild -if "code" in guild_member_info: - if guild_member_info["code"] == 10004: - ak_message("User is not a member of the guild") - else: - ak_create_event("discord_error", source=context["source"], code=guild_member_info["code"]) - ak_message("Discord API error, try again later.") - return False - -# Get all discord_groups -discord_groups = Group.objects.filter(attributes__discord_role_id__isnull=False) - -# Filter matching roles based on guild_member_info['roles'] -user_groups_discord_updated = discord_groups.filter(attributes__discord_role_id__in=guild_member_info["roles"]) - -# Set matchin_roles in flow context -request.context["flow_plan"].context["groups"] = user_groups_discord_updated - -# Create event with roles added -ak_create_event( - "discord_role_sync", - user_discord_roles_added=", ".join(str(group) for group in user_groups_discord_updated), -) - -return True - -``` +5. Click **Finish**. You can now bind this policy to the chosen enrollment and/or authentication flow of the Discord OAuth source. +6. Navigate to **Flows and Stages** > **Flows** and click the name of the flow in question. +7. Open the **Policy/Group/User Bindings** tab and click **Bind existing Policy/Group/User**. +8. Select the policy that you previously created and click **Create**. +9. Optionally, repeat the process for any other flows that you want the policy applied to. -Now bind this policy to the chosen enrollment flows for the Discord OAuth source. +## Resources -#### Sync on authentication - -The following policy will apply the above behaviour when a user logs in. - -```python -from authentik.core.models import Group -GUILD_API_URL = "https://discord.com/api/users/@me/guilds/{guild_id}/member" - -### CONFIG ### -guild_id = "" -############## - -# Ensure flow is only run during OAuth logins via Discord -if not isinstance(context['source'], OAuthSource) or context['source'].provider_type != "discord": - return True - -# Get the user-source connection object from the context, and get the access token -connection = context.get("goauthentik.io/sources/connection") -if not connection: - return False -access_token = connection.access_token - -guild_member_request = requests.get( - GUILD_API_URL.format(guild_id=guild_id), - headers={ - "Authorization": f"Bearer {access_token}" - }, -) -guild_member_info = guild_member_request.json() - -# Ensure we are not being ratelimited -if guild_member_request.status_code == 429: - ak_message(f"Discord is throttling this connection. Retry in {int(guild_member_info['retry_after'])}s") - return False - -# Ensure user is a member of the guild -if "code" in guild_member_info: - if guild_member_info["code"] == 10004: - ak_message("User is not a member of the guild") - else: - ak_create_event("discord_error", source=context["source"], code=guild_member_info["code"]) - ak_message("Discord API error, try again later.") - return False - -# Get all discord_groups -discord_groups = Group.objects.filter(attributes__discord_role_id__isnull=False) - -# Split user groups into discord groups and non discord groups -user_groups_non_discord = request.user.ak_groups.exclude(pk__in=discord_groups.values_list("pk", flat=True)) -user_groups_discord = list(request.user.ak_groups.filter(pk__in=discord_groups.values_list("pk", flat=True))) - -# Filter matching roles based on guild_member_info['roles'] -user_groups_discord_updated = discord_groups.filter(attributes__discord_role_id__in=guild_member_info["roles"]) - -# Combine user_groups_non_discord and matching_roles -user_groups_updated = user_groups_non_discord.union(user_groups_discord_updated) - -# Update user's groups -request.user.ak_groups.set(user_groups_updated) - -# Create event with roles changed -ak_create_event( - "discord_role_sync", - user_discord_roles_before=", ".join(str(group) for group in user_groups_discord), - user_discord_roles_after=", ".join(str(group) for group in user_groups_discord_updated), -) - -return True - -``` - -Now bind this policy to the chosen authentication flows for the Discord OAuth source. - -### Store OAuth info in attribute and create avatar attribute from Discord avatar - -:::info -Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds.members.read` scopes added under **Protocol settings**. -::: - -:::info -In order to use the created attribute in authentik you will have to set authentik configuration arguments found at: https://docs.goauthentik.io/docs/core/settings#avatars -::: - -Create a new **Expression Policy** with the content below, adjusting the variables where required: - -```python -import base64 -import requests - -AVATAR_SIZE = "64" # Valid values: 16,32,64,128,256,512,1024. Larger values may cause HTTP error 431 on applications/providers due to headers being too large. - -# Only change below here if you know what you are doing. -AVATAR_URL = "https://cdn.discordapp.com/avatars/{id}/{avatar}.png?size={avatar_size}" -AVATAR_STREAM_CONTENT = "data:image/png;base64,{base64_string}" # Converts base64 image into html syntax usable with authentik's avatar attributes feature - - -def get_as_base64(url): - """Returns the base64 content of the url""" - return base64.b64encode(requests.get(url).content) - - -def get_avatar_from_avatar_url(url): - """Returns an authentik-avatar-attributes-compatible string from an image url""" - cut_url = f"{url}" - return AVATAR_STREAM_CONTENT.format( - base64_string=(get_as_base64(cut_url).decode("utf-8")) - ) - - -# Ensure flow is only run during OAuth logins via Discord -if not isinstance(context['source'], OAuthSource) or context['source'].provider_type != "discord": - return True - -user = request.user -userinfo = request.context["oauth_userinfo"] - -# Assigns the discord attributes to the user -user.attributes["discord"] = { - "id": userinfo["id"], - "username": userinfo["username"], - "discriminator": userinfo["discriminator"], - "email": userinfo["email"], - "avatar": userinfo["avatar"], - "avatar_url": ( - AVATAR_URL.format( - id=userinfo["id"], avatar=userinfo["avatar"], avatar_size=AVATAR_SIZE - ) - if userinfo["avatar"] - else None - ), -} - -# If the user has an avatar, assign it to the user -avatar_url = user.attributes["discord"].get("avatar_url", None) -if avatar_url is not None: - user.attributes["avatar"] = get_avatar_from_avatar_url(avatar_url) - -user.save() -return True - -``` - -Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source. - -:::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). -::: +- [Discord Developer Documentation](https://discord.com/developers/docs/intro) +- [Discord Developer Documentation - OAuth2](https://discord.com/developers/docs/topics/oauth2#oauth2) 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..a42ab594caa8 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 -support_level: community tags: - source - entra @@ -8,6 +7,8 @@ tags: - active-directory --- +Allows users to authenticate using their Entra ID credentials. + ## Preparation The following placeholders are used in this guide: @@ -16,6 +17,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: @@ -23,12 +26,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. @@ -39,9 +42,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 @@ -56,7 +60,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` @@ -71,14 +75,18 @@ To support the integration of Entra ID with authentik, you need to create an Ent 3. Click **Save**. -:::info +:::info Group Membership When group membership information is synced from Entra ID, authentik creates all groups that a user is a member of. ::: -:::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. @@ -97,3 +105,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/facebook/index.md b/website/docs/users-sources/sources/social-logins/facebook/index.md index cd47f270527a..35995b62a2ed 100644 --- a/website/docs/users-sources/sources/social-logins/facebook/index.md +++ b/website/docs/users-sources/sources/social-logins/facebook/index.md @@ -1,73 +1,74 @@ --- title: Facebook -support_level: community +tags: + - source + - facebook + - meta --- -Adding Facebook as a source allows users to authenticate through authentik using their Facebook credentials. +Allows users to authenticate using their Facebook credentials. ## Preparation -The following placeholders are used: +The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. ## Facebook configuration -To integrate authentik with Facebook and access the user credentials from Facebook, you first need to register with Meta for Developers and create a developers account. Refer to the [Facebook documentation](https://developers.facebook.com/docs/development) for exact steps. +To integrate Facebook with authentik you will need to create an OAuth application in the Meta for Developers Dashboard. -1. Visit https://developers.facebook.com/ and log in to your Facebook account. -2. After you log in, go to https://developers.facebook.com/async/registration and follow the steps to register as a developer. +1. Log in to the [Meta for Developers Dashboard](https://developers.facebook.com/) with your Facebook account. +2. After logging in, [register as a developer](https://developers.facebook.com/async/registration). Refer to the [Facebook development documentation](https://developers.facebook.com/docs/development) for more information. -Next, create an app so that Facebook generates a unique ID for your authentik app. +After registering, you need to create an app so that Facebook generates a unique ID for authentik. -:::info -You will need the Facebook **App ID** and **App Secret** values from the Facebook app in order to configure the authentik integration. See Step 11. below for instructions. -::: - -3. On the Meta for Developers Dashboard click **Create**. +3. On the [Meta for Developers Dashboard](https://developers.facebook.com/) click **Create**. 4. Follow the prompts to create the app. -After you create the app you need to customize the login settings. - -5. Go back to the Dashboard and in the left navigation pane click **Use Cases**. -6. On the **Use cases** page, click **Customize** under **Authentication and account creation**. -7. On the **Customize** page, click **Go to settings**. -8. On the **Facebook Login settings** page set the **Valid OAuth redirect URIs** field to `https://authentik.company/source/oauth/callback/facebook/` and then click **Save**. +After creating the app you need to customize its login settings. -9. Navigate to the **Use cases > Customize** page. -10. Under **Permissions** click **Add** for the **email** permission. +5. On the [Meta for Developers Dashboard](https://developers.facebook.com/) click **Use Cases** in the left navigation pane. +6. Under **Authentication and account creation** click **Customize** and then **Go to settings**. +7. Set the **Valid OAuth redirect URIs** field to `https://authentik.company/source/oauth/callback/facebook/` and then click **Save**. +8. Navigate to the **Use cases** > **Customize** page. +9. Under **Permissions** click **Add** for the **email** permission. -Next, you need to obtain the App ID and the App Secret for the Facebook app, and enter those into your authentik source configuration. +Next, you need to obtain the **App ID** and **App Secret** for the Facebook app. These will be required when creating the source in authentik. -11. Go back to the Dashboard, and in the bottom left in the navigation pane, click on **App settings > Basic**. -12. Copy the **App ID** and the **App secret** values and temporarily store them in a safe place until you enter them into authentik. +10. Go back to the Dashboard, and in the bottom left of the navigation pane, click **App settings** > **Basic**. +11. Take note of the **App ID** and the **App secret** values. Finally, you need to publish the Facebook app. -12. Go back to the Dashboard, and on the **Create and publish this app** page, follow the prompts. +12. Go back to the Dashboard, and on the **Create and publish this app** page, follow the prompts to complete the process. ## authentik configuration -1. Log in to authentik as administrator, and then navigate to **Directory > Federation & Social login**. -2. Click **Create**. -3. In the **New Source** box, for **Select type** select **Facebook OAuth Source** and then click **Next**. -4. Define the following fields: - - **Name**: provide a descriptive name - - **Slug**: leave default value (If you choose a different slug then the default, the URL will need to be updated to reflect the change) - - **User matching mode**: leave default option unless other configuration is needed - - **User path**: leave default option unless other configuration is needed - - **Icon**: optionally you can select a specific icon of logo to display on the login form. - - **Protocol settings** - - **Consumer Key**: enter the **App ID** from Facebook - - **Consumer Secret**: enter the **App Secret** from Facebook - - **Scopes**: define any further access scopes - - **Flow settings** - - **Authentication flow**: leave the default `default-source-authentication` option. - - **Enrollment flow**: leave the default `default-source-enrollment` option. -5. Click **Finish** to save your settings and close the box. - -You now have Facebook as a source. Verify by checking that appears on the **Directory > Federation & Social login** page in authentik. - -:::info +To support the integration of Facebook with authentik, you need to create a Facebook OAuth source in authentik. + +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 **Facebook OAuth Source** as the source type. + - **Create Facebook OAuth Source**: provide a name, a slug which must match the slug used in the Facebook `Valid OAuth redirect URIs` field (e.g. `facebook`), and the following required configurations: + - **Protocol settings** + - **Consumer Key**: enter the **App ID** from Facebook. + - **Consumer Secret**: enter the **App Secret** from Facebook. + - **Scopes** _(optional)_: define any further access scopes. +3. Click **Finish** to save your settings. + +:::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/). +::: + +## 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 + +- [Meta for Developers Documentation - Facebook Login Overview](https://developers.facebook.com/docs/facebook-login/overview) diff --git a/website/docs/users-sources/sources/social-logins/github/githubdeveloper1.png b/website/docs/users-sources/sources/social-logins/github/githubdeveloper1.png deleted file mode 100644 index 773699e3b44c..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/github/githubdeveloper1.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/github/githubdeveloperexample.png b/website/docs/users-sources/sources/social-logins/github/githubdeveloperexample.png deleted file mode 100644 index 69a684244389..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/github/githubdeveloperexample.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/github/githubexample2.png b/website/docs/users-sources/sources/social-logins/github/githubexample2.png deleted file mode 100644 index d7bcb8dfa8d4..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/github/githubexample2.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/github/index.mdx b/website/docs/users-sources/sources/social-logins/github/index.mdx index d75c7460067d..4d73a26e6001 100644 --- a/website/docs/users-sources/sources/social-logins/github/index.mdx +++ b/website/docs/users-sources/sources/social-logins/github/index.mdx @@ -1,68 +1,77 @@ --- title: Github -support_level: authentik +tags: + - source + - github --- -Allows users to authenticate using their Github credentials +Allows users to authenticate using their Github credentials. ## Preparation The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `www.my.company` Homepage URL for your site +- `www.my.company` is the Homepage URL for your site -## Github +## Github configuration -1. Create an OAuth app under Developer Settings https://github.com/settings/developers by clicking on the **Register a new application** +To integrate GitHub with authentik you will need to create an OAuth application in the Discord Developer Portal. -![Register OAuth App](./githubdeveloper1.png) +1. Log in to the GitHub and open the [Developer Settings](https://github.com/settings/developers) menu. +2. Create an OAuth app by clicking on the **Register a new application** button and set the following values: + - **Application Name**: `authentik` + - **Homepage URL**: `www.my.company` + - **Authorization callback URL**: `https://authentik.company/source/oauth/callback/github` -2. **Application Name:** Choose a name users will recognize ie: authentik -3. **Homepage URL:** www.my.company -4. **Authorization callback URL:**: https://authentik.company/source/oauth/callback/github -5. Click **Register Application** +3. Click **Register Application** +4. Click **Generate a new client secret** and take note of the **Client Secret** and **Client ID**. These values will be required in the next section. -Example screenshot +## authentik configuration -![](./githubdeveloperexample.png) +To support the integration of GitHub with authentik, you need to create an GitHub OAuth source in authentik. -6. Copy the **Client ID** and _save it for later_ -7. Click **Generate a new client secret** and _save it for later_ You will not be able to see the secret again, so be sure to copy it now. +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 **GitHub OAuth Source** as the source type. + - **Create Facebook OAuth Source**: provide a name, a slug which must match the slug used in the GitHub `Authorization callback URL` field (e.g. `github`), and set the following required configurations: + - **Protocol settings** + - **Consumer Key**: `` + - **Consumer Secret**: `` + - **Scopes** _(optional)_: define any further access scopes. +3. Click **Finish** to save your settings. -## authentik - -8. Under **Directory > Federation & Social login** click **Create Github OAuth Source**. -9. **Name:** Choose a name (For the example I use Github) -10. **Slug:** github (If you choose a different slug the URLs will need to be updated to reflect the change) -11. **Consumer Key:** Client ID from step 6 -12. **Consumer Secret:** Client Secret from step 7 +:::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). +::: -Here is an example of a complete authentik Github OAuth Source +:::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/). +::: -![](./githubexample2.png) +## Optional additional configuration -Save, and you now have Github as a source. +### Checking for membership of a GitHub Organisation :::info -For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page). +Ensure that the GitHub OAuth source in **Federation & Social login** has the additional `read:org` scope added under **Protocol settings** > **Scopes**. ::: -### Checking for membership of a GitHub Organisation - -To check if the user is member of an organisation, you can use the following policy on your flows: +To check if the user is member of an organisation, you can use the following policy on your flows. -:::info -Make sure to include `read:org` in the sources' _Scopes_ setting. -::: +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Policies**. +3. Click **Create**, select **Expression Policy** and then **Next**. +4. Provide a name for the policy and set the following expression: ```python +# Set this value +accepted_org = "your_organization" + # Ensure flow is only run during oauth logins via Github if not isinstance(context['source'], OAuthSource) or context["source"].provider_type != "github": return True -accepted_org = "foo" - # Get the user-source connection object from the context, and get the access token connection = context["goauthentik.io/sources/connection"] access_token = connection.access_token @@ -71,7 +80,6 @@ access_token = connection.access_token github_username = context["oauth_userinfo"] # Github does not include Organisations in the userinfo endpoint, so we have to call another URL - orgs_response = requests.get( "https://api.github.com/user/orgs", auth=(github_username["login"], access_token), @@ -95,10 +103,18 @@ if not user_matched: return user_matched ``` -If a user is not member of the chosen organisation, they will see this message +5. Click **Finish**. You can now bind this policy to the chosen enrollment and/or authentication flow of the GitHub OAuth source. +6. Navigate to **Flows and Stages** > **Flows** and click the name of the flow in question. +7. Open the **Policy/Group/User Bindings** tab and click **Bind existing Policy/Group/User**. +8. Select the policy that you previously created and click **Create**. +9. Optionally, repeat the process for any other flows that you want the policy applied to. + +If a user is not member of the chosen organisation, they will see this message: ![](./github_org_membership.png) -:::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). -::: +## 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 diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/authentiksource.png b/website/docs/users-sources/sources/social-logins/google/cloud/authentiksource.png deleted file mode 100644 index a8f5ca03458c..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/authentiksource.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper2.png b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper2.png index 5ad1fd89eab5..5e89969df207 100644 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper2.png and b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper2.png differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper3.png b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper3.png index 5e89969df207..26215358e97f 100644 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper3.png and b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper3.png differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper4.png b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper4.png index 26215358e97f..40ed69b97508 100644 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper4.png and b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper4.png differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper5.png b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper5.png deleted file mode 100644 index 0d14ce65d25c..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper5.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper6.png b/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper6.png deleted file mode 100644 index 40ed69b97508..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/google/cloud/googledeveloper6.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/google/cloud/index.md b/website/docs/users-sources/sources/social-logins/google/cloud/index.md index 4941c1cfeda9..b40a271bfb1f 100644 --- a/website/docs/users-sources/sources/social-logins/google/cloud/index.md +++ b/website/docs/users-sources/sources/social-logins/google/cloud/index.md @@ -1,11 +1,14 @@ --- title: Google Cloud (with OAuth) sidebar_label: Google Cloud (OAuth) -tags: [integration, oauth, google] -support_level: community +tags: + - source + - google + - google cloud + - oauth --- -Allows users to authenticate using their Google credentials +Allows users to authenticate using their Google credentials. ## Preparation @@ -13,91 +16,101 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -## Google +## Google configuration -You will need to create a new project, and OAuth credentials in the Google Developer console. The developer console can be overwhelming at first. +To integrate Google with authentik you will need to create a new project, and OAuth credentials in the Google Developer console. -1. Visit https://console.developers.google.com/ to create a new project -2. Create a New project. +1. Log in to the [Google Developer Console](https://console.developers.google.com/). +2. Click on **GLogin** in the top left and then **New Project**. ![](./googledeveloper1.png) -3. **Project Name**: Choose a name -4. **Organization**: Leave as default if unsure -5. **Location**: Leave as default if unsure +3. Set the following values: + - **Project Name**: Provide a name + - **Organization**: Leave as default if unsure + - **Location**: Leave as default if unsure + +4. Click **Create**. +5. Select your project from the drop down at the top. +6. Click the **Credentials** menu icon on the left which looks like a key. ![](./googledeveloper2.png) -6. Click **Create** -7. Choose your project from the drop down at the top -8. Click the **Credentials** menu item on the left. It looks like a key. +7. On the right side, click on **Configure Consent Screen**. ![](./googledeveloper3.png) -9. Click on **Configure Consent Screen** +8. Set the following required fields: + - **User Type**: If you do not have a Google Workspace (GSuite) account choose _External_. If you do have a Google Workspace (Gsuite) account and want to limit access to only users inside of your organization choose _Internal_. + - **App Name**: `authentik` + - **User Support Email**: Must have a value + - **Authorized Domains**: authentik.company + - **Developer Contact Info**: Must have a value +9. Click **Save and Continue** +10. If you have special scopes configured for google, enter them on this screen. If not click **Save and Continue**. +11. If you want to create test users enter them here, if not click **Save and Continue**. +12. From the **Summary** page click on the **Credentials** menu icon on the left which looks like a key. +13. Click **Create Credentials** on the top of the screen and select **OAuth Client ID**. +14. Set the following required fields: + - **Application Type**: `Web Application` + - **Name**: Provide a name + - **Authorized redirect URIs**: `https://authentik.company/source/oauth/callback/google/` ![](./googledeveloper4.png) -10. **User Type:** If you do not have a Google Workspace (GSuite) account choose _External_. If you do have a Google Workspace (Gsuite) account and want to limit access to only users inside of your organization choose _Internal_ - -_I'm only going to list the mandatory/important fields to complete._ - -11. **App Name:** Choose an Application -12. **User Support Email:** Must have a value -13. **Authorized Domains:** authentik.company -14. **Developer Contact Info:** Must have a value -15. Click **Save and Continue** -16. If you have special scopes configured for google, enter them on this screen. If not click **Save and Continue** -17. If you want to create Test Users enter them here, if not click **Save and Continue** -18. From the _Summary Page_ click on the \*_Credentials_ link on the left. Same link as step 8 -19. Click **Create Credentials** on the top of the screen -20. Choose **OAuth Client ID** - -![](./googledeveloper5.png) - -21. **Application Type:** Web Application -22. **Name:** Choose a name -23. **Authorized redirect URIs:** `https://authentik.company/source/oauth/callback/google/` - -![](./googledeveloper6.png) - -24. Click **Create** -25. Copy and store _Your Client ID_ and _Your Client Secret_ for later - -## authentik +15. Click **Create**. +16. Take note of the **Client ID** and **Client Secret**. These values will be required in the next section. -26. Under **Directory > Federation & Social login** click **Create Google OAuth Source** +## authentik configuration -27. **Name**: Choose a name (For the example I use Google) -28. **Slug**: google (If you choose a different slug the URLs will need to be updated to reflect the change) -29. **Consumer Key:** Your Client ID from step 25 -30. **Consumer Secret:** Your Client Secret from step 25 +To support the integration of Google with authentik, you need to create a Google OAuth source in authentik. -Here is an example of a complete authentik Google 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 **Google OAuth Source** as the source type. + - **Create Google OAuth Source**: provide a name, a slug which must match the slug used in the Google `Authorized redirect URI` field (e.g. `google`), and set the following required configurations: + - **Protocol settings** + - **Consumer Key**: `` + - **Consumer Secret**: `` + - **Scopes** _(optional)_: define any further access scopes. +3. Click **Finish** to save your settings. -![](./authentiksource.png) - -Save, and you now have Google as a 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). ::: -## Username mapping +:::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/). +::: + +## Optional additional configuration -Since google does not have the concept of a username, authentik will by default prompt the user for a username when they first enroll through a google source. To change this behaviour and automatically use the email address as username, create an expression policy to set the username to the email, and bind it to the enrollment flow. +### Username mapping -Create an expression policy with this expression: +Google does not have the concept of a username, therefore authentik will by default prompt the user for a username when they first enroll through a google source. To change this behaviour and automatically use the email address as username, create an expression policy to set the username to the email, and bind it to the enrollment flow. + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Policies**. +3. Click **Create**, select **Expression Policy** and then **Next**. +4. Provide a name for the policy and set the following expression: ```python email = request.context["prompt_data"]["email"] # Direct set username to email + request.context["prompt_data"]["username"] = email # Set username to email without domain # request.context["prompt_data"]["username"] = email.split("@")[0] return False ``` -Afterwards, edit the source's enrollment flow (by default _default-source-enrollment_), expand the policies bound to the first stage (_default-source-enrollment-prompt_), and bind the policy created above. Make sure the newly created policy comes before _default-source-enrollment-if-username_. Afterwards, any new logins will automatically have their google email address used as their username. +5. Click **Finish**. You can now bind this policy to the chosen enrollment flow of the Google OAuth source. +6. Navigate to **Flows and Stages** > **Flows** and click the name of the flow in question. +7. Open the **Stage Bindings** tab, expand the policies bound to the first stage and click **Bind existing Policy/Group/User**. +8. Select the policy that you previously created and click **Create**. + +:::note +If using the default enrollment flow the policy should be bound to the **default-source-enrollment-prompt** stage. Ensure that the policy comes before **default-source-enrollment-if-username** +::: -This can be combined with disallowing users from changing their usernames, see [Configuration](../../../../../sys-mgmt/settings.md#allow-users-to-change-username). +Afterwards, any new logins will automatically have their google email address used as their username. This can be combined with disallowing users from changing their usernames, see [Configuration](../../../../../sys-mgmt/settings.md#allow-users-to-change-username). diff --git a/website/docs/users-sources/sources/social-logins/google/index.mdx b/website/docs/users-sources/sources/social-logins/google/index.mdx index 44898019ee09..35083e64f71c 100644 --- a/website/docs/users-sources/sources/social-logins/google/index.mdx +++ b/website/docs/users-sources/sources/social-logins/google/index.mdx @@ -11,17 +11,16 @@ This page provides an overview of how to configure each protocol as a federated authentik can also be configuration to authenticate users into Google services. For more information, see the [Google Workspace Integration](/integrations/services/google/) guide. - ::: ## Google Cloud (OAuth) Google Cloud Identity Platform provides OAuth 2.0 as a federated identity provider. This configuration guide shows how to set up OAuth 2.0 as the authentication method between Google and authentik. -[Configure Google Cloud with authentik ›](./cloud/index.md) +[Configure Google Cloud with authentik](./cloud/index.md) ## Google Workspace (SAML) Google Workspace (formerly G Suite) allows users to authenticate into applications using their company email addresses. This configuration guide shows how to set up Security Assertion Markup Language (SAML) as the authentication method between Google Workspace and authentik. -[Configure Google Workspace with authentik ›](./workspace/index.md) +[Configure Google Workspace with authentik](./workspace/index.md) diff --git a/website/docs/users-sources/sources/social-logins/google/workspace/index.md b/website/docs/users-sources/sources/social-logins/google/workspace/index.md index 2d8fc4a2de5c..c9e1596bd2f0 100644 --- a/website/docs/users-sources/sources/social-logins/google/workspace/index.md +++ b/website/docs/users-sources/sources/social-logins/google/workspace/index.md @@ -1,17 +1,20 @@ --- title: Google Workspace (with SAML) sidebar_label: Google Workspace (SAML) -tags: [integration, saml, google] -support_level: authentik +tags: + - source + - google + - google workspace + - saml --- -This topic covers configuring authentik to authenticate users with their Google Workspace credentials. +Allows users to authenticate using their Google Workspace credentials. ## What is Google Workspace? Google Workspace (formerly G Suite) is a collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google. -Organizations using Google Workspace allow their users to authenticate into applications using their company email addresses. This guide shows how to set up Security Assertion Markup Language (SAML) as the authentication method between Google Workspace and authentik. +Organizations using Google Workspace allow their users to authenticate into applications using their company email addresses. This guide shows how to set up Security Assertion Markup Language (SAML) as the authentication method between Google Workspace and authentik. ## SAML Authentication Flow @@ -38,147 +41,86 @@ In short, the user navigates to the application, is redirected to authentik, cho The key characteristic that makes this an IdP-to-IdP flow is that authentik is acting as an intermediary identity provider, brokering trust between your application and Google Workspace. ---- - ## Preparation -By the end of this integration, your authentik instance will allow users to authenticate using their Google Workspace credentials. - -You'll need to have authentik instance running and accessible on an HTTPS domain, and a Google Workspace domain with super-administrator access. - -Keep a text-editor handy because we'll be copying and pasting values between the two services. - -### Placeholders +The following placeholders are used in this guide: -The following placeholders are used: - -- `authentik.company`: The Fully Qualified Domain Name of the authentik installation. +- `authentik.company` is the FQDN of the authentik installation. ## Google Workspace configuration -We'll need some information from Google to complete the integration, so -start by logging into [Workspace Admin Console](https://admin.google.com/) as a super-admin. +To integrate Google Workspace with authentik you will need to create a SAML application in the Google Workspace Admin Console. ### Create a new application -From the Workspace Admin Console, navigate to the _Apps_ section, and then to _Web and mobile apps_. -Continue by expanding the **Add app** dropdown and selecting **Add custom SAML app.** - -Within the app creation page, define the following **Name** and **Description** for the new application. - -| Field | Value | -| ----------- | ---------------------------- | -| Name | authentik | -| Description | Single Sign-On for authentik | - -Press **Continue** to generate the SAML configuration we'll need to complete the integration. - -### Google Identity Provider details - -You should now be presented with a choice to download metadata file containing the SAML configuration, or copy the details to your clipboard. - -Under _Option 2_, copy the SSO URL to your text editor and download the certificate. - -:::info{title="Entity ID"} +1. Log in to the [Google Workspace Admin Console](https://admin.google.com/) as a super-admin. +2. Navigate to **Apps** > **Web and mobile apps**. +3. Expand the **Add app** dropdown and select **Add custom SAML app**. +4. Set the following fields: + - **Name**: `authentik` + - **Description**: `Single Sign-On for authentik` +5. Press **Continue** to generate the SAML configuration. +6. Under **Option 2**, download the certificate and take note of the **SSO URL**. Both will be required when configuring authentik. +:::info Entity ID authentik is acting as both a Service Provider (SP) to Google and an Identity Provider (IdP) to your applications. Since we only need the SP configuration, you can ignore the Entity ID provided by Google. - ::: -With the SSO URL and certificate downloaded, press **Continue** to proceed to the next step. +7. Click **Continue**. ### Service Provider details -We'll need to provide Google with some information about our authentik instance, specifically the Assertion Consumer Service (ACS) URL. This URL is where Google sends the SAML response after a user is authenticated. We'll also need to provide the Entity ID, which can be any unique identifier, but we recommend using the URL of your authentik instance. - -| Field | Value | -| --------------- | --------------------------------------------------- | -| ACS URL | `https://authentik.company/source/saml/google/acs/` | -| Entity ID | `https://authentik.company` | -| Start URL | `https://authentik.company` | -| Name ID format | `EMAIL` | -| Name ID | Basic Information › Primary Email | -| Signed Response | Enabled ✅ | - -:::info{title="Verify signed responses"} - -Enabling signed responses indicates that the entire SAML authentication response will be signed by Google. You'll need to configure uploaded certificates in authentik if you enable this option. - -[Read more about uploading certificates ›](../../../../../sys-mgmt/certificates) +8. We'll need to provide Google with some information about our authentik instance. Set the following fields: + - **ACS URL**: `https://authentik.company/source/saml/google/acs/` + - **Entity ID**: `https://authentik.company` + - **Start URL**: `https://authentik.company` + - **Name ID format**: `EMAIL` + - **Name ID**: Basic Information › Primary Email + - **Signed Response**: Enabled +:::info Verify signed responses +Enabling signed responses indicates that the entire SAML authentication response will be signed by Google. You'll need to [configure certificates in authentik](../../../../../sys-mgmt/certificates) if you enable this option. ::: -Before you proceed, copy these values to your text editor as we'll need them when configuring authentik. - ### Attribute mapping -Next, we configure which user attributes Google should send to authentik. -This is where we map the Google Directory attributes to the attributes that authentik expects. - -| Google Directory attributes | App attributes | -| --------------------------------- | -------------- | -| Basic Information › Primary Email | `email` | +9. Next, we configure which user attributes Google should send to authentik, and map them to the attributes that authentik expects. Set the following field: + - **Basic Information › Primary Email**: `email` ### Enable the application for your organization -Finally, we complete the application creation process by saving the configuration. - -You should now see the new application in the list of SAML apps. View the application details and confirm that the SSO URL and Entity ID are correct. Note that you may need to **enable the app** for your organization to allow users to authenticate. +10. Finally, we complete the application creation process by saving the configuration. ---- +You should now see the new application in the list of SAML apps. View the application details and confirm that the **SSO URL** and **Entity ID** are correct. You may need to **Enable the app** for your organization to allow users to authenticate. ## authentik configuration -We'll now configure authentik to accept SAML authentication from Google Workspace. - -Start by logging into your authentik instance as an administrator and navigating to the Admin Interface. - -### Create a Federation Source - -In the Admin interface, navigate to **Directory > Federation & Social login** and press **Create**. - -In the **New source** box, choose **SAML Source** and continue by filling in the following fields: - -| Field | Value | -| ----- | ---------------- | -| Name | Google Workspace | -| Slug | `google` | - -:::info{title="Choosing a slug"} -Your choice of `slug` should match the ACS URL you provided to Google Workspace. -You can choose a different slug, but you will need to update the ACS URL in Google Workspace to match. -::: - -:::info +To support the integration of Google Workspace with authentik, you need to create an SAML source in authentik. + +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 **SAML Source** as the source type. + - **Create SAML Source**: provide a name, a slug which must match the slug used in the Google Workspace `ACS URL` field (e.g. `google`), and set the following required configurations: + - **Protocol settings** + - **SSO URL**: SSO URL from Google Workspace + - **Issuer (Entity ID)**: `https://authentik.company` + - **Verification Certificate**: Certificate downloaded from Google Workspace + - **Advanced Protocol Settings**: + - **Allow IdP-initiated Login**: Enabled + - **NameID Policy**: `Email address` +3. Click **Finish** to save your settings. + +:::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). ::: -#### Protocol settings - -Next, we'll configure the SAML protocol settings for the source. Fill in the following fields with the values you copied from Google Workspace: - -| | | -| ------------------------ | --------------------------------------------------------- | -| SSO URL | `https://accounts.google.com/o/saml2/idp?idpid=#########` | -| Issuer (Entity ID) | `https://authentik.company` | -| Verification Certificate | _Certificate downloaded from Google Workspace_ | - -#### Advanced protocol settings - -Depending on your Google Workspace configuration, you might need to adjust the advanced protocol settings. - -| Field | Value | -| ------------------------- | ------------- | -| Allow IdP-initiated Login | Enabled ✅ | -| NameID Policy | Email address | - -Finally, save the source configuration and confirm the application is present in the list of federated sources. - -## Testing your configuration +:::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/index.md). +::: -To test your configuration, navigate to the login page of your authentik instance and confirm the Google Workspace option is available as an alternative login method. +## Source property mappings -Next, click on the Google Workspace button and confirm that you are redirected to authenticate via your Google Workspace credentials. After successful authentication **with a non-super-admin account**, you should be redirected back to your authentik instance and logged in. +Source property mappings allow you to modify or gather extra information from sources. See the [overview](../../../property-mappings/index.md) for more information. ## Troubleshooting @@ -199,10 +141,8 @@ In the Google Workspace Admin Console, go to **Menu > Apps > Web and mobile apps This may take a few minutes to propagate, so try logging in again after a short wait. -## External references +## Resources -- [Google Workspace Admin Console](https://admin.google.com/) -- [Google Developer Console](https://support.google.com/a/answer/6327792) -- [Setting up SAML with Google Workspace](https://support.google.com/a/answer/6087519) -- [SAML app error messages](https://support.google.com/a/answer/6301076) -- [SAML authentication flow](https://infosec.mozilla.org/guidelines/iam/saml.html) +- [Google Workspace Admin Help - Creating custom attributes using the user schema](https://support.google.com/a/answer/6327792) +- [Google Workspace Admin Help - Set up your own custom SAML app](https://support.google.com/a/answer/6087519) +- [Google Workspace Admin Help - SAML app error messages](https://support.google.com/a/answer/6301076) diff --git a/website/docs/users-sources/sources/social-logins/mailcow/index.md b/website/docs/users-sources/sources/social-logins/mailcow/index.md index 77e5208addfc..b7c869ff58ff 100644 --- a/website/docs/users-sources/sources/social-logins/mailcow/index.md +++ b/website/docs/users-sources/sources/social-logins/mailcow/index.md @@ -1,53 +1,52 @@ --- title: Mailcow -support_level: community +tags: + - source + - mailcow --- -Allows users to authenticate using their Mailcow credentials +Allows users to authenticate using their Mailcow credentials. ## Preparation The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `mailcow.company` is the FQDN of the mailcow installation. +- `mailcow.company` is the FQDN of the Mailcow installation. -## Mailcow +## Mailcow configuration -1. Log in to mailcow as an admin and navigate to the OAuth2 Apps settings +To integrate Mailcow with authentik you will need to create an OAuth application in Mailcow. -![OAuth2 Apps menu](./mailcow1.png) +1. Log in to Mailcow as an administrator +2. Navigate to **System** > **Configuration**, and then **Access** > **OAuth2 Apps**. +3. Click **Add OAuth2 client** and provide the **Redirect URI**: `https://authentik.company/source/oauth/callback/mailcow/` +4. Take note of the **Client ID** and **Client Secret**. These values will be required in the next section. -2. Click "Add OAuth2 Client" +## authentik configuration -3. Insert the redirect URL: `https://authentik.company/source/oauth/callback/mailcow/` - -![Add OAuth2 Client](./mailcow2.png) - -4. Copy the **Client ID** and **Client secret** and _save it for later_ - -![ClientID and Secret](./mailcow3.png) - -## authentik - -5. Under **Directory > Federation & Social login** click **Create > Mailcow OAuth Source** - -![Mailcow OAuth Source](./mailcow4.png) - -6. **Name:** Choose a name (For the example I used Mailcow) -7. **Slug:** mailcow (You can choose a different slug, if you do you will need to update the Mailcow redirect URL and point it to the correct slug.) -8. **Consumer Key:** Client ID from step 4 -9. **Consumer Secret:** Client Secret from step 4 -10. **Authorization URL:** https://mailcow.company/oauth/authorize -11. **Access token URL:** https://mailcow.company/oauth/token -12. **Profile URL:** https://mailcow.company/oauth/profile - -Here is an example of a complete authentik Mailcow OAuth Source - -![](./mailcow5.png) - -Save, and you now have Mailcow as a 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 **OAuth Source** as the source type. + - **Create OAuth Source**: provide a name, a slug which must match the slug used in the Mailcow `Redirect URI` field (e.g. `mailcow`), and set the following required configurations: + - **Protocol settings** + - **Consumer Key**: `` + - **Consumer Secret**: `` + - **Scopes** _(optional)_: define any further access scopes. + - **URL Settings** + - **Authorization URL**: `https://mailcow.company/oauth/authorize` + - **Access token URL**: `https://mailcow.company/oauth/token` + - **Profile URL**: `https://mailcow.company/oauth/profile` +3. Click **Finish** to save your settings. :::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). ::: + +:::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/). +::: + +## 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. diff --git a/website/docs/users-sources/sources/social-logins/mailcow/mailcow1.png b/website/docs/users-sources/sources/social-logins/mailcow/mailcow1.png deleted file mode 100644 index 78191554b4de..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/mailcow/mailcow1.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/mailcow/mailcow2.png b/website/docs/users-sources/sources/social-logins/mailcow/mailcow2.png deleted file mode 100644 index 9c4a4e440a2a..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/mailcow/mailcow2.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/mailcow/mailcow3.png b/website/docs/users-sources/sources/social-logins/mailcow/mailcow3.png deleted file mode 100644 index 0a63cecd7e3a..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/mailcow/mailcow3.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/mailcow/mailcow4.png b/website/docs/users-sources/sources/social-logins/mailcow/mailcow4.png deleted file mode 100644 index f28f031fd808..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/mailcow/mailcow4.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/mailcow/mailcow5.png b/website/docs/users-sources/sources/social-logins/mailcow/mailcow5.png deleted file mode 100644 index c8c30e3b8d92..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/mailcow/mailcow5.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/plex/index.md b/website/docs/users-sources/sources/social-logins/plex/index.md index 30f23c136ef0..08b14e1eb98b 100644 --- a/website/docs/users-sources/sources/social-logins/plex/index.md +++ b/website/docs/users-sources/sources/social-logins/plex/index.md @@ -1,37 +1,38 @@ --- title: Plex -support_level: community +tags: + - source + - plex --- -Allows users to authenticate using their Plex credentials +Allows users to authenticate using their Plex credentials. ## Preparation None -## authentik > Sources +## authentik configuration -Add _Plex_ as a _source_ +To support the integration of Plex with authentik, you need to create a Plex source in authentik. -- Name: Choose a name -- Slug: Set a slug -- Client ID: Set a unique Client Id or leave the generated ID -- Press _Load Servers_ to login to plex and pick the authorized Plex Servers for "allowed users" -- Decide if _anyone_ with a plex account can authenticate or only friends you share with - -Save, and you now have Plex as a 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 **Plex Source** as the source type. + - **Create Plex Source**: provide a name, a slug, and set the following required configurations: + - **Protocol settings** + - **Client ID**: Set a unique Client ID or leave the generated ID + - Click **Load Servers** to login to Plex and pick the authorized Plex Servers for "allowed users". + - Decide if _anyone_ with a Plex account can authenticate or only friends you share access with. +3. Click **Finish** to save your settings. :::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). ::: -## Plex source property mappings - -See the [overview](../../property-mappings/index.md) for information on how property mappings work. - -### Expression data +:::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/). +::: -The following variables are available to OAuth source property mappings: +## Source property mappings -- `info`: A Python dictionary containing Plex user data. -- `auth_api`: A Plex client object to make requests to the Source with authentication built-in. +Source property mappings allow you to modify or gather extra information from sources. See the [overview](../../property-mappings/index.md) for more information. diff --git a/website/docs/users-sources/sources/social-logins/twitch/index.md b/website/docs/users-sources/sources/social-logins/twitch/index.md index 4cb42b4823fd..5c53150dbf0b 100644 --- a/website/docs/users-sources/sources/social-logins/twitch/index.md +++ b/website/docs/users-sources/sources/social-logins/twitch/index.md @@ -1,9 +1,11 @@ --- title: Twitch -support_level: community +tags: + - source + - twitch --- -Allows users to authenticate using their Twitch credentials +Allows users to authenticate using their Twitch credentials. ## Preparation @@ -11,49 +13,48 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -## Twitch +## Twitch configuration -1. Click **Register Your Application** in the Twitch Developers Console https://dev.twitch.tv/console +To integrate Twitch with authentik you will need to create an OAuth application in the Twitch Developers Console. -![Register Your Application Button](./twitch1.png) +1. Log in to the [Twitch Developers Console](https://dev.twitch.tv/console). +2. Next to **Applications** click **Register Your Application** and set the following fields: + - **Name**: `authentik` + - **OAuth Redirect URLs**: `https://authentik.company/source/oauth/callback/twitch` + - **Category**: select a category for your application -2. Name your Application +3. Click **Create** to finish the registration of your application. +4. Next to your newly created application, click **Manage**. +5. Generate a secret by clicking **New Secret**. +6. Take note of the **Client ID** and **Client Secret**. This value will be required in the next section. +7. Click **Save**. -3. Add https://authentik.company/source/oauth/callback/twitch in the **OAuth Redirect URLs** field +## authentik configuration -4. Select a Category for your Application +To support the integration of Twitch with authentik, you need to create an Twitch OAuth source in authentik. -5. Click **Create** to finish the registration of your Application +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 **Twitch OAuth Source** as the source type. + - **Create OAuth Source**: provide a name, a slug which must match the slug used in the Twitch `OAuth Redirect URLs` field (e.g. `twitch`), and set the following required configurations: + - **Protocol settings** + - **Consumer Key**: `` + - **Consumer Secret**: `` + - **Scopes** _(optional)_: define any further access scopes. +3. Click **Finish** to save your settings. -![Create Application](./twitch2.png) - -6. Click **Manage** on your newly created Application - -![Manage Application](./twitch3.png) - -7. Copy your Client ID and save it for later - -8. Click **New Secret** to create a new Secret - -9. Copy the above Secret and also save it for later - -![Copy Keys](./twitch4.png) - -## authentik - -10. Under _Directory > Federation & Social login_ Click **Create Twitch OAuth Source** +:::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). +::: -11. **Name:** Choose a name (For the example I used Twitch) -12. **Slug:** twitch (You can choose a different slug, if you do you will need to update the Twitch redirect URL and point it to the correct slug.) -13. **Consumer Key:** Client ID from step 7 -14. **Consumer Secret:** Secret from step 9 +:::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/). +::: -Here is an example of a complete authentik Twitch OAuth Source +## Source property mappings -![Authentik Source Example](./twitch5.png) +Source property mappings allow you to modify or gather extra information from sources. See the [overview](../../property-mappings/index.md) for more information. -Save, and you now have Twitch as a source. +## Resources -:::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). -::: +- [Twitch Developer Documentation](https://dev.twitch.tv/docs) diff --git a/website/docs/users-sources/sources/social-logins/twitch/twitch1.png b/website/docs/users-sources/sources/social-logins/twitch/twitch1.png deleted file mode 100644 index 324cf95414c0..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/twitch/twitch1.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/twitch/twitch2.png b/website/docs/users-sources/sources/social-logins/twitch/twitch2.png deleted file mode 100644 index 6e15e000a0cc..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/twitch/twitch2.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/twitch/twitch3.png b/website/docs/users-sources/sources/social-logins/twitch/twitch3.png deleted file mode 100644 index f9b77e210e39..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/twitch/twitch3.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/twitch/twitch4.png b/website/docs/users-sources/sources/social-logins/twitch/twitch4.png deleted file mode 100644 index fa4626723a58..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/twitch/twitch4.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/twitch/twitch5.png b/website/docs/users-sources/sources/social-logins/twitch/twitch5.png deleted file mode 100644 index b837e59d56cf..000000000000 Binary files a/website/docs/users-sources/sources/social-logins/twitch/twitch5.png and /dev/null differ diff --git a/website/docs/users-sources/sources/social-logins/twitter/index.md b/website/docs/users-sources/sources/social-logins/twitter/index.md index d19268fd6f7d..7843307667f8 100644 --- a/website/docs/users-sources/sources/social-logins/twitter/index.md +++ b/website/docs/users-sources/sources/social-logins/twitter/index.md @@ -1,9 +1,12 @@ --- -title: Twitter -support_level: authentik +title: X (Twitter) +tags: + - source + - x + - twitter --- -Allows users to authenticate using their twitter credentials +Allows users to authenticate using their X credentials. ## Preparation @@ -11,37 +14,46 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -## Twitter +## X configuration -You will need to create a new project, and OAuth credentials in the Twitter Developer console. +To integrate X with authentik you will need to create an OAuth application in the X Developer Portal. -1. Visit https://developer.twitter.com/ to create a new App -2. Select an environment fitting to your use-case -3. Give the app a name, for example _authentik_ -4. Finish setting up the app by clicking **App settings**. Any of the API keys on this screen are not used by authentik. -5. Click the **Set up** button +1. Log in to the [X Developer Portal](https://developer.twitter.com/). +2. Navigate to **Projects & Apps** > **Overview**. +3. Click the **App Settings** icon (cogwheel) next to the Project App that you want to use. For information on creating a new Project App, refer to the [X Developer Documentation](https://docs.x.com/fundamentals/developer-apps#app-management). +4. Under **User authentication settings**, click **Set up** and set the following required fields: + - **App permissions**: `Read` + - **Type of App**: `Web App, Automated App or Bot` + - **Callback URI / Redirect URL**: `https://authentik.company/source/oauth/callback/x/` + - **Website URL**: `https://authentik.company` -![](./twitter1.png) +5. Click **Save**. +6. Take note of the **Client ID** and **Client Secret**. These values will be required in the next section. +7. Click **Done**. -6. Enable **OAuth 2.0** -7. Set **Type of App** to _Web_ -8. Set **Callback URI / Redirect URL** to `https://authentik.company/source/oauth/callback/twitter/` -9. Set **Website URL** to `https://authentik.company` +## authentik configuration -![](./twitter2.png) +To support the integration of X with authentik, you need to create a Twitter OAuth source in authentik. -10. Confirm with **Save** -11. Copy and store **Client ID** and **Client Secret** for later - -## authentik - -1. Under **Directory > Federation & Social login** click **Create Twitter OAuth Source** - -2. **Name**: Choose a name (For the example I use Google) -3. **Slug**: twitter (If you choose a different slug the URLs will need to be updated to reflect the change) -4. **Consumer Key:** Your Client ID from step 25 -5. **Consumer Secret:** Your Client Secret from step 25 +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 **Twitter OAuth Source** as the source type. + - **Create OAuth Source**: provide a name, a slug which must match the slug used in the X `Callback URI / Redirect URL` field (e.g. `x`), and set the following required configurations: + - **Protocol settings** + - **Consumer Key**: Enter the Client ID from the X Developer Portal. + - **Consumer Secret**: Enter the Client Secret from the X Developer Portal. + - **Scopes** _(optional)_: define any further access scopes. +3. Click **Finish**. :::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). ::: + +:::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/). +::: + +## Resources + +- [X Developer Portal Documentation](https://docs.x.com/fundamentals/developer-portal) +- [X Developer Documentation - App Management](https://docs.x.com/fundamentals/developer-apps#app-management)