Username and password authentication method

The userpass auth method allows users to authenticate in Deckhouse Stronghold using a username and password.

Method features

When using the userpass method, keep the following features in mind:

• Usernames and passwords are specified directly in the authentication method at the path auth/userpass/users/.
• The userpass method cannot read usernames and passwords from an external source.
• Entered usernames are converted to lowercase. For example, Mary and mary are equivalent entries.

Configuration

To allow users to authenticate, configure the userpass method. These steps are usually completed by an operator or configuration management tool.

To configure authentication using the userpass method, follow these steps:

1. Enable the userpass auth method:

   • Stronghold in DKP
   • Stronghold in Linux

   d8 stronghold auth enable userpass

   stronghold auth enable userpass

   The method will be enabled at the auth/userpass path.

   To enable the method at a different path, use the -path flag:

   • Stronghold in DKP
   • Stronghold in Linux

   d8 stronghold auth enable -path=<userpass_mount_path> userpass

   stronghold auth enable -path=<userpass_mount_path> userpass

2. If necessary, create a user who is allowed to authenticate:

   • Stronghold in DKP
   • Stronghold in Linux

   d8 stronghold write auth/<userpass_mount_path>/users/alice \
     password=Pass-123! \
     token_policies=admins

   stronghold write auth/<userpass_mount_path>/users/alice \
     password=Pass-123! \
     token_policies=admins

This creates user alice with password Pass-123! and the admins policy.

User authentication using the userpass method

Example command for user authentication using the userpass method:

d8 stronghold login -method=userpass username=alice password="Pass-123!"

stronghold login -method=userpass username=alice password="Pass-123!"

User lockout

If a user provides incorrect credentials several times in a row, Stronghold stops validating them for a while and returns an access denied error. This behavior is called user lockout (user_lockout).

The time for which a user is locked out is called lockout duration (lockout_duration). After this time expires, the user can log in again.

The number of failed login attempts after which a user is locked out is called lockout threshold (lockout_threshold). The lockout threshold counter resets after a few minutes without login attempts or after a successful login. The interval after which the counter resets when there are no login attempts is called lockout counter reset (lockout_counter_reset).

User lockout helps reduce the risk of password guessing attacks.

The user lockout feature is enabled by default. Default values:

• lockout_threshold: 5 attempts.
• lockout_duration: 15 minutes.
• lockout_counter_reset: 15 minutes.

You can disable user lockout with the auth tune command by setting the disable_lockout parameter to true:

d8 stronghold auth tune -user-lockout-disable=true userpass

stronghold auth tune -user-lockout-disable=true userpass

Changing your own password

You can allow a user to change their own password in the userpass method. To do this, create a policy where the path to the user’s password is formed based on the authenticated user’s name.

Creating a policy

Use the following policy template:

path "auth/userpass/users/{{identity.entity.aliases.<accessor>.name}}/password" {
  capabilities = ["update"]
}

Get the <accessor> value with the command:

d8 stronghold read -field=accessor sys/auth/userpass

stronghold read -field=accessor sys/auth/userpass

The {{identity.entity.aliases.<accessor>.name}} template automatically substitutes the authenticated user’s name. Therefore, the path always points only to the current user’s password.

The template works after logging in via the userpass method.

Allowing a user to change their own password

To allow a user to change their own password using the userpass method, follow these steps:

ACCESSOR=$(d8 stronghold read -field=accessor sys/auth/userpass)

ACCESSOR=$(stronghold read -field=accessor sys/auth/userpass)

d8 stronghold policy write self-change-password - <<EOF
path "auth/userpass/users/{{identity.entity.aliases.${ACCESSOR}.name}}/password" {
  capabilities = ["update"]
}
EOF

stronghold policy write self-change-password - <<EOF
path "auth/userpass/users/{{identity.entity.aliases.${ACCESSOR}.name}}/password" {
  capabilities = ["update"]
}
EOF

1. Assign the policy to the user you want to allow to change their password:

d8 stronghold write auth/userpass/users/alice/policies \
  token_policies="self-change-password"

stronghold write auth/userpass/users/alice/policies \
  token_policies="self-change-password"

d8 stronghold write auth/userpass/users/alice \
  password="OldPass-123!" \
  token_policies="self-change-password"

stronghold write auth/userpass/users/alice \
  password="OldPass-123!" \
  token_policies="self-change-password"