Theme
SD MILIEU

2017-5-26

express-session README日本語訳

翻訳途中

express-session の設定項目が意味不明で日本語情報もほとんど見当たらなかったので、自身の理解のために雑に翻訳。英文そのままの所は未翻訳。

翻訳信頼性は限りなく 0 に等しいので参考にしないほうが良い。

自分自身が追記した注釈に関しては「独自追記」と記載。

翻訳元

GitHub - expressjs/session: Simple session middleware for Express(2017.05.26 時点)

インストール

npm registryを通して利用可能なNode.jsモジュールです。

インストールはnpm installコマンドで出来ます。

$ npm install express-session

API

var session = require('express-session')

session(options)

与えられた options に従ってセッション Middleware を作成します。

**Note:**セッションデータはクッキーには保存されません、クッキーに保存されるのはセッション ID です。セッションデータ自体はサーバーサイドで保存されます。

**Note:**バージョン 1.5.0 以降、このモジュールにcookie-parser ミドルウェアは不要になりました。このモジュールは今ではreq/resを用いて直接クッキーを読み書きしています。cookie-parserを使用すると、もし secret がこのモジュールとcookie-parser間で統一されていない場合不具合の原因になってしまいます。

**Warning:**デフォルトのサーバーサイドのセッションストレージであるMemoryStoreは、わざと本番環境のために設計していません。MemoryStoreは多くの状況でメモリリークを引き起こし、does not scale past a single process,つまりMemoryStoreは開発やデバッグ用途のものなのです。

セッションの保存方式一覧は、Compatible Session Storesを確認してください。

Options

express-sessionは options オブジェクトに以下のプロパティを利用できます。

cookie

セッション ID を保存するクッキーのための設定です。

デフォルトは以下の通りです。

{
  path: '/',
  httpOnly: true,
  secure: false,
  maxAge: null
}

以下のオプションはこのオブジェクトに設定できるものです。

独自追記：一般的な Cookie の Option なので省略

genid

新しいセッション ID を生成するために呼ばれる関数。セッション ID として使用される文字列を返却する関数を与えて下さい。ID を生成する際にreqに関わる値を使用したい時のために、第一引数にreqが与えられています。

デフォルトは、ID を生成するためにuid-safeライブラリを使用している関数です。

**NOTE:**ユニークな ID を生成する際には、セッション ID が競合しないよう注意して下さい。

app.use(session({
  genid: function(req) {
    return genuuid() // use UUIDs for session IDs
  },
  secret: 'keyboard cat'
}))
name

HTTP レスポンスに設定するセッション ID クッキーの名前です。

デフォルトはconnect.sidです。

**NOTE:**もし複数のアプリを同一ホスト名で走らせるなら (this is just the name, i.e. localhost or 127.0.0.1; different schemes and ports do not name a different hostname)、セッションのクッキーをお互いに分離させる必要があります。シンプルな方法としてはアプリ毎に異なる name を設定することです。

proxy

クッキーに secure 属性が設定されている際に、リバースプロキシを信頼するかどうか。

デフォルトはundefined。

  • true: X-Forwaded-Protoヘッダーが使用されます。
  • false: 全てのヘッダーは無視され、接続はダイレクトな TLS/SSL 接続の時のみセキュアとみなされます。
  • undefined: express のtrust proxyの設定を使用します。

**独自追記:**この項目よくわからないのであくまで予想だけど、リバースプロキシは簡単に信頼していいものではなく、X-Forwaded-Proto ヘッダーが改鼠される可能性があるみたい。Set-Cookie で secure 属性を設定しているにも関わらず、リバースプロキシとクライアント間の通信が http なのに https と見なしてクッキーを送ったら MITM 攻撃でセッションハイジャックされるので、それの対策っぽい。

**独自追記:**X-Forwaded-Proto ヘッダーは、クライアントとロードバランサ間のプロトコルが HTTP なのか HTTPS なのか判別するためのヘッダー。ロードバランサを使用している際には、サーバーは何も対策していなければロードバランサとサーバー間のプロトコルしか判別出来ないっぽい。それだと Cookie の secure オプションを適用するかどうか判断する際に困るからこの設定がある、みたい。

**独自追記:**リバースプロキシ参考：リバースプロキシって何？触りだけ学んだサーバー/インフラ入門 - Qiita

resave

Forces the session to be saved back to the session store, even if the session was never modified during the request. Depending on your store this may be necessary, but it can also create race conditions where a client makes two parallel requests to your server and changes made to the session in one request may get overwritten when the other request ends, even if it made no changes (this behavior also depends on what store you're using).

The default value is true, but using the default has been deprecated, as the default will change in the future. Please research into this setting and choose what is appropriate to your use-case. Typically, you'll want false.

How do I know if this is necessary for my store? The best way to know is to check with your store if it implements the touch method. If it does, then you can safely set resave: false. If it does not implement the touch method and your store sets an expiration date on stored sessions, then you likely need resave: true.

rolling

セッション ID のクッキーを毎レスポンスに強制的に付与します。そのことでクッキーの期限がリセットされます。

デフォルトは false です。

**独自追記:**通常はクッキーの期限が切れない限り新しくレスポンスにクッキーを付与しないんだけど、このオプションを true すると毎回 Set-Cookie されていており、またそれの Expire は maxAge を元に計算された新しい期限が設定されていた。

**NOTE:**このオプションがtrueに設定されており、saveUninitializedオプションがfalseに設定されているなら、he cookie will not be set on a response with an uninitialized session.

saveUninitialized

Forces a session that is "uninitialized" to be saved to the store. A session is uninitialized when it is new but not modified. Choosing false is useful for implementing login sessions, reducing server storage usage, or complying with laws that require permission before setting a cookie. Choosing false will also help with race conditions where a client makes multiple parallel requests without a session.

The default value is true, but using the default has been deprecated, as the default will change in the future. Please research into this setting and choose what is appropriate to your use-case.

Note if you are using Session in conjunction with PassportJS, Passport will add an empty Passport object to the session for use after a user is authenticated, which will be treated as a modification to the session, causing it to be saved. This has been fixed in PassportJS 0.3.0

secret

必須設定

セッション ID クッキーを暗号化するための secret です。単一の secret なら文字列、複数の secret なら配列を指定します。配列を指定した場合、セッション ID クッキーの暗号化には最初の要素のみが使用され、リクエスト内の署名の復号には全ての要素が使用されます。

store

session store のインスタンスです。デフォルトでは新しくMemoryStoreインスタンスが指定されています。

unset

req.sessionを unset した際（deleteや、nullを設定する等）の結果をコントロールします。

デフォルトはkeepで

  • destroy: レスポンス終了時にセッションが破棄されます。
  • keep: ストア内のセッションは維持されますが、リクエストによってセッションの変更が発生したとしても無視され保存されません。

独自追記：以下未翻訳