# Django 5.0.9.dev20240806133106 ドキュメント

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

    ユーザにパスワードが設定されていないものとしてマークします。これは、パスワードに空の文字列を付けることと同じではありません。ユーザに対する `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()` が呼び出されます。

    `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 4.1.8:

  `SECRET_KEY_FALLBACKS` を使用したフォールバックの検証が追加されました。

  Changed in Django 5.0:

  `aget_user()` 関数が追加されました。