# Django 6.0.7 ドキュメント

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

    `raw_password` が `None` のとき、`set_unusable_password(()` が使われるのと同じように、パスワードは使用に適さないパスワードになります。

  check_password(raw_password)
  acheck_password(raw_password)

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

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

  set_unusable_password()

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

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

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

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

  has_usable_password()

    ユーザに対して `set_unusable_password()` が呼ばれている場合、`False` を返します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  has_module_perms(package_name)
  ahas_module_perms(package_name)

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

    与えられたパッケージ (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)
  acreate_user(username, email=None, password=None, **extra_fields)

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

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

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

    パスワードが指定されなかった場合、 `set_unusable_password()` が呼び出されます。

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

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

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

  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` にセットします。

  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

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

  codename

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

### メソッド

他のあらゆる Django モデル と同じように、 `Permission` オブジェクトも標準的なデータアクセスのメソッドが使えます。

class models.Permission
  user_perm_str
    New in Django 6.1.

    Returns the string representation for use in `has_perm`.

## `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)
  aget_user_permissions(user_obj, obj=None)

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

    空の集合を返します。

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

    非同期バージョン: `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()` を使用します。

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

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

    `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()` also allows an object to be passed as a parameter, but unlike other methods it returns an empty queryset if `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` となる可能性があります。(バックエンドでこれを通過するため).

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

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

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

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

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

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

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

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

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

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

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

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

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

  user_can_authenticate()

    Returns whether the user is allowed to authenticate. To match the behavior of `AuthenticationForm.confirm_login_allowed()`, this method returns `False` for users with `is_active=False`. Custom user models that don't have an `is_active` field are allowed.

  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)
  aauthenticate(request, remote_user)

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

    渡された `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)
  aconfigure_user(request, user, created=True)

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

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

    この設定は、リモートとローカルのシステム間で属性を同期させる方法として、ユーザーの作成時に一度だけ実行することもできますし (`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` のインスタンスを返します。