Pow.Plug.Session (Pow v1.0.23) View Source

This plug will handle user authorization using session.

The plug will store user and session metadata in the cache store backend. The session metadata has at least an :inserted_at and a :fingerprint key. The :inserted_at value is used to determine if the session has to be renewed, and is set each time a session is created. The :fingerprint will be a random unique id and will stay the same if a session is renewed.

When a session is renewed the old session is deleted and a new created.

You can add additional metadata to sessions by setting or updated the assigned private :pow_session_metadata key in the conn. The value has to be a keyword list.

The session id used in the client is signed using Pow.Plug.sign_token/4 to prevent timing attacks.

Example

@pow_config [
  repo: MyApp.Repo,
  user: MyApp.User,
  current_user_assigns_key: :current_user,
  session_key: "auth",
  credentials_cache_store: {Pow.Store.CredentialsCache,
                            ttl: :timer.minutes(30),
                            namespace: "credentials"},
  session_ttl_renewal: :timer.minutes(15),
  cache_store_backend: Pow.Store.Backend.EtsCache,
  users_context: Pow.Ecto.Users
]

# ...

plug Plug.Session, @session_options
plug Pow.Plug.Session, @pow_config

Configuration options

  • :credentials_cache_store - see Pow.Plug.Base.

  • :cache_store_backend - see Pow.Plug.Base.

  • :session_key - session key name, defaults to "auth". If :otp_app is used it'll automatically prepend the key with the :otp_app value.

  • :session_ttl_renewal - the ttl in milliseconds to trigger renewal of sessions. Defaults to 15 minutes in miliseconds.

Custom metadata

The assigned private :pow_session_metadata key in the conn can be populated with custom metadata. This data will be stored in the session metadata when the session is created, and fetched in subsequent requests.

Here's an example of how one could add sign in timestamp, IP, and user agent information to the session metadata:

def append_to_session_metadata(conn) do
  client_ip  = to_string(:inet_parse.ntoa(conn.remote_ip))
  user_agent = get_req_header(conn, "user-agent")

  metadata =
    conn.private
    |> Map.get(:pow_session_metadata, [])
    |> Keyword.put_new(:first_seen_at, DateTime.utc_now())
    |> Keyword.put(:ip, client_ip)
    |> Keyword.put(:user_agent, user_agent)

  Plug.Conn.put_private(conn, :pow_session_metadata, metadata)
end

The :first_seen_at will only be set if it doesn't already exist in the session metadata, while :ip and :user_agent will be updated each time the session is created.

The method should be called after Pow.Plug.Session.call/2 has been called to ensure that the metadata, if any, has been fetched.

Session expiration

Pow.Store.CredentialsCache will, by default, invalidate any session token 30 minutes after it has been generated. To keep sessions alive the :session_ttl_renewal option is used to determine when a session token becomes stale and a new session ID has to be generated for the user (deleting the previous one in the process).

If :session_ttl_renewal is set to zero, a new session token will be generated on every request.

To change the amount of time a session can be alive, both the TTL for Pow.Store.CredentialsCache and :session_ttl_renewal option should be changed:

plug Pow.Plug.Session, otp_app: :my_app,
  session_ttl_renewal: :timer.minutes(1),
  credentials_cache_store: {Pow.Store.CredentialsCache, ttl: :timer.minutes(15)}

In the above, a new session token will be generated when a request occurs more than a minute after the current session token was generated. The session is invalidated if there is no request for the next 14 minutes.

There are no absolute session timeout; sessions can be kept alive indefinitely.

Link to this section Summary

Functions

Configures the connection for Pow, and fetches user.

Create new session with a randomly generated unique session id.

Delete an existing session in the credentials cache.

Calls create/3 and assigns the current user.

Calls delete/2 and removes the current user assigned to the conn.

Calls fetch/2 and assigns the current user to the conn.

Fetches session from credentials cache.

Link to this section Functions

Configures the connection for Pow, and fetches user.

If no options have been passed to the plug, the existing configuration will be pulled with Pow.Plug.fetch_config/1

:plug is appended to the passed configuration, so the current plug will be used in any subsequent calls to create, update and delete user credentials from the connection. The configuration is then set for the conn with Pow.Plug.put_config/2.

If a user can't be fetched with Pow.Plug.current_user/2, do_fetch/2 will be called.

Link to this function

create(conn, user, config)

View Source

Specs

create(Plug.Conn.t(), map(), Pow.Config.t()) :: {Plug.Conn.t(), map()}

Create new session with a randomly generated unique session id.

This will store the unique session id with user credentials in the credentials cache. The session id will be stored in the connection with Plug.Conn.put_session/3. Any existing sessions will be deleted first with delete/2.

The unique session id will be prepended by the :otp_app configuration value, if present.

If an assigned private :pow_session_metadata key exists in the conn, it'll be passed on as the metadata for the session. However the :inserted_at value will always be overridden. If no :fingerprint exists in the metadata a random UUID value will be generated as its value.

The session id will be signed for public consumption with Pow.Plug.sign_token/4.

See do_create/3 for more.

Specs

Delete an existing session in the credentials cache.

This will delete a session in the credentials cache with the session id fetched through Plug.Conn.get_session/2. The session in the connection is deleted too with Plug.Conn.delete_session/2.

See do_delete/2 for more.

Link to this function

do_create(conn, user, config)

View Source

Calls create/3 and assigns the current user.

The user is assigned to the conn with Pow.Plug.assign_current_user/3.

Calls delete/2 and removes the current user assigned to the conn.

The user assigned is removed from the conn with Pow.Plug.assign_current_user/3.

Calls fetch/2 and assigns the current user to the conn.

The user is assigned to the conn with Pow.Plug.assign_current_user/3.

Specs

fetch(Plug.Conn.t(), Pow.Config.t()) :: {Plug.Conn.t(), map() | nil}

Fetches session from credentials cache.

This will fetch a session from the credentials cache with the session id fetched through Plug.Conn.get_session/2 session. If the credentials are stale (timestamp is older than the :session_ttl_renewal value), a global lock will be set, and the session will be regenerated with create/3. Nothing happens if setting the lock failed.

The metadata of the session will be assigned as a private :pow_session_metadata key in the conn so it may be used in create/3.

If the credentials cache returns a nil value the session will be immediately deleted as it means the context method could not find the associated user.

The session id will be decoded and verified with Pow.Plug.verify_token/4.

See do_fetch/2 for more.