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

必須。パスワードのハッシュとメタデータです。（Djangoは生のパスワードを保存しません。）生のパスワードは任意の長さにでき、任意の文字を含むことができます。このフィールドのメタデータは、パスワードが使用不可であることを示すことがあります。詳細については、パスワードに関するドキュメント を参照してください。

groups

Group への多対多のリレーションシップです。

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()

ユーザーのパスワードが設定されていないことを示すために、password フィールドのメタデータを更新します。これは、パスワードが空の文字列であることとは異なります。このユーザーに対して check_password() を呼び出しても、決して True を返しません。このメソッドは User オブジェクトを保存しません。

アプリケーションの認証が 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() が呼び出されます。

If no email is provided, email will be set to an empty string.

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 オブジェクトには以下のフィールドがあります:

class models.Permission

name

必須です。255 文字以下です。例: 'Can vote'。

content_type

必須です。django_content_type データベーステーブルへの参照で、インストールされた各モデルのレコードを含みます。

codename

必須です。100 文字以下です。例: 'can_vote'。

メソッド

他のあらゆる 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_user_permissions(user_obj, obj=None)[ソース]

空の集合を返します。

get_group_permissions(user_obj, obj=None)[ソース]

空の集合を返します。

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 を返します。

has_module_perms(user_obj, app_label)[ソース]

user_obj がアプリ app_label に対して権限を持っているかどうかを返します。

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 を返すため、非アクティブなユーザを拒否しない点が異なります。

ユーティリティ関数

get_user(request)[ソース]

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() 関数が追加されました。