Cookie Strategy

FrogBot offers the ability to Authenticate via HTTP-only cookies. These can be read from the responses of login, logout, refresh, and me auth operations. FrogBot uses the frogbot cookie prefix by default. Authentication tokens are stored in frogbot-token; language and theme preferences use frogbot-lng and frogbot-theme. While a user is in a “Sign in with …” or “Connect account” flow, FrogBot also sets a short-lived OAuth state cookie, frogbot-oauth-<state>, or __Host-frogbot-oauth-<state> when the callback URL is https. It lasts 10 minutes and is cleared when the provider redirects back. You can override the prefix with the root cookiePrefix configuration option. Every cookie above follows it:

import { buildConfig } from 'frogbot'

export default buildConfig({
  cookiePrefix: 'acme', // acme-token, acme-theme, acme-lng, acme-oauth-<state>
})

Apps upgrading from the previous default invalidate existing payload-token sessions. Users must log in once after the upgrade. Changing cookiePrefix has the same effect, and an OAuth sign-in or account connection in progress during the change fails and must be started again.

Browser storage

The admin panel also keeps some short-lived UI state in browser storage. These keys have fixed names, never leave the browser and don’t follow cookiePrefix:

sessionStorage payload-pending-success-toast, after saving a document;
localStorage _payloadClipboard, when copying a field or row.

Tip: You can access the logged-in user from within Access Control and Hooks through the req.user argument. More details.

Automatic browser inclusion

Modern browsers automatically include http-only cookies when making requests directly to URLs—meaning that if you are running your API on https://example.com, and you have logged in and visit https://example.com/test-page, your browser will automatically include the FrogBot authentication cookie for you.

HTTP Authentication

However, if you use fetch or similar APIs to retrieve FrogBot resources from its REST or GraphQL API, you must specify to include credentials (cookies). Fetch example, including credentials:

const response = await fetch('http://localhost:3000/api/pages', {
  credentials: 'include',
})

const pages = await response.json()

For more about including cookies in requests from your app to your FrogBot API, read the MDN docs.

Tip: To make sure you have a FrogBot cookie set properly in your browser after logging in, you can use the browsers Developer Tools > Application > Cookies > [your-domain-here]. The Developer tools will still show HTTP-only cookies.

CSRF Attacks

CSRF (cross-site request forgery) attacks are common and dangerous. By using an HTTP-only cookie, FrogBot removes many XSS vulnerabilities, however, CSRF attacks can still be possible. For example, let’s say you have a popular app https://frogbot-finances.com that allows users to manage finances, send and receive money. As FrogBot is using HTTP-only cookies, that means that browsers automatically will include cookies when sending requests to your domain - no matter what page created the request. So, if a user of https://frogbot-finances.com is logged in and is browsing around on the internet, they might stumble onto a page with malicious intent. Let’s look at an example:

// malicious-intent.com
// makes an authenticated request as on your behalf

const maliciousRequest = await fetch(`https://frogbot-finances.com/api/me`, {
  credentials: 'include',
}).then((res) => await res.json())

In this scenario, if your cookie was still valid, malicious-intent.com would be able to make requests like the one above on your behalf. This is a CSRF attack.

CSRF Prevention

Define domains that you trust and are willing to accept FrogBot HTTP-only cookie based requests from. Use the csrf option on the base FrogBot Config to do this:

// frogbot.config.ts

import { buildConfig } from 'frogbot'

const config = buildConfig({
  serverURL: 'https://my-frogbot-instance.com',
  csrf: [
    // whitelist of domains to allow cookie auth from
    'https://your-frontend-app.com',
    'https://your-other-frontend-app.com',
    // `config.serverURL` is added by default if defined
  ],
  collections: [
    // collections here
  ],
})

export default config

Cross domain authentication

If your frontend is on a different domain than your FrogBot API then you will not be able to use HTTP-only cookies for authentication by default as they will be considered third-party cookies by the browser. There are a few strategies to get around this:

1. Use subdomains

Cookies can cross subdomains without being considered third party cookies, for example if your API is at api.example.com then you can authenticate from example.com.

2. Configure cookies

If option 1 isn’t possible, then you can get around this limitation by configuring your cookies on your authentication collection to achieve the following setup:

SameSite: None // allows the cookie to cross domains
Secure: true // ensures it's sent over HTTPS only
HttpOnly: true // ensures it's not accessible via client side JavaScript

Configuration example:

{
  slug: 'users',
  auth: {
    cookies: {
      sameSite: 'none',
      secure: true,
    }
  },
  fields: [
    // your auth fields here
  ]
},

If you’re configuring cors in your FrogBot config, you cannot use a wildcard and must specify the list of allowed domains.

Good to know: Setting up secure: true will not work if you’re developing on http://localhost or any non-https domain. For local development you should conditionally set this to false based on the environment.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Browser storage

Automatic browser inclusion

HTTP Authentication

CSRF Attacks

CSRF Prevention

Cross domain authentication

1. Use subdomains

2. Configure cookies

​Cookie names

​Browser storage

​Automatic browser inclusion

​HTTP Authentication

​CSRF Attacks

​CSRF Prevention

​Cross domain authentication

1. Use subdomains

2. Configure cookies

Cookie names

Browser storage

Automatic browser inclusion

HTTP Authentication

CSRF Attacks

CSRF Prevention

Cross domain authentication