FYI - Blog series using this approach with FastAPI by Nils de Bruin - https://medium.com/@nils_29588

In the future will this method be included in the docs? I think a httponly cookie is the best way to store the jwt token, and not sending in the body with json. Also thanks @joaodlf i will try your solution in my project in the next couple of days.

Edit: Tried it today and it works nicely.

Isn't this approach still vulnerable to CSRF attacks?
Adding the SameSite=Lax flag to the cookie could mitigate most of the vulnerabilities that come with cookies (and works in most modern browsers). Otherwise you would have to add some kind of verification cookie to your frontend and implement additional logic to handle this (similar to Django csrf_token).

@cbows yes it is still vulnerable to CSRF. But it's XSS safe (with httponly=true), which sending in the body (and storing on the client) isn't. SameSite is not fully supported in all browsers https://caniuse.com/#search=samesite yet. But i do think as well, that it does minimize the vulnerability a lot, if you don't have some cross-origin scenarios.

Otherwise yes you have to use a token. in fastapi you could maybe implement it in your jwt claim and store it on the client. and with every request you send it in the header and compare it with the claim

I think stuff like this would be awesome to include in the docs. fastapi and also the docs are really awesome. Thats why i think to have the best possible security in the docs is really nice and a big selling point :-)

I totally agree with you. This definitely should go in the docs. With SameSite=Lax it might even be superior to the current approach in terms of default security.

According to starlette docs, samesite='lax' is the default when setting cookies.

I have to look if it's beeing set in my cookie. But that would make it even more relevant to include this in the docs or even implement a class in fastapi

@cbows I just checked my cookie and it does not set samesite. current version of fastapi (0.54.1) uses starlette (0.13.2). If you check starlette the current version is 0.13.4 and there it is set in the code. so fastapi first needs to update to 0.13.4 as a dependency. right now we have to set it manually

I agree the docs should be updated to an example with HttpOnly cookies since I think that's best practice to protect session tokens from XSS

Just as a heads up, you could follow the way that flask_jwt_extended does things where the function that sets the tokens as cookies also creates csrf tokens:
https://flask-jwt-extended.readthedocs.io/en/stable/tokens_in_cookies/

FYI, @wshayes broken link (I think) should lead to this: https://archive.is/UsaXo

I agree the docs should be updated to an example with HttpOnly cookies since I think that's best practice to protect session tokens from XSS

Perhaps @SelfhostedPro's suggestion which shows:

NOTE: This is just a basic example of how to enable cookies. This is
vulnerable to CSRF attacks, and should not be used as is. See
csrf_protection_with_cookies.py for a more complete example!

And leads to: https://archive.is/Bv1ub
Could be incorporated for a fully secure solution whilst maintaining old browser support

what is latest on this?

FYI - Blog series using this approach with FastAPI by Nils de Bruin - https://medium.com/@nils_29588

this page is now 404

I think a better option is to save the token in a samtesite=Strict cookie

from owasp csrf-cheatsheet:

The Strict value will prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.

afaik this will prevent csrf and xss attacks

Would it be an alternative to stick with a short-lived access-token in the body and add an additional long-lived refresh-token in a cookie?

Hi @BigSamu, it's been quite a while since I've touched a project that uses fastapi, but your conclusion at the end makes sense to me - You'll need to hook into the logout endpoint (possibly via class extension as well?) and delete the cookie.

Is there a final solution on this ??

Note for Swagger UI and Swagger Editor users: Cookie authentication is currently not supported for “try it out” requests due to browser security restrictions. See this issue for more information. SwaggerHub does not have this limitation.

https://swagger.io/docs/specification/v3_0/authentication/cookie-authentication/

According to the below link, the best way to make cookies work would be to authenticate via an endpoint using the cookie, and then navigate to the swagger UI page hosted on the same domain. You would lose any authentication UI elements in swagger, but that would work...

swagger-api/swagger-js#1163

Having an http-only same-site="strict" is actually a huge pain to work with because it won't be shared across subdomains. For example, docs.your-domain.com won't receive cookies set to api.your-domain.com or your-domain.com.

A solid alternative is to use an access token for authentication and a refresh token for getting new access tokens. The access token lives in a tab's memory, which means it cannot be stolen using XSS. The flow is as follows:

• User logs in with email and password.
• A response is sent with a
  • set-cookie header that sets a refresh token as an http-only=True same-site="strict" cookie
  • an access token in the response's JSON body.
• The frontend saves the access token, for example, in a React Context.
• The frontend will include the token in the authorization header as Authorization: Bearer <token> for every request to a protected endpoint.
• When the access token expires, the browser will call /auth/refresh to get a new access token. This is the only endpoint in the backend that uses the refresh http-only cookie for authentication. If the cookie is there and correct, it will issue a new access token in a response's JSON body.

This mitigates CSRF because the browser will have to actively set the value of the Authorization header in each request, which is simply impossible to "break" with a CSRF attack because JS is needed to manipulate the request's headers to insert Authorization: Bearer <token-from-a-variable-in-JS>.

And it mitigates XSS because the access token is stored in memory which means other tabs can't access it, unlike local storage for example.

But keep in mind that implementing this in React will not be straight forward and for some reason there isn't a single decent tutorial out there on this.

This is an example that implements a React Context doing what was just explained.

import axios from "axios";
import {createContext, useContext, useEffect, useMemo, useState} from "react";
import {useNavigate} from "react-router-dom";
import {ROUTES} from "@/routes/index.jsx";

axios.defaults.baseURL = "https://p.local/api"

const AuthContext = createContext();

/**
 * serializeToken takes the body of a successful authentication response
 * containing an access token. In my backend setup for this project, the response body also
 * includes an ISO timestamp indicating the token's expiration.
 *
 * The function returns an object that includes the token and its
 * expiration information. This allows the frontend to:
 *   - Schedule automatic refreshes before the token expires
 *   - Know if the token is stale without having to test it on a protected endpoint
 */
export function serializeToken(data) {
    const expiration = new Date(data.access_expiration)

    return {
        token: data.access,
        expiration: expiration,
        expirationPadded: new Date(expiration.getTime() - 2 * 1000) // -2 secs
    }
}

export function isTokenValid(token) {
    return token && token.expirationPadded > new Date()
}

function AuthProvider({children}) {
    const [token, setToken] = useState();
    const [error, setError] = useState();
    const [user, setUser]=useState();
    const navigate = useNavigate();

    useEffect(() => {
        refreshToken()
    }, []);

    async function refreshToken() {
        try {
            const response = await axios.post(
                "/auth/token/refresh",
                {},
                {withCredentials: true}
            )
            const newToken = serializeToken(response.data)
            setToken(newToken);
            setError(null);
            setUser(response.data.user)
            return newToken

        } catch (err) {
            if (err.response) {
                setError(err.response)
                setToken(null)
            }
            // don't put navigate here. it will also force all public routes into /login
        }
    }

    async function useFetch(method, url, data, config) {
        let tokenToUse = token

        if (!isTokenValid(token)) {
            const newAccess = await refreshToken()
            if (!newAccess) {
                navigate(ROUTES.LOGIN.absPath)
                return
            }
            tokenToUse = newAccess
        }

        if (tokenToUse) {
            const response = await axios.request({
                method,
                url,
                ...(method === "get" ? { params: data } : { data }),
                ...config,
                headers: {
                    Authorization: `Bearer ${tokenToUse.token}`,
                    ...(config?.headers || {})
                },
            })
            return response.data
        }
    }

    const contextValue = useMemo(() => ({
        token,
        setToken,
        error,
        user,
        setUser,
        refreshToken,
        useFetch,
    }), [token, error, useFetch]);

    return (
        <AuthContext.Provider value={contextValue}>{children}</AuthContext.Provider>
    );
}

export const useAuthContext = () => {
    return useContext(AuthContext);
};

export default AuthProvider;

This can then be used to create a ProtectedRoute component:

import {Navigate, Outlet} from "react-router-dom";
import {isTokenValid, useAuthContext} from "../store/authContext.jsx";
import LoadingPage from "@/components/pages/loadingPage.jsx";
import {ROUTES} from "@/routes/index.jsx";

export default function ProtectedRoute() {
    const {token, error, refreshToken} = useAuthContext()

    if (token) {
        if (!isTokenValid(token)) {
            refreshToken()
        }
        return <Outlet/>
    }

    if (error?.status === 401 || error?.status === 403) {
        return <Navigate to={ROUTES.LOGIN.absPath}/>
    }

    return <LoadingPage/>
}

You can check out my full code in this repo. You will probably have a hard time running the project since it's unfinished, but I polished pretty well everything auth related in that frontent.