website/docs: add new content from old PR #9524 (#10158)

Co-authored-by: 4d62 <ext@4d62.me>
Co-authored-by: "Brian, Chen" <wildfox@126.com>
Co-authored-by: Tana M Berry <tana@goauthentik.com>

website/docs/property-mappings/index.md

@@ -23,6 +23,8 @@ LDAP Property Mappings are used when you define a LDAP Source. These mappings de
 
 These are configured with most common LDAP setups.
 
+You can also configure [custom LDAP property mappings](../sources/ldap/index.md#custom-ldap-property-mapping).
+
 ## Scope Mapping
 
 Scope Mappings are used by the OAuth2 Provider to map information from authentik to OAuth2/OpenID Claims. Values returned by a Scope Mapping are added as custom claims to Access and ID tokens.

website/docs/sources/ldap/index.md

@@ -73,6 +73,22 @@ By default, authentik ships with [pre-configured mappings](../../property-mappin
 
 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.
 
+### Custom LDAP Property Mapping
+
+If the default source mapping is not enough, you can set your own custom LDAP property mapping.
+
+For example, the setting `ldap-displayName-mapping:name` means that the LDAP source field `displayName` will be mapped to the `name` field in authentik.
+
+Here are the steps:
+
+1. In authentik, open the Admin interface, and then navigate to **Customization -> Property Mappings**.
+2. Click **Create**, select **LDAP Property Mapping**, and then click **Next**.
+3. Type a unique and meaningful **Name**, such as `ldap-displayName-mapping:name`.
+4. In the**Object field** field, type the name of an existing authentik field, such as `name`. If you want to add more extended attributes, you can type `attributes.mobile` for example.
+5. In the **Expression** field enter Python expressions to retrieve the value from LDAP source. For example `return list_flatten(ldap.get("displayName"))`.
+
+`list_flatten(["input string array"])` will convert a string array to a single string. If you are not sure whether the LDAP field is an array or not, you can map the field to any `attributes.xxx` and then check the sync result in authentik UI.
+
 ## Password login
 
 By default, authentik doesn't update the password it stores for a user when they log in using their LDAP credentials. That means that if the LDAP server is not reachable by authentik, users will not be able to log in. This behavior can be turned on with the **Update internal password on login** setting on the LDAP source.
@@ -83,9 +99,9 @@ Sources created prior to the 2024.2 release have this setting turned on by defau
 
 Be aware of the following security considerations when turning on this functionality:
 
--   Updating the LDAP password does not invalid the password stored in authentik, however for LDAP Servers like FreeIPA and Active Directory, authentik will lock its internal password during the next LDAP sync. For other LDAP servers, the old passwords will still be valid indefinitely.
+-   Updating the LDAP password does not invalidate the password stored in authentik; however for LDAP Servers like FreeIPA and Active Directory, authentik will lock its internal password during the next LDAP sync. For other LDAP servers, the old passwords will still be valid indefinitely.
 -   Logging in via LDAP credentials overwrites the password stored in authentik if users have different passwords in LDAP and authentik.
--   Custom security measures used to secure the password in LDAP may differ from the ones used in authentik. Depending on threat model and security requirements this could lead to unknowingly being non-compliant.
+-   Custom security measures that are used to secure the password in LDAP may differ from the ones used in authentik. Depending on threat model and security requirements this could lead to unknowingly being non-compliant.
 
 ## Troubleshooting