PhoenixKit.Users.Auth.User (phoenix_kit v1.6.16)

View Source

User schema for PhoenixKit authentication system.

This schema defines the core user entity with email-based authentication and account management features.

Fields

  • email: User's email address (unique, required for authentication)
  • password: Virtual field for password input (redacted in logs)
  • hashed_password: Bcrypt-hashed password stored in database (redacted)
  • current_password: Virtual field for password confirmation (redacted)
  • confirmed_at: Timestamp when email was confirmed (nil for unconfirmed accounts)

Security Features

  • Password hashing with bcrypt
  • Email uniqueness enforcement
  • Password strength validation
  • Sensitive field redaction in logs
  • Email confirmation workflow support

Summary

Types

t()

Functions

admin?(user)

Checks if a user is an admin or owner.

confirm_changeset(user)

Confirms the account by setting confirmed_at.

custom_fields_changeset(user, attrs)

A user changeset for updating custom fields.

email_changeset(user, attrs, opts \\ [])

A user changeset for changing the email.

excluded_fields()

Returns list of fields excluded from get_user_field for security.

full_name(user)

Gets the user's full name by combining first and last name.

generate_username_from_email(email)

Generate a username from an email address.

get_roles(user)

Gets all roles for a user.

has_role?(user, role_name)

Checks if a user has a specific role.

owner?(user)

Checks if a user is an owner.

password_changeset(user, attrs, opts \\ [])

A user changeset for changing the password.

preferred_locale_changeset(user, attrs)

A user changeset for updating preferred locale/dialect.

profile_changeset(user, attrs, opts \\ [])

A user changeset for updating profile information.

registration_changeset(user, attrs, opts \\ [])

A user changeset for registration.

status_changeset(user, attrs)

A user changeset for updating active status.

timezone_changeset(user, attrs)

A user changeset for updating timezone preference.

unconfirm_changeset(user)

Unconfirms the account by setting confirmed_at to nil.

valid_password?(arg1, password)

Verifies the password.

validate_current_password(changeset, password)

Validates the current password otherwise adds an error to the changeset.

Types

t()

@type t() :: %PhoenixKit.Users.Auth.User{
  __meta__: term(),
  confirmed_at: NaiveDateTime.t() | nil,
  current_password: String.t() | nil,
  custom_fields: map() | nil,
  email: String.t(),
  first_name: String.t() | nil,
  hashed_password: String.t(),
  id: integer() | nil,
  inserted_at: NaiveDateTime.t(),
  is_active: boolean(),
  last_name: String.t() | nil,
  password: String.t() | nil,
  preferred_locale: String.t() | nil,
  registration_city: String.t() | nil,
  registration_country: String.t() | nil,
  registration_ip: String.t() | nil,
  registration_region: String.t() | nil,
  role_assignments: term(),
  roles: term(),
  updated_at: NaiveDateTime.t(),
  user_timezone: String.t() | nil,
  username: String.t() | nil
}

Functions

admin?(user)

Checks if a user is an admin or owner.

Examples

iex> admin?(user)
true

confirm_changeset(user)

Confirms the account by setting confirmed_at.

custom_fields_changeset(user, attrs)

A user changeset for updating custom fields.

Custom fields are stored as JSONB and can contain arbitrary key-value pairs.

Examples

iex> custom_fields_changeset(user, %{custom_fields: %{"phone" => "555-1234"}})
%Ecto.Changeset{valid?: true}

iex> custom_fields_changeset(user, %{custom_fields: "invalid"})
%Ecto.Changeset{valid?: false}

email_changeset(user, attrs, opts \\ [])

A user changeset for changing the email.

It requires the email to change otherwise an error is added.

excluded_fields()

Returns list of fields excluded from get_user_field for security.

These fields contain sensitive or internal data and should not be accessed via the generic field accessor.

Examples

iex> excluded_fields()
[:password, :current_password, :hashed_password, :__meta__, :__struct__]

full_name(user)

Gets the user's full name by combining first and last name.

Examples

iex> full_name(%User{first_name: "John", last_name: "Doe"})
"John Doe"

iex> full_name(%User{first_name: "John", last_name: nil})
"John"

iex> full_name(%User{first_name: nil, last_name: nil})
nil

generate_username_from_email(email)

Generate a username from an email address.

Takes the part before @ symbol, converts to lowercase, replaces dots with underscores, and ensures it meets validation requirements.

Examples

iex> generate_username_from_email("john.doe@example.com")
"john_doe"

iex> generate_username_from_email("user@example.com")
"user"

get_roles(user)

Gets all roles for a user.

Examples

iex> get_roles(user)
["Admin", "User"]

has_role?(user, role_name)

Checks if a user has a specific role.

Examples

iex> has_role?(user, "Admin")
true

iex> has_role?(user, "Owner")
false

owner?(user)

Checks if a user is an owner.

Examples

iex> owner?(user)
true

password_changeset(user, attrs, opts \\ [])

A user changeset for changing the password.

Options

  • :hash_password - Hashes the password so it can be stored securely in the database and ensures the password field is cleared to prevent leaks in the logs. If password hashing is not needed and clearing the password field is not desired (like when using this changeset for validations on a LiveView form), this option can be set to false. Defaults to true.

preferred_locale_changeset(user, attrs)

A user changeset for updating preferred locale/dialect.

This allows authenticated users to select their preferred dialect variant (e.g., en-GB instead of en-US) while URLs continue to show base codes.

Validation

  • Format: Must match ~r/^[a-z]{2}(-[A-Z]{2})?$/
  • Existence: Must exist in predefined language list
  • NULL allowed: Indicates "use system default"

Examples

iex> preferred_locale_changeset(user, %{preferred_locale: "en-GB"})
#Ecto.Changeset<...>

iex> preferred_locale_changeset(user, %{preferred_locale: nil})
#Ecto.Changeset<...>  # Clears preference, uses defaults

iex> preferred_locale_changeset(user, %{preferred_locale: "invalid"})
#Ecto.Changeset<errors: [preferred_locale: {"must be a valid locale format", []}]>

profile_changeset(user, attrs, opts \\ [])

A user changeset for updating profile information.

Options

  • :validate_email - Validates the uniqueness of the email, in case you don't want to validate the uniqueness of the email (like when using this changeset for validations on a LiveView form before submitting the form), this option can be set to false. Defaults to true.

registration_changeset(user, attrs, opts \\ [])

A user changeset for registration.

It is important to validate the length of both email and password. Otherwise databases may truncate the email without warnings, which could lead to unpredictable or insecure behaviour. Long passwords may also be very expensive to hash for certain algorithms.

Options

  • :hash_password - Hashes the password so it can be stored securely in the database and ensures the password field is cleared to prevent leaks in the logs. If password hashing is not needed and clearing the password field is not desired (like when using this changeset for validations on a LiveView form), this option can be set to false. Defaults to true.

  • :validate_email - Validates the uniqueness of the email, in case you don't want to validate the uniqueness of the email (like when using this changeset for validations on a LiveView form before submitting the form), this option can be set to false. Defaults to true.

status_changeset(user, attrs)

A user changeset for updating active status.

timezone_changeset(user, attrs)

A user changeset for updating timezone preference.

Examples

iex> timezone_changeset(user, %{"user_timezone" => "+5"})
%Ecto.Changeset{valid?: true}

iex> timezone_changeset(user, %{"user_timezone" => "invalid"})
%Ecto.Changeset{valid?: false}

unconfirm_changeset(user)

Unconfirms the account by setting confirmed_at to nil.

valid_password?(arg1, password)

Verifies the password.

If there is no user or the user doesn't have a password, we call Bcrypt.no_user_verify/0 to avoid timing attacks.

validate_current_password(changeset, password)

Validates the current password otherwise adds an error to the changeset.