@spec delete_session(Plug.Conn.t(), Charon.Config.t()) :: Plug.Conn.t()

Delete the persistent session identified by the session_id in the token claims.

Note that the token remains valid until it expires, it is left up to the client to drop the access token. It will no longer be possible to refresh the session, however.

This function also instructs browsers to clear signature cookies.

@spec upsert_session(Plug.Conn.t(), Charon.Config.t(), upsert_session_opts()) ::
  Plug.Conn.t()

Create or update a session. If a session exists in the conn, the session is updated / refreshed, otherwise a new one is created. Refresh an existing session by putting it on the connection with Charon.TokenPlugs.load_session/2.

In both cases, new access / refresh tokens are created and stored in the conn's private map. The server-side session stored in the session store is created / updated as well.

If a new session is created, options :user_id and :token_transport must be provided or an error will be raised.

The token transport can be:

• :cookie_only - full tokens are returned to the client as cookies
• :cookie - partial tokens are returned to the client as cookies (only the tokens' signature, the rest should be sent in the response body)
• :bearer - no cookies are sent to the client, the tokens should be sent in the response body

Please read up on CSRF protection in README when using cookies. The slightly awkward naming of :cookie and :cookie_only exists for legacy reasons and is kept for backwards compatibility.

If config option :enforce_browser_cookies is enabled, browser clients will be attempted to be detected by the presence of (forbidden) header "Sec-Fetch-Mode", in which case only cookie-based token transports will be allowed.

Optionally, it is possible to add extra claims to the access- and refresh tokens or to store extra payload in the server-side session.

Session stores may return an optimistic locking error, meaning there are concurrent updates to a session. In this case, upsert/3 will raise a Charon.SessionPlugs.SessionUpdateConflictError, which should result in an HTTP 409 Conflict error. If the session store returns another error, a Charon.SessionPlugs.SessionStorageError is raised, which is an unrecoverable state that should result in an HTTP 500 Internal Server Error.

Claims

The following claims are set by default:

• "exp" expires at (this value is guaranteed to never outlive the session itself)
• "iat" time of token creation
• "iss" issuer, usually a url like "https://myapp.com"
• "jti" jwt id, random unique id for the token (a refresh token's id is stored in the session as well)
• "nbf" not before, same value as "iat" but means "token not valid before this time"
• "sid" session id
• "sub" subject, the user id of the session owner
• "type" type, "access" or "refresh"
• "styp" session type

Additional claims or overrides can be provided with opts.

Options:

• :user_id (required when creating a new session) - The user ID for the session owner
• :token_transport (required when creating a new session) - How tokens are transported to the client
• :access_claim_overrides - Map of additional or overridden claims for the access token
• :refresh_claim_overrides - Map of additional or overridden claims for the refresh token
• :extra_session_payload - Map of additional data to store in the server-side session
• :session_type - Session type atom (defaults to :full). Used to categorize sessions that require different lifecycle management. For example, OAuth2 provider sessions (see CharonOauth2) or API key sessions might use a distinct type to ensure they are excluded from bulk operations like "logout all sessions". Only needed for specialized use cases.

Examples

Create a new session for a user:

iex> conn = upsert_session(conn(), @config, user_id: 1, token_transport: :bearer)
iex> %Session{} = Utils.get_session(conn)
iex> %Tokens{} = Utils.get_tokens(conn)

Create a session with infinite lifespan:

iex> conn = upsert_session(conn(), %{@config | session_ttl: :infinite}, user_id: 1, token_transport: :bearer)
iex> %Session{expires_at: :infinite} = Utils.get_session(conn)

Add extra payload to the session:

iex> conn = upsert_session(
...>   conn(),
...>   @config,
...>   user_id: 1,
...>   token_transport: :bearer,
...>   extra_session_payload: %{role: :admin}
...> )
iex> %Session{extra_payload: %{role: :admin}} = Utils.get_session(conn)