Skip to main content

Environment Variables

The env vars are only applicable to the Jackson service. If you are using the npm library then look for the options below when initializing the library.

General configuration​

HOSTNAME​

If you need to bind to a specific hostname, you can define HOSTNAME environment variable. For example, if you are planning to use a Docker health check like wget -q --spider http://localhost:{PORT}/api/health || exit 1 set HOSTNAME=0.0.0.0 to listen to localhost.

HOST_URL​

The URL to bind to. Default: localhost

PORT​

The port to bind to. Default: 5225

EXTERNAL_URL​

The public URL to reach this service. This is used internally to construct the callback url at which the SAML/OIDC IdP sends back the authorization response.

Default: http://{HOST_URL}:{PORT}

NPM library option: externalUrl

JACKSON_API_KEYS​

A comma separated list of API keys that will be validated when serving the API requests for SSO connection (/api/v1/connections) and Directory Sync (/api/v1/directory-sync).

For example JACKSON_API_KEYS=key1,key2,key3

The API requests will then need to specify an Authorization header which contains one of the API keys above in this format: Api-Key key1

SAML_AUDIENCE​

The value of this setting (same as SP EntityID of Jackson) allows the Jackson instance to verify that it is the intended recipient of a SAML response. The same value is also set in the SAML App created on the IdP end by your customers. Once set do not change this value unless you get your customers to reconfigure their SAML App again. It is case-sensitive. This does not have to be a real URL.

Default: https://saml.boxyhq.com

NPM library option: samlAudience

samlPath​

NOTE: This is only applicable to our npm library.

The ACS path at which the saml response is sent back from the SAML IdP. Set this when using the npm package.

NPM library option: samlPath

For example: /api/oauth/saml

oidcPath​

NOTE: This is only applicable to our npm library.

The redirect_uri at which the Authorization response is sent back from the OpenID Connect IdP. Set this when using the npm package.

NPM library option: oidcPath

For example: /api/oauth/oidc

IDP_DISCOVERY_PATH​

This is the path for showing the IdP Selection screen in case there are multiple SSO Connections for the same tenant and product. This path is also used to show the App Selection screen in the case of IdP-initiated SAML login (Different apps using the same SAML IdP). Set this when using the npm package.

NPM library option: idpDiscoveryPath

For example: /idp/select - You can find an implementation of IdP/App Selection here.

CLIENT_SECRET_VERIFIER​

When tenant and product are used for the SAML flow (and PKCE is not being used) then we use dummy as placeholders for client_id and client_secret. This is not a security issue because SAML is tenanted and hence your Identity Provider will block access to anyone trying to log into your SAML tenant. However for additional security you should set CLIENT_SECRET_VERIFIER to a random secret and use that value as the client_secret during the OAuth 2.0 flow.

Default: dummy

NPM library option: clientSecretVerifier

IDP_ENABLED​

Set to true to enable IdP initiated login for SAML. SP initiated login is the only recommended flow but you might have to support IdP login at times.

Default: false

NPM library option: idpEnabled

PUBLIC_KEY​

This is the public key of the private key used to sign the SAML requests. Jackson expects the public key to be base64 encoded.

NPM library option: certs.publicKey

PRIVATE_KEY​

This is the private key used to sign the SAML requests. Jackson expects the private key to be base64 encoded.

NPM library option: certs.privateKey

To generate a private key and public key pair you can use the following command:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out public.crt -sha256 -days 365 -nodes

# Convert the public key to base64
cat public.crt | base64

# Convert the private key to base64
cat key.pem | base64

OpenID configuration​

For supporting OpenID flow, we need to set the algorithm and keys used to sign the ID token JWT.

OPENID_JWS_ALG​

The algorithm used to sign the id_token. Jackson uses jose to create the ID token. Supported algorithms can be found here.

Default: RS256

NPM library option: openid.jwsAlg

OPENID_RSA_PRIVATE_KEY​

Base64 value of private key. To generate one:

openssl genrsa -out private-key.pem 3072
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private_key.pem
cat private_key.pem | base64

NPM library option: openid.jwtSigningKeys.private

OPENID_RSA_PUBLIC_KEY​

Base64 value of public key. You can generate the public key from the private key as shown below:

openssl rsa -in private_key.pem -pubout -out public_key.pem
cat public_key.pem | base64

NPM library option: openid.jwtSigningKeys.public

OPENID_REQUEST_PROFILE_SCOPE​

By setting this to false, the profile scope will no longer be automatically included in the Authorization request to the OIDC provider. This will enable apps to request the minimum required authorization permissions from the signed in user. Apps can explicitly send the profile scope in the request to Jackson which will then be forwarded to the OIDC provider.

Default: true

NPM library option: openid.requestProfileScope

Database configuration​

DB_ENGINE​

Supported values are redis, sql, mongo, mem, planetscale, dynamodb

Default: sql

NPM library option: db.engine

NOTE: If you are using DynamoDB then you also need to set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. For additional options like region and capacity units check this section

NOTE: mem DB (In memory database) is useful to test the Jackson setup locally and is not intended for production. In a serverless deployment like Vercel, the mem DB won't persist across API calls since each call is a fresh lambda invocation with an entirely new context.

DB_TYPE​

Only needed when DB_ENGINE is sql. Supported values are postgres, mysql, mariadb, mssql

Default: postgres

NPM library option: db.type

DB_URL​

The database URL to connect to. If you are using self-signed certificates then pass sslmode=no-verify instead of sslmode=require in the DB_URL. This is because self-signed certs will be rejected as unauthorized in strict mode. Also, set DB_SSL=true and DB_SSL_REJECT_UNAUTHORIZED=false (see env vars below for more details).

Example: postgres://postgres:postgres@localhost:5432/postgres or postgres://postgres:postgres@localhost:5432/postgres?sslmode=no-verify

For mssql the URL takes the form of sqlserver://localhost:1433;database=<db name>;username=<username>;password=<password>;encrypt=true

NOTE: If you are using DynamoDB then you also need to set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. For additional options like region and capacity units check this section

NPM library option: db.url

DB_SSL​

This needs to be set to true if you are using SSL with your database (You should definitely be using SSL if the database needs to be access via a public url).

Default: false

DB_SSL_REJECT_UNAUTHORIZED​

If you are using a self-signed certificate then set this to false, otherwise it will be rejected due to Certificate Authority checks.

Default: true

DB_MANUAL_MIGRATION​

Set this to true to trigger execution of migration scripts when you use our Jackson docker image.

Optionally you can run the npm scripts present in ./npm/package.json to run db specific migrations.

Make sure you have set the correct value for DB_ENGINE environment variable as the migration script checks that to run correct command and migration file.

NPM library option: db.manualMigration Default: false

DB_TTL​

TTL for the code, session and token stores (in seconds)

Default: 300

NPM library option: db.ttl

DB_CLEANUP_LIMIT​

Limit cleanup of TTL entries to this number

Default: 1000

NPM library option: db.cleanupLimit

DB_ENCRYPTION_KEY​

To encrypt data at rest specify a 32 byte key (encoded in base64)

You can use openssl to generate a random 32 byte key:

openssl rand -base64 32

NPM library option: db.encryptionKey

PGSSLMODE​

If you use Heroku to deploy Postgres (or use self-signed certs for Postgres) then set this to no-verify. See Heroku docs for more details

DB_DYNAMODB_REGION​

If you are using DynamoDB then you can specify the region.

Default: us-east-1

NPM library option: db.dynamodb.region

DB_DYNAMODB_RCUS​

If you are using DynamoDB then you can specify the read capacity units. Check AWS docs for more details

Default: 5

NPM library option: db.dynamodb.readCapacityUnits

DB_DYNAMODB_WCUS​

If you are using DynamoDB then you can specify the write capacity units.

Default: 5

NPM library option: db.dynamodb.writeCapacityUnits

Webhook configuration​

WEBHOOK_URL​

Specify a webhook URL to receive events about sso and directory connections.

NPM library option: webhook.endpoint

WEBHOOK_SECRET​

Specify a secret to be used to sign the webhook payload. This is used to verify the authenticity of the webhook payload.

NPM library option: webhook.secret

Both the WEBHOOK_URL and WEBHOOK_SECRET are required to enable webhook events.

Pre-loaded Connections​

PRE_LOADED_CONNECTION​

If you only need a single tenant or a handful of pre-configured tenants then this config will help you read and load IdP (both OpenID and SAML)connections. It works well with the mem DB engine so you don't have to configure any external databases for this to work (though it works with those as well). This is a path (absolute or relative) to a directory that contains files organized in the format described in the next section. Check this section for more details

NPM library option: preLoadedConnection

Opentelemetry configuration​

Jackson supports observability via OpenTelemetry. The following env vars are available for configuration (along with the rest of the supported ones)

OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT​

Target URL to which the exporter is going to send metrics.

Example: https://ingest.lightstep.com:443/metrics/otlp/v0.6

OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_METRICS_HEADERS​

Headers relevant for the endpoint, useful for specifying authentication details for providers.

Example: lightstep-access-token=<token>,...

OTEL_EXPORTER_OTLP_PROTOCOL or OTEL_EXPORTER_OTLP_METRICS_PROTOCOL​

The transport protocol. Options MUST be one of: grpc, http/protobuf or http/json.

OTEL_EXPORTER_DEBUG​

Set this to true to enable debug logs for Opentelemetry. This is only meant for purposes of debugging otel locally.

Admin Portal configuration​

Below variables are used to enable Magic link based authentication for Admin Portal. The SMTP_ variables are used for sending email which contain the magic link (one-time use) for sign in.

SMTP_HOST​

The SMTP host like smtp.example.com.

SMTP_PORT​

The SMTP server port like 587.

SMTP_USER​

Username for the SMTP server.

SMTP_PASSWORD​

Password for the SMTP server.

SMTP_FROM​

From address used to send mail like: [email protected].

NEXTAUTH_URL​

When running locally this will point to the local server: http://localhost:5225. When deploying to production, set this to the canonical URL of the site. More details here.

NEXTAUTH_SECRET​

Set this to a random string. You can use openssl rand -base64 32 to get one. This secret is used to encrypt JWT and hash the email verification token. More details here.

NEXTAUTH_ACL​

Set this to a comma separated string of email addresses or glob patterns like: [email protected],*@marvel.com. Access will be denied to email addresses which don't match. If you don't specify any value access is denied to all.

NEXTAUTH_ADMIN_CREDENTIALS​

Set this to a comma separated string of the pattern email:password to enable login to the Admin Portal, for example [email protected]:Password123. If you don't specify any value access is denied to all.

ADMIN_PORTAL_SSO_TENANT​

This will be used as the tenant for the SSO connections (added from Settings tab) used to login into the Admin portal itself. Set this to a value that is less likely to conflict with the main Enterprise SSO connections.

Default: _jackson_boxyhq

ADMIN_PORTAL_SSO_PRODUCT​

This will be used as the product for the SSO connections (added from Settings tab) used to login into the Admin portal itself. Set this to a value that is less likely to conflict with the main Enterprise SSO connections.

Default: _jackson_admin_portal

RETRACED_HOST_URL​

If you'd like to use the Admin Portal to manage our Audit Logs service (Retraced) then set this env var to the URL of the service.

RETRACED_EXTERNAL_URL​

If you'd like to use the Admin Portal to manage our Audit Logs service (Retraced) then set this env var to the Public URL of the service. If this is the same as RETRACED_HOST_URL above then you can skip this and it will default to the value of RETRACED_HOST_URL.

Default: It is set to RETRACED_HOST_URL if RETRACED_EXTERNAL_URL is not defined.

RETRACED_ADMIN_ROOT_TOKEN​

you need to set the admin root token for Retraced so that we can connect to Retraced and fetch projects and audit logs.

Anonymous Analytics​

BOXYHQ_NO_TELEMETRY or DO_NOT_TRACK​

Set one of these to 1 or true to turn off our anonymous analytics. We only track usage events once per day and it does not contain any information that can identify you in any form.

Directory Sync​

The following env vars are used to configure the directory sync feature.

DSYNC_GOOGLE_ env vars are only applicable if you are using Google Workspace as a directory sync provider.

DSYNC_WEBHOOK_BATCH_SIZE​

Enable batch processing of directory sync events. The value represents the number of events to batch together instead of sending each event individually. This requires you to configure a cron job to process the queued events. Alternatively you can set DSYNC_WEBHOOK_BATCH_CRON_INTERVAL below if you are not deploying the service in an Edge environment.

DSYNC_WEBHOOK_BATCH_CRON_INTERVAL​

The cron interval at which to process the queued events. Provide a number in seconds. By default, the cron job is disabled.

NPM library option: dsync.webhookBatchCronInterval

DSYNC_GOOGLE_CRON_INTERVAL​

The cron interval at which to sync the Google Workspace. Provide a number in seconds. By default, the cron job is disabled.

NPM library option: dsync.providers.google.cronInterval

DSYNC_GOOGLE_CLIENT_ID​

The Google authentication client ID.

NPM library option: dsync.providers.google.clientId

DSYNC_GOOGLE_CLIENT_SECRET​

The Google authentication client secret.

NPM library option: dsync.providers.google.clientSecret

dsync.providers.google.authorizePath​

The authorization endpoint for Google SCIM.

NPM library option: dsync.providers.google.authorizePath

For example: /api/scim/oauth/authorize

dsync.providers.google.callbackPath​

The path to redirect to after completing the authorization request for Google SCIM.

NPM library option: dsync.providers.google.callbackPath

For example: /api/scim/oauth/callback

Enterprise Features​

BOXYHQ_LICENSE_KEY​

Contact us to obtain a license for our Enterprise Features - Portal Branding, Identity Federation and Ory Integration.

Enterprise Features - Ory Integration​

ENTERPRISE_ORY_SDK_TOKEN​

Your Ory Network Session Token. To obtain this use the Ory CLI and copy out your session token.

ENTERPRISE_ORY_PROJECT_ID​

Your Ory Network Project ID.