> ## 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 - Security rules

> The security node bundles all security-relevant shop settings: bot protection, hash and encryption methods and the management of keys and secrets.

export const KonfigDeeplink = ({node}) => <>
    You can open this setting directly in the Admin Interface via the following link:{" "}
    <code>{`https://<shop-domain>/admin/config/${node}`}</code>{" "}
    (<a href="/en/admin-interface/konfigurations-deeplinks">Deeplink overview</a>)
  </>;

The `security` node bundles all security-relevant settings of the shop: bot protection, hash and encryption methods, and the management of keys / secrets.

***

## `security*` - Basic structure

The basic structure of the `security` node is shown below:

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

#### Parameter description

| **Parameter**       | **Description**                                   |
| ------------------- | ------------------------------------------------- |
| `friendlyCaptchaV1` | Integrates FriendlyCaptcha into the shop.         |
| `recaptchav3`       | Integrates Google reCAPTCHA into the shop.        |
| `method`            | Defines how sensitive data is processed.          |
| `actionGuard`       | Protects individual actions with a captcha check. |

***

## `security.friendlyCaptchaV1` - Bot protection with FriendlyCaptcha

The `security.friendlyCaptchaV1` node integrates Friendly Captcha into the storefront in order to prevent spam and detect bots.

<KonfigDeeplink node="security.friendlyCaptchaV1" />

#### Example configuration

```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 overview

| **Parameter** | **Type** | **Description**                                                                                                                                                            |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string   | Freely selectable internal configuration name.                                                                                                                             |
| `apiKey`      | string   | Secret server key for verification at FriendlyCaptcha.                                                                                                                     |
| `siteKey`     | string   | Public key for integrating FriendlyCaptcha.                                                                                                                                |
| `verifyUrl`   | string   | Endpoint for server-side verification with FriendlyCaptcha.      Default:   `https://eu-api.friendlycaptcha.eu/api/v1/siteverify`                                          |
| `apiUrl`      | string   | Endpoint for loading the "puzzle" that the browser solves automatically to confirm that it is not a bot.      Default:   `https://eu-api.friendlycaptcha.eu/api/v1/puzzle` |

***

## `security.method` - Encrypt sensitive data

The `security.method` node defines how sensitive data is processed (hashing, encrypted storage).

<KonfigDeeplink node="security.method" />

#### Example configuration

```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"
    }
  ]
}
```

#### Parameter description

| **Parameter** | **Type**      | **Description**                                                                                          |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------- |
| `hash`        | list (object) | List of configured hash methods for one-way hashing (e.g. passwords).                                    |
| `id`          | string        | Technical name of the hash method, freely selectable (e.g. `password_v1`).<br />Must not contain `#`.    |
| `salt`        | string        | An additional, random value that is appended to the data before hashing.                                 |
| `pepper`      | string        | A secret additional value used together with the `salt` before hashing.                                  |
| `encrypt`     | list (object) | List of configured encryption methods for reversible data (e.g. tokens, sensitive fields).               |
| `id`          | string        | Technical name of the encryption method, freely selectable (e.g. `token_v1`).<br />Must not contain `#`. |
| `secret`      | string        | Secret key for data encryption.                                                                          |

***

## `security.recaptchav3` - Bot protection with Google reCAPTCHA

The `security.recaptchav3` node integrates Google reCAPTCHA into the storefront in order to prevent spam and detect bots.

<KonfigDeeplink node="security.recaptchav3" />

#### Example configuration

```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 overview

| **Parameter**  | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                               |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string   | Freely selectable identifier of the configuration (e.g. context-specific like "`recaptcha_checkout`").                                                                                                                                                                                                                                                                                        |
| `minimumScore` | float    | Threshold for the score (`0.0` — `1.0`). Requests with a score below this value are treated as suspicious.   Usually a value between `0.3` (lenient evaluation) and `0.7` (stricter evaluation) is chosen.   More information: [https://developers.google.com/recaptcha/docs/v3?hl=en#interpreting\_the\_score](https://developers.google.com/recaptcha/docs/v3?hl=en#interpreting_the_score) |
| `secretKey`    | string   | Server-side secret key of Google reCAPTCHA.                                                                                                                                                                                                                                                                                                                                                   |
| `verifyUrl`    | string   | Endpoint for token verification.   Usually `https://www.google.com/recaptcha/api/siteverify` is used here.                                                                                                                                                                                                                                                                                    |

***

## `security.actionGuard` - Captcha protection for actions

The `actionGuard` node allows individual [actions](/en/frontend/referenz/aktionen) to be protected with a captcha. If an action is configured this way, the system checks on every execution whether the frontend has supplied a valid captcha token. If the action is executed as opt-in (e.g. via a confirmation link in an email), this check is skipped.

<KonfigDeeplink node="security.actionGuard" />

#### Example configuration

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

#### Parameter description

| **Parameter** | **Type**                 | **Description**                                                                                                                                                                                                              |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actionName`  | string                   | Name of the action to be protected by the captcha check (e.g. `Login`).                                                                                                                                                      |
| `captcha`     | singleService (optional) | Reference to the captcha service to be used. `captchaCheck` is a hard-coded service that references one of the configured captcha services — that is, either `captchaCheck.friendlyCaptchaV1` or `captchaCheck.recaptchav3`. |