Configuration

Container Environment Variables

You can configure all three components of the authentication server either by passing the relevant CLI flags or through the environment. As you'll notice throughout the following, the environment variable name are identical to the CLI flags, except that they have a per-service prefix and all punctuation is replaced with underscores. If you are deploying through Docker Compose, the recommended way to update the environment is adding the options to the environment: section. Similarly, Kubernetes allows specifying a container's environment in the env: map.

Additionally, you could also use envconsul to inject them from a Consul instance before starting the process. This approach requires an additional step, as you would need to write your own Dockerfile, inheriting from our distributed images and updating the environment in a custom entrypoint.sh script. Note that our images are based on the special scratch image, so it is possible to copy the binary for the service you are rebuilding from the container's root.

nextAuth Server

Database

NEXTAUTH_NS_DB_URI(_FILE)

--db.uri(-file) string
Database URI to connect to (defaults to ":memory:").

Dialect	URI
MySQL/MariaDB	mysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?loc=Local
PostgreSQL	postgres://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}

NEXTAUTH_NS_DB_LOG_MODE

--db.log-mode
Enable detailed database logs.

NEXTAUTH_NS_DB_CONNECTION_MAX_IDLE_TIME

--db.connection-max-idle-time duration
Maximum amount of time a database connection may be idle.

NEXTAUTH_NS_DB_CONNECTION_MAX_LIFETIME

--db.connection-max-lifetime duration
Maximum amount of time a database connection may be reused.

NEXTAUTH_NS_DB_MAX_IDLE_CONNECTIONS

--db.max-idle-connections int
Maximum number of database connections in the idle connection pool (defaults to 2).

NEXTAUTH_NS_DB_MAX_OPEN_CONNECTIONS

--db.max-open-connections int
Maximum number of open connections to the database.

NEXTAUTH_NS_DB_CLEANUP_INTERVAL

--db.cleanup-interval duration
Period between database cleanups (defaults to 1m0s).

NEXTAUTH_NS_DB_ENABLE_MIGRATIONS

--db.enable-migrations
Whether database migrations should be applied automatically.

Key-Value Store

NEXTAUTH_NS_KV_URI(_FILE)

--kv.uri(-file) string
Key-value store URI to connect to. This flag can remain empty if no key-value store backend is used.

Backend	URI
Redis	redis://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}
Redis Cluster	redis://{USERNAME}:{PASSWORD}@{HOST}:{PORT},{HOST}:{PORT},{HOST}:{PORT}/{DATABASE}?maxRedirects={MAX REDIRECTS}&readOnly=false&routeByLatency=false&routeRandomly=false
Redis Sentinel	redis-sentinel://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?sentinelMaster={SENTINEL MASTER}

When configuring a Redis Cluster, maxRedirects configures the maximum number of retries before giving up (defaults to eight). Furthermore, setting one of the readOnly, routeByLatency, or routeRandomly parameters will respectively route read-only commands only to slave nodes, to the closest master or slave node, or to a random master or slave node.

Info

The redis and redis-sentinel schemes have secure variants rediss and rediss-sentinel which will enable TLS for the connection to Redis.

Transports

HTTP

NEXTAUTH_NS_HTTP_ADDR

--http.addr string
Listen address for the HTTP transport (defaults to ":8080").

NEXTAUTH_NS_HTTP_TLS_CERTIFICATE(_FILE)

--http.tls-certificate(-file) string
PEM-encoded TLS certificate for the HTTP transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_HTTP_TLS_KEY(_FILE)

--http.tls-key(-file) string
PEM-encoded TLS private key for the HTTP transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_HTTP_TLS_CLIENT_AUTH

--http.tls-client-auth string
TLS client authentication policy for the HTTP transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_NS_HTTP_TLS_VERIFY_PEER

--http.tls-verify-peer
Close connection for unregistered peers (see here).

SIGMA-I

NEXTAUTH_NS_SIGMAI_ADDR

--sigmai.addr string
Listen address for the SIGMA-I transport (defaults to ":8888").

NEXTAUTH_NS_SIGMAI_TLS_CERTIFICATE(_FILE)

--sigmai.tls-certificate(-file) string
PEM-encoded TLS certificate for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_SIGMAI_TLS_KEY(_FILE)

--sigmai.tls-key(-file) string
PEM-encoded TLS private key for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_SIGMAI_TLS_CLIENT_AUTH

--sigmai.tls-client-auth string
TLS client authentication policy for the SIGMA-I transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_NS_SIGMAI_LEGACY

--sigmai.legacy
Enable legacy SIGMA-I support.

Warning

Please contact nextAuth to determine whether you should toggle this option.

WebSocket

NEXTAUTH_NS_WEBSOCKET_ADDR

--websocket.addr string
Listen address for the WebSocket transport (defaults to ":9999").

NEXTAUTH_NS_WEBSOCKET_TLS_CERTIFICATE(_FILE)

--websocket.tls-certificate(-file) string
PEM-encoded TLS certificate for the WebSocket transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_WEBSOCKET_TLS_KEY(_FILE)

--websocket.tls-key(-file) string
PEM-encoded TLS private key for the WebSocket transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_WEBSOCKET_TLS_CLIENT_AUTH

--websocket.tls-client-auth string
TLS client authentication policy for the WebSocket transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

Admin

NEXTAUTH_NS_ADMIN_ADDR

--admin.addr string
Listen address for the admin transport (defaults to ":9613").

NEXTAUTH_NS_ADMIN_TLS_CERTIFICATE(_FILE)

--admin.tls-certificate(-file) string
PEM-encoded TLS certificate for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_ADMIN_TLS_KEY(_FILE)

--admin.tls-key(-file) string
PEM-encoded TLS private key for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_NS_ADMIN_TLS_CLIENT_AUTH

--admin.tls-client-auth string
TLS client authentication policy for the admin transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_NS_ADMIN_DEBUG

--admin.debug
Enable additional endpoints for debugging and profiling.

NEXTAUTH_NS_ADMIN_SWAGGER

--admin.swagger
Enable /swagger endpoint on the Admin transport (see Network Setup).

Authentication

NEXTAUTH_NS_ROOT_API_KEY(_FILE)

--root-api-key(-file) string
Key which is granted root permissions.

License

NEXTAUTH_NS_LICENSE(_FILE)

--license(-file) string
Optional license issued by nextAuth. Please contact support for more information.

Defaults

NEXTAUTH_NS_DEFAULT_APP_NAME

--default-app-name string
Name of the default app (e.g., nextAuth). Note that changing this setting will update the name for all existing servers where it was not set explicitly.

NEXTAUTH_NS_DEFAULT_APP_ANDROID

--default-app-android string
Default app distribution URL for Android (e.g., https://play.google.com/store/apps/details?id=com.nauth.client). Note that changing this setting will update the URL for all existing servers where it was not set explicitly.

NEXTAUTH_NS_DEFAULT_APP_IOS

--default-app-ios string
Default app distribution URL for iOS (e.g., https://apps.apple.com/be/app/nextauth/id1176128845). Note that changing this setting will update the URL for all existing servers where it was not set explicitly.

NEXTAUTH_NS_DEFAULT_SITE_URL

--default-site-url string
Default URL of the main website (e.g., https://mydomain.com).

NEXTAUTH_NS_DEFAULT_SIGMAI_URI

--default-sigmai-uri string
Default SIGMA-I connection URI (e.g., wss://nextauth.mydomain.com/ns/sigmai).

NEXTAUTH_NS_DEFAULT_WEBSOCKET_URI

--default-websocket-uri string
Default WebSocket connection URI (e.g., wss://nextauth.mydomain.com/ns/websocket).

NEXTAUTH_NS_DEFAULT_SFS_SERVER_ID

--default-sfs-server-id string
Server ID of the default Second Factor Server.

Warning

Changes to this value will not affect existing servers. If you have not already created a server on the SFS (see here), you can do so through its sfs server create command, which will print this argument's value.

NEXTAUTH_NS_DEFAULT_SFS_PUBLIC_KEY

--default-sfs-public-key string
Default Second Factor Server public key.

Warning

Changes to this value will not affect existing servers. If you have not already created a server on the SFS (see here), you can do so through its sfs server create command, which will print this argument's value.

NEXTAUTH_NS_LEGACY_PUSH_CREDENTIALS(_FILE)

--legacy-push-credentials(-file) string Push message credentials (Firebase Cloud Messaging) for legacy mobile app.

Warning

Please contact nextAuth to determine whether you should set this option.

Logging

NEXTAUTH_NS_LOG_FORMAT

--log-format string
Output format of the logs. Allowed values are "logfmt" and "json". Defaults to "logfmt".

NEXTAUTH_NS_LOG_LEVEL

--log-level string
Filters all log events below this level. Allowed values are "fatal", "panic", "dpanic", "error", "warn", "info", and "debug". Defaults to "info".

X-Forwarded-For

NEXTAUTH_NS_XFF_HEADERS

--xff.headers strings
Ordered list of header keys referencing the client ip (defaults to [X-Real-IP,X-Forwarded-For]).

Second Factor Server

Database

NEXTAUTH_SFS_DB_URI(_FILE)

--db.uri(-file) string
Database URI to connect to (defaults to ":memory:").

Dialect	URI
MySQL/MariaDB	mysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?loc=Local
PostgreSQL	postgres://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}

NEXTAUTH_SFS_DB_LOG_MODE

--db.log-mode
Enable detailed database logs.

NEXTAUTH_SFS_DB_CONNECTION_MAX_IDLE_TIME

--db.connection-max-idle-time duration
Maximum amount of time a database connection may be idle.

NEXTAUTH_SFS_DB_CONNECTION_MAX_LIFETIME

--db.connection-max-lifetime duration
Maximum amount of time a database connection may be reused.

NEXTAUTH_SFS_DB_MAX_IDLE_CONNECTIONS

--db.max-idle-connections int
Maximum number of database connections in the idle connection pool (defaults to 2).

NEXTAUTH_SFS_DB_MAX_OPEN_CONNECTIONS

--db.max-open-connections int
Maximum number of open connections to the database.

NEXTAUTH_SFS_DB_ENABLE_MIGRATIONS

--db.enable-migrations
Whether database migrations should be applied automatically.

Transports

SIGMA-I

NEXTAUTH_SFS_SIGMAI_ADDR

--sigmai.addr string
Listen address for the SIGMA-I transport (defaults to ":8888").

NEXTAUTH_SFS_SIGMAI_TLS_CERTIFICATE(_FILE)

--sigmai.tls-certificate(-file) string
PEM-encoded TLS certificate for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_SFS_SIGMAI_TLS_KEY(_FILE)

--sigmai.tls-key(-file) string
PEM-encoded TLS private key for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_SFS_SIGMAI_TLS_CLIENT_AUTH

--sigmai.tls-client-auth string
TLS client authentication policy for the SIGMA-I transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

Admin

NEXTAUTH_SFS_ADMIN_ADDR

--admin.addr string
Listen address for the admin transport (defaults to ":9613").

NEXTAUTH_SFS_ADMIN_TLS_CERTIFICATE(_FILE)

--admin.tls-certificate(-file) string
PEM-encoded TLS certificate for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_SFS_ADMIN_TLS_KEY(_FILE)

--admin.tls-key(-file) string
PEM-encoded TLS private key for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_SFS_ADMIN_TLS_CLIENT_AUTH

--admin.tls-client-auth string
TLS client authentication policy for the admin transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_SFS_ADMIN_DEBUG

--admin.debug
Enable additional endpoints for debugging and profiling.

Logging

NEXTAUTH_SFS_LOG_FORMAT

--log-format string
Output format of the logs. Allowed values are "logfmt" and "json". Defaults to "logfmt".

NEXTAUTH_SFS_LOG_LEVEL

--log-level string
Filters all log events below this level. Allowed values are "fatal", "panic", "dpanic", "error", "warn", "info", and "debug". Defaults to "info".

Message Center

Database

NEXTAUTH_MC_DB_URI(_FILE)

--db.uri(-file) string
Database URI to connect to (defaults to ":memory:").

Dialect	URI
MySQL/MariaDB	mysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?loc=Local
PostgreSQL	postgres://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}

NEXTAUTH_MC_DB_LOG_MODE

--db.log-mode
Enable detailed database logs.

NEXTAUTH_MC_DB_CONNECTION_MAX_IDLE_TIME

--db.connection-max-idle-time duration
Maximum amount of time a database connection may be idle.

NEXTAUTH_MC_DB_CONNECTION_MAX_LIFETIME

--db.connection-max-lifetime duration
Maximum amount of time a database connection may be reused.

NEXTAUTH_MC_DB_MAX_IDLE_CONNECTIONS

--db.max-idle-connections int
Maximum number of database connections in the idle connection pool (defaults to 2).

NEXTAUTH_MC_DB_MAX_OPEN_CONNECTIONS

--db.max-open-connections int
Maximum number of open connections to the database.

NEXTAUTH_MC_DB_CLEANUP_INTERVAL

--db.cleanup-interval duration
Period between database cleanups (defaults to 1m0s).

NEXTAUTH_MC_DB_ENABLE_MIGRATIONS

--db.enable-migrations
Whether database migrations should be applied automatically.

Transports

HTTP

NEXTAUTH_MC_HTTP_ADDR

--http.addr string
Listen address for the HTTP transport (defaults to ":8080").

NEXTAUTH_MC_HTTP_TLS_CERTIFICATE(_FILE)

--http.tls-certificate(-file) string
PEM-encoded TLS certificate for the HTTP transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_HTTP_TLS_KEY(_FILE)

--http.tls-key(-file) string
PEM-encoded TLS private key for the HTTP transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_HTTP_TLS_CLIENT_AUTH

--http.tls-client-auth string
TLS client authentication policy for the HTTP transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_MC_HTTP_TLS_VERIFY_PEER

--http.tls-verify-peer
Close connection for unregistered peers (see here).

gRPC

NEXTAUTH_MC_GRPC_ADDR

--grpc.addr string
Listen address for the gRPC transport (defaults to ":9090").

NEXTAUTH_MC_GRPC_TLS_CERTIFICATE(_FILE)

--grpc.tls-certificate(-file) string
PEM-encoded TLS certificate for the gRPC transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_GRPC_TLS_KEY(_FILE)

--grpc.tls-key(-file) string
PEM-encoded TLS private key for the gRPC transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_GRPC_TLS_CLIENT_AUTH

--grpc.tls-client-auth string
TLS client authentication policy for the gRPC transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_MC_GRPC_TLS_VERIFY_PEER

--grpc.tls-verify-peer
Close connection for unregistered peers (see here).

SIGMA-I

NEXTAUTH_MC_SIGMAI_ADDR

--sigmai.addr string
Listen address for the SIGMA-I transport (defaults to ":8888").

NEXTAUTH_MC_SIGMAI_PUBLIC_KEY

--sigmai.public-key string
Public key for the SIGMA-I transport.

NEXTAUTH_MC_SIGMAI_SECRET_KEY(_FILE)

--sigmai.secret-key(-file) string
Secret key for the SIGMA-I transport or alternatively the path to the secret key file.

NEXTAUTH_MC_SIGMAI_TLS_CERTIFICATE(_FILE)

--sigmai.tls-certificate(-file) string
PEM-encoded TLS certificate for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_SIGMAI_TLS_KEY(_FILE)

--sigmai.tls-key(-file) string
PEM-encoded TLS private key for the SIGMA-I transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_SIGMAI_TLS_CLIENT_AUTH

--sigmai.tls-client-auth string
TLS client authentication policy for the SIGMA-I transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

Admin

NEXTAUTH_MC_ADMIN_ADDR

--admin.addr string
Listen address for the admin transport (defaults to ":9613").

NEXTAUTH_MC_ADMIN_TLS_CERTIFICATE(_FILE)

--admin.tls-certificate(-file) string
PEM-encoded TLS certificate for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_ADMIN_TLS_KEY(_FILE)

--admin.tls-key(-file) string
PEM-encoded TLS private key for the admin transport. This flag can remain empty if TLS should not be enabled.

NEXTAUTH_MC_ADMIN_TLS_CLIENT_AUTH

--admin.tls-client-auth string
TLS client authentication policy for the admin transport. Allowed values are "no-client-certificate", "request-client-certificate", "require-any-client-certificate", "verify-client-certificate-if-given", "require-and-verify-client-certificate". Defaults to "no-client-certificate".

NEXTAUTH_MC_ADMIN_DEBUG

--admin.debug
Enable additional endpoints for debugging and profiling.

Authentication

NEXTAUTH_MC_ROOT_API_KEY(_FILE)

--root-api-key(-file) string
Key which is granted root permissions.

Encryption

NEXTAUTH_MC_BOX_PUBLIC_KEY

--box.public-key string
Public key for the instance ID encryption.

NEXTAUTH_MC_BOX_SECRET_KEY(_FILE)

--box.secret-key(-file) string
Secret key for the instance ID encryption or alternatively the path to the secret key file.

Logging

NEXTAUTH_MC_LOG_FORMAT

--log-format string
Output format of the logs. Allowed values are "logfmt" and "json". Defaults to "logfmt".

NEXTAUTH_MC_LOG_LEVEL

--log-level string
Filters all log events below this level. Allowed values are "fatal", "panic", "dpanic", "error", "warn", "info", and "debug". Defaults to "info".

Management

The mgmt Docker image contains the management interface for the Authentication Server, providing both the Dashboard and Account Management. Similar to the Authentication Server, it can be configured through environment variables.

NEXTAUTH_ROOT_APIKEY

Root API key for the nextAuth Server API.

NEXTAUTH_SERVER_URL

Base URL for the nextAuth Server API (e.g., http://ns:8080).