website/docs: add General Setup instructions for LDAP Provider (#3680)

* Added General Setup instructions for LDAP Provider

* Added General Setup instructions for LDAP Provider and updated relative links

* updated LDAP Outpost note verbiage

* Corrected the case for LDAP and renamed to Generic Setup

* removed ldapsearch example from index page

* updated verbiage around multifactor authentication

* removed note about local LDAP provider

* updated sidebar to reflect generic_setup

* updated logging info

* corrected typo

* updated stage creation instructions and screenshot

* corrected another typo

* corrected another typo

* reword some things

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>
Co-authored-by: Jens Langhammer <jens.langhammer@beryju.org>

website/docs/providers/ldap/generic_setup.md

@@ -0,0 +1,93 @@
+---
+title: Generic Setup
+---
+
+### Create User/Group
+
+1. Create a new user account to test LDAP bind under _Directory_ -> _Users_ -> _Create_, in this example called `ldapservice`.
+
+    Note the DN of this user will be `cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io`
+
+2. Create a new group for LDAP searches. In this example `ldapsearch`. Add the `ldapservice` user to this new group.
+
+:::info
+Note: The `default-authentication-flow` validates MFA by default, and currently only Duo-based MFA devices are supported by LDAP. If you plan to use only dedicated service accounts to bind to LDAP, then you can use the default flow and skip the extra steps below and continue at [Create LDAP Provider](#create-ldap-provider)
+:::
+
+### LDAP Flow
+
+#### Create Custom Stages
+
+1. Create a new identification stage. _Flows & Stage_ -> _Stages_ -> _Create_
+   ![](./general_setup1.png)
+2. Name it something meaningful like `ldap-identification-stage`. Select User fields Username and Email (and UPN if it is relevant to your setup).
+   ![](./general_setup2.png)
+3. Create a new password stage. _Flows & Stage_ -> _Stages_ -> _Create_
+   ![](./general_setup3.png)
+4. Name it something meaningful like `ldap-authentication-password`. Leave the defaults for Backends.
+   ![](./general_setup4.png)
+5. Create a new user login stage. _Flows & Stage_ -> _Stages_ -> _Create_
+   ![](./general_setup5.png)
+6. Name it something meaningful like `ldap-authentication-login`.
+   ![](./general_setup6.png)
+
+#### Create Custom Flow
+
+1. Create a new authentication flow under _Flows & Stage_ -> _Flows_ -> _Create_, and name it something meaningful like `ldap-authentication-flow`
+   ![](./general_setup7.png)
+2. Click the newly created flow and choose _Stage Bindings_.
+   ![](./general_setup8.png)
+3. Click `Bind Stage` choose `ldap-identification-stage` and set the order to `10`.
+   ![](./general_setup9.png)
+4. Click `Bind Stage` choose `ldap-authentication-login` and set the order to `30`.
+   ![](./general_setup11.png)
+5. Edit the `ldap-identification-stage`.
+   ![](./general_setup12.png)
+6. Change the Password stage to `ldap-authentication-password`.
+   ![](./general_setup13.png)
+
+### Create LDAP Provider
+
+1. Create the LDAP Provider under _Applications_ -> _Providers_ -> _Create_.
+   ![](./general_setup14.png)
+2. Name is something meaningful like `LDAP`, bind the custom flow created previously (or the default flow, depending on setup) and specify the search group created earlier.
+   ![](./general_setup15.png)
+
+### Create LDAP Application
+
+1. Create the LDAP Application under _Applications_ -> _Applications_ -> _Create_ and name it something meaningful like `LDAP`. Choose the provider created in the previous step.
+   ![](./general_setup16.png)
+
+### Create LDAP Outpost
+
+1. Create (or update) the LDAP Outpost under _Applications_ -> _Outposts_ -> _Create_. Set the Type to `LDAP` and choose the `LDAP` application created in the previous step.
+   ![](./general_setup17.png)
+
+### ldapsearch Test
+
+Test connectivity by using ldapsearch.
+
+:::info
+ldapsearch can be installed on Linux system with these commands
+
+```
+sudo apt-get install ldap-utils -y # Debian-based systems
+sudo yum install openldap-clients -y # CentOS-based systems
+```
+
+:::
+
+```
+ldapsearch \
+  -x \
+  -h <LDAP Outpost IP address> \
+  -p 389 \ # Production should use SSL 636
+  -D 'cn=ldapservice,ou=users,DC=ldap,DC=goauthentik,DC=io' \
+  -w '<ldapuserpassword>' \
+  -b 'DC=ldap,DC=goauthentik,DC=io' \
+  '(objectClass=user)'
+```
+
+:::info
+This query will log the first successful attempt in an event in the _Events_ -> _Logs_ area, further successful logins from the same user are not logged as they are cached in the outpost.
+:::

website/docs/providers/ldap/index.md

@@ -5,7 +5,7 @@ title: LDAP Provider
 You can configure an LDAP Provider for applications that don't support any newer protocols or require LDAP.
 
 :::info
-Note: This provider requires the deployment of the [LDAP Outpost](../outposts/)
+Note: This provider requires the deployment of the [LDAP Outpost](../../outposts/)
 :::
 
 All users and groups in authentik's database are searchable. Currently, there is limited support for filters (you can only search for objectClass), but this will be expanded in further releases.
@@ -16,19 +16,6 @@ You can configure under which base DN the information should be available. For t
 
 Users are available under `ou=users,<base DN>` and groups under `ou=groups,<base DN>`. To aid compatibility, each user belongs to its own "virtual" group, as is standard on most Unix-like systems. This group does not exist in the authentik database, and is generated on the fly. These virtual groups are under the `ou=virtual-groups,<base DN>` DN.
 
-You can bind using the DN `cn=<username>,ou=users,<base DN>`, or using the following ldapsearch command for example:
-
-```
-ldapsearch \
-  -x \ # Only simple binds are currently supported
-  -h *ip* \
-  -p 389 \
-  -D 'cn=*user*,ou=users,DC=ldap,DC=goauthentik,DC=io' \ # Bind user and password
-  -w '*password*' \
-  -b 'ou=users,DC=ldap,DC=goauthentik,DC=io' \ # The search base
-  '(objectClass=user)'
-```
-
 The following fields are currently sent for users:
 
 -   `cn`: User's username
@@ -72,7 +59,7 @@ This enables you to bind on port 636 using LDAPS, StartTLS is not supported.
 
 ## Integrations
 
-See the integration guide for [sssd](../../integrations/services/sssd/) for
+See the integration guide for [sssd](../../../integrations/services/sssd/) for
 an example guide.
 
 ## Bind Modes
@@ -81,9 +68,9 @@ All bind modes rely on flows.
 
 The following stages are supported:
 
--   [Identification](../flow/stages/identification/)
--   [Password](../flow/stages/password/)
--   [Authenticator validation](../flow/stages/authenticator_validate/)
+-   [Identification](../../flow/stages/identification/)
+-   [Password](../../flow/stages/password/)
+-   [Authenticator validation](../../flow/stages/authenticator_validate/)
 
     Note: Authenticator validation currently only supports DUO devices
 

website/docs/releases/v2022.5.md

@@ -19,7 +19,7 @@ slug: "2022.5"
 
     Instead of always executing the configured flow when a new Bind request is received, the provider can now be configured to cache the session from the initial flow execution, and directly validate credentials in the outpost. This drastically improves the bind performance.
 
-    See [LDAP provider](../providers/ldap.md#cached-bind)
+    See [LDAP provider](../providers/ldap/index.md#cached-bind)
 
 -   OAuth2: Add support for `form_post` response mode
 -   Don't prompt users for MFA when they've authenticated themselves within a time period

website/sidebars.js

@@ -65,7 +65,15 @@ module.exports = {
                         "providers/proxy/forward_auth",
                     ],
                 },
-                "providers/ldap",
+                {
+                    type: "category",
+                    label: "LDAP Provider",
+                    link: {
+                        type: "doc",
+                        id: "providers/ldap/index",
+                    },
+                    items: ["providers/ldap/generic_setup"],
+                },
             ],
         },
         {