Custom Strategies

This is an advanced feature, so only attempt this if you are an experienced developer. Otherwise, just let FrogBot’s built-in authentication handle user auth for you.Development Note: Changes to custom authentication strategies require a full server restart to take effect. Auth strategies are not hot-reloaded during development. Consider using tools like nodemon for auto-restart functionality.

Creating a strategy

A strategy authenticates a user from information in an incoming request. A strategy is made up of the following:

Parameter	Type	Default	Description
`name`	`string`	Required	The name of your strategy.
`authenticate`	`(args: AuthStrategyFunctionArgs) => AuthStrategyResult \| Promise<AuthStrategyResult>`	Required	A function that takes the arguments below and returns an object with `user`, directly or as a promise.

The authenticate function is passed the following arguments:

Argument	Type	Default	Description
`canSetHeaders`	`boolean`	—	Whether the calling context can set response headers. Treat an omitted value as `false`.
`frogbot`	`FrogBot`	Always set	The initialized FrogBot instance. Use its Local API to look up users.
`headers`	`Headers`	Always set	The incoming request headers.
`isGraphQL`	`boolean`	—	Whether the strategy is running within the GraphQL endpoint. Treat an omitted value as `false`.
`req`	`FrogBotRequest`	—	The `FrogBotRequest`, when there is one. Some authentication calls have no request, so read credentials from `headers`.
`strategyName`	`string`	—	The name of the strategy being run.

authenticate returns an AuthStrategyResult:

Property	Type	Default	Description
`user`	`(TypedUser & { collection?: string; _strategy?: string }) \| null`	Required	The authenticated user document with its `collection` slug, or `null` when the request doesn’t identify a user.
`responseHeaders`	`Headers`	—	Headers added to the response. Only return them when `canSetHeaders` is `true`.

Example strategy

Import AuthStrategy from frogbot to type your strategy, then add it to an auth collection’s strategies array. Return { user: null } when the credentials are missing or do not identify a user. Otherwise, return the user document with its collection slug. You can also return responseHeaders: new Headers(...) when canSetHeaders is true. This example uses a per-user code as a credential. Keep it secret and send it only over HTTPS. With the local strategy disabled, custom user fields such as email may be nullable; return the complete document rather than requiring an email address.

import type { AuthStrategy, CollectionConfig } from 'frogbot';

export const codeStrategy: AuthStrategy = {
  name: 'code-strategy',
  authenticate: async ({ frogbot, headers, req }) => {
    const code = headers.get('code');

    if (!code) {
      return { user: null };
    }

    const usersQuery = await frogbot.find({
      collection: 'users',
      overrideAccess: true,
      depth: 0,
      limit: 1,
      req,
      where: {
        code: {
          equals: code,
        },
      },
    });

    const user = usersQuery.docs[0];

    return {
      user: user ? { ...user, collection: 'users' } : null,
    };
  },
};

export const Users: CollectionConfig = {
  slug: 'users',
  auth: {
    disableLocalStrategy: true,
    strategies: [codeStrategy],
  },
  fields: [
    {
      name: 'code',
      type: 'text',
      index: true,
      unique: true,
    },
    {
      name: 'email',
      type: 'text',
    },
  ],
};

When a strategy throws

If your strategy throws, FrogBot logs the error on the server with the collection and strategy names, then tries the next strategy. If no strategy authenticates a user, the request remains anonymous and normal access control applies. The authentication response never includes the reason the strategy failed.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Creating a strategy

Example strategy

When a strategy throws

​Creating a strategy

​Example strategy

​When a strategy throws

Creating a strategy

Example strategy

When a strategy throws