v0.21

認証

はじめに

dframeworkでは認証の実装が極めて簡単です。グローバルなAuthファサードはアプリケーション全体でユーザーセッションと認証状態を管理するためのシンプルで統一されたapiを提供します。

設定

認証設定はconfig/auth.jsに記述します。デフォルトでは単一モデル認証設定がUserを参照しています。

1// config/auth.js
2export default {
3 model: 'User'
4};

セッションクッキー名はconfig/session.js内のcookieまたはSESSION_COOKIE環境変数(デフォルトはsid)でカスタマイズできます。

1// config/session.js
2export default {
3 cookie: Env.value('SESSION_COOKIE', 'sid'),
4};

ユーザーの認証

ログイン

ユーザーをアプリケーションにログインさせるにはAuthファサードのloginメソッドを使用します。このメソッドはユーザーモデルインスタンスを受け取ります。第2引数として追加のセッションデータを渡すことも可能であり第3引数にセッションを永続的(長期生存)にするかどうかを示すブール値を渡すこともできます。

NOTE

ユーザーが`Auth.login()`を介してログインするとそのIDが安全に保存されセッション固定化攻撃を緩和するためにセッション識別子が自動的に再生成されます。

1import { Hash } from 'dframework';
2import User from '../models/User.js';
3
4export async function authenticate(req, res) {
5 const user = await User.findByEmail('tarou@example.com');
6
7 if (user && await Hash.verify('secret', user.password)) {
8 // log the user in and set a long lived session cookie
9 await Auth.login(user, { role: 'admin' }, true);
10
11 return redirect('/dashboard');
12 }
13
14 return back('/login').withErrors({ email: 'invalid credentials' });
15}

ログアウト

デフォルトガードからユーザーをログアウトさせるにはlogoutメソッドを使用します。これにより他のアクティブなガードセッションを保持したままデフォルトガードのセッションキーがクリアされます。

1await Auth.logout();

認証状態の確認

現在のリクエストが認証されているかどうかを判定するにはcheckメソッドを使用します。ユーザーがログインしている場合はtrueを返します。

1if (Auth.check()) {
2 // the user is logged in
3}

認証済みユーザーの取得

Authファサードのuserメソッドを介して認証済みユーザーにアクセスできます。これはアクティブなユーザーモデルインスタンスを返しユーザーが未認証の場合はnullを返します。

1const user = Auth.user();
2
3if (user) {
4 Log.info(`welcome back, ${user.name}`);
5}

ユーザーIDの取得

プロパティを手動で参照することなく認証済みユーザーのIDを迅速に取得するにはidメソッドを使用します。

1const userId = Auth.id();

マルチガード認証

アプリケーションで複数の異なるエンティティタイプ(例えば一般ユーザーと管理者)に対して独立した認証が必要な場合はconfig/auth.jsでガードを定義できます。

ガードの定義

ガードはconfig/auth.jsのguardsオブジェクト配下に登録します。各ガードはモデルとオプションのカスタムセッションキー(デフォルトは${guardName}Id)を指定します。

1// config/auth.js
2export default {
3 default: 'web',
4 guards: {
5 web: {
6 model: 'User',
7 sessionKey: 'userId'
8 },
9 admin: {
10 model: 'Admin',
11 sessionKey: 'adminId'
12 }
13 }
14};

ガードの使用

特定のガードで認証アクションを実行するにはAuthファサードのguardメソッドを使用します。

1// check if an admin is logged in
2if (Auth.guard('admin').check()) {
3 const admin = Auth.guard('admin').user();
4 const adminId = Auth.guard('admin').id();
5}
6
7// log in an admin (preserves active user sessions on other guards)
8await Auth.guard('admin').login(adminUser);
9
10// log out admin only
11await Auth.guard('admin').logout();

すべてのガード読み取り(user()、check()、id())はリクエスト中完全に同期的です。

すべてのガードのフラッシュ

アクティブなすべてのガードログインを完全にクリアしセッションデータを1回の呼び出しで消去するにはflushを使用します。

1await Auth.flush();

ハッシュ化

dframeworkは安全なパスワードハッシュ化にbcryptを使用するHashファサードを提供します。

標準ハッシュ化

パスワードをハッシュ化するにはmakeメソッドを使用します。安全なソルトを自動的に生成し12ラウンドのbcryptハッシュを適用します。

1import { Hash } from 'dframework';
2
3const hashedPassword = await Hash.make('my-password');

平文パスワードをハッシュと照合して検証するにはverifyメソッドを使用します。

1if (await Hash.verify('plain-text', hashedPassword)) {
2 // passwords match
3}

決定論的高速ハッシュ化

エントロピーの高いトークン(apiキーやパーソナルアクセストークンなど)をデータベースでの完全一致検索が可能な方法で安全にハッシュ化したい場合があります。fastメソッドはサーバーサイドのAPP_KEYをペッパーとして使用した決定論的sha256ハッシュを提供します。

1// generating a token and saving its fast hash
2const token = Hash.random(40);
3const hashedToken = Hash.fast(token);
4
5// querying the database for the exact hashed token
6const record = await TokenModel.where('token', Hash.fast('provided-token')).first();

基本認証

dframeworkはRouteファサードを介してhttp基本認証(basic authentication)の組み込みサポートを直接提供します。チェーン可能なルートビルダー、ルート修飾子、グループオプション、または簡略記法グループを使用して個別ルートまたはルートグループ全体を保護できます。

クレデンシャルはconfig/auth.jsのauth.basic配下でグローバルに設定するかルート定義で直接指定できます。

ルート修飾子

ルート定義に直接.basicAuth()をチェーンします。

1// using credentials configured in config/auth.js
2Route.get('/metrics', 'app.MetricsController@show').basicAuth();
3
4// with explicit credentials and custom realm
5Route.get('/metrics', 'app.MetricsController@show').basicAuth('admin', 'secret123', 'internal area');

チェーン可能なビルダー

.domain()、.port()、.middleware()と並んで任意の順序でルート定義の前に.basicAuth()を配置できます。

1Route.basicAuth('admin', 'secret123', 'internal area')
2 .port(8080)
3 .get('/metrics', 'app.MetricsController@show');

動的バリデーター

データベースやカスタムストレージに対してクレデンシャルを検証するために非同期のバリデーターコールバックを渡します。

1Route.basicAuth(async (username, password) => {
2 const admin = await Admin.where('username', username).first();
3 if (!admin) return false;
4 return await Hash.verify(password, admin.password);
5}).get('/dashboard', 'app.DashboardController@index');
6
7// with a custom realm
8Route.basicAuth({
9 validator: async (username, password) => {
10 const admin = await Admin.where('username', username).first();
11 if (!admin) return false;
12 return await Hash.verify(password, admin.password);
13 },
14 realm: 'Admin Area'
15}).get('/dashboard', 'app.DashboardController@index');

ルートグループ

グループオプションまたはグループ簡略記法を使用して複数のルートを基本認証で保護します。

1// group options using config defaults
2Route.group({ basicAuth: true }, (admin) => {
3 admin.get('/dashboard', 'admin.AdminController@index');
4});
5
6// group shorthand with config defaults and zero parameter callback
7Route.basicAuth(() => {
8 Route.get('/status', 'admin.StatusController@show');
9});
10
11// group shorthand with explicit credentials
12Route.basicAuth('admin', 'secret', (admin) => {
13 admin.get('/settings', 'admin.SettingsController@index');
14});
15
16// group shorthand with custom validator
17Route.basicAuth(async (user, pass) => user === 'admin' && pass === 'secret', (admin) => {
18 admin.get('/panel', 'admin.PanelController@index');
19});