Authentication

FerretDB does not store authentication information (usernames and passwords) itself but uses the backend’s authentication mechanisms. The default username and password can be specified in FerretDB’s connection string, but the client could use a different user by providing a username and password in MongoDB URI. For example, if the server was started with postgres://user1:pass1@postgres:5432/ferretdb, anonymous clients will be authenticated as user1, but clients that use mongodb://user2:pass2@ferretdb:27018/ferretdb?tls=true&authMechanism=PLAIN MongoDB URI will be authenticated as user2. Since usernames and passwords are transferred in plain text, the use of TLS is highly recommended.

PostgreSQL backend with default username and password

In following examples, default username and password are specified in FerretDB’s connection string user1:pass1. Ensure user1 is a PostgreSQL user with necessary privileges. See more about creating PostgreSQL user and PostgreSQL authentication methods.

Using ferretdb package

Start ferretdb by specifying --postgresql-url with default username and password.

ferretdb --postgresql-url=postgres://user1:pass1@localhost:5432/ferretdb

An anonymous client is authenticated with default user1 from --postgresql-url.

mongosh 'mongodb://127.0.0.1/ferretdb'

A client that specify username and password in MongoDB URI as below is authenticated as user2.

mongosh 'mongodb://user2:pass2@127.0.0.1/ferretdb?authMechanism=PLAIN'

Using Docker

For Docker, specify FERRETDB_POSTGRESQL_URL with default username and password.

services:
  postgres:
    image: postgres
    restart: on-failure
    environment:
      - POSTGRES_USER=username
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=ferretdb
    volumes:
      - ./data:/var/lib/postgresql/data
  ferretdb:
    image: ghcr.io/ferretdb/ferretdb
    restart: on-failure
    ports:
      - 27017:27017
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://user1:pass1@postgres:5432/ferretdb
networks:
  default:
    name: ferretdb

To start ferretdb, use docker compose.

docker compose up

An anonymous client is authenticated with user1 from FERRETDB_POSTGRESQL_URL. Use following command to run mongosh inside the temporary MongoDB container, attached to the same Docker network.

docker run --rm -it --network=ferretdb --entrypoint=mongosh \
  mongo 'mongodb://ferretdb/ferretdb'

A client that specify username and password in MongoDB URI as below is authenticated as user2.

docker run --rm -it --network=ferretdb --entrypoint=mongosh \
  mongo 'mongodb://user2:pass2@ferretdb/ferretdb?authMechanism=PLAIN'

Authentication Handshake

note

Some drivers may still use the legacy hello command to complete a handshake.

If you encounter any issues while authenticating with FerretDB, try setting the Stable API version to V1 on the client as this may prevent legacy commands from being used. Please refer to your specific driver documentation on how to set this field.

If this does not resolve your issue please file a bug report here.