Pow v1.0.16 PowPersistentSession.Plug.Cookie View Source
This plug will handle persistent user sessions with cookies.
By default, the cookie will expire after 30 days. The cookie expiration will be renewed on every request where a user is assigned to the conn. The token in the cookie can only be used once to create a session.
If an assigned private :pow_session_metadata
key exists in the conn with a
keyword list containing a :fingerprint
key, that fingerprint value will be
set along with the user clause as the persistent session value as
{[id: user_id], session_metadata: [fingerprint: fingerprint]}
.
Example
defmodule MyAppWeb.Endpoint do
# ...
plug Pow.Plug.Session, otp_app: :my_app
plug PowPersistentSession.Plug.Cookie
#...
end
Configuration options
:persistent_session_store
- seePowPersistentSession.Plug.Base
:cache_store_backend
- seePowPersistentSession.Plug.Base
:persistent_session_cookie_key
- session key name. This defaults to "persistent_session_cookie". If:otp_app
is used it'll automatically prepend the key with the:otp_app
value.:persistent_session_ttl
- used for both backend store and max age for cookie. SeePowPersistentSession.Plug.Base
for more.:persistent_session_cookie_opts
- keyword list of cookie options, seePlug.Conn.put_resp_cookie/4
for options. The default options are[max_age: max_age, path: "/"]
where:max_age
is the value defined in:persistent_session_ttl
.:persistent_session_cookie_expiration_timeout
- integer value in seconds for how much time should go by before cookie should expire after the token is fetched inauthenticate/2
. Defaults to 10.
Custom metadata
You can assign a private :pow_persistent_session_metadata
key in the conn
with custom metadata as a keyword list. The only current use this has is to
set :session_metadata
that'll be passed on as :pow_session_metadata
for
new session generation.
session_metadata =
conn.private
|> Map.get(:pow_session_metadata, [])
|> Keyword.take([:first_seen_at])
Plug.Conn.put_private(conn, :pow_persistent_session_metadata, session_metadata: session_metadata)
This ensure that you are able to keep session metadata consistent between browser sessions.
When a persistent session token is used, the
:pow_persistent_session_metadata
assigns key in the conn will be populated
with a :session_metadata
keyword list so that the session metadata that was
pulled from the persistent session can be carried over to the new persistent
session. :fingerprint
will always be ignored as to not record the old
fingerprint.
Link to this section Summary
Functions
Authenticates a user with the persistent session cookie.
Sets a persistent session cookie with an auto generated token.
Expires the persistent session cookie.
Link to this section Functions
authenticate(conn, config)
View Sourceauthenticate(Plug.Conn.t(), Pow.Config.t()) :: Plug.Conn.t()
Authenticates a user with the persistent session cookie.
If a persistent session cookie exists, it'll fetch the credentials from the persistent session cache.
After the value is fetched from the cookie, it'll be updated to expire after
the value of :persistent_session_cookie_expiration_timeout
so invalid
cookies will be deleted eventually. This timeout prevents immediate deletion
of the cookie so in case of multiple simultaneous requests, the cache has
time to update the value.
If credentials was fetched successfully, the token in the cache is deleted, a
new session is created, and create/2
is called to create a new persistent
session cookie. This will override any expiring cookie.
If a :session_metadata
keyword list is fetched from the persistent session
metadata, all the values will be merged into the private
:pow_session_metadata
key in the conn.
The expiration date for the cookie will be reset on each request where a user is assigned to the conn.
call(conn, config)
View Sourcecall(Plug.Conn.t(), Pow.Config.t()) :: Plug.Conn.t()
create(conn, user, config)
View Sourcecreate(Plug.Conn.t(), map(), Pow.Config.t()) :: Plug.Conn.t()
Sets a persistent session cookie with an auto generated token.
The token is set as a key in the persistent session cache with the id fetched
from the struct. Any existing persistent session will be deleted first with
delete/2
.
If an assigned private :pow_session_metadata
key exists in the conn with a
keyword list containing a :fingerprint
value, then that value will be set
in a :session_metadata
keyword list in the persistent session metadata. The
value will look like:
{[id: user_id], session_metadata: [fingerprint: fingerprint]}
The unique cookie id will be prepended by the :otp_app
configuration
value, if present.
delete(conn, config)
View Sourcedelete(Plug.Conn.t(), Pow.Config.t()) :: Plug.Conn.t()
Expires the persistent session cookie.
If a persistent session cookie exists it'll be updated to expire immediately, and the token in the persistent session cache will be deleted.