# Django 5.2.8 ドキュメント

# `django.contrib.auth`

このドキュメントでは、Django の 認証システムのコンポーネントの API リファレンス資料を提供しています。 これらのコンポーネントの使い方や、認証と認可をカスタマイズする方法の詳細は、認証トピックガイド を参照してください。

## `User` モデル

class models.User

### フィールド

class models.User

  `User` オブジェクトには、以下のフィールドがあります:

  username

    必須です。150 文字以下です。英数字のほか、`_`、`@`、`+`、`.`、`-` が使えます。

    大半のユースケースでは、`max_length` の設定で十分対応できます。より長い長さが必要な場合は、カスタムユーザーモデル を使用してください。

  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` は保存しません。

    When the `raw_password` is `None`, the password will be set to an unusable password, as if `set_unusable_password()` were used.

  check_password(raw_password)
  acheck_password(raw_password)

    非同期バージョン: `acheck_password()`

    与えられた生の文字列が、ユーザに対して正しいパスワードであれば `True` を返します。 (比較する際にはパスワードハッシュを処理します。)

  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 return `True`. Doesn't save the `User` object.

    アプリケーションの認証が LDAP ディレクトリなどの既存の外部ソースに対して行われている場合は、これが必要になることがあります。

    パスワードリセットの制限

    使用できないパスワードを持つユーザーは、 `PasswordResetView` を通じてパスワードリセットのメールをリクエストすることができません。

  has_usable_password()

    Returns `False` if `set_unusable_password()` has been called for this user.

  get_user_permissions(obj=None)
  aget_user_permissions(obj=None)

    非同期バージョン: `aget_user_permissions()`

    ユーザーが直接持っているパーミッション文字列のセットを返します。

    もし `obj` が渡された場合、この特定のオブジェクトのユーザパーミッションのみを返します。

    Changed in Django 5.2:

    `aget_user_permissions()` メソッドが追加されました。

  get_group_permissions(obj=None)
  aget_group_permissions(obj=None)

    非同期バージョン: `aget_group_permissions()`

    ユーザがグループを通して持つパーミッションの文字列のセットを返します。

    `obj` が渡されたとき、指定されたオブジェクトに対するグループパーミッションのみを返します。

    Changed in Django 5.2:

    `aget_group_permissions()` メソッドが追加されました。

  get_all_permissions(obj=None)
  aget_all_permissions(obj=None)

    非同期バージョン: `aget_all_permissions()`

    ユーザがグループおよびユーザパーミッションを通して持つパーミッションの文字列のセットを返します。

    `obj` が渡された場合、指定されたオブジェクトに対するパーミッションのみを返します。

    Changed in Django 5.2:

    `aget_all_permissions()` メソッドが追加されました。

  has_perm(perm, obj=None)
  ahas_perm(perm, obj=None)

    非同期バージョン: `ahas_perm()`

    perm が `"<app label>.<permission codename>"` という形式で、ユーザーが特定の権限を持っている場合、`True` を返します (詳しくは パーミッション のドキュメントを参照)。もしユーザーが非アクティブの場合、このメソッドは常に `False` を返します。アクティブなスーパーユーザーの場合、このメソッドは常に `True` を返します。

    `obj` が渡された場合、このメソッドは指定されたオブジェクトに対してパーミッションのチェックを行い、モデルに対しては行いません。

    Changed in Django 5.2:

    `ahas_perm()` メソッドが追加されました。

  has_perms(perm_list, obj=None)
  ahas_perms(perm_list, obj=None)

    非同期バージョン: `ahas_perms()`

    指定された権限を持つかどうかを判定し、持つ場合は `True` を返します。各 perm は `"<app label>.<permission codename>"` の形式です。ユーザーが非アクティブの場合、このメソッドは常に `False` を返します。アクティブなスーパーユーザーの場合、このメソッドは常に `True` を返します。

    `obj` が渡された場合、このメソッドは指定されたオブジェクトに対してパーミッションのチェックを行い、モデルに対しては行いません。

    Changed in Django 5.2:

    `ahas_perms()` メソッドが追加されました。

  has_module_perms(package_name)
  ahas_module_perms(package_name)

    非同期バージョン: `ahas_module_perms()`

    与えられたパッケージ (Djangoアプリのラベル) 内でユーザーが何らかの権限を持っている場合、`True` を返します。ユーザーが非アクティブな場合、このメソッドは常に `False` を返します。アクティブなスーパーユーザーの場合、このメソッドは常に `True` を返します。

    Changed in Django 5.2:

    `ahas_module_perms()` メソッドが追加されました。

  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)
  acreate_user(username, email=None, password=None, **extra_fields)

    非同期バージョン: `acreate_user()`

    `User` を作成、保存して返します。

    `username` と `password` は指定された通りに設定されます。 `email` のドメイン部分は自動的に小文字に変換され、返される `User` オブジェクトには `is_active` が `True` に設定されます。

    If no password is provided, `set_unusable_password()` will be called.

    Eメールが指定されない場合、 `email` は空文字列に設定されます。

    `extra_fields` キーワード引数は、`User` クラスの `__init__` メソッドに渡され、カスタムユーザーモデル に任意のフィールドを設定することを可能にします。

    使用例については ユーザーの作成 を参照してください。

    Changed in Django 5.2:

    `acreate_user()` メソッドが追加されました。

  create_superuser(username, email=None, password=None, **extra_fields)
  acreate_superuser(username, email=None, password=None, **extra_fields)

    非同期バージョン: `acreate_superuser()`

    `create_user()` と同じですが、`is_staff` と `is_superuser` を `True` にセットします。

    Changed in Django 5.2:

    `acreate_superuser()` メソッドが追加されました。

  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()` always returns the empty string.

  - `is_anonymous` が `False` ではなく `True` です。

  - `is_authenticated` が `False` ではなく `True` です。

  - `is_staff` と `is_superuser` が常に `False` です。

  - `is_active` が常に `False` です。

  - `groups` と `user_permissions` が常に空です。

  - `set_password()`, `check_password()`, `save()` and `delete()` raise `NotImplementedError`.

実際には `AnonymousUser` オブジェクトを使う必要はないでしょうが、次のセクションで説明するように、Web リクエストで使用されます。

## `Permission` モデル

class models.Permission

### フィールド

`Permission` オブジェクトには以下のフィールドがあります:

class models.Permission
  name

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

  content_type

    必須です。 `ContentType` モデルを参照する外部キーです。

  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`

    A dictionary of keyword arguments containing the user credentials that were passed to `authenticate()` or your own custom authentication backend. Credentials matching a set of 'sensitive' patterns (including password) will not be sent in the clear as part of the signal.

  `request`

    `authenticate()` に提供されている場合、 `HttpRequest` オブジェクト。

## 認証のバックエンド

このセクションでは、Django に付属する認証バックエンドについて詳しく説明します。 使用方法と独自の認証バックエンドの作成方法については、ユーザ認証ガイド の 他の認証ソースのセクション を参照してください。

### 利用可能な認証バックエンド

以下のバックエンドが `django.contrib.auth.backends` 内で利用可能です:

class BaseBackend

  すべての必須メソッドのデフォルト実装を提供する基底クラス。デフォルトでは、ユーザーを拒否し、パーミッションを提供しません。

  get_user_permissions(user_obj, obj=None)
  aget_user_permissions(user_obj, obj=None)

    非同期バージョン: `aget_user_permissions()`

    空の集合を返します。

    Changed in Django 5.2:

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

  get_group_permissions(user_obj, obj=None)
  aget_group_permissions(user_obj, obj=None)

    非同期バージョン: `aget_group_permissions()`

    空の集合を返します。

    Changed in Django 5.2:

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

  get_all_permissions(user_obj, obj=None)
  aget_all_permissions(user_obj, obj=None)

    非同期バージョン: `aget_all_permissions()`

    `user_obj` が持つ権限文字列のセットを取得するには、 `get_user_permissions()` および `get_group_permissions()` を使用します。

    Changed in Django 5.2:

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

  has_perm(user_obj, perm, obj=None)
  ahas_perm(user_obj, perm, obj=None)

    非同期バージョン: `ahas_perm()`

    `user_obj` が権限文字列 `perm` を持っているかどうかを確認するには、 `get_all_permissions()` メソッドを使用します。

    Changed in Django 5.2:

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

class ModelBackend

  This is the default authentication backend used by Django. It authenticates using credentials consisting of a user identifier and password. For Django's default user model, the user identifier is the username, for custom user models it is the field specified by USERNAME_FIELD (see Customizing Users and authentication).

  また、 `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)
  aauthenticate(request, username=None, password=None, **kwargs)

    非同期バージョン: `aauthenticate()`

    `username` と `password` を用いて、 `User.check_password` を呼び出すことで認証を試みます。もし `username` が指定されていない場合、 `CustomUser.USERNAME_FIELD` キーを使用して `kwargs` からユーザー名を取得しようとします。認証されたユーザーを返すか、`None` を返します。

    `request` は `HttpRequest` で、 `authenticate()` が提供されていない場合 `None` となる可能性があります。(バックエンドでこれを通過するため).

    Changed in Django 5.2:

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

  get_user_permissions(user_obj, obj=None)
  aget_user_permissions(user_obj, obj=None)

    非同期バージョン: `aget_user_permissions()`

    `user_obj` が持つユーザー権限から許可文字列のセットを返します。 `is_anonymous` または `is_active` が `False` の場合は空のセットが返されます。

    Changed in Django 5.2:

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

  get_group_permissions(user_obj, obj=None)
  aget_group_permissions(user_obj, obj=None)

    非同期バージョン: `aget_group_permissions()`

    ユーザーが所属するグループの権限から `user_obj` が持つ権限文字列のセットを返します。もし `is_anonymous` や `is_active` が `False` の場合は空のセットを返します。

    Changed in Django 5.2:

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

  get_all_permissions(user_obj, obj=None)
  aget_all_permissions(user_obj, obj=None)

    非同期バージョン: `aget_all_permissions()`

    `user_obj` が持つユーザーパーミッションとグループパーミッションを含むパーミッション文字列のセットを返します。もし `is_anonymous` または `is_active` が `False` の場合は空のセットを返します。

    Changed in Django 5.2:

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

  has_perm(user_obj, perm, obj=None)
  ahas_perm(user_obj, perm, obj=None)

    非同期バージョン: `ahas_perm()`

    `user_obj` が権限文字列 `perm` を持っているかをチェックするには、`get_all_permissions()` を使用します。 `user_obj` が `is_active` でない場合は、 `False` を返します。

    Changed in Django 5.2:

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

  has_module_perms(user_obj, app_label)
  ahas_module_perms(user_obj, app_label)

    非同期バージョン: `ahas_module_perms()`

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

    Changed in Django 5.2:

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

  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

  Use this backend to take advantage of external-to-Django-handled authentication. It authenticates using usernames passed in `request.META['REMOTE_USER']`. See the Authenticating against REMOTE_USER documentation.

  もしより細かな制御が必要な場合は、このクラスを継承した独自の認証バックエンドを作成し、これらの属性やメソッドをオーバーライドできます。

  create_unknown_user

    `True` または `False` 。データベースにユーザーオブジェクトが存在しない場合に、作成するかどうかを決定します。 デフォルトは `True` です。

  authenticate(request, remote_user)
  aauthenticate(request, remote_user)

    非同期バージョン: `aauthenticate()`

    渡された `remote_user` というユーザー名は信頼されたものとして扱われます。このメソッドは、指定されたユーザー名のユーザーオブジェクトを返し、`create_unknown_user` が `True` の場合は新しいユーザーオブジェクトを作成します。

    `create_unknown_user` が `False` であり、指定されたユーザー名の `User` オブジェクトがデータベースに見つからない場合、`None` を返します。

    `request` は `HttpRequest` で、 `authenticate()` が提供されていない場合 `None` となる可能性があります。(バックエンドでこれを通過するため).

    Changed in Django 5.2:

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

  clean_username(username)

    ユーザー名の使用前に (LDAP DN 情報を取り除くなど) `username` に対して任意のクリーニングを実行します。クリーニングされたユーザー名を返します。

  configure_user(request, user, created=True)
  aconfigure_user(request, user, created=True)

    非同期バージョン: `aconfigure_user()`

    認証のたびにユーザーを設定します。このメソッドは、認証対象のユーザーを取得または作成した直後に呼び出され、たとえば LDAP ディレクトリ内の属性に基づいてユーザーのグループを設定するなどの、カスタムの初期設定アクションを実行するために使用できます。ユーザーオブジェクトを返します。ユーザーの取得または作成が同期コンテキストで行われた場合は `configure_user` が、非同期コンテキストで行われた場合は `aconfigure_user` が呼び出されます。

    この設定は、リモートとローカルのシステム間で属性を同期させる方法として、ユーザーの作成時に一度だけ実行することもできますし (`created` は `True`)、既存のユーザーに対して実行することもできます (`created` は `False`)。

    `request` は `HttpRequest` で、 `authenticate()` が提供されていない場合 `None` となる可能性があります。(バックエンドでこれを通過するため).

    Changed in Django 5.2:

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

  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` のインスタンスを返します。