Skip to main content
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": {}
  }
}
Parameter description
ParameterDescription
friendlyCaptchaV1Integrates FriendlyCaptcha into the shop.
recaptchav3Integrates Google reCAPTCHA into the shop.
methodDefines how sensitive data is processed.

​
security.friendlyCaptchaV1 - Bot protection with FriendlyCaptcha

The security.friendlyCaptchaV1 node integrates Friendly Captcha into the storefront in order to prevent spam and detect bots. 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
ParameterTypeDescription
namestringFreely selectable internal configuration name.
apiKeystringSecret server key for verification at FriendlyCaptcha.
siteKeystringPublic key for integrating FriendlyCaptcha.
verifyUrlstringEndpoint for server-side verification with FriendlyCaptcha. Default: https://eu-api.friendlycaptcha.eu/api/v1/siteverify
apiUrlstringEndpoint 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). Example configuration 
{
  "encrypt": [
    {
      "id": "token_v1",
      "secret": "ABC123"
    }
  ],
  "hash": [
    {
      "id": "password_v1",
      "salt": "shop-wide-salt-a9c3f1",
      "pepper": "env:SECURITY_PEPPER"
    }
  ]
}
Parameter description
ParameterTypeDescription
hashlist (object)List of configured hash methods for one-way hashing (e.g. passwords).
idstringTechnical name of the hash method, freely selectable (e.g. password_v1).
Must not contain #.
saltstringAn additional, random value that is appended to the data before hashing.
pepperstringA secret additional value used together with the salt before hashing.
encryptlist (object)List of configured encryption methods for reversible data (e.g. tokens, sensitive fields).
idstringTechnical name of the encryption method, freely selectable (e.g. token_v1).
Must not contain #.
secretstringSecret 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. Example configuration 
{
  "minimumScore": 0.5,
  "name": "recaptchav3",
  "secretKey": "",
  "verifyUrl": "https://www.google.com/recaptcha/api/siteverify"
}
Parameter overview
ParameterTypeDescription
namestringFreely selectable identifier of the configuration (e.g. context-specific like “recaptcha_checkout”).
minimumScorefloatThreshold 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
secretKeystringServer-side secret key of Google reCAPTCHA.
verifyUrlstringEndpoint 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. Example configuration 
actionName: Login
captcha:
  service: captchaCheck.friendlyCaptchaV1
Parameter description
ParameterTypeDescription
actionNamestringName of the action to be protected by the captcha check (e.g. Login).
captchasingleService (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.