diff --git a/website/docs/customize/blueprints/v1/models.mdx b/website/docs/customize/blueprints/v1/models.mdx index 30ea59d3a2..f6aa69e179 100644 --- a/website/docs/customize/blueprints/v1/models.mdx +++ b/website/docs/customize/blueprints/v1/models.mdx @@ -45,6 +45,33 @@ For example: password: this-should-be-a-long-value ``` +### `password_hash` + +In blueprints, a user's password can also be set using the `password_hash` field. The value must be a valid Django password hash, such as one generated with the `hash_password` management command. + +Use `password_hash` when you need to import or bootstrap an existing hash without exposing the raw password to authentik: + +```bash +docker compose run --rm server hash_password 'your-password' +``` + +For example: + +```yaml +# [...] +- model: authentik_core.user + state: present + identifiers: + username: test-user + attrs: + name: test user + password_hash: pbkdf2_sha256$1000000$xKKFuYtJEE27km09BD49x2$4+Z6j3utmouPF5mik0Z21L2P0og5IlmMmIJ46Tj3zCM= +``` + +`password` and `password_hash` are mutually exclusive; setting both on the same user causes blueprint validation to fail. + +Because no raw password is available when `password_hash` is used, authentik only updates the local password verifier. This does not propagate the password to LDAP or Kerberos integrations, even when password writeback is enabled. + ### `permissions` The `permissions` field can be used to set global permissions for a user. A full list of possible permissions is included in the JSON schema for blueprints. diff --git a/website/docs/install-config/automated-install.mdx b/website/docs/install-config/automated-install.mdx index cccef64655..a2dbb3a787 100644 --- a/website/docs/install-config/automated-install.mdx +++ b/website/docs/install-config/automated-install.mdx @@ -10,9 +10,9 @@ These can't be defined using the file-based syntax (`file://`), so you can't pas ### `AUTHENTIK_BOOTSTRAP_PASSWORD_HASH` -Configure the default password for the `akadmin` user using a pre-hashed password. Only read on the first startup. +Configure the default password for the `akadmin` user using a pre-hashed Django password value. Only read on the first startup. -This updates authentik's stored password hash directly. It does not propagate the password to LDAP or Kerberos integrations. +This stores the hash directly as authentik's local password verifier. Because authentik never sees the raw password, this does not propagate the password to LDAP or Kerberos integrations, even when password writeback is enabled. To generate a hash, run this command before your initial deployment: @@ -20,6 +20,8 @@ To generate a hash, run this command before your initial deployment: docker compose run --rm server hash_password 'your-password' ``` +The generated hash includes a random salt, so running the command multiple times for the same password produces different output. Use the complete output as the value of `AUTHENTIK_BOOTSTRAP_PASSWORD_HASH`. + :::warning Escaping `$` in Docker Compose Password hashes contain `$` characters which Docker Compose interprets as variable references. @@ -51,6 +53,12 @@ Configure the default password for the `akadmin` user. Only read on the first st Setting both `AUTHENTIK_BOOTSTRAP_PASSWORD` and `AUTHENTIK_BOOTSTRAP_PASSWORD_HASH` will result in an error. +### Other hashed-password import paths + +For post-install automation, hashed passwords can also be set via blueprints with the `password_hash` user attribute, or via the `/api/v3/core/users//set_password_hash/` API endpoint with the hash provided in the `password` field. The API endpoint requires the `authentik_core.set_user_password_hash` permission and can target regular users or service accounts. + +These paths also only update authentik's local password verifier and do not propagate to LDAP or Kerberos integrations. + ### `AUTHENTIK_BOOTSTRAP_TOKEN` Create a token for the default `akadmin` user. Only read on the first startup. The string you specify for this variable is the token key you can use to authenticate yourself to the API. @@ -75,7 +83,8 @@ When using password hashes in quoted YAML strings as shown above, no escaping of - Using Helm templating syntax (e.g., `{{ .Values.something }}`) where `$` has special meaning - Referencing values from environment variable substitution in your values file - ::: + +::: Or store the password hash in a secret and reference it via `envFrom`: diff --git a/website/docs/users-sources/sources/protocols/kerberos/index.md b/website/docs/users-sources/sources/protocols/kerberos/index.md index 1b1b948407..6b40b32b8a 100644 --- a/website/docs/users-sources/sources/protocols/kerberos/index.md +++ b/website/docs/users-sources/sources/protocols/kerberos/index.md @@ -99,7 +99,7 @@ If not specified, the server name defaults to trying out all entries in the keyt There are some extra settings you can configure: - Update internal password on login: when a user logs in to authentik using the Kerberos source as a password backend, their internal authentik password will be updated to match the one from Kerberos. -- Use password writeback: when a user changes their password in authentik, their Kerberos password is automatically updated to match the one from authentik. This is only available if synchronization is configured. +- Use password writeback: when a user changes their password in authentik, their Kerberos password is automatically updated to match the one from authentik. This is only available if synchronization is configured, and requires authentik to receive the raw password. Password hashes imported or set with `password_hash`, `AUTHENTIK_BOOTSTRAP_PASSWORD_HASH`, or the password-hash API endpoint are not written back to Kerberos. ## Kerberos source property mappings diff --git a/website/docs/users-sources/sources/protocols/ldap/index.md b/website/docs/users-sources/sources/protocols/ldap/index.md index b70229dae4..8ef1fadcb2 100644 --- a/website/docs/users-sources/sources/protocols/ldap/index.md +++ b/website/docs/users-sources/sources/protocols/ldap/index.md @@ -17,7 +17,7 @@ To create or edit a source in authentik, open the Admin interface and navigate t - **Enabled**: Toggle this option on to allow authentik to use the defined LDAP source. - **Update internal password on login**: When the user logs in to authentik using the LDAP password backend, the password is stored as a hashed value in authentik. Toggle off (default setting) if you do not want to store the hashed passwords in authentik. - **Sync users**: Enable or disable user synchronization between authentik and the LDAP source. -- **User password writeback**: Enable this option if you want to write password changes that are made in authentik back to LDAP. +- **User password writeback**: Enable this option if you want to write password changes that are made in authentik back to LDAP. This requires authentik to receive the raw password. Password hashes imported or set with `password_hash`, `AUTHENTIK_BOOTSTRAP_PASSWORD_HASH`, or the password-hash API endpoint are not written back to LDAP. - **Sync groups**: Enable/disable group synchronization between authentik and the LDAP source. - **Delete Not Found Objects**: :ak-version[2025.6] This option synchronizes user and group deletions from LDAP sources to authentik. User deletion requires enabling **Sync users** and group deletion requires enabling **Sync groups**.