Settings

scenario

scenario groups the player-facing behavior for password registration, password authentication, and password changes.

registration

enabled

• Takes: true or false
• Current template default: true
• Affects: whether the Credential provider allows new account registration in the registration and migration flows

If this is disabled, the registration step denies the flow with the provider's registration-disabled message instead of accepting a new password.

requireRepeat

• Takes: true or false
• Current template default: true
• Affects: whether registration is a two-step password flow with a confirmation step

When this is enabled, the first password entry is hashed and stored in pipeline state, then the player must send the same password again to confirm it. When this is disabled, the account is created immediately after the first valid password entry.

password

The registration.password subsection is actively enforced by the Credential provider during registration and when players use the change-password command.

Whitespace is always rejected by runtime password validation, even though that rule is not exposed as a separate config field.

minLength

• Takes: a non-negative integer
• Current template default: 6
• Affects: the minimum accepted password length

Set this to 0 to stop enforcing a minimum length.

maxLength

• Takes: a non-negative integer
• Current template default: 32
• Affects: the maximum accepted password length

Set this to 0 to stop enforcing a maximum length.

minUpper

• Takes: a non-negative integer
• Current template default: 1
• Affects: the minimum number of uppercase characters required in a password

Set this to 0 to stop requiring uppercase characters.

minLower

• Takes: a non-negative integer
• Current template default: 1
• Affects: the minimum number of lowercase characters required in a password

Set this to 0 to stop requiring lowercase characters.

minNumber

• Takes: a non-negative integer
• Current template default: 1
• Affects: the minimum number of digits required in a password

Set this to 0 to stop requiring digits.

minSpecial

• Takes: a non-negative integer
• Current template default: 1
• Affects: the minimum number of non-letter, non-digit characters required in a password

Set this to 0 to stop requiring special characters.

scenario:
  registration:
    enabled: true
    requireRepeat: true
    password:
      minLength: 8
      maxLength: 64
      minUpper: 1
      minLower: 1
      minNumber: 1
      minSpecial: 1

{
  "scenario": {
    "registration": {
      "enabled": true,
      "requireRepeat": true,
      "password": {
        "minLength": 8,
        "maxLength": 64,
        "minUpper": 1,
        "minLower": 1,
        "minNumber": 1,
        "minSpecial": 1
      }
    }
  }
}

authentication.bruteforce

authentication.bruteforce controls the failed-password sentinel used by the Password authentication step.

When a player enters a wrong password, the provider records a brute-force attempt. Depending on these settings, that can append a warning message, deny the login attempt for a lockout window, or do nothing at all.

maxAttempts

• Takes: a non-negative integer
• Current template default: 5
• Affects: how many failed password attempts are allowed before the sentinel reaches its limit

If this is 0 or lower, the brute-force sentinel is disabled.

lockout.enabled

• Takes: true or false
• Current template default: true
• Affects: whether hitting the attempt limit turns into a hard temporary lockout

If this is disabled, attempts are still counted inside the lockout duration window, but the provider does not deny the player with a lockout message. That means warning messages can still be shown while hard lockouts stay off.

lockout.duration

• Takes: a positive duration
• Current template default: "5m"
• Affects: how long failed-attempt entries stay active and, when lockout is enabled, how long the player stays locked out

This duration is not only the lockout length. It is also the TTL used to remember failed attempts in the sentinel cache. If the duration is zero or negative, the runtime effectively stops recording brute-force attempts.

warning.enabled

• Takes: true or false
• Current template default: true
• Affects: whether the provider can append remaining-attempt warnings after invalid passwords

warning.thresholdPercentage

• Takes: a percentage integer
• Current template default: 50
• Affects: how early the remaining-attempt warning starts appearing

The runtime clamps this to the 0 to 100 range. With the default maxAttempts: 5 and thresholdPercentage: 50, warning messages begin on the third failed attempt, because that leaves only two tries remaining.

changePassword.requireRepeat

• Takes: true or false
• Current template default: true
• Affects: whether /changepassword <current> <new> [repeat] requires the repeat argument

When this is enabled, omitting the repeat argument is treated as a mismatch. When this is disabled, the repeat argument becomes optional, but if the player does provide it, it still has to match the new password.

cryptography

cryptography controls how the Credential provider hashes new passwords and whether older hashes should be upgraded after a successful login.

algorithm

• Takes: "bcrypt" or "argon2"
• Current template default: "bcrypt"
• Affects: which registered hasher is used for new password hashes

The registry normalizes algorithm ids case-insensitively. The built-in Credential provider currently registers bcrypt and argon2.

Changing this does not instantly invalidate already stored passwords. Stored accounts remember their hashing method, so existing hashes continue to verify with their original algorithm as long as that hasher is available. The configured algorithm mainly decides what is used for new registrations, password changes, and automatic rehashing.

If this value is blank or points to a missing hasher, new password hashes cannot be created and registration or password-change flows will fail.

autoupgrade

• Takes: true or false
• Current template default: true
• Affects: whether a successful password verification can rehash the password into the currently configured algorithm

When this is enabled, a player who logs in successfully with an older stored hashing method is automatically upgraded to the configured algorithm. This only happens after a successful verification event.

algorithms.bcrypt.cost

• Takes: a positive integer
• Current template default: 12
• Affects: the bcrypt work factor used when cryptography.algorithm resolves to bcrypt

The bcrypt hasher throws if this is 0 or lower. Higher values are slower but more expensive to brute-force.

algorithms.argon2.iterations

• Takes: a positive integer
• Current template default: 3
• Affects: the Argon2id iteration count used when cryptography.algorithm resolves to argon2

algorithms.argon2.parallelism

• Takes: a positive integer
• Current template default: 1
• Affects: the Argon2id parallelism value used when cryptography.algorithm resolves to argon2

algorithms.argon2.memoryKb

• Takes: a positive integer
• Current template default: 65536
• Affects: the Argon2id memory budget in kilobytes used when cryptography.algorithm resolves to argon2

All three Argon2 fields must stay positive or hashing throws at runtime.