Application Settings¶

The API server reads application settings from environment variables defined in the underlying runtime environment (i.e., inside the deployed API container). Individual settings are listed below by category and use case.

Security Settings¶

Security settings are used to configure application networking and request signing. These values should be chosen with care. Improperly configured settings can introduce dangerous vulnerabilities and may damage your production deployment.

Core Security¶

The Keystone API requires a random secret key to sign and verify requests. Secret keys are conventionally 50 characters long and can be generated using common utilities like openssl (e.g., openssl rand -base64 48 | cut -c1-50). Administrators should always configure their own custom key and persist the value across application instances and restarts.

SSL/TLS¶

Enabling TLS is strongly recommended in production. Enabling HSTS is also recommended, but only when TLS is already fully configured. Administrators are cautioned to consider the potentially irreversible side effects of HSTS before enabling it.

Alternatively, administrators can implement TLS/HSTS support using a reverse proxy. When using a reverse proxy for TLS, the settings below can be left at their default values.

Auth Tokens¶

The following settings define which domains are allowed to interact with the API server. These settings should be made as restrictive as possible, helping prevent unauthorized access to the API.

In most deployments, the settings above should be configured as follows:

• SECURE_SSL_TOKENS: Enabled when serving over HTTPS and disabled otherwise.
• SECURE_ALLOWED_HOSTS: Set to the domain name(s) where the API is hosted
  (e.g., api.example.com).
• SECURE_ALLOWED_ORIGINS: Set to the full URL(s) of the frontend web application
  (e.g., https://app.example.com).
• SECURE_TOKEN_DOMAIN: Only required when the API and frontend are hosted on different subdomains of the same parent domain. This setting should specify the parent domain with a leading dot (e.g., .example.com) to allow token sharing across subdomains.

Default values are defined relative to the following list of default local addresses:

• http://localhost:80
• https://localhost:443
• http://localhost:4200
• http://localhost:8000
• http://127.0.0.1:80
• https://127.0.0.1:443
• http://127.0.0.1:4200
• http://127.0.0.1:8000

General Configuration¶

Keystone uses file storage for various static and user driven content. By default, these files are stored in subdirectories of the installed application directory (<app>). It is generally recommended to customize the storage location using a filesystem with enterprise grade backup and redundancy.

Logging¶

Keystone automatically purges log records according to the policy settings below. Application logs are written to disk using a size-based policy that rotates files according to a maximum file size/count. Audit, request, and task logs are maintained in the application database and are removed once they exceed a configured age (in seconds).

API Throttling¶

API settings are used to throttle incoming API requests against a maximum limit. Limits are specified as the maximum number of requests per day, minute, hour, or second.

Database Connection¶

Official support is included for both SQLite and PostgreSQL databases. Using SQLite is only intended for use in development or testing. The PostgreSQL backend should always be used in production settings.

Redis Connection¶

The following settings define the network location and connection information for the application Redis cache. Enabling password authentication is strongly recommended.

Email Notifications¶

Keystone will default to using a local server when issuing email notifications. An alternative SMTP server can be specified using the settings below. Securing your production email server with a username/password is strongly recommended.

LDAP Authentication¶

Using LDAP for authentication is optional and disabled by default. To enable LDAP, set the AUTH_LDAP_SERVER_URI value to the desired LDAP endpoint. Enabling LDAP integration will also add LDAP related health checks to the API health endpoint.

Application user fields are mapped to LDAP attributes by specifying the AUTH_LDAP_ATTR_MAP setting. The following example maps the first_name and last_name fields used by Keystone to the LDAP attributes givenName and sn:

AUTH_LDAP_ATTR_MAP="first_name=givenName,last_name=sn"

A full list of available user fields can be found in the project's OpenApi specification.