View Source PowPersistentSession.Plug.Cookie (Pow v1.0.38)

This plug will handle persistent user sessions with cookies.

The cookie and token will expire after 30 days. 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 as the persistent session value as {user, session_metadata: [fingerprint: fingerprint]}.

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

Example

defmodule MyAppWeb.Endpoint do

# ...

plug Pow.Plug.Session, otp_app: :my_app
plug PowPersistentSession.Plug.Cookie
#...

end

Configuration options

:persistent_session_store - see PowPersistentSession.Plug.Base
:cache_store_backend - see PowPersistentSession.Plug.Base
:persistent_session_cookie_key - cookie key name. This defaults to "persistent_session". 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. See PowPersistentSession.Plug.Base for more.
:persistent_session_cookie_opts - keyword list of cookie options, see Plug.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.

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.

Summary

Functions

authenticate(conn, config)

Authenticates a user with the persistent session cookie.

create(conn, user, config)

Sets a persistent session cookie with a randomly generated unique token.

delete(conn, config)

Expires the persistent session.

Functions

authenticate(conn, config)

@spec authenticate(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.

If credentials was fetched successfully, a global lock is set and the token in the cache is deleted, a new session is created, and create/2 is called to create a new persistent session cookie. If setting the lock failed, the user will fetched will be set for the conn with Pow.Plug.assign_current_user/3.

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.

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

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

create(conn, user, config)

@spec create(Plug.Conn.t(), map(), Pow.Config.t()) :: Plug.Conn.t()

Sets a persistent session cookie with a randomly generated unique 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: {user, session_metadata: [fingerprint: fingerprint]}

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

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

delete(conn, config)

@spec delete(Plug.Conn.t(), Pow.Config.t()) :: Plug.Conn.t()

Expires the persistent session.

If a persistent session cookie exists the token in the persistent session cache will be deleted, and cookie deleted with Plug.Conn.delete_resp_cookie/3.