website/docs: move Sources from Integrations into Docs (#9515)

* moved Sources form Integrations to Docs

* files moved

* fixed setting options

* fixed broken links and added redirects

* try single-sourcing Sources docs

* tweaks

* fighting links

* still fighting links

* fightng sidebar

* fighting with sidebar

* add logos and tweak

* image tweaks

* Optimised images with calibre/image-actions

* added remaining UI definitions

* kens edits

---------

Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>

website/developer-docs/docs/templates/index.md

@@ -16,7 +16,7 @@ The most common types are:
 
 ### Add a new integration
 
-To add documentation for a new [integration](../../../integrations/) (with support level Community or Vendor), please use the integration template [`service.md`](https://github.com/goauthentik/authentik/blob/main/website/integrations/_template/service.md) file from our GitHub repo. You can download the template file using the following command:
+To add documentation for a new integration (with support level Community or Vendor), please use the integration template [`service.md`](https://github.com/goauthentik/authentik/blob/main/website/integrations/_template/service.md) file from our GitHub repo. You can download the template file using the following command:
 
 ```shell
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/integrations/_template/service.md

website/docs/flow/stages/identification/index.md

@@ -12,7 +12,7 @@ Select which fields the user can use to identify themselves. Multiple fields can
 -   Email
 -   UPN
 
-    UPN will attempt to identify the user based on the `upn` attribute, which can be imported with an [LDAP Source](/integrations/sources/ldap/)
+    UPN will attempt to identify the user based on the `upn` attribute, which can be imported with an [LDAP Source](/docs/sources/ldap/)
 
 ## Password stage
 
@@ -32,7 +32,7 @@ When enabled, any user identifier will be accepted as valid (as long as they mat
 
 ## Source settings
 
-Some sources (like the [OAuth Source](../../../../integrations/sources/oauth/) and [SAML Source](../../../../integrations/sources/saml/)) require user interaction. To make these sources available to users, they can be selected in the Identification stage settings, which will show them below the selected [user field](#user-fields).
+Some sources (like the [OAuth Source](../../../../docs/sources/oauth/) and [SAML Source](../../../../docs/sources/saml/)) require user interaction. To make these sources available to users, they can be selected in the Identification stage settings, which will show them below the selected [user field](#user-fields).
 
 By default, sources are only shown with their icon, which can be changed with the _Show sources' labels_ option.
 

website/docs/flow/stages/source/index.md

@@ -7,7 +7,7 @@ title: Source stage
 
 ---
 
-The source stage injects an [OAuth](../../../../integrations/sources/oauth/) or [SAML](../../../../integrations/sources/saml/) Source into the flow execution. This allows for additional user verification, or to dynamically access different sources for different user identifiers (username, email address, etc).
+The source stage injects an [OAuth](../../../../docs/sources/oauth/) or [SAML](../../../../docs/sources/saml/) Source into the flow execution. This allows for additional user verification, or to dynamically access different sources for different user identifiers (username, email address, etc).
 
 ```mermaid
 sequenceDiagram
@@ -44,13 +44,13 @@ This stage can be used to leverage an external OAuth/SAML identity provider.
 
 For example, you can authenticate users by routing them through a custom device-health solution.
 
-Another use case is to route users to authenticate with your legacy (Okta, etc) IdP and then use the returned identity and attributes within authentik as part of an authorization flow, for example as part of an IdP migration. For authentication/enrollment this is also possible with an [OAuth](../../../../integrations/sources/oauth/)/[SAML](../../../../integrations/sources/saml/) source by itself.
+Another use case is to route users to authenticate with your legacy (Okta, etc) IdP and then use the returned identity and attributes within authentik as part of an authorization flow, for example as part of an IdP migration. For authentication/enrollment this is also possible with an [OAuth](../../../../docs/sources/oauth/)/[SAML](../../../../docs/sources/saml/) source by itself.
 
 ### Options
 
 #### Source
 
-The source the user is redirected to. Must be a web-based source, such as [OAuth](../../../../integrations/sources/oauth/) or [SAML](../../../../integrations/sources/saml/). Sources like [LDAP](../../../../integrations/sources/ldap/) are _not_ compatible.
+The source the user is redirected to. Must be a web-based source, such as [OAuth](../../../../docs/sources/oauth/) or [SAML](../../../../docs/sources/saml/). Sources like [LDAP](../../../../docs/sources/ldap/) are _not_ compatible.
 
 #### Resume timeout
 

website/docs/index.mdx

@@ -3,11 +3,11 @@ title: Welcome to authentik
 slug: /
 ---
 
-## About authentik technical documentation
+## About authentik documentation
 
 Our tech docs cover the typical topics, from installation to configuration, adding providers, defining policies and creating login flows, event monitoring, security, and attributes. [Enterprise](./enterprise/index.md) version documentation is included here, within our standard tech docs.
 
--   For information about integrating a specific application or software into authentik, refer to our [Integrations](../integrations) section, accessible from the top menu bar.
+-   For information about integrating a specific application or software into authentik, refer to our Integrations section, accessible from the top menu bar.
 
 -   For developer-focused documentation, such as using our APIs and blueprints, setting up your development environment, translations, or how to contribute, refer to the [Developer](../developer-docs) area, accessible from the top menu bar.
 

website/docs/releases/2022/v2022.5.md

@@ -7,7 +7,7 @@ slug: "/releases/2022.5"
 
 -   Twitter Source has been migrated to OAuth2
 
-    This requires some reconfiguration on both Twitter's and authentik's side. Check out the new Twitter integration docs [here](../../integrations/sources/twitter/)
+    This requires some reconfiguration on both Twitter's and authentik's side. Check out the new Twitter integration docs [here](../../docs/sources/twitter/)
 
 -   OAuth Provider: Redirect URIs are now checked using regular expressions
 

website/docs/releases/2024/v2024.4.md

@@ -37,7 +37,7 @@ slug: /releases/2024.4
 
     Provision users and groups in authentik using an SCIM API.
 
-    For details refer to [SCIM Source](../../../integrations/sources/scim/)
+    For details refer to [SCIM Source](../../../docs/sources/scim/)
 
 -   **Configurable WebAuthn device restrictions**
 
@@ -57,7 +57,7 @@ slug: /releases/2024.4
 
     When authentik is configured to federate with an LDAP source, upon authentication, authentik hashed the password and stored it in its own database. This allows authentication to function when LDAP is unreachable. Admins can now configure this behavior for when this is not desirable.
 
-    For details refer to [LDAP Source](../../../integrations/sources/ldap/)
+    For details refer to [LDAP Source](../../../docs/sources/ldap/)
 
 -   **Configurable app password token expiring**
 

website/docs/sources/general.md

@@ -0,0 +1,16 @@
+---
+title: Overview of sources
+slug: general
+---
+
+Sources allow you to connect authentik to an external user directory. Sources can also be used with social login providers such as Facebook, Twitter, or GitHub.
+
+### Add Sources to Default Login Page
+
+To have sources show on the default login screen you will need to add them. The process below assumes that you have not created or renamed the default stages and flows.
+
+1. In the Admin interface, navigate to the **Flows** section.
+2. Click on **default-authentication-flow**.
+3. Click the **Stage Bindings** tab.
+4. Chose **Edit Stage** for the _default-authentication-identification_ stage.
+5. Under **Sources** you should see the additional sources that you have configured. Click all applicable sources to have them displayed on the Login page.

website/docs/sources/ldap/index.md

@@ -2,9 +2,7 @@
 title: LDAP Source
 ---
 
-Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc.
+Sources allow you to connect authentik to an existing user directory. This source allows you to import users and groups from an LDAP Server.
-
-This source allows you to import users and groups from an LDAP Server.
 
 :::info
 For Active Directory, follow the [Active Directory Integration](../active-directory/)
@@ -12,31 +10,66 @@ For Active Directory, follow the [Active Directory Integration](../active-direct
 For FreeIPA, follow the [FreeIPA Integration](../freeipa/)
 :::
 
--   **Server URI**: URI to your LDAP server/Domain Controller.
+## Configuration options for LDAP sources
 
-    You can specify multiple servers by separating URIs with a comma, like `ldap://ldap1.company,ldap://ldap2.company`.
+To create or edit a source in authentik, open the Admin interface and navigate to **Directory -> Ferderation and Social login**. There you can create a new LDAP source, or edit an existing one, using the following settings.
 
-    When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
+-   **Enabled**: Toggle this option on to allow authentik to use the defined LDAP source.
+
+-   **Update internal password on login**: When the user logs in to authentik using the LDAP password backend, the password is stored as a hashed value in authentik. Toggle off (default setting) if you do not want to store the hashed passwords in authentik.
+
+-   **Synch User**: Enable or disable user synchronization between authentik and the LDAP source.
+
+-   **User password writeback**: Enable this option if you want to write password changes that are made in authentik back to LDAP.
+
+-   **Synch groups**: Enable/disable group synchronization. Groups are synced in the background every 5 minutes.
+
+-   **Sync parent group**: Optionally set this group as the parent group for all synced groups. An example use case of this would be to import Active Directory groups under a root `imported-from-ad` group.
+
+#### Connection settings
+
+-   **Server URI**: URI to your LDAP server/Domain Controller. You can specify multiple servers by separating URIs with a comma, like `ldap://ldap1.company,ldap://ldap2.company`. When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
+
+    -   **Enable StartTLS**: Enables StartTLS functionality. To use LDAPS instead, use port `636`.
+    -   **Use Server URI for SNI verification**: this setting is required for servers using TLS 1.3+
+
+-   **TLS Verification Certificate**: Specify a keypair to validate the remote certificate.
+
+-   **TLS Client authentication**: Client certificate keypair to authenticate against the LDAP Server's Certificate.
 
 -   **Bind CN**: CN of the bind user. This can also be a UPN in the format of `user@domain.tld`.
+
 -   **Bind password**: Password used during the bind process.
--   **Enable StartTLS**: Enables StartTLS functionality. To use LDAPS instead, use port `636`.
+
--   **Base DN**: Base DN used for all LDAP queries.
+-   **Base DN**: Base DN (distinguished name) used for all LDAP queries.
+
+#### LDAP Attribute mapping
+
+-   **User Property mappings** and **Group Property Mappings**: Define which LDAP properties map to which authentik properties. The default set of property mappings is generated for Active Directory. See also [LDAP Property Mappings](../../../docs/property-mappings/#ldap-property-mapping).
+
+#### Additional Settings
+
+-   **Group**: Parent group for all the groups imported from LDAP.
+
+-   **User path**: Path template for all new users created.
+
 -   **Addition User DN**: Prepended to the base DN for user queries.
+
 -   **Addition Group DN**: Prepended to the base DN for group queries.
+
 -   **User object filter**: Consider objects matching this filter to be users.
+
 -   **Group object filter**: Consider objects matching this filter to be groups.
--   **User group membership field**: This field contains the user's group memberships.
+
+-   **Group membership field**: This field contains the user's group memberships.
+
 -   **Object uniqueness field**: This field contains a unique identifier.
--   **Sync groups**: Enable/disable group synchronization. Groups are synced in the background every 5 minutes.
--   **Sync parent group**: Optionally set this group as the parent group for all synced groups. An example use case of this would be to import Active Directory groups under a root `imported-from-ad` group.
--   **Property mappings** and **Group Property Mappings**: Define which LDAP properties map to which authentik properties. The default set of property mappings is generated for Active Directory. See also [LDAP Property Mappings](../../../docs/property-mappings/#ldap-property-mapping)
 
 ## Property mappings
 
 LDAP property mappings can be used to convert the raw LDAP response into an authentik user/group.
 
-By default, authentik ships with some pre-configured mappings for the most common LDAP setups.
+By default, authentik ships with [pre-configured mappings](../../property-mappings/index.md#ldap-property-mapping) for the most common LDAP setups. These mappings can be found on the LDAP Source Configuration page in the Admin interface.
 
 You can assign the value of a mapping to any user attribute, or save it as a custom attribute by prefixing the object field with `attribute.` Keep in mind though, data types from the LDAP server will be carried over. This means that with some implementations, where fields are stored as array in LDAP, they will be saved as array in authentik. To prevent this, use the built-in `list_flatten` function.
 
@@ -56,4 +89,4 @@ Be aware of the following security considerations when turning on this functiona
 
 ## Troubleshooting
 
-To troubleshoot LDAP sources and their synchronization, see [LDAP Troubleshooting](../../../docs/troubleshooting/ldap_source)
+To troubleshoot LDAP sources and their synchronization, see [LDAP Troubleshooting](../../../docs/troubleshooting/ldap_source).

website/docs/sources/oauth/index.md

@@ -2,10 +2,6 @@
 title: OAuth Source
 ---
 
-:::note
-All Integration-specific Sources are documented in the Integrations Section
-:::
-
 This source allows users to enroll themselves with an external OAuth-based Identity Provider. The generic provider expects the endpoint to return OpenID-Connect compatible information. Vendor-specific implementations have their own OAuth Source.
 
 -   Policies: Allow/Forbid users from linking their accounts with this provider.

website/integrations/index.mdx

@@ -0,0 +1,20 @@
+---
+title: Integrations overview
+slug: /
+---
+
+There are two main types of integrations with authentik: **Applications** and **Sources**.
+
+## Applications
+
+authentik integrates with many applications. For a full list, and to learn more about adding documentation for a new application, refer to the [Applications](../integrations/services/index.mdx) documentation.
+
+![](./apps-logo.png)
+
+## Sources
+
+In addition to applications, authentik also integrates with external sources, including federated directories like Active Directory and through protocols such as LDAP, OAuth, SAML, and SCIM sources. Sources are a way for authentik to use external credentials for authentication and verification. Sources in authentik can also be used for social logins, using external providers such as Facebook, Twitter, etc.
+
+To learn more, refer to the [Sources](../docs/sources/general) documentation.
+
+![](./sources-logo.png)

website/integrations/services/index.mdx

@@ -1,11 +1,10 @@
 ---
 title: Applications
-slug: /
 ---
 
 import DocCardList from "@theme/DocCardList";
 
-Below is a list of all integrations, or applications that are known to work with authentik. All integrations will have one of these badges:
+Below is a list of all applications that are known to work with authentik. All app integrations will have one of these badges:
 
 -   <span class="badge badge--secondary">Support level: Community</span> The integration
     is community maintained.
@@ -16,14 +15,16 @@ Below is a list of all integrations, or applications that are known to work with
 -   <span class="badge badge--primary">Support level: authentik</span> The integration
     is regularly tested by the authentik team.
 
-### Add a new integration
+### Add a new application
 
-To add documentation for a new integration (with support level Community or Vendor), please use the integration template [`service.md`](https://github.com/goauthentik/authentik/blob/main/website/integrations/_template/service.md) file from our GitHub repo. You can download the template file using the following command:
+To add documentation for a new application (with support level Community or Vendor), please use the integration template [`service.md`](https://github.com/goauthentik/authentik/blob/main/website/integrations/_template/service.md) file from our GitHub repo. You can download the template file using the following command:
 
 ```shell
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/integrations/_template/service.md
 ```
 
+Don't forget to edit the `sidebarsIntegrations.js` file to add your new integration to the lefthand navigation bar.
+
 ## Integration categories
 
 <DocCardList />

website/integrations/sources/general.md

@@ -1,16 +0,0 @@
----
-title: General
-slug: general
----
-
-Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc.
-
-### Add Sources to Default Login Page
-
-To have sources show on the default login screen you will need to add them. This is assuming you have not created or renamed the default stages and flows.
-
-1. Access the **Flows** section
-2. Click on **default-authentication-flow**
-3. Click the **Stage Bindings** tab
-4. Chose **Edit Stage** for the _default-authentication-identification_ stage
-5. Under **Sources** you should see the additional sources you have configured. Click all applicable sources to have them displayed on the Login Page

website/netlify.toml

@@ -44,3 +44,9 @@
   from = "/docs/core/applications"
   to = "/docs/applications"
   status = 302
+
+# Moved Sources from Integrations to Docs
+[[redirects]]
+   from = "/integrations/sources/*"
+   to = "/docs/sources/:splat"
+   status = 302

website/sidebars.js

@@ -32,7 +32,7 @@ const docsSidebar = {
         },
         {
             type: "category",
-            label: "Core Concepts",
+            label: "Core Concepts & Tasks",
             collapsed: true,
             items: [
                 "core/terminology",
@@ -135,6 +135,50 @@ const docsSidebar = {
                 },
             ],
         },
+        {
+            type: "category",
+            label: "Sources",
+            collapsed: true,
+            link: {
+                type: "doc",
+                id: "sources/general",
+            },
+            items: [
+                {
+                    type: "category",
+                    label: "Directory synchronization",
+                    items: [
+                        "sources/active-directory/index",
+                        "sources/freeipa/index",
+                    ],
+                },
+                {
+                    type: "category",
+                    label: "Protocols",
+                    items: [
+                        "sources/ldap/index",
+                        "sources/oauth/index",
+                        "sources/saml/index",
+                        "sources/scim/index",
+                    ],
+                },
+                {
+                    type: "category",
+                    label: "Social Logins",
+                    items: [
+                        "sources/apple/index",
+                        "sources/azure-ad/index",
+                        "sources/discord/index",
+                        "sources/github/index",
+                        "sources/google/index",
+                        "sources/mailcow/index",
+                        "sources/twitch/index",
+                        "sources/plex/index",
+                        "sources/twitter/index",
+                    ],
+                },
+            ],
+        },
         {
             type: "category",
             label: "Outposts",

website/sidebarsIntegrations.js

@@ -8,9 +8,14 @@ module.exports = {
             type: "html",
             value: generateVersionDropdown(docsSidebar),
         },
+        {
+            type: "doc",
+            id: "index",
+        },
         {
             type: "category",
             label: "Applications",
+            collapsed: false,
             link: {
                 type: "doc",
                 id: "services/index",
@@ -156,52 +161,5 @@ module.exports = {
                 },
             ],
         },
-        {
-            type: "category",
-            label: "Federation & Social login",
-            link: {
-                type: "generated-index",
-                title: "Sources",
-                slug: "sources",
-                description:
-                    "Sources of users which can be federated with authentik",
-            },
-            items: [
-                {
-                    type: "category",
-                    label: "Directory synchronization",
-                    items: [
-                        "sources/active-directory/index",
-                        "sources/freeipa/index",
-                    ],
-                },
-                "sources/general",
-                {
-                    type: "category",
-                    label: "Protocols",
-                    items: [
-                        "sources/ldap/index",
-                        "sources/oauth/index",
-                        "sources/saml/index",
-                        "sources/scim/index",
-                    ],
-                },
-                {
-                    type: "category",
-                    label: "Social Logins",
-                    items: [
-                        "sources/apple/index",
-                        "sources/azure-ad/index",
-                        "sources/discord/index",
-                        "sources/github/index",
-                        "sources/google/index",
-                        "sources/mailcow/index",
-                        "sources/twitch/index",
-                        "sources/plex/index",
-                        "sources/twitter/index",
-                    ],
-                },
-            ],
-        },
     ],
 };