Este documento proporciona material de referencia de API para los componentes del sistema de autenticación de Django. Para obtener más detalles sobre el uso de estos componentes o cómo personalizar la autenticación y autorización, consulte la guía de temas de autenticación.
Los objetos User tienen los siguientes campos:
Requerido. 150 caracteres o menos. Los nombres de usuario pueden contener caracteres alfanuméricos, _, @, +, . y -.
La longitud máxima debería ser suficiente para muchos casos de uso. Si necesitas una longitud mayor, por favor utiliza un modelo de usuario personalizado.
Opcional (blank=True). 150 caracteres o menos.
Opcional (blank=True). 150 caracteres o menos.
Optional (blank=True). Dirección de correo electrónico.
Requerido. Una hash de, y metadatos sobre, la contraseña. (Django no almacena la contraseña en texto plano.) Las contraseñas en texto plano pueden ser arbitrariamente largas y contener cualquier carácter. Los metadatos en este campo pueden marcar la contraseña como inutilizable. Consulte la documentación de contraseñas.
Relación muchos a muchos con Permission
Booleano. Permite que este usuario acceda al sitio administrativo.
Booleano. Marca esta cuenta de usuario como activa. Recomendamos establecer esta bandera en False en lugar de eliminar cuentas. De esa manera, si las aplicaciones tienen cualquier clave foránea a usuarios, las claves foráneas no se romperán.
Esto no controla necesariamente si el usuario puede iniciar sesión o no. Los backends de autenticación no están obligados a comprobar la bandera is_active pero el backend por defecto (ModelBackend) y el RemoteUserBackend sí lo hacen. Puedes utilizar AllowAllUsersModelBackend o AllowAllUsersRemoteUserBackend si deseas permitir que los usuarios inactivos inicien sesión. En ese caso, también querrás personalizar la AuthenticationForm utilizada por la LoginView ya que rechaza a los usuarios inactivos. Ten en cuenta que los métodos de verificación de permisos como has_perm() y la autenticación en el administrador de Django devuelven False para los usuarios inactivos.
Booleano. Trata a este usuario como si tuviera todos los permisos sin asignar ningún permiso en particular.
Una fecha y hora del último inicio de sesión del usuario.
La fecha/hora cuando se creó la cuenta.
Atributo de solo lectura que siempre es True (a diferencia de AnonymousUser.is_authenticated que siempre es False). Esta es una forma de determinar si el usuario ha sido autenticado. Esto no implica ninguna autorización y no verifica si el usuario está activo o tiene una sesión válida. Aunque normalmente comprobarás este atributo en request.user para saber si se ha poblado por la AuthenticationMiddleware (representando al usuario actualmente conectado), debes saber que este atributo es True para cualquier instancia de User.
Atributo de solo lectura que siempre es False. Esta es una forma de diferenciar objetos User y AnonymousUser. En general, debes preferir usar el atributo is_authenticated en lugar de este.
Devuelve el nombre de usuario del usuario. Dado que el modelo User puede ser reemplazado, debes utilizar este método en lugar de referenciar directamente el atributo de nombre de usuario.
Devuelve la first_name más la last_name, con un espacio entre ellas.
Devuelve la first_name.
Establece el password del usuario en la cadena de texto bruta dada, tomando cuidado del almacenamiento de contraseñas. No guarda el objeto User.
Cuando raw_password es None, el password se establecerá en una contraseña inutilizable, como si se hubiera utilizado la función set_unusable_password().
Versión asíncrona: acheck_password()
Devuelve True si la cadena de texto bruta dada es la contraseña correcta para el usuario. (Esto se encarga del almacenamiento de contraseñas en la comparación.)
Los usuarios se marcan como no tener contraseña establecida actualizando los metadatos en el campo password. Esto no es lo mismo que tener una cadena vacía para la contraseña. check_password() para este usuario nunca devolverá True. No guarda el objeto User.
Es posible que necesites esto si la autenticación de tu aplicación tiene lugar contra un directorio externo existente, como un directorio LDAP.
Restricción de restablecimiento de contraseña
Los usuarios con una contraseña inutilizable no podrán solicitar un correo electrónico de restablecimiento de contraseña a través de PasswordResetView.
Devuelve False si se ha llamado a set_unusable_password() para este usuario.
Versión asíncrona: aget_user_permissions()
Devuelve un conjunto de cadenas de permiso que el usuario tiene directamente.
Si se pasa obj como parámetro, solo devuelve las permisos del usuario para este objeto específico.
Se agregó el método aget_user_permissions().
Versión asíncrona: aget_group_permissions()
Los textos traducidos son:
Si se pasa obj, solo devuelve las permisos de grupo para este objeto específico.
Se agregó el método aget_group_permissions().
Versión asíncrona: aget_all_permissions()
Returns a set of permission strings that the usuario tiene, tanto a través de permisos de grupo como de usuario.
Si se pasa obj, solo devuelve los permisos para este objeto específico.
Se agregó el método aget_all_permissions().
Versión asíncrona: ahas_perm()
Returns True si el usuario tiene la especificada permiso, donde perm es en formato "<app label>.<permission codename>". (ver documentación sobre permissions). Si el usuario está inactivo, este método siempre devolverá False. Para un superusuario activo, este método siempre devolverá True.
Si se pasa obj, este método no verificará la permiso para el modelo, sino para este objeto específico.
ahas_perm() método fue agregado.
Versión asíncrona: ahas_perms()
Devuelve True si el usuario tiene cada uno de los permisos especificados, donde cada permiso está en formato "<etiqueta de aplicación>.<código de nombre de permiso>". Si el usuario está inactivo, este método siempre devolverá False. Para un superusuario activo, este método siempre devolverá True.
Si se pasa obj, este método no comprobará los permisos para el modelo, sino para el objeto específico.
ahas_perms() método fue agregado.
Versión asíncrona: ahas_module_perms()
Devuelve True si el usuario tiene algún permiso en la paqueta dada (la etiqueta de aplicación Django). Si el usuario está inactivo, este método siempre devolverá False. Para un superusuario activo, este método siempre devolverá True.
ahas_module_perms() método fue agregado.
Envía un correo electrónico al usuario. Si from_email es None, Django utiliza el DEFAULT_FROM_EMAIL. Cualquier **kwargs se pasan a la llamada subyacente de send_mail().
El modelo de usuario User tiene un administrador personalizado que tiene los siguientes métodos auxiliares (además de los métodos proporcionados por BaseUserManager):
Versión asíncrona: acreate_user()
Crea, guarda y devuelve un objeto User.
Se establecen los atributos username y password tal como se dan. La parte del dominio de email se convierte automáticamente a minúsculas, y el objeto User devuelto tendrá is_active establecido en True.
Si no se proporciona contraseña, se llamará a set_unusable_password().
Si no se proporciona correo electrónico, email se establecerá en una cadena vacía.
Los argumentos de palabra clave extra_fields se pasan a través del método __init__ del objeto User para permitir establecer campos arbitrarios en un modelo de usuario personalizado:ref:` <auth-custom-user>`.
Consulte Crear usuarios para ver ejemplos de uso.
Se agregó el método acreate_user().
Versión asíncrona: acreate_superuser()
Same como create_user(), pero establece is_staff y is_superuser a True.
Se agregó el método acreate_superuser().
Devuelve usuarios que tienen el permiso dado perm en formato "<app label>.<permission codename> o como instancia de Permission. Devuelve un queryset vacío si no se encuentran usuarios con el permiso perm.
Si is_active es True (por defecto), devuelve solo usuarios activos, o si False, devuelve solo usuarios inactivos. Utilice None para devolver todos los usuarios sin importar su estado de actividad.
Si include_superusers es True (por defecto), el resultado incluirá superusuarios.
Si se pasa backend y está definido en AUTHENTICATION_BACKENDS, entonces este método lo utilizará. De lo contrario, utilizará el backend de AUTHENTICATION_BACKENDS si solo hay uno, o lanzará una excepción.
AnonymousUser¶La clase django.contrib.auth.models.AnonymousUser implementa la interfaz django.contrib.auth.models.User, con estas diferencias:
El id siempre es None.
El atributo username siempre es una cadena vacía.
get_username() siempre devuelve la cadena vacía.
is_anonymous es True en lugar de False.
is_authenticated es False en lugar de True.
is_staff y is_superuser siempre son False.
is_active siempre es False.
groups y user_permissions siempre están vacías.
set_password(), check_password(), save() y delete() levantan NotImplementedError.
En la práctica, probablemente no necesitarás utilizar objetos de tipo AnonymousUser por tu cuenta, pero se utilizan por las solicitudes web, como se explica en el siguiente apartado.
Permisos modelo¶Permission objetos tienen los siguientes campos:
Requerido. 255 caracteres o menos. Ejemplo: 'Puede votar'.
Requerido. Una clave foránea al modelo ContentType.
Requerido. 100 caracteres o menos. Ejemplo: 'puede_votar'.
Los objetos Permission tienen los métodos de acceso a datos estándar como cualquier otro modelo Django.
Grupo¶Los objetos Group tienen los siguientes campos:
Requerido. 150 caracteres o menos. Se permiten cualquier carácter. Ejemplo: 'Usuarios geniales'.
Campo muchos a muchos con Permission:
group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()
Un validador de campo que permite solo letras y números ASCII, además de @, ., +, - y _.
Un validador de campo que permite caracteres Unicode, además de @, ., +, - y _. El validador predeterminado para User.username.
El marco de autenticación utiliza los siguientes señales :doc:``signals <topics/signales> que se pueden utilizar para notificaciones cuando un usuario inicia sesión o se desconecta.
Se envía cuando un usuario se loguea con éxito.
Argumentos enviados con este señal:
La clase del usuario que acaba de iniciar sesión.
La instancia actual HttpRequest.
La instancia del usuario que acaba de iniciar sesión.
Se envía cuando se llama al método de cierre de sesión.
Como arriba: la clase del usuario que acaba de cerrar sesión o None si el usuario no estaba autenticado.
La instancia actual HttpRequest.
La instancia del usuario que acaba de cerrar sesión o None si el usuario no estaba autenticado.
Se envía cuando el usuario falla en iniciar sesión con éxito
El nombre del módulo utilizado para la autenticación.
credentialsUn diccionario de argumentos clave que contiene las credenciales del usuario que se pasaron a authenticate() o su propio backend de autenticación personalizado. Las credenciales que coincidan con un conjunto de patrones “sensibles” (incluyendo la contraseña) no se enviarán en claro como parte del señal.
El objeto HttpRequest, si uno se proporcionó a authenticate().
Esta sección detalla los backends de autenticación que vienen con Django. Para obtener información sobre cómo utilizarlos y cómo escribir tus propios backends de autenticación, consulta la sección Otros fuentes de autenticación del Guía de autenticación de usuarios.
Los siguientes backends están disponibles en django.contrib.auth.backends:
Una clase base que proporciona implementaciones por defecto para todos los métodos requeridos. Por defecto, rechazará a cualquier usuario y no proporcionará permisos.
Versión asíncrona: aget_user_permissions()
Devuelve un conjunto vacío.
Se agregó la función aget_user_permissions().
Versión asíncrona: aget_group_permissions()
Devuelve un conjunto vacío.
Se agregó la función aget_group_permissions().
Versión asíncrona: aget_all_permissions()
Utiliza get_user_permissions() y get_group_permissions() para obtener el conjunto de cadenas de permiso que tiene user_obj.
Se agregó la función aget_all_permissions().
Versión asíncrona: ahas_perm()
Utiliza get_all_permissions() para comprobar si user_obj tiene la cadena de permiso perm.
La traducción de los textos es la siguiente:
Este es el backend de autenticación por defecto utilizado por Django. Autentica utilizando credenciales que consisten en un identificador de usuario y contraseña. Para el modelo de usuario predeterminado de Django, el identificador de usuario es el nombre de usuario, para modelos de usuarios personalizados es el campo especificado por USERNAME_FIELD (consulte Personalizando Usuarios y autenticación).
También maneja el modelo de permisos predeterminado definido para User y PermissionsMixin.
has_perm(), get_all_permissions(), get_user_permissions(), y get_group_permissions() permiten pasar un objeto como parámetro para permisos específicos de objetos, pero este backend no los implementa más que devolviendo un conjunto vacío de permisos si obj is not None.
with_perm() también permite pasar un objeto como parámetro, pero a diferencia de otros métodos devuelve una consulta vacía si obj is not None.
Versión asíncrona: aauthenticate()
Intenta autenticar username con password llamando a User.check_password. Si no se proporciona username, intenta fetchear un nombre de usuario desde kwargs utilizando la clave CustomUser.USERNAME_FIELD. Devuelve un usuario autenticado o None.
request es una HttpRequest y puede ser None si no se proporcionó a authenticate() (que lo pasa al backend).
aauthenticate() función fue agregada.
Versión asíncrona: aget_user_permissions()
Devuelve el conjunto de cadenas de permisos que user_obj tiene desde sus propias permisos del usuario. Devuelve un conjunto vacío si is_anonymous o is_active es False.
Se agregó la función aget_user_permissions().
Versión asíncrona: aget_group_permissions()
Returns el conjunto de cadenas de permiso que user_obj tiene desde los permisos de los grupos a los que pertenece. Devuelve un conjunto vacío si is_anonymous o is_active es False.
Se agregó la función aget_group_permissions().
Versión asíncrona: aget_all_permissions()
Returns el conjunto de cadenas de permiso que user_obj tiene, incluyendo tanto los permisos del usuario como los permisos de grupo. Devuelve un conjunto vacío si is_anonymous o is_active es False.
Se agregó la función aget_all_permissions().
Versión asíncrona: ahas_perm()
Utiliza la función get_all_permissions() para comprobar si user_obj tiene la cadena de permiso perm. Devuelve False si el usuario no está is_active.
La traducción de los textos es la siguiente:
Versión asíncrona: ahas_module_perms()
Returns si user_obj tiene algún permiso en la aplicación app_label.
La función ahas_module_perms() fue agregada.
Returns si el usuario está permitido para autenticarse. Para coincidir con el comportamiento de AuthenticationForm que prohibe a los usuarios inactivos de iniciar sesión, este método devuelve False para los usuarios con is_active=False. Los modelos de usuario personalizados que no tienen un campo is_active están permitidos.
Returns todos los usuarios activos que tienen el permiso perm en la forma de "<app label>.<permission codename>" o una instancia de Permission. Devuelve un conjunto vacío si no se encuentran usuarios con el perm.
Si is_active es True (por defecto), devuelve solo usuarios activos, o si False, devuelve solo usuarios inactivos. Utilice None para devolver todos los usuarios sin importar su estado de actividad.
Si include_superusers es True (por defecto), el resultado incluirá superusuarios.
Igual que ModelBackend excepto que no rechaza a los usuarios inactivos porque user_can_authenticate() siempre devuelve True.
Cuando uses este backend, es probable que desees personalizar la forma de autenticación utilizada por el LoginView sobreescribiendo el método confirm_login_allowed() ya que rechaza a los usuarios inactivos.
Utilice este backend para aprovechar la autenticación gestionada externamente a Django. Autentica utilizando nombres de usuario pasados en request.META['REMOTE_USER']. Consulte la documentación Autenticando contra REMOTE_USER .
Si necesitas más control, puedes crear tu propio backend de autenticación que herede de esta clase y sobreescribas estos atributos o métodos:
Verdadero o Falso. Determina si se crea un objeto de usuario si no está ya en la base de datos. Por defecto es Verdadero.
Versión asíncrona: aauthenticate()
El nombre de usuario pasado como remote_user se considera confiable. Este método devuelve el objeto de usuario con el nombre de usuario dado, creando un nuevo objeto de usuario si create_unknown_user es Verdadero.
Devuelve None si create_unknown_user es Falso y no se encuentra en la base de datos un objeto User con el nombre de usuario dado.
request es una HttpRequest y puede ser None si no se proporcionó a authenticate() (que lo pasa al backend).
aauthenticate() función fue agregada.
Realiza cualquier limpieza sobre el nombre de usuario (por ejemplo, eliminando información DN LDAP) antes de utilizarlo para obtener o crear un objeto de usuario. Devuelve el nombre de usuario limpio.
Versión asíncrona: aconfigure_user()
Configura al usuario en cada intento de autenticación. Este método se llama inmediatamente después de fetchear o crear el objeto de usuario que se está autenticando, y se puede utilizar para realizar acciones de configuración personalizadas, como establecer los grupos del usuario según atributos en un directorio LDAP. Devuelve el objeto de usuario. Cuando se llama a fetchear o crear un usuario desde un contexto síncrono, configure_user se llama, aconfigure_user se llama desde contextos asíncronos.
La configuración se puede realizar una vez cuando el usuario es creado (created es Verdadero) o en usuarios existentes (created es Falso) como forma de sincronizar atributos entre los sistemas remotos y locales.
request es una HttpRequest y puede ser None si no se proporcionó a authenticate() (que lo pasa al backend).
Se agregó la función aconfigure_user().
Devuelve si el usuario está permitido para autenticarse. Este método devuelve Falso para usuarios con is_active=False. Los modelos de usuario personalizados que no tienen un campo is_active están permitidos.
Lo mismo que RemoteUserBackend excepto porque no rechaza a los usuarios inactivos porque user_can_authenticate siempre devuelve True.
Versión asíncrona: aget_user()
Devuelve la instancia del modelo de usuario asociada a la sesión dada en el request.
Verifica si el backend de autenticación almacenado en la sesión está presente en AUTHENTICATION_BACKENDS. Si es así, utiliza el método get_user() del backend para recuperar la instancia del modelo de usuario y luego verifica la sesión llamando al método get_session_auth_hash() del modelo de usuario. Si la verificación falla y se proporcionan claves de fallback en SECRET_KEY_FALLBACKS, verifica la sesión contra cada clave de fallback utilizando el método get_session_auth_fallback_hash().
Devuelve una instancia de AnonymousUser si el backend de autenticación almacenado en la sesión ya no está presente en AUTHENTICATION_BACKENDS, si un usuario no se devuelve por el método get_user() del backend o si la hash de autenticación de la sesión no es válida.
may 31, 2026