API リファレンス¶

基本的な使い方¶

>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
>>>
# この操作で、User オブジェクト user を保存できるようになります。
# 他のフィールドを変更したければ、属性を変更します。
>>> user.is_staff = True
>>> user.save()

>>> from django.contrib.auth.models import User
>>> u = User.objects.get(username__exact='john')
>>> u.set_password('new password')
>>> u.save()

パスワード¶

User オブジェクトの password フィールドは、以下の形式:

hashtype$salt$hash

すなわちハッシュ方式 (hashtype)、ハッシュソルト (salt)、そしてハッシュ値 (hash) をドル記号 ("$") で分割した文字列形式をとります。

ハッシュ形式は sha1 (デフォルト) または md5 、 crypt のいずれか で、それぞれパスワードの一方向ハッシュ化アルゴリズムを表します。 salt は生 のパスワード文字列からハッシュを生成するときに味付け (salt) しておくための ランダムな文字列です。 crypt のサポートは、 Python の標準モジュール crypt がサポートされている環境だけで有効です。また、 crypt のサポー トは開発版の Django でのみ利用できます。

例えば:

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

User.set_password() および User.check_password() set_password() および関数は、これら の値の設定やチェックを背後で行っています。

バージョン 0.90 のような以前の Django では、パスワードソルトなしの単純な MD5 ハッシュを使っていました。この形式は、以前のバージョンとの互換性を持た せるためにまだサポートしています。ただし、古いパスワードのユーザに対する check_password() が成功すると、パ スワードは自動的に新しい形式に変換されます。

匿名ユーザ (Anonymous users)¶

class models.AnonymousUser¶

django.contrib.auth.models.AnonymousUser は django.contrib.auth.models.User と同じインタフェースを実装した クラスですが、以下の点で User と異 なります:

• id は常に None です。
• is_staff および is_superuser は常に False です。
• is_active は常に False です。
• groups および user_permissions は常に空で す。
• is_anonymous() は False でなく True を返します。
• is_authenticated() は True でなく False を返します。
• has_perm() は常に False を返します。
• set_password(), check_password(), save(), delete(), set_groups() および set_permissions() は NotImplementedError を送出します。

おそらく、実践上意識して AnonymousUser オブジェクトを使う必要はないはずです。とはいえ、匿名ユーザは次節で述べるよ うな形で Web リクエストで使われています。

スーパユーザの作成¶

INSTALLED_APPS に 'django.contrib.auth' を追加した直後に manage.py syncdb を実行すると、スーパユーザの作成を促す プロンプトを表示します。後でスーパユーザを作成したい場合には、以下のように コマンドラインユーティリティを使います。

manage.py createsuperuser --username=joe --email=joe@example.com

ユーティリティはパスワードの入力を促します。入力すると、ユーザは即座に作成 されます。 --username や --email オプションを省 略すると、ユーティリティはそれらの値を入力するよう促します。

古い Django も使っている場合、以前からあるコマンドラインのスーパユーザ作成 方法も使えます:

python /path/to/django/contrib/auth/create_superuser.py

/path/to/ は自分のシステムの Django コードベースへのパスに応じて読 み変えて下さい。 manage.py は自動的に正しいパスと環境変数を決定するので、 manage.py を使うよう推奨します。

追加のユーザ情報の保存¶

ユーザに追加の情報をひもづけて保存したい場合のために、 Django ではサイトご とにユーザに関連付けられた「ユーザプロファイル」を取り出すためのメソッドを 提供しています。

ユーザプロファイルを利用するには、まず、ユーザにひもづけて保存したい情報を 入れるためのフィールドや持たせたいメソッド、そして User モデルへの ForeignKey を持ったモデルを定義します。 ForeignKey には unique=True をセットし、 ユーザごとにモデルが一つだけ生成されるようにします。

このモデルをあるサイトのユーザプロファイルモデルにするには、 AUTH_PROFILE_MODULE に以下の内容をドット区切りの文字列で指定しま す:

1. ユーザプロファイルモデルを定義している (小文字に変換した) アプリケーショ ン名 (別の言い方をするなら、 manage.py startapp で アプリケーションを作成するときに指定する名前を全て小文字にしたもの)。
2. (小文字に変換した) モデルクラス名

例えば、プロファイルモデルが UserProfile という名前のクラスで、 accounts というアプリケーションで定義されているなら、設定値は以下のよう になるでしょう:

AUTH_PROFILE_MODULE = 'accounts.userprofile'

上記の方法でユーザプロファイルモデルを定義して指定すると、ユーザオブジェ クトには get_profile() というメソッ ドが付加されます。このメソッドは、ユーザに関連付けられているプロファイルモ デルのインスタンスを返します。

さらに詳しい情報は、 Django book の 12 章 を参照してください。

ユーザをログインさせる¶

Django では、 django.contrib.auth の中で、 authenticate() と login() という二つの関数を提供しています。

authenticate()¶

あるユーザ名とパスワードに対する認証を行うには、 authenticate() を使ってください。この関数 は二つのキーワード引数、 username と password をとり、ユーザ名 に対してパスワードが有効であった場合に User オブジェクトを返します。パス ワードが無効だった場合には、 authenticate() は None を返します。例 えば:

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    if user.is_active:
        print "You provided a correct username and password!"
    else:
        print "Your account has been disabled!"
else:
    print "Your username and password were incorrect."

login()¶

ユーザをログインさせるには、ビューの中で login() を使ってください。この関数は HttpRequest オブジェクトと User オブジェクトを引数にとります。 login() は Django のセッションフレームワー クを使って、ユーザの ID をセッションに保存します。従って、上でも述べた ように、セッションミドルウェアをインストールしておかねばなりません。

以下の例は authenticate() と login() の使い方を示しています:

from django.contrib.auth import authenticate, login

def my_view(request):
    username = request.POST['username']
    password = request.POST['password']
    user = authenticate(username=username, password=password)
    if user is not None:
        if user.is_active:
            login(request, user)
            # Redirect to a success page.
        else:
            # Return a 'disabled account' error message
    else:
        # Return an 'invalid login' error message.

ユーザのパスワードを手動で調べる¶

check_password()¶

ユーザ認証を手動で行うために平文パスワードとデータベース上のハッシュ化 パスワードを比較したい場合には、 django.contrib.auth.models.check_password() という便宜関数を使えます。この関数は、調べたい平文パスワードと、比較対 象のデータベースに格納されているユーザの password フィールド全体の 二つの引数をとり、二つが一致すれば True を、そうでなければ False を返します。

ユーザをログアウトさせる¶

logout()¶

django.contrib.auth.login() でログインしたユーザをログアウトさ せるには、ビューの中で django.contrib.auth.logout() を使ってください。この関数は、 HttpRequest オブジェクトを引数に取り、戻り値を持 ちません。例を以下に示します:

from django.contrib.auth import logout

def logout_view(request):
    logout(request)
    # Redirect to a success page.

ユーザがログインしていなくても logout() は エラーを送出しないことに注意してください。

Django 1.0 で変更されました: logout() を呼び出すとセッションデータを消去するようになりました。

logout() を呼び出すと、現在のリクエストに 結び付いたセッションデータを全て抹消します。その時に記憶されていたデー タは全て除去されます。これは、他のユーザが同じブラウザを使ってログイン し、直前にブラウザを使っていたユーザのセッションデータを読み出したりで きないようにするためです。ユーザのログアウト後に何らかのセッションデー タを記憶させたければ、 django.contrib.auth.logout() の 後で 行ってください。

ログインユーザだけがアクセスできるように制限をかける¶

from django.http import HttpResponseRedirect

def my_view(request):
    if not request.user.is_authenticated():
        return HttpResponseRedirect('/login/?next=%s' % request.path)
    # ...

def my_view(request):
    if not request.user.is_authenticated():
        return render_to_response('myapp/login_error.html')
    # ...

(r'^accounts/login/$', 'django.contrib.auth.views.login'),

その他の組み込みビュー¶

認証システムでは、 login ビューの他にも便利なビューをいくつか提供してい ます:

django.contrib.auth.views.logout()¶

ユーザをログアウトさせます。

オプション引数:

• template_name: ログアウトページのテンプレートの完全な名前です。 この引数を省略すると、デフォルト値の registration/logged_out.html を使います。

テンプレートコンテキスト:

• title: "Logged out" という文字列を翻訳した値になります。

django.contrib.auth.views.logout_then_login()¶

ユーザをログアウトさせてから、ログインページにリダイレクトします。

オプション引数:

• login_url: ログインページへのリダイレクト先です。この引数を省 略すると、デフォルト値の settings.LOGIN_URL を使います。

django.contrib.auth.views.password_change()¶

ユーザがパスワードを変更できるようにします。

オプション引数:

• template_name: パスワード変更ページのテンプレートの完全な名前 です。この引数を省略すると、デフォルト値の registration/password_change_form.html を使います。

テンプレートコンテキスト:

• form: パスワード変更のためのフォームです。

django.contrib.auth.views.password_change_done()¶

ユーザがパスワードを変更した後のページを表示するためのビューです。

オプション引数:

• template_name: パスワード変更完了ページのテンプレートの完全な 名前です。この引数を省略すると、デフォルト値の registration/password_change_done.html を使います。

django.contrib.auth.views.password_reset()¶

ユーザがパスワードをリセットできるようにします。また、新たなパスワード をメールで送信します。

オプション引数:

• template_name: パスワードリセットページのテンプレートの完全な 名前です。この引数を省略すると、デフォルト値の registration/password_reset_form.html を使います。
• email_template_name: 新しいパスワードを e-mail で送信する際に 使うテンプレートの完全な名前です。この引数を省略すると、デフォル ト値の registration/password_reset_email.html を使います。

テンプレートコンテキスト:

• form: パスワードリセットのためのフォームです。

django.contrib.auth.views.password_reset_done()¶

ユーザがパスワードをリセットした後のページを表示するためのビューです。

オプション引数:

• template_name: パスワードリセット完了ページのテンプレートの完 全な名前です。この引数を省略すると、デフォルト値の registration/password_reset_done.html を使います。

django.contrib.auth.views.redirect_to_login()¶

ログインページにリダイレクトし、ログインに成功したら別の URL に戻れるよ うにするためのビューです。

必須の引数:

• next: ログイン成功後のリダイレクト先 URL です。

オプション引数:

• login_url: ログインページへのリダイレクト先です。 この引数を省略すると、デフォルト値の settings.LOGIN_URL を使います。

組み込みフォーム¶

組み込みビューを使いたくないけれども、フォームクラスを書かずに済ませたい場 合のために、認証システムでは組み込みのフォームをいくつか提供しています:

• django.contrib.auth.forms.AdminPasswordChangeForm: Admin イ ンタフェースでユーザのパスワード変更に使われているフォームです。
• django.contrib.auth.forms.AuthenticationForm: ユーザをログイ ンさせるためのフォームです。
• django.contrib.auth.forms.PasswordChangeForm: ユーザにパスワー ドを変更させるためのフォームです。
• django.contrib.auth.forms.PasswordResetForm: パスワードをリ セットし、新たなパスワードを送信するためのフォームです。
• django.contrib.auth.forms.UserCreationForm: 新たなユーザを作 成するためのフォームです。

テストにパスしたログインユーザだけがアクセスできるように制限をかける¶

特定のパーミッションやその他のテストの結果に応じたアクセスの制限には、前節 で説明したの本質的に同じことをします。

一番簡単な方法は、ビュー内で直接 request.user に対するテストを実行す るというものです。例えば、以下のビューではユーザがログイン済みで、かつ polls.can_vote というパーミッションを持っているかチェックします:

def my_view(request):
    if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
        return HttpResponse("You can't vote in this poll.")
    # ...

decorators.user_passes_test()¶

user_passes_test デコレータを使えば、手間を省けます:

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)

ここでは、簡単な例としてパーミッションのテストに user_passes_test() を使っています が、単にあるユーザがあるパーミッションを有しているかをテストしたいだけ なら、後で解説する django.contrib.auth.decorators.permission_required() デコレータ を使えます。

Python 2.4 のデコレータ構文ならこうなります:

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.has_perm('polls.can_vote'))
def my_view(request):
    # ...

user_passes_test() には必須の引数 が一つあります。この引数は、 User を引数に取り、ユーザにページのビューを許可する場合には True を返す 呼び出し可能オブジェクトでなければなりません。 user_passes_test() は User が匿名かどうかを自動的に調べ ないので注意してください。

user_passes_test() はオプション の引数として login_url をとります。この引数を使うとログインページへ の URL を指定できます (デフォルトでは settings.LOGIN_URL になります)。

Python 2.3 風の構文で書いた例を示します:

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)

Python 2.4 風の構文で例を書くと以下のようになります:

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')
def my_view(request):
    # ...

アクセスを汎用ビューに制限する¶

アクセスを 汎用ビュー に制限するには、ビューを 囲む薄いラッパコードを書き、URLconf を変更して、ジェネリックビュー自体では なくラッパコードを指すようにします。例えば:

from django.views.generic.date_based import object_detail

@login_required
def limited_object_detail(*args, **kwargs):
    return object_detail(*args, **kwargs)

デフォルトのパーミッション¶

INSTALLED_APPS 設定に django.contrib.auth を追加している場合、 インストールされている全てのアプリケーションのモデルについて、追加 (add)、 変更 (change)、および削除 (delete) というデフォルトのパーミッションが作成さ れます。

これらのパーミッションは、 manage.py syncdb を実行した ときに生成されます。厳密には、 django.contrib.auth を INSTALLED_APPS 設定に追加した直後に syncdb を実行する と、その時インストールされていた全てのアプリケーションと、新たに追加したア プリケーションのデフォルトパーミッションが作成されます。以後、 manage.py syncdb を実行するたびに、新たに追加されたモデ ルのデフォルトパーミッションが生成されます。

カスタムのパーミッション¶

カスタムのパーミッションを生成するには、 permissions という モデルのメタ属性 を使います。

この例では、三つのカスタムパーミッションを生成しています:

class USCitizen(models.Model):
    # ...
    class Meta:
        permissions = (
            ("can_drive", "Can drive"),
            ("can_vote", "Can vote in elections"),
            ("can_drink", "Can drink alcohol"),
        )

この定義の役割は、 manage.py syncdb を実行したときに追 加のパーミッションを追加することだけです。

API リファレンス¶

class models.Permission¶

ユーザと同様、パーミッションは Django モデルとして実装されています。実 装は django/contrib/auth/models.py にあります。

ユーザ¶

現在のログインユーザは、 User インスタ ンスであっても AnonymousUser インスタ ンスであっても、テンプレート変数 {{ user }} に入ります:

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

パーミッション¶

現在のログインユーザのパーミッションはテンプレート変数 {{ perms }} に入っ ています。この変数はパーミッションオブジェクトをテンプレートで扱いやすくす るためのプロキシ (proxy) である、 django.core.context_processors.PermWrapper のインスタンスです。

{{ perms }} オブジェクトに対して 1 段の属性参照を行うと、実際には User.has_module_perms へのプロキシになっています。例えば下記の例は、ログインユーザが foo とい うアプリケーションへのパーミッションを持っている場合に True を表示しま す:

{{ perms.foo }}

2 段階属性を参照すると、 User.has_perm へのプロキ シに到達します。以下の例では、ログインユーザが foo.can_vote へのパーミッ ションを持つ場合に True を表示します:

{{ perms.foo.can_vote }}

こうして、テンプレート内で {% if %} 文を使ってチェックを行えます:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.can_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

他の認証バックエンドを指定する¶

舞台裏では、 Django は認証に使う「認証バックエンド」のリストを維持していま す。前述の「ユーザをログインさせる」で説明したように django.contrib.auth.authenticate() を呼び出すと、Django は全ての認 証バックエンドにわたって認証テストを試みます。最初の認証メソッドに失敗する と次の認証バックエンド、という具合にして、認証に成功しない限り、全てのバッ クエンドを試すまで続けます。

認証に使うバックエンドのリストは AUTHENTICATION_BACKENDS 設定に 指定します。この値は Python モジュールパス名からなるタプルで、認証方法を実 装したクラスの名前を指定します。認証クラスは Python パス上のどこにあっても かまいません。

デフォルトでは、 AUTHENTICATION_BACKENDS の値は:

('django.contrib.auth.backends.ModelBackend',)

に設定されています。このクラスは、 Django のユーザデータベースをチェックす る認証スキームです。

AUTHENTICATION_BACKENDS の順番には意味があり、同じユーザ名とパス ワードが複数のバックエンドで有効な値であったとしても、 Django は最初にユー ザ名とパスワードがマッチした時点で認証処理を停止します。

認証バックエンドを作成する¶

認証バックエンドの実体は、 get_user(user_id) と authenticate(**credentials) という二つのメソッドを実装したクラスです。

get_user メソッドはユーザ名、データベース ID などを表す引数 user_id をとり、対応する User オブジェクトを返します。

authenticate メソッドは証明情報、すなわちユーザ名とパスワードなどをキー ワード引数の形で受け取ります。ほとんどの場合、以下のような形式をとります:

class MyBackend:
    def authenticate(self, username=None, password=None):
        # Check the username/password and return a User.

以下のようにトークンに対する認証を行うようにも書けます:

class MyBackend:
    def authenticate(self, token=None):
        # Check the token and return a User.

どちらの方法でも、 authenticate は受け取った証明情報をチェックし、証明 情報が有効な場合、対応する User オブジェクトを返さねばなりません。証明 情報が無効なら、 None を返します。

Django の admin システムは、冒頭で説明した Django の User オブジェクト と強くカップリングしています。従って、今のところ自作の認証バックエンドを扱 うには、 (LDAP ディレクトリや外部の SQL データベースなどのような) 別のバッ クエンド上のユーザに対して Django の User オブジェクトを生成するのがベ ストです。あらかじめスクリプトを書いておいてもよいですし、ユーザが最初にロ グインした際に、 authenticate メソッドでその処理を行うようにしてもよい でしょう。

以下に示すバックエンドの例では、 settings.py ファイルに定義されたユーザ 名とパスワードに対して認証を行い、ユーザが最初に認証を行ったときに User オブジェクトを生成します:

from django.conf import settings
from django.contrib.auth.models import User, check_password

class SettingsBackend:
    """
    Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.

    Use the login name, and a hash of the password. For example:

    ADMIN_LOGIN = 'admin'
    ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
    """
    def authenticate(self, username=None, password=None):
        login_valid = (settings.ADMIN_LOGIN == username)
        pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
        if login_valid and pwd_valid:
            try:
                user = User.objects.get(username=username)
            except User.DoesNotExist:
                # Create a new user. Note that we can set password
                # to anything, because it won't be checked; the password
                # from settings.py will.
                user = User(username=username, password='get from settings.py')
                user.is_staff = True
                user.is_superuser = True
                user.save()
            return user
        return None

    def get_user(self, user_id):
        try:
            return User.objects.get(pk=user_id)
        except User.DoesNotExist:
            return None

カスタムのバックエンドでパーミッションを扱う¶

カスタムの認証バックエンドから、独自のパーミッションを提供できます。

認証バックエンドがパーミッション照会のための関数 (get_group_permissions(), get_all_permissions(), has_perm(), および has_module_perms()) をサポートして いる場合、ユーザモデルはパーミッションの照会をバックエンドに移譲します。

あるユーザに付与されるパーミッションの集合は、全てのバックエンドの返しうる パーミッションのスーパーセットです。すなわち、 Django はいずれかのバックエ ンドのパーミッションを、どのユーザにも付与できます。

前述の単純なバックエンドで、万能の管理ユーザを作る方法は、以下のようにとても 簡単です:

class SettingsBackend:

    # ...

    def has_perm(self, user_obj, perm):
        if user_obj.username == settings.ADMIN_LOGIN:
            return True
        else:
            return False

この書き方だと、上の例でアクセスを認可されたユーザにはあらゆるパーミッショ ンが許されます。バックエンドの認証関数はユーザオブジェクトを引数にとります。 また、ユーザオブジェクトの代わりに、 User のコンストラクタと同じ引数も指定 できます。

認可の API は、 django/contrib/auth/backends.py で実装されています。この バックエンドはデフォルトのバックエンドであり、ほとんどの場合 auth_permission にパーミッションを問い合わせます。