website/docs: add source property mappings, rework provider property …

…mappings (goauthentik#10652)

web/src/admin/property-mappings/BasePropertyMappingForm.ts

@@ -16,7 +16,7 @@ export abstract class BasePropertyMappingForm<T extends PropertyMapping> extends
     string
 > {
     docLink(): string {
-        return "/docs/property-mappings/expression?utm_source=authentik";
+        return "/docs/providers/property-mappings/expression?utm_source=authentik";
     }
 
     getSuccessMessage(): string {

web/src/admin/property-mappings/PropertyMappingLDAPSourceForm.ts

@@ -9,6 +9,10 @@ import { LDAPSourcePropertyMapping, PropertymappingsApi } from "@goauthentik/api
 
 @customElement("ak-property-mapping-ldap-source-form")
 export class PropertyMappingLDAPSourceForm extends BasePropertyMappingForm<LDAPSourcePropertyMapping> {
+    docLink(): string {
+        return "/docs/sources/property-mappings/expression?utm_source=authentik";
+    }
+
     loadInstance(pk: string): Promise<LDAPSourcePropertyMapping> {
         return new PropertymappingsApi(DEFAULT_CONFIG).propertymappingsSourceLdapRetrieve({
             pmUuid: pk,

web/src/admin/property-mappings/PropertyMappingOAuthSourceForm.ts

@@ -9,6 +9,10 @@ import { OAuthSourcePropertyMapping, PropertymappingsApi } from "@goauthentik/ap
 
 @customElement("ak-property-mapping-oauth-source-form")
 export class PropertyMappingOAuthSourceForm extends BasePropertyMappingForm<OAuthSourcePropertyMapping> {
+    docLink(): string {
+        return "/docs/sources/property-mappings/expression?utm_source=authentik";
+    }
+
     loadInstance(pk: string): Promise<OAuthSourcePropertyMapping> {
         return new PropertymappingsApi(DEFAULT_CONFIG).propertymappingsSourceOauthRetrieve({
             pmUuid: pk,

web/src/admin/property-mappings/PropertyMappingRACForm.ts

@@ -162,7 +162,7 @@ export class PropertyMappingRACForm extends ModelForm<RACPropertyMapping, string
                                 target="_blank"
                                 rel="noopener noreferrer"
                                 href="${docLink(
-                                    "/docs/property-mappings/expression?utm_source=authentik",
+                                    "/docs/providers/property-mappings/expression?utm_source=authentik",
                                 )}"
                             >
                                 ${msg("See documentation for a list of all variables.")}

web/src/admin/property-mappings/PropertyMappingSAMLSourceForm.ts

@@ -9,6 +9,10 @@ import { PropertymappingsApi, SAMLSourcePropertyMapping } from "@goauthentik/api
 
 @customElement("ak-property-mapping-saml-source-form")
 export class PropertyMappingSAMLSourceForm extends BasePropertyMappingForm<SAMLSourcePropertyMapping> {
+    docLink(): string {
+        return "/docs/sources/property-mappings/expression?utm_source=authentik";
+    }
+
     loadInstance(pk: string): Promise<SAMLSourcePropertyMapping> {
         return new PropertymappingsApi(DEFAULT_CONFIG).propertymappingsSourceSamlRetrieve({
             pmUuid: pk,

web/src/admin/property-mappings/PropertyMappingSCIMSourceForm.ts

@@ -9,6 +9,10 @@ import { PropertymappingsApi, SCIMSourcePropertyMapping } from "@goauthentik/api
 
 @customElement("ak-property-mapping-scim-source-form")
 export class PropertyMappingSCIMSourceForm extends BasePropertyMappingForm<SCIMSourcePropertyMapping> {
+    docLink(): string {
+        return "/docs/sources/property-mappings/expression?utm_source=authentik";
+    }
+
     loadInstance(pk: string): Promise<SCIMSourcePropertyMapping> {
         return new PropertymappingsApi(DEFAULT_CONFIG).propertymappingsSourceScimRetrieve({
             pmUuid: pk,

website/docs/core/terminology.md

@@ -61,9 +61,9 @@ See [Flows](../flow/index.md)
 
 ### Property Mappings
 
-Property Mappings allow you to make information available for external applications. For example, if you want to login to AWS with authentik, you'd use Property Mappings to set the user's roles in AWS based on their group memberships in authentik.
+Property Mappings allow you to make information available for external applications, and to modify how information from sources are stored in authentik. For example, if you want to log in to AWS with authentik, you'd use property mappings to set the user's roles in AWS based on their group memberships in authentik.
 
-See [Property Mappings](../property-mappings/index.md)
+See [Providers Property Mappings](../providers/property-mappings/index.md) and [Source Property Mappings](../sources/property-mappings/index.md).
 
 ### Outpost
 

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

@@ -63,7 +63,7 @@ A flag which decides whether or not this field is required.
 A field placeholder, shown within the input field.
 
 By default, the placeholder is interpreted as-is. If you enable _Interpret placeholder as expression_, the placeholder
-will be evaluated as a python expression. This happens in the same environment as [_Property mappings_](../../../property-mappings/expression).
+will be evaluated as a Python expression. This happens in the same environment as [_Policies_](../../../policies/expression).
 
 In the case of `Radio Button Group` and `Dropdown` prompts, this field defines all possible values (choices). When interpreted as-is, only one value will be allowed (the placeholder string). When interpreted as expression, a list of values can be returned to define multiple choices. For example, `return ["first option", 42, "another option"]` defines 3 possible values.
 
@@ -78,7 +78,7 @@ The prompt's initial value. It can also be left empty, in which case the field w
 With the `hidden` prompt, the initial value will also be the actual value, because the field is hidden to the user.
 
 By default, the initial value is interpreted as-is. If you enable _Interpret initial value as expression_, the initial value
-will be evaluated as a python expression. This happens in the same environment as [_Property mappings_](../../../property-mappings/expression).
+will be evaluated as a Python expression. This happens in the same environment as [_Policies_](../../../policies/expression).
 
 In the case of `Radio Button Group` and `Dropdown` prompts, this field defines the default choice. When interpreted as-is, the default choice will be the initial value string. When interpreted as expression, the default choice will be the returned value. For example, `return 42` defines `42` as the default choice.
 

website/docs/providers/oauth2/index.md

@@ -4,7 +4,7 @@ title: OAuth2 Provider
 
 This provider supports both generic OAuth2 as well as OpenID Connect
 
-Scopes can be configured using Scope Mappings, a type of [Property Mappings](../../property-mappings/#scope-mapping).
+Scopes can be configured using scope mappings, a type of [property mapping](../property-mappings/index.md#scope-mappings).
 
 | Endpoint             | URL                                                                  |
 | -------------------- | -------------------------------------------------------------------- |

website/docs/property-mappings/expression.mdx → website/docs/providers/property-mappings/expression.mdx

@@ -2,23 +2,23 @@
 title: Expressions
 ---
 
-The property mapping should return a value that is expected by the Provider/Source. Supported types are documented in the individual Provider/Source. Returning `None` is always accepted and would simply skip the mapping for which `None` was returned.
+The property mapping should return a value that is expected by the provider. Supported types are documented in the individual provider. Returning `None` is always accepted and would simply skip the mapping for which `None` was returned.
 
 ## Available Functions
 
-import Functions from "../expressions/_functions.md";
+import Functions from "../../expressions/_functions.md";
 
 <Functions />
 
 ## Variables
 
-import Objects from "../expressions/_objects.md";
+import Objects from "../../expressions/_objects.md";
 
 <Objects />
 
-import User from "../expressions/_user.md";
+import User from "../../expressions/_user.md";
 
 <User />
 
 -   `request`: The current request. This may be `None` if there is no contextual request. See ([Django documentation](https://docs.djangoproject.com/en/3.0/ref/request-response/#httprequest-objects))
--   Other arbitrary arguments given by the provider, this is documented on the Provider/Source.
+-   Other arbitrary arguments given by the provider, this is documented on the provider.

website/docs/providers/property-mappings/index.md

@@ -0,0 +1,13 @@
+---
+title: Provider property mappings
+---
+
+Property mappings allow you to pass information to external applications. For example, pass the current user's groups as a SAML parameter.
+
+## SAML property mappings
+
+SAML property mappings allow you embed information into the SAML authentication request. This information can then be used by the application to, for example, assign permissions to the object.
+
+## Scope mappings
+
+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/providers/rac/how-to-rac.md

@@ -54,7 +54,7 @@ Next, you need to add a property mapping for each of the remote machines you wan
             - **Enable font smoothing**: optional
             - **Enable full window dragging**: optional
         - Advanced settings:
-            - **Expressions**: optional, using Python you can define custom [expressions](../../property-mappings/expression.mdx).
+            - **Expressions**: optional, using Python you can define custom [expressions](../property-mappings/expression.mdx).
 
 4. Click **Finish** to save your settings and close the modal.
 

website/docs/providers/saml/index.md

@@ -2,7 +2,7 @@
 title: SAML Provider
 ---
 
-This provider allows you to integrate enterprise software using the SAML2 Protocol. It supports signed requests and uses [Property Mappings](../../property-mappings/#saml-property-mapping) to determine which fields are exposed and what values they return. This makes it possible to expose vendor-specific fields.
+This provider allows you to integrate enterprise software using the SAML2 protocol. It supports signed requests and uses [property mappings](../property-mappings/#saml-property-mappings) to determine which fields are exposed and what values they return. This makes it possible to expose vendor-specific fields.
 Default fields are exposed through auto-generated Property Mappings, which are prefixed with "authentik default".
 
 | Endpoint                  | URL                                                          |

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

@@ -32,6 +32,20 @@ To try out the release candidate, replace your Docker image tag with the latest
 
     **If you have any custom property mappings, we recommend migrating them to this new format.**
 
+-   **OAuth and SAML sources now sync groups by default**
+
+    OAuth (specifically OpenID and Okta) sources now sync groups by default when a `groups` claim is available.
+
+    SAML sources now sync groups by default when a `http://schemas.xmlsoap.org/claims/Group` attribute is available in the assertion.
+
+    To disable that behavior, create an OAuth/SAML source property mapping with the following expression:
+
+    ```python
+    return {
+        "groups": [],
+    }
+    ```
+
 ### Manual action may be required
 
 -   **Changes to the external user type**
@@ -50,6 +64,8 @@ To try out the release candidate, replace your Docker image tag with the latest
 
 ## New features
 
+-   **Source property mappings for SCIM, OAuth, SAML and Plex sources**
+
 -   **SAML Source encryption support**
 
     It is now possible to configure a SAML Source to decrypt and validate encrypted assertions. This can be configured by certaing a [Certificate-keypair](../../core/certificates.md) and selecting it in the SAML Source.

website/docs/security/security-hardening.md

@@ -6,7 +6,7 @@ While authentik is secure out of the box, you can take steps to further increase
 
 ### Expressions
 
-[Expressions](../property-mappings/expression.mdx) allow super-users and other highly privileged users to create custom logic within authentik to modify its behaviour. Editing/creating these expressions is, by default, limited to super-users and any related events are fully logged.
+[Expressions](../policies/expression.mdx) allow super-users and other highly privileged users to create custom logic within authentik to modify its behaviour. Editing/creating these expressions is, by default, limited to super-users and any related events are fully logged.
 
 However, for further hardening, it is possible to prevent any user (even super-users) from using expressions to create or edit any objects. To do so, configure your deployment to block API requests to these endpoints:
 

website/docs/sources/index.md

@@ -7,10 +7,11 @@ Sources allow you to connect authentik to an external user directory. Sources ca
 
 ### Find your source
 
-Sources are in three general categories:
+Sources are in the following general categories:
 
+-   **Protocols** ([LDAP](./ldap/index.md), [OAuth](./oauth/index.md), [SAML](./saml/index.md), and [SCIM](./scim/index.md))
+-   [**Property mappings**](./property-mappings/index.md) or how to import data from a source
 -   **Directory synchronization** (Active Directory, FreeIPA)
--   **Protocols** (LDAP, OAuth, SAML, and SCIM)
 -   **Social logins** (Apple, Discord, Twitch, Twitter, and many others)
 
 For instructions to add a specific source, refer to the documentation links in the left navigation pane.

website/docs/sources/ldap/index.md

@@ -45,7 +45,7 @@ To create or edit a source in authentik, open the Admin interface and navigate t
 
 #### 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).
+-   **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 our documentation on [property mappings](#ldap-source-property-mappings).
 
 #### Additional Settings
 
@@ -65,11 +65,11 @@ To create or edit a source in authentik, open the Admin interface and navigate t
 
 -   **Object uniqueness field**: This field contains a unique identifier.
 
-## Property mappings
+## LDAP source property mappings
 
-LDAP property mappings can be used to convert the raw LDAP response into an authentik user/group.
+See the [overview](../property-mappings/index.md) for information on how property mappings work.
 
-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.
+By default, authentik ships with [pre-configured mappings](#built-in-property-mappings) 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. 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. Here is an example mapping for the user's username and a custom attribute for a phone number:
 
@@ -82,19 +82,36 @@ return {
 }
 ```
 
-### Custom LDAP Property Mapping
+### Built-in property mappings
 
-If the default source mapping is not enough, you can set your own custom LDAP property mapping.
+LDAP property mappings are used when you define a LDAP source. These mappings define which LDAP property maps to which authentik property. By default, the following mappings are created:
 
-Here are the steps:
+-   authentik default Active Directory Mapping: givenName
+-   authentik default Active Directory Mapping: sAMAccountName
+-   authentik default Active Directory Mapping: sn
+-   authentik default Active Directory Mapping: userPrincipalName
+-   authentik default LDAP Mapping: mail
+-   authentik default LDAP Mapping: Name
+-   authentik default OpenLDAP Mapping: cn
+-   authentik default OpenLDAP Mapping: uid
 
-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"))`.
+These are configured with most common LDAP setups.
 
-`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.
+### Expression data
+
+The following variables are available to LDAP source property mappings:
+
+-   `ldap`: A Python dictionary containing data from LDAP.
+-   `dn`: The object DN.
+
+### Additional expression semantics
+
+If you need to skip synchronization for a specific object, you can raise the `StopSync` exception:
+
+```python
+if ldap.get("cn") == "doNotSync":
+    raise StopSync
+```
 
 ## Password login
 

website/docs/sources/oauth/index.md

@@ -31,3 +31,29 @@ This URL is fetched upon saving the source, and all the URLs will be replaced by
 To simplify Machine-to-machine authentication, you can create an OAuth Source as "trusted" source of JWTs. Create a source and configure either the Well-known URL or the OIDC JWKS URL, or you can manually enter the JWKS data if you so desire.
 
 Afterwards, this source can be selected in one or multiple OAuth2 providers, and any JWT issued by any of the configured sources' JWKS will be able to authenticate. To learn more about this, see [JWT-authentication](/docs/providers/oauth2/client_credentials#jwt-authentication).
+
+## OAuth source property mappings
+
+See the [overview](../property-mappings/index.md) for information on how property mappings work.
+
+### Expression data
+
+The following variables are available to OAuth source property mappings:
+
+-   `info`: A Python dictionary containing OAuth claims. For example (values might differ depending on the source):
+    ```python
+    {
+        "iss": "https://source.company",
+        "sub": "f153e7da687eec8c8789c72b6cc6bb5197df7b48b263b3151f36908e1bc10691",
+        "aud": "01e4DmQiG1d3kaewD3Mkz7E7kXknk9j43eZMkNaE",
+        "aud": "a7809c1b1c4aaa50adfb68660a6273dd9c8d15e4",
+        "email": "[email protected]",
+        "email_verified": True,
+        "name": "User",
+        "given_name": "User",
+        "preferred_username": "user",
+        "nickname": "user",
+    }
+    ```
+-   `client`: An OAuth client object to make requests to the Source with authentication built-in.
+-   `token`: A Python dictionary containing OAuth tokens.