python social auth - pipeline のデフォルト機能まとめ

# python social auth の Pipeline のデフォルト機能のまとめ

[Python Social Auth - Pipline](https://python-social-auth.readthedocs.io/en/latest/pipeline.html)
を日本語訳しただけ

途中で力尽きたのでそこまで

## 概要

python social auth は `Pipeline` という 拡張可能なメカニズムを用いており、
ユーザは認証や関連付け、切断周りの自作関数をpipelineに自由に組み込むことができる

関数は処理に必要な値や、strategyに必要な値などの引数、あるいはuserオブジェクトや、requestを引数にとることになる
エラー回避のために、引数には**kwargsを入れておくことが推奨されている

Pipelineの各関数は`dict型`もしくは`None`を返すことができ、
その他の返り値はインスタンスレスポンスとして扱われ、クライアントに直接返される

dictが返された場合、値はkwargsとして次のPipelineの引数に渡される
Noneの場合は`[]`が返される

## Pipeline

認証フローは下記の通りのパイプラインを通して処理されていく
このパイプラインには関数を追加することもできるし、不要なものは取り除くこともできる
デフォルトでは、ユーザを作成しOAuthプロバイダから提供されるデータの中で基本的なものを抜き出してくれる

```py
(
    # ユーザの情報を取得し、後のユーザ作成処理で使える要素を抜き出して返します
    # この機能はプロバイダからのレスポンスにすでに含まれていることが多いですが、
    # たまに含まれてないことがあるので、そういう時に便利です
    'social_core.pipeline.social_auth.social_details',

    # social uid というものをリクエストの中から取得します
    # この uid とは、認証プロバイダでのユーザを一意に識別するIDです
    'social_core.pipeline.social_auth.social_uid',

    # 認証プロセスが有効かどうかを検証する関数です
    # ここで email の検証や、 ドメインのホワイトリスト適用が実行されます
    'social_core.pipeline.social_auth.auth_allowed',

    # 送られてきたアカウントがすでにウェブサイト上に存在するかどうかを検証します
    'social_core.pipeline.social_auth.social_user',

    # 取得した情報をもとにユーザネームを作成します
    # 同名被りが発生しそうであれば、ランダムの文字列を後ろにつけます
    'social_core.pipeline.user.get_username',

    # ユーザのemailアドレスに、検証用のメールを送信します
    # デフォルトでは無効となっています
    # 'social_core.pipeline.mail.mail_validation',

    # すでに同じemailで登録されていた場合、取得した詳細情報をそのユーザに統合します
    # デフォルトでは無効となっています
    # 'social_core.pipeline.social_auth.associate_by_email',

    # ユーザが見つからなかった場合、作成します
    'social_core.pipeline.user.create_user',

    # ソーシャルアカウントと、サイト内のユーザアカウントを結びつけるレコードを作成します
    'social_core.pipeline.social_auth.associate_user',

    # このsettings.pyで指定した値を、ソーシャルデータの中にextra_dataとして追加します
    # access_tokenなどです
    'social_core.pipeline.social_auth.load_extra_data',

    # ソーシャルアカウントに変更点があれば、変更点を統合します
    'social_core.pipeline.user.user_details',
)
```

このパイプラインはsettings.pyで`SOCIAL_AUTH_PIPELINE`の項目を追加することでオーバーライドできる

```py
SOVIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.auth_allowed',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    # 'social_core.pipeline.mail.mail_validation',
    # 'social_core.pipeline.social_auth.associate_by_email',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
)
```

ログイン処理のみ有効にして、新規ユーザの作成を行いたくない場合は↓のように設定する

```py
SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.auth_allowed',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
)
```

しかしながらこの設定は、ユーザがすでに認証されていることを想定していることに注意
つまり、dict内に`user`キーがすでに追加されている状態である

認証機能を完全に外部にゆだねる場合、`user`キーを追加するメソッドをパイプラインに含めるようにしなければならない
例えば、以下のように`user`をdictに追加するようなオリジナルのメソッドを追加する

```py
SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.auth_allowed',
    'myapp.pipeline.load_user', # このメソッドでuserをreturnするようにする
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
)
```