Skip to content

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".