Environment variables¶

Fief server relies heavily on environment variables for configuration. You'll likely need to adjust those settings for your deployment.

Set environment variables¶

Using Docker¶

When running Fief server with Docker, the most straightforward way is to use the -e option on the command line, as shown in Getting started.

docker run \
  --name fief-server \
  -p 8000:8000 \
  -d \
  -e "SECRET=XXX" \
  -e "FIEF_CLIENT_ID=XXX" \
  -e "FIEF_CLIENT_SECRET=XXX" \
  -e "ENCRYPTION_KEY=XXX" \
  -e "PORT=8000" \
  -e "FIEF_DOMAIN=localhost:8000" \
  -e "CSRF_COOKIE_SECURE=False" \
  -e "LOGIN_SESSION_COOKIE_SECURE=False" \
  -e "SESSION_COOKIE_SECURE=False" \
  -e "FIEF_ADMIN_SESSION_COOKIE_SECURE=False" \
  ghcr.io/fief-dev/fief:latest

However, it may become hard to maintain when having lot of variables to set. An alternative way is to use a .env file. It's a simple file where each line consists of a key and a value separated by an equal sign:

.env

SECRET=XXX
FIEF_CLIENT_ID=XXX
FIEF_CLIENT_SECRET=XXX
ENCRYPTION_KEY=XXX
PORT=8000
FIEF_DOMAIN=localhost:8000
CSRF_COOKIE_SECURE=False
LOGIN_SESSION_COOKIE_SECURE=False
SESSION_COOKIE_SECURE=False
FIEF_ADMIN_SESSION_COOKIE_SECURE=False

Then, you can reference this file in the Docker command:

docker run \
  --name fief-server \
  -p 8000:8000 \
  -d \
  --env-file .env \
  ghcr.io/fief-dev/fief:latest

Other methods of deployment¶

Depending on your method of deployment, the way of setting environment variables will be different. We show you several ways of deploying Fief in production in the previous section.

Reference¶

For each variable, we'll try to provide a sensible example value to help you configure it correctly. Throughout the examples, we'll assume that you host your Fief server on the sub-domain fief.bretagne.duchy.

General¶

Name	Description	Default	Allowed values	Example
`ENVIRONMENT`	Name of the deployment environment	production	development, staging, production	production
`LOG_LEVEL`	Log verbosity
`TELEMETRY_ENABLED`	Whether to enable telemetry	True
`ALLOW_ORIGIN_REGEX`	Regex used to control CORS access to your API	http://.*localhost:[0-9]+		https://.*\.bretagne.duchy
`PORT`	Internal port on which the Fief server is available	8000		8000
`FORWARDED_ALLOW_IPS`	Comma separated list of IPs to trust with proxy headers. Read more	127.0.0.1

Secrets¶

Name	Description	Allowed values
`SECRET`	Secret value used to sign reset password tokens.	Any sufficiently long string
`ENCRYPTION_KEY`	Key used to encrypt the external databases credentials inside the main database	A valid Fernet key encoded in UTF-8
`GENERATED_JWK_SIZE`	Size in bits of the generated RSA key pair used to sign JWT.	4096

Encryption key generator

The encryption key should be a valid key for the Fernet encryption algorithm. Use the generator above to get yours! Keep it secret.

Database¶

Name	Description	Default	Allowed values	Example
`DATABASE_TYPE`	Type of the main database	SQLITE	POSTGRESQL, MYSQL, SQLITE	POSTGRESQL
`DATABASE_HOST`	Host of the main database			localhost
`DATABASE_PORT`	Listening port of the main database			5432
`DATABASE_USERNAME`	Main database user			fief
`DATABASE_PASSWORD`	Main database user's password			fiefpassword
`DATABASE_NAME`	Main database name	fief.db		fief
`DATABASE_SSL_MODE`	Main database SSL mode		Varies by database type	require
`DATABASE_LOCATION`	For SQLite databases, path where to store the database files	Current working directory
`DATABASE_POOL_RECYCLE_SECONDS`	Maximum lifetime in seconds of a database connection in the connection pool. Useful for servers cutting idle connections after some time. Read more.	600 (10 minutes)
`DATABASE_POOL_PRE_PING`	Whether to always issue a query before returning a database connection to make sure it's alive. Read more.	False
`DATABASE_POOL_SIZE`	Number of connections to the database to keep alive. Read more.	5
`DATABASE_POOL_MAX_OVERFLOW`	Maximum number of extra database connection to spawn when pool size is reached. Read more.	10
`DATABASE_URL`	Full database connection string, useful for some cloud providers. It'll take precedence over the single parameters above.

More details about how to configure a database in the dedicated section.

Configure database

Redis¶

We use a Redis instance to manage background jobs (send emails, heavy computations...). A Redis instance is already up-and-running in the official Docker image, but you can provide your own one if needed.

Name	Description	Default	Allowed values	Example
`REDIS_URL`	URL of a Redis server	redis://localhost:6379

Email provider¶

Name	Description	Default	Allowed values	Example
`EMAIL_PROVIDER`	Type of email provider	NULL	NULL, SMTP, POSTMARK, SENDGRID	POSTMARK
`EMAIL_PROVIDER_PARAMS`	Configuration dictionary of the email provider	{}		{"server_token": "XXX-XXX"}
`DEFAULT_FROM_EMAIL`	Default transactional emails sender email address	contact@fief.dev		contact@bretagne.duchy
`DEFAULT_FROM_NAME`	Default transactional emails sender name	Fief		Bretagne

More details about how to configure an email provider in the dedicated section.

Configure email provider

Webhooks¶

Name	Description	Default	Allowed values	Example
`WEBHOOKS_MAX_ATTEMPTS`	Maximum attempts to deliver a webhook event before giving up.	5

To protect against Cross-Site-Request-Forgery attacks on authentication pages, we use the double-submit cookie pattern.

Name	Description	Default
`CSRF_CHECK_ENABLED`	Whether to enable the CSRF protection. In most cases, this should remain enabled.	True
`CSRF_COOKIE_NAME`	Name of the CSRF token cookie	fief_csrftoken
`CSRF_COOKIE_SECURE`	Secure flag of the login session cookie	True

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

The user locale cookie maintains the language of the user on the authentication pages.

Name	Description	Default
`USER_LOCALE_COOKIE_NAME`	Name of the user locale cookie	fief_locale
`USER_LOCALE_COOKIE_DOMAIN`	Domain of the user locale cookie	Empty string
`USER_LOCALE_COOKIE_SECURE`	Secure flag of user locale cookie	True
`USER_LOCALE_LIFETIME_SECONDS`	Lifetime of the user locale cookie in seconds	86400 * 30 (30 days)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

The login hint cookie is used to remember the last method a user used to login. Its value can either be an email address or the ID of an OAuth Provider enabled on the user's tenant.

Name	Description	Default
`LOGIN_HINT_COOKIE_NAME`	Name of the login hint cookie	fief_login_hint
`LOGIN_HINT_COOKIE_DOMAIN`	Domain of the login hint cookie	Empty string
`LOGIN_HINT_COOKIE_SECURE`	Secure flag of login hint cookie	True
`LOGIN_HINT_COOKIE_LIFETIME_SECONDS`	Lifetime of the login hint cookie in seconds	86400 * 30 (30 days)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

A login session is a cookie used to maintain the state of the login flow of a user, from the login page until they're redirected to your application.

Name	Description	Default
`LOGIN_SESSION_COOKIE_NAME`	Name of the login session cookie	fief_login_session
`LOGIN_SESSION_COOKIE_DOMAIN`	Domain of the login session cookie	Empty string
`LOGIN_SESSION_COOKIE_SECURE`	Secure flag of the login session cookie	True
`LOGIN_SESSION_LIFETIME_SECONDS`	Lifetime of the login session cookie in seconds	600 (10 minutes)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

Registration session¶

A registration session is a cookie used to maintain the state of the registration flow of a new user, from the registration page until their account is created.

Name	Description	Default
`REGISTRATION_SESSION_COOKIE_NAME`	Name of the registration session cookie	fief_registration_session
`REGISTRATION_SESSION_COOKIE_DOMAIN`	Domain of the registration session cookie	Empty string
`REGISTRATION_SESSION_COOKIE_SECURE`	Secure flag of the registration session cookie	True
`REGISTRATION_SESSION_LIFETIME_SECONDS`	Lifetime of the registration session cookie in seconds	600 (10 minutes)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

Email verification¶

Users must verify their email address using a code sent by email. The code is a random string composed of letters and digits, e.g. ABC123.

Name	Description	Default	Allowed values	Example
`EMAIL_VERIFICATION_CODE_LENGTH`	Length of the verification code	6
`EMAIL_VERIFICATION_LIFETIME_SECONDS`	Lifetime of the verification code in seconds	3600 (1 hour)

OAuth session¶

An OAuth session is used to maintain the state of an OAuth authentication with an OAuth Provider, from the moment they click on the Sign in with... button until they're redirected.

Name	Description	Default	Allowed values	Example
`OAUTH_SESSION_LIFETIME_SECONDS`	Lifetime of the OAuth session in seconds	600 (10 minutes)

Session¶

A session is a cookie used to maintain the session of a user on the Fief authentication pages. It's different from the session you'll maintain in your own application.

Its purpose is to allow a user to re-authenticate quickly to your app without having them to input their credentials again.

Name	Description	Default
`SESSION_COOKIE_NAME`	Name of the session cookie	fief_session
`SESSION_COOKIE_DOMAIN`	Domain of the session cookie	Empty string
`SESSION_COOKIE_SECURE`	Secure flag of the session cookie	True
`SESSION_LIFETIME_SECONDS`	Lifetime of the session cookie in seconds	86400 * 30 (30 days)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

Client redirect URIs¶

Name	Description	Default	Allowed values	Example
`CLIENT_REDIRECT_URI_SSL_REQUIRED`	Whether to enforce the use of HTTPS URL for Client redirect URIs	True

This flag should be True in production

Using SSL/HTTPS URLs for the OAuth2 callback is critical for security. Allowing a non-encrypted redirection could enable malicious users to steal the authorization code during the process.

This flag is provided for convenience when running Fief in development and testing environments.

Authorization codes and tokens lifetimes¶

Authorization codes are temporary codes generated during the OAuth2 authentication flow. Access tokens, ID tokens and refresh tokens are generated after a successful OAuth2 authentication flow.

The variables below control the default lifetime for each one of them when a client is created. Those values can then be customized per client.

Name	Description	Default
`DEFAULT_AUTHORIZATION_CODE_LIFETIME_SECONDS`	Default lifetime of the authorization code in seconds. For security reasons, this value should remain low. OAuth2 specification recommends a value of 10 minutes.	600 (10 minutes)
`DEFAULT_ACCESS_ID_TOKEN_LIFETIME_SECONDS`	Default lifetime of the access token and ID token in seconds.	86400 (24 hours)
`DEFAULT_REFRESH_TOKEN_LIFETIME_SECONDS`	Default lifetime of the refresh token in seconds.	2592000 (30 days)

Fief-ception¶

Fief-ception is a mind-fucking concept describing the fact that we actually use Fief to authenticate Fief admins 🤯

That's why we set necessary variables to create the main client and first admin user, as described in the Getting started section.

The variables below are here to configure the Fief server with a proper Fief client, as you would do in your own application!

Name	Description	Default	Example
`FIEF_DOMAIN`	Domain of your Fief instance	localhost:8000	fief.bretagne.duchy
`FIEF_CLIENT_ID`	Client ID in your instance
`FIEF_CLIENT_SECRET`	Client secret in your instance
`FIEF_ENCRYPTION_KEY`	Optional RSA key used to encrypt the JWT tokens
`FIEF_MAIN_USER_EMAIL`	Email address of the first admin user. If provided, the user will be created automatically on startup.		anne@bretagne.duchy
`FIEF_MAIN_USER_PASSWORD`	Password of the first admin user. If `FIEF_MAIN_USER_EMAIL` is provided, the user will be created automatically on startup with this password. Otherwise, a random password will be generated.		SuperSecretAndStrongPassword
`FIEF_MAIN_ADMIN_API_KEY`	Admin API token to create at server startup		SuperSecretAndStrongToken

Admin session¶

An admin session is a cookie used to maintain the session of a user on the Fief admin dashboard.

Name	Description	Default
`FIEF_ADMIN_SESSION_COOKIE_NAME`	Name of the admin session cookie	fief_admin_session
`FIEF_ADMIN_SESSION_COOKIE_DOMAIN`	Domain of the admin session cookie	Empty string
`FIEF_ADMIN_SESSION_COOKIE_SECURE`	Secure flag of the admin session cookie	True

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

Session data¶

The admin session data is a mechanism to store temporary data during the session of a user on the Fief admin dashboard.

Name	Description	Default
`SESSION_DATA_COOKIE_NAME`	Name of the session data cookie	fief_session_data
`SESSION_DATA_COOKIE_DOMAIN`	Domain of the session data cookie	Empty string
`SESSION_DATA_COOKIE_SECURE`	Secure flag of the session data cookie	True
`SESSION_DATA_COOKIE_LIFETIME_SECONDS`	Lifetime of the registration session cookie in seconds	`None` (session cookie)

_COOKIE_SECURE flag should be True in production

Browser cookies support the Secure flag, which tells the browser to not forward the cookie if the site is not requested in HTTPS.

For your convenience when starting Fief on your local machine, the Quickstart command will set those flags to False for every Fief cookies.

However, for security reasons, it's strongly recommended to set those flags to True (the default if not specified) when deploying to production.

Environment variables¶

Set environment variables¶

Using Docker¶

Other methods of deployment¶

Reference¶

General¶

Secrets¶

Database¶

Redis¶

Email provider¶

Webhooks¶

CSRF cookie¶

User locale cookie¶

Login hint cookie¶

Login session¶

Registration session¶

Email verification¶

OAuth session¶

Session¶

Client redirect URIs¶

Authorization codes and tokens lifetimes¶

Fief-ception¶

Admin session¶

Session data¶