> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# security - Sicherheitsregeln

> Der security-Knoten bündelt sicherheitsrelevante Shopeinstellungen: Bot-Schutz, Hash- und Verschlüsselungsmethoden sowie Verwaltung von Schlüsseln und Secrets.

export const KonfigDeeplink = ({node}) => <>
    Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden:{" "}
    <code>{`https://<shop-domain>/admin/config/${node}`}</code>{" "}
    (<a href="/konfiguration/konfigurations-deeplinks">Deeplink-Übersicht</a>)
  </>;

Der Knoten `security` bündelt alle sicherheitsrelevanten Einstellungen des Shops. Bot-Schutz, Hash- und Verschlüsselungsmethoden und die Verwaltung von Schlüsseln/Secrets.

***

## `security*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens `security`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "security": {
    "friendlyCaptchaV1": {},
    "recaptchav3": {},
    "method": {},
    "actionGuard": {}
  }
}
```

#### Parameterbeschreibung

| **Parameter**       | **Beschreibung**                                  |
| ------------------- | ------------------------------------------------- |
| `friendlyCaptchaV1` | Bindet FriendlyCaptcha in den Shop ein.           |
| `recaptchav3`       | Bindet Google reCAPTCHA in den Shop ein.          |
| `method`            | Definiert, wie sensible Daten verarbeitet werden. |
| `actionGuard`       | Schützt einzelne Aktionen per Captcha-Prüfung.    |

***

## `security.friendlyCaptchaV1` - Bot-Schutz mit FriendlyCaptcha

Der Knoten `security.friendlyCaptchaV1` bindet Friendly Captcha in die Storefront ein, um Spam zu verhindern und Bots zu erkennen.

<KonfigDeeplink node="security.friendlyCaptchaV1" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "name": "friendlyCaptchaV1",
  "apiKey": "",
  "siteKey": "",
  "verifyUrl": "https://eu-api.friendlycaptcha.eu/api/v1/siteverify",
  "apiUrl": "https://eu-api.friendlycaptcha.eu/api/v1/puzzle"
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                                                                                                                                                                 |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`        | string  | Frei wählbarer, interner Konfigurationsname.                                                                                                                                                     |
| `apiKey`      | string  | Geheimer Server-Schlüssel für die Verifizierung bei FriendlyCaptcha.                                                                                                                             |
| `siteKey`     | string  | Öffentlicher Schlüssel für die Einbindung von FriendlyCaptcha.                                                                                                                                   |
| `verifyUrl`   | string  | Endpunkt zur Server-Identifikation von FriendlyCaptcha.      Default:   `https://eu-api.friendlycaptcha.eu/api/v1/siteverify`                                                                    |
| `apiUrl`      | string  | Endpunkt zum Laden des “Puzzles”, die der Browser automatisch löst, um zu bestätigen, dass es sich nicht um einen Bot handelt.      Default:   `https://eu-api.friendlycaptcha.eu/api/v1/puzzle` |

***

## `security.method` - Sensible Daten verschlüsseln

Der Knoten `security.method` definiert, wie sensible Daten verarbeitet werden (Hashing, verschlüsseltes Speichern).

<KonfigDeeplink node="security.method" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "encrypt": [
    {
      "id": "token_v1",
      "secret": "ABC123"
    }
  ],
  "hash": [
    {
      "id": "password_v1",
      "salt": "shop-wide-salt-a9c3f1",
      "pepper": "env:SECURITY_PEPPER"
    }
  ]
}
```

#### Parameterbeschreibung

| **Parameter** | **Typ**       | **Beschreibung**                                                                                               |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------- |
| `hash`        | list (object) | Liste konfigurierter Hash-Verfahren für Einweg-Hashing (z.B. Passwörter).                                      |
| `id`          | string        | Technischer Name des Hash-Verfahrens, frei wählbar. (z.B. `password_v1`)<br />Darf kein `#` enthalten.         |
| `salt`        | string        | Ein zusätzlicher, zufälliger Wert, der vor dem Hashen an die Daten angehängt wird.                             |
| `pepper`      | string        | Ein geheimer Zusatzwert, der zusätzlich zum `salt` vor dem Hashen verwendet wird.                              |
| `encrypt`     | list (object) | Liste konfigurierter Verschlüsselungsverfahren für reversible Daten (z.B. Tokens, sensible Felder).            |
| `id`          | string        | Technischer Name des Verschlüsselungsverfahrens, frei wählbar. (z.B. `token_v1`)<br />Darf kein `#` enthalten. |
| `secret`      | string        | Geheimer Schlüssel für die Datenverschlüsselung.                                                               |

***

## `security.recaptchav3` - Bot-Schutz mit Google reCAPTCHA

Der Knoten `security.recaptchav3` bindet Google reCAPTCHA in die Storefront ein, um Spam zu verhindern und Bots zu erkennen.

<KonfigDeeplink node="security.recaptchav3" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "minimumScore": 0.5,
  "name": "recaptchav3",
  "secretKey": "",
  "verifyUrl": "https://www.google.com/recaptcha/api/siteverify"
}
```

#### Parameterübersicht

| **Parameter**  | **Typ** | **Beschreibung**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`         | string  | Frei wählbare Kennung der Konfiguration. (z.B. Einsatzortbezogen wie “`recaptcha_checkout`”)                                                                                                                                                                                                                                                                                                                                                                                                           |
| `minimumScore` | float   | Schwellwert für die Bewertung (`0.0` - `1.0`). Requests mit Score unter diesem Wert gelten als verdächtig. Liegt der Score unter dem angegebenen Wert, wird die Anfrage als verdächtig behandelt.   Normalerweise wird ein Wert zwischen `0.3` (großzügigere Bewertung) bis `0.7` (strengere Bewertung) genommen.   Mehr Informationen: [https://developers.google.com/recaptcha/docs/v3?hl=de#interpreting\_the\_score](https://developers.google.com/recaptcha/docs/v3?hl=de#interpreting_the_score) |
| `secretKey`    | string  | Serverseitiger Geheimschlüssel von Google reCAPTCHA.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `verifyUrl`    | string  | Endpunkt zur Token-Prüfung.   In der Regel wird hier `https://www.google.com/recaptcha/api/siteverify` verwendet.                                                                                                                                                                                                                                                                                                                                                                                      |

***

## `security.actionGuard` - Captcha-Schutz für Aktionen

Der Knoten `actionGuard` ermöglicht es, einzelne [Aktionen](/frontend/referenz/aktionen) mit einem Captcha zu schützen. Wird eine Aktion auf diese Weise konfiguriert, prüft das System bei jeder Ausführung, ob das Frontend einen gültigen Captcha-Token mitgeschickt hat. Wird die Aktion jedoch als Opt-In (z.B. über einen Bestätigungslink in einer Mail) ausgeführt, entfällt diese Prüfung.

<KonfigDeeplink node="security.actionGuard" />

#### Beispielkonfiguration

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
actionName: Login
captcha:
  service: captchaCheck.friendlyCaptchaV1
```

#### Parameterbeschreibung

| **Parameter** | **Typ**                  | **Beschreibung**                                                                                                                                                                                                                                 |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `actionName`  | string                   | Name der Action, die durch den Captcha-Check geschützt werden soll. (z.B. `Login`)                                                                                                                                                               |
| `captcha`     | singleService (optional) | Referenz auf den zu verwendeten Captcha-Dienst. `captchaCheck` ist ein fest implementierter Service, der auf einen der konfigurierten Captcha-Dienste verweist - also entweder `captchaCheck.friendlyCaptchaV1` oder `captchaCheck.recaptchav3`. |