django.contrib.auth
¶
このドキュメントでは、Django の 認証システムのコンポーネントの API リファレンス資料を提供しています。 これらのコンポーネントの使い方や、認証と認可をカスタマイズする方法の詳細は、認証トピックガイド を参照してください。
User
モデル¶
- class models.User¶
フィールド¶
- class models.User
User
オブジェクトには、以下のフィールドがあります:- username¶
必須です。150 文字以下です。英数字のほか、
_
、@
、+
、.
、-
が使えます。max_length
は多くの状況で十分のはずです。もしより長い文字数が必要な場合は、独自のユーザモデル を参照してください。utf8mb4
エンコーディングで MySQL を使っている場合は (適切な Unicode をサポートするために推奨されています)、最大でもmax_length=191
としてください。なぜなら、MySQL は、デフォルトでは 191 文字まででしかユニークインデックスを作成できないからです。
- first_name¶
オプション (
blank=True
)。150 文字以下。
- last_name¶
オプション (
blank=True
)。150 文字以下。
- email¶
オプション (
blank=True
)。メールアドレス。
- password¶
Required. A hash of, and metadata about, the password. (Django doesn't store the raw password.) Raw passwords can be arbitrarily long and can contain any character. The metadata in this field may mark the password as unusable. See the password documentation.
- user_permissions¶
Permission
への多対多のリレーションシップです。
- is_staff¶
真偽値。このユーザに管理サイトへのアクセスを許可します。
- is_active¶
ブール値。このユーザーアカウントをアクティブとしてマークします。アカウントを削除する代わりに、このフラグを
False
に設定することを推奨します。そうすれば、アプリケーションにユーザーへの外部キーがある場合でも、外部キーが壊れることはありません。この属性は、必ずしもユーザがログインできるかどうかをコントロールするわけではありません。認証バックエンドは必ずしも
is_active
フラグをチェックしませんが、デフォルトのバックエンド (ModelBackend
) とRemoteUserBackend
はチェックを行います。非アクティブのユーザがログインできるようにしたい場合は、AllowAllUsersModelBackend
やAllowAllUsersRemoteUserBackend
を使うことができます。この場合、非アクティブのユーザを拒否してしまうので、LoginView
によって使われるAuthenticationForm
もカスタマイズした方が良いでしょう。has_perm()
のようなパーミッションチェックのメソッドや Django admin 内の認証はすべて非アクティブユーザに対してFalse
を返すことに注意してください。
- is_superuser¶
真偽値。このユーザには特にパーミッションを割り当てずに、すべてのパーミッションを持つものとして扱います。
- last_login¶
ユーザーが最後にログインした日時です。
- date_joined¶
アカウントが作成された日時。
属性¶
- class models.User
- is_authenticated¶
(
AnonymousUser.is_authenticated
が常にFalse
なのとは対照的に) 常にTrue
の読み取り専用属性です。ユーザが認証済みかどうかを知らせる方法です。これはパーミッションという意味ではなく、ユーザーがアクティブかどうか、また有効なセッションがあるかどうかをチェックするわけでもありません。 通常、request.user
のこの属性をチェックしてAuthenticationMiddleware
(現在ログイン中のユーザを表します) によって格納されているかどうかを調べます。User
のインスタンスの場合、この属性はTrue
となります。
- is_anonymous¶
常に
False
の読み取り専用属性です。User
オブジェクトとAnonymousUser
オブジェクトを区別する方法です。一般的に、is_authenticated
を使う方が好ましいと言えます。
メソッド¶
- class models.User
- get_username()¶
ユーザのユーザ名を返します。
User
モデルはスワップアウトされることがあるので、ユーザ名を直接参照する代わりにこのメソッドを使う必要があります。
- get_full_name()¶
first_name
とlast_name
をスペースでつないだ文字列を返します。
- get_short_name()¶
first_name
を返します。
- set_password(raw_password)¶
指定された生の文字列に、ユーザのパスワードをセットし、パスワードのハッシュ処理を行います。
User
は保存しません。raw_password
がNone
のとき、set_unusable_password()
が使われるのと同じように、パスワードは使用に適さないパスワードになります。
- check_password(raw_password)¶
- acheck_password(raw_password)¶
非同期バージョン:
acheck_password()
与えられた生の文字列が、ユーザに対して正しいパスワードであれば
True
を返します。 (比較する際にはパスワードハッシュを処理します。)Changed in Django 5.0:acheck_password()
メソッドが追加されました。
- set_unusable_password()¶
Marks the user as having no password set by updating the metadata in the
password
field. This isn't the same as having a blank string for a password.check_password()
for this user will never returnTrue
. Doesn't save theUser
object.アプリケーションの認証が LDAP ディレクトリなどの既存の外部ソースに対して行われている場合は、これが必要になることがあります。
パスワードリセットの制限
使用できないパスワードを持つユーザーは、
PasswordResetView
を通じてパスワードリセットのメールをリクエストすることができません。
- has_usable_password()¶
ユーザに対して
set_unusable_password()
が呼ばれている場合、False
を返します。
- get_user_permissions(obj=None)¶
ユーザーが直接持っているパーミッション文字列のセットを返します。
もし
obj
が渡された場合、この特定のオブジェクトのユーザパーミッションのみを返します。
- get_group_permissions(obj=None)¶
ユーザがグループを通して持つパーミッションの文字列のセットを返します。
obj
が渡されたとき、指定されたオブジェクトに対するグループパーミッションのみを返します。
- get_all_permissions(obj=None)¶
ユーザがグループおよびユーザパーミッションを通して持つパーミッションの文字列のセットを返します。
obj
が渡された場合、指定されたオブジェクトに対するパーミッションのみを返します。
- has_perm(perm, obj=None)¶
perm が
"<app label>.<permission codename>"
という形式で、ユーザーが特定の権限を持っている場合、True
を返します (詳しくは パーミッション のドキュメントを参照)。もしユーザーが非アクティブの場合、このメソッドは常にFalse
を返します。アクティブなスーパーユーザーの場合、このメソッドは常にTrue
を返します。obj
が渡された場合、このメソッドは指定されたオブジェクトに対してパーミッションのチェックを行い、モデルに対しては行いません。
- has_perms(perm_list, obj=None)¶
指定された権限を持つかどうかを判定し、持つ場合は
True
を返します。各 perm は"<app label>.<permission codename>"
の形式です。ユーザーが非アクティブの場合、このメソッドは常にFalse
を返します。アクティブなスーパーユーザーの場合、このメソッドは常にTrue
を返します。obj
が渡された場合、このメソッドは指定されたオブジェクトに対してパーミッションのチェックを行い、モデルに対しては行いません。
- has_module_perms(package_name)¶
与えられたパッケージ (Djangoアプリのラベル) 内でユーザーが何らかの権限を持っている場合、
True
を返します。ユーザーが非アクティブな場合、このメソッドは常にFalse
を返します。アクティブなスーパーユーザーの場合、このメソッドは常にTrue
を返します。
- email_user(subject, message, from_email=None, **kwargs)¶
ユーザに E メールを送信します。
from_email
がNone
の場合、Django はDEFAULT_FROM_EMAIL
を使用します。全ての**kwargs
は元となるsend_mail()
呼び出しに渡されます。
マネージャメソッド¶
- class models.UserManager¶
User
モデルは、(BaseUserManager
で提供されるメソッドに加えて) 以下のヘルパーメソッドを有する独自のマネージャを持っています:- create_user(username, email=None, password=None, **extra_fields)¶
User
を作成、保存して返します。username
とpassword
は指定された通りに設定されます。email
のドメイン部分は自動的に小文字に変換され、返されるUser
オブジェクトにはis_active
がTrue
に設定されます。パスワードが指定されなかった場合、
set_unusable_password()
が呼び出されます。extra_fields
キーワード引数は、User
クラスの__init__
メソッドに渡され、カスタムユーザーモデル に任意のフィールドを設定することを可能にします。使用例については ユーザーの作成 を参照してください。
- create_superuser(username, email=None, password=None, **extra_fields)¶
create_user()
と同じですが、is_staff
とis_superuser
をTrue
にセットします。
- with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)¶
与えられたパーミッション
perm
を持つユーザを"<app label>.<permission codename>"
形式、またはPermission
インスタンスで返します。もしperm
を持つユーザが見つからなかった場合、空のクエリセットを返します。is_active
がTrue
(デフォルト) の場合、アクティブなユーザーのみを返し、False
の場合、非アクティブなユーザーのみを返します。アクティブ状態に関わらずすべてのユーザーを返すにはNone
を使用してください。include_superusers
がTrue
(デフォルト) の場合、結果にはスーパーユーザーが含まれます。もし
backend
が渡され、それがAUTHENTICATION_BACKENDS
で定義されている場合、このメソッドはそれを使用します。そうでない場合、1つだけならばAUTHENTICATION_BACKENDS
内のbackend
を使用し、複数ある場合は例外を発生させます。
AnonymousUser
オブジェクト¶
- class models.AnonymousUser¶
django.contrib.auth.models.AnonymousUser
は、django.contrib.auth.models.User
インターフェースを実装するクラスで、以下の点が異なります。id が常に
None
です。username
が常に空の文字列です。get_username()
が常に空の文字列を返します。is_anonymous
がFalse
ではなくTrue
です。is_authenticated
がFalse
ではなくTrue
です。is_staff
とis_superuser
が常にFalse
です。is_active
が常にFalse
です。groups
とuser_permissions
が常に空です。set_password()
、check_password()
、save()
、delete()
がNotImplementedError
を投げます。
実際には AnonymousUser
オブジェクトを使う必要はないでしょうが、次のセクションで説明するように、Web リクエストで使用されます。
Permission
モデル¶
- class models.Permission¶
フィールド¶
Permission
オブジェクトには以下のフィールドがあります:
メソッド¶
他のあらゆる Django モデル と同じように、 Permission
オブジェクトも標準的なデータアクセスのメソッドが使えます。
Group
モデル¶
- class models.Group¶
フィールド¶
Group
オブジェクトには以下のフィールドがあります:
- class models.Group
- name¶
必須。150文字以下。任意の文字が使用可能。例:
'Awesome Users'
。
- permissions¶
Permission
への多対多のフィールドです:group.permissions.set([permission_list]) group.permissions.add(permission, permission, ...) group.permissions.remove(permission, permission, ...) group.permissions.clear()
バリデータ (Validator)¶
- class validators.ASCIIUsernameValidator¶
ASCII 文字と数字、さらに
@
、.
、+
、-
、_
のみを許可するフィールドバリデータ。
- class validators.UnicodeUsernameValidator¶
Unicode 文字を許可するフィールドバリデータで、
@
、.
、+
、-
、_
に加えて指定された文字も許可します。User.username
のデフォルトのバリデータです。
ログインとログアウトのシグナル¶
認証フレームワークは、ユーザーがログインやログアウトをしたときの通知に使うことができる、以下の シグナル を使用します。
- user_logged_in¶
ユーザがログインに成功したときに送信されます。
このシグナルとともに送信される引数は以下の通りです:
sender
たった今ログインしたユーザのクラスです。
request
現在の
HttpRequest
インスタンスです。user
たった今ログインしたユーザのインスタンスです。
- user_logged_out¶
logout メソッドが呼ばれたときに送信されます。
sender
上記の通り: たった今ログアウトしたユーザのクラス、もしくはユーザが認証されなかった場合は
None
となります。request
現在の
HttpRequest
インスタンスです。user
たった今ログアウトしたユーザのインスタンスか、ユーザが認証されなかった場合は
None
です。
- user_login_failed¶
ユーザがログインに失敗したときに送信されます。
sender
認証のために使われるモジュールの名前です。
credentials
authenticate()
か独自の認証バックエンドに渡されたユーザ資格情報を含む、キーワード引数のディクショナリです。'sensitive' パターンのセットに一致する (パスワードを含んだ) 資格情報は、シグナルの一部として明確には送信されません。request
authenticate()
に提供されている場合、HttpRequest
オブジェクト。
認証のバックエンド¶
このセクションでは、Django に付属する認証バックエンドについて詳しく説明します。 使用方法と独自の認証バックエンドの作成方法については、ユーザ認証ガイド の 他の認証ソースのセクション を参照してください。
利用可能な認証バックエンド¶
以下のバックエンドが django.contrib.auth.backends
内で利用可能です:
- class BaseBackend[ソース]¶
すべての必須メソッドのデフォルト実装を提供する基底クラス。デフォルトでは、ユーザーを拒否し、パーミッションを提供しません。
- get_all_permissions(user_obj, obj=None)[ソース]¶
user_obj
が持つ権限文字列のセットを取得するには、get_user_permissions()
およびget_group_permissions()
を使用します。
- has_perm(user_obj, perm, obj=None)[ソース]¶
user_obj
が権限文字列perm
を持っているかどうかを確認するには、get_all_permissions()
メソッドを使用します。
- class ModelBackend[ソース]¶
これは Django が使うデフォルトの認証バックエンドです。ユーザ識別子とパスワードからなる認証情報を使って認証します。Django のデフォルトのユーザモデルでは、ユーザ識別子はユーザ名で、カスタムユーザモデルでは USERNAME_FIELD で指定されたフィールドです (ユーザと認証のカスタマイズ を参照してください)。
また、
User
とPermissionsMixin
で定義されているデフォルトのパーミッションモデルも扱います。has_perm()
、get_all_permissions()
、get_user_permissions()
、 およびget_group_permissions()
メソッドは、特定のオブジェクトの権限を扱うためにオブジェクトをパラメータとして受け取ることができますが、このバックエンドは、obj is not None
の場合に、権限の空セットを返す以外は実装されていません。with_perm()
もオブジェクトを引数として渡すことができますが、他のメソッドと異なり、obj is not None
の場合は空のクエリセットを返します。- authenticate(request, username=None, password=None, **kwargs)[ソース]¶
username
とpassword
を用いて、User.check_password
を呼び出すことで認証を試みます。もしusername
が指定されていない場合、CustomUser.USERNAME_FIELD
キーを使用してkwargs
からユーザー名を取得しようとします。認証されたユーザーを返すか、None
を返します。request
はHttpRequest
で、authenticate()
が提供されていない場合None
となる可能性があります。(バックエンドでこれを通過するため).
- get_user_permissions(user_obj, obj=None)[ソース]¶
user_obj
が持つユーザー権限から許可文字列のセットを返します。is_anonymous
またはis_active
がFalse
の場合は空のセットが返されます。
- get_group_permissions(user_obj, obj=None)[ソース]¶
ユーザーが所属するグループの権限から
user_obj
が持つ権限文字列のセットを返します。もしis_anonymous
やis_active
がFalse
の場合は空のセットを返します。
- get_all_permissions(user_obj, obj=None)[ソース]¶
user_obj
が持つユーザーパーミッションとグループパーミッションを含むパーミッション文字列のセットを返します。もしis_anonymous
またはis_active
がFalse
の場合は空のセットを返します。
- has_perm(user_obj, perm, obj=None)[ソース]¶
user_obj
が権限文字列perm
を持っているかをチェックするには、get_all_permissions()
を使用します。user_obj
がis_active
でない場合は、False
を返します。
- user_can_authenticate()[ソース]¶
ユーザーが認証を許可されているかどうかを返します。
非アクティブなユーザーのログインを禁止する
AuthenticationForm
の動作に合わせるため、このメソッドはis_active=False
を持つユーザーに対してFalse
を返します。is_active
フィールドを持たないカスタムユーザーモデルは許可されます。
- with_perm(perm, is_active=True, include_superusers=True, obj=None)[ソース]¶
パーミッション
perm
を持つ全てのアクティブユーザを"<app label>.<permission codename>"
形式、またはPermission
インスタンスで返します。もしperm
を持つユーザが見つからなかった場合、空のクエリセットを返します。is_active
がTrue
(デフォルト) の場合、アクティブなユーザーのみを返し、False
の場合、非アクティブなユーザーのみを返します。アクティブ状態に関わらずすべてのユーザーを返すにはNone
を使用してください。include_superusers
がTrue
(デフォルト) の場合、結果にはスーパーユーザーが含まれます。
- class AllowAllUsersModelBackend[ソース]¶
ModelBackend
と同様ですが、user_can_authenticate()
は常にTrue
を返すため、非アクティブなユーザーを拒否しません。このバックエンドを使用する際は、おそらく、
LoginView
で使用されるAuthenticationForm
クラスをカスタマイズしたいと思うでしょう。非アクティブなユーザーを拒否するconfirm_login_allowed()
メソッドをオーバーライドすることが推奨されます。
- class RemoteUserBackend[ソース]¶
このバックエンドを使用して、Django 以外で処理される外部認証を利用します。これは、
request.META['REMOTE_USER']
に渡されたユーザ名を使用して認証を行います。詳細は、 REMOTE_USER を使った認証方法 のドキュメントを参照してください。もしより細かな制御が必要な場合は、このクラスを継承した独自の認証バックエンドを作成し、これらの属性やメソッドをオーバーライドできます。
- create_unknown_user¶
True
またはFalse
。データベースにユーザーオブジェクトが存在しない場合に、作成するかどうかを決定します。 デフォルトはTrue
です。
- authenticate(request, remote_user)[ソース]¶
渡された
remote_user
というユーザー名は信頼されたものとして扱われます。このメソッドは、指定されたユーザー名のユーザーオブジェクトを返し、create_unknown_user
がTrue
の場合は新しいユーザーオブジェクトを作成します。create_unknown_user
がFalse
であり、指定されたユーザー名のUser
オブジェクトがデータベースに見つからない場合、None
を返します。request
はHttpRequest
で、authenticate()
が提供されていない場合None
となる可能性があります。(バックエンドでこれを通過するため).
- clean_username(username)[ソース]¶
ユーザー名の使用前に (LDAP DN 情報を取り除くなど)
username
に対して任意のクリーニングを実行します。クリーニングされたユーザー名を返します。
- configure_user(request, user, created=True)[ソース]¶
認証を試みるたびにユーザを設定します。このメソッドは、認証対象のユーザを取得または作成した直後にコールされ、 LDAP ディレクトリの属性に基づいてユーザのグループを設定するなどのカスタム設定アクションを実行するために使用できます。ユーザオブジェクトを返します。
この設定は、リモートとローカルのシステム間で属性を同期させる方法として、ユーザーの作成時に一度だけ実行することもできますし (
created
はTrue
)、既存のユーザーに対して実行することもできます (created
はFalse
)。request
はHttpRequest
で、authenticate()
が提供されていない場合None
となる可能性があります。(バックエンドでこれを通過するため).
- user_can_authenticate()¶
ユーザが認証を許可されているかどうかを返します。このメソッドは
is_active=False
を持つユーザに対してFalse
を返します。is_active
フィールドを持たないカスタムユーザモデルは許可されます。
- class AllowAllUsersRemoteUserBackend[ソース]¶
RemoteUserBackend
と同じですが、user_can_authenticate
は常にTrue
を返すため、非アクティブなユーザを拒否しない点が異なります。
ユーティリティ関数¶
- aget_user(request)¶
非同期バージョン:
aget_user()
与えられた
request
のセッションに関連付けられたユーザモデルのインスタンスを返します。セッションに保存されている認証バックエンドが
AUTHENTICATION_BACKENDS
に存在するかどうかをチェックします。もし存在すれば、バックエンドのget_user()
メソッドを使ってユーザーモデルのインスタンスを取得し、ユーザーモデルのget_session_auth_hash()
メソッドを呼び出してセッションを検証します。検証に失敗し、SECRET_KEY_FALLBACKS
が指定された場合、get_session_auth_fallback_hash()
メソッドを使用して各フォールバックキーに対してセッションを検証します。セッションに保存されている認証バックエンドが
AUTHENTICATION_BACKENDS
にない場合、バックエンドのget_user()
メソッドでユーザが返されない場合、またはセッションの認証ハッシュが検証されない場合、AnonymousUser
のインスタンスを返します。Changed in Django 5.0:aget_user()
関数が追加されました。