defmodule Pow.Plug.Session do
@moduledoc """
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.
"""
use Pow.Plug.Base
alias Plug.Conn
alias Pow.{Config, Plug, UUID}
@session_key "auth"
@session_ttl_renewal :timer.minutes(15)
@doc """
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.
"""
@impl true
@spec fetch(Conn.t(), Config.t()) :: {Conn.t(), map() | nil}
def fetch(conn, config) do
case client_store_fetch(conn, config) do
{nil, conn} -> {conn, nil}
{session_id, conn} -> fetch(conn, session_id, config)
end
end
defp fetch(conn, session_id, config) do
{store, store_config} = store(config)
{session_id, store.get(store_config, session_id)}
|> convert_old_session_value()
|> handle_fetched_session_value(conn, config)
end
@doc """
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.
"""
@impl true
@spec create(Conn.t(), map(), Config.t()) :: {Conn.t(), map()}
def create(conn, user, config) do
metadata = Map.get(conn.private, :pow_session_metadata, [])
{user, metadata} = session_value(user, metadata)
conn =
conn
|> delete(config)
|> before_send_create({user, metadata}, config)
|> Conn.put_private(:pow_session_metadata, metadata)
{conn, user}
end
defp session_value(user, metadata) do
metadata =
metadata
|> Keyword.put_new(:fingerprint, gen_fingerprint())
|> Keyword.put(:inserted_at, timestamp())
{user, metadata}
end
defp gen_fingerprint(), do: UUID.generate()
defp before_send_create(conn, value, config) do
{store, store_config} = store(config)
session_id = gen_session_id(config)
register_before_send(conn, fn conn ->
store.put(store_config, session_id, value)
client_store_put(conn, session_id, config)
end)
end
@doc """
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.
"""
@impl true
@spec delete(Conn.t(), Config.t()) :: Conn.t()
def delete(conn, config), do: before_send_delete(conn, config)
defp before_send_delete(conn, config) do
{store, store_config} = store(config)
register_before_send(conn, fn conn ->
case client_store_fetch(conn, config) do
{nil, conn} ->
conn
{session_id, conn} ->
store.delete(store_config, session_id)
client_store_delete(conn, config)
end
end)
end
# TODO: Remove by 1.1.0
defp convert_old_session_value({session_id, {user, timestamp}}) when is_number(timestamp), do: {session_id, {user, inserted_at: timestamp}}
defp convert_old_session_value(any), do: any
defp handle_fetched_session_value({_session_id, :not_found}, conn, _config), do: {conn, nil}
defp handle_fetched_session_value({session_id, nil}, conn, config) do
{store, store_config} = store(config)
store.delete(store_config, session_id)
{conn, nil}
end
defp handle_fetched_session_value({session_id, {user, metadata}}, conn, config) when is_list(metadata) do
conn
|> Conn.put_private(:pow_session_metadata, metadata)
|> renew_stale_session(session_id, user, metadata, config)
end
defp renew_stale_session(conn, session_id, user, metadata, config) do
metadata
|> Keyword.get(:inserted_at)
|> session_stale?(config)
|> case do
true -> lock_create(conn, session_id, user, config)
false -> {conn, user}
end
end
defp lock_create(conn, session_id, user, config) do
id = {[__MODULE__, session_id], self()}
nodes = Node.list() ++ [node()]
case :global.set_lock(id, nodes, 0) do
true ->
{conn, user} = create(conn, user, config)
conn = register_before_send(conn, fn conn ->
:global.del_lock(id, nodes)
conn
end)
{conn, user}
false ->
{conn, user}
end
end
defp session_stale?(inserted_at, config) do
ttl = Config.get(config, :session_ttl_renewal, @session_ttl_renewal)
session_stale?(inserted_at, config, ttl)
end
defp session_stale?(_inserted_at, _config, nil), do: false
defp session_stale?(inserted_at, _config, ttl) do
inserted_at + ttl < timestamp()
end
defp gen_session_id(config) do
uuid = UUID.generate()
Plug.prepend_with_namespace(config, uuid)
end
defp session_key(config) do
Config.get(config, :session_key, default_session_key(config))
end
defp default_session_key(config) do
Plug.prepend_with_namespace(config, @session_key)
end
defp timestamp, do: :os.system_time(:millisecond)
defp client_store_fetch(conn, config) do
conn = Conn.fetch_session(conn)
with session_id when is_binary(session_id) <- Conn.get_session(conn, session_key(config)),
{:ok, session_id} <- Plug.verify_token(conn, signing_salt(), session_id) do
{session_id, conn}
else
_any -> {nil, conn}
end
end
defp signing_salt(), do: Atom.to_string(__MODULE__)
defp client_store_put(conn, session_id, config) do
signed_session_id = Plug.sign_token(conn, signing_salt(), session_id, config)
conn
|> Conn.fetch_session()
|> Conn.put_session(session_key(config), signed_session_id)
|> Conn.configure_session(renew: true)
end
defp client_store_delete(conn, config) do
conn
|> Conn.fetch_session()
|> Conn.delete_session(session_key(config))
end
end
