security - Security rules - WEBSALE Dokumentation

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:

{
  "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. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/security.friendlyCaptchaV1 (Deeplink overview)

Example configuration

{
  "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	Name of the service in consent management. If cookie consent for this service is missing, the captcha check fails.
`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). You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/security.method (Deeplink overview)

Example configuration

{
  "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`). 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`). 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. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/security.recaptchav3 (Deeplink overview)

Example configuration

{
  "minimumScore": 0.5,
  "name": "recaptchav3",
  "secretKey": "",
  "verifyUrl": "https://www.google.com/recaptcha/api/siteverify"
}

Parameter overview

Parameter	Type	Description
`name`	string	Name of the service in consent management. If cookie consent for this service is missing, the captcha check fails.
`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
`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 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. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/security.actionGuard (Deeplink overview)

Example configuration

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`. Consent and request parameters of the two services are described in Validation and check services.

​security* - Basic structure

​Parameter description

​security.friendlyCaptchaV1 - Bot protection with FriendlyCaptcha

​Example configuration

​Parameter overview

​security.method - Encrypt sensitive data

​Example configuration

​Parameter description

​security.recaptchav3 - Bot protection with Google reCAPTCHA

​Example configuration

​Parameter overview

​security.actionGuard - Captcha protection for actions

​Example configuration

​Parameter description

`security*` - Basic structure

Parameter description

`security.friendlyCaptchaV1` - Bot protection with FriendlyCaptcha

Example configuration

Parameter overview

`security.method` - Encrypt sensitive data

Example configuration

Parameter description

`security.recaptchav3` - Bot protection with Google reCAPTCHA

Example configuration

Parameter overview

`security.actionGuard` - Captcha protection for actions

Example configuration

Parameter description