# Config
Config is loaded into simple-auth in the following ways (in-order):
- YAML configuration file, starting with
simpleauth.default.yml(embedded, as seen below) - Environment configuration prefixed with
SA_, egSA_PRODUCTION=trueorSA_METADATA_COMPANY=SuperCorp - Command line argument flags. eg
--metadata-company=SuperCorp - Any additional configuration specified in the
includefield (see below)
TIP
When translating from yaml to other formats (eg. metadata.company):
- When an argument, seprate with
-, eg--metadata-company - When an environment variable, separate with a
_, egSA_METADATA_COMPANY
TIP: Boolean Flags
For boolean flags, when setting via argument, you can shorthand it by not providing a value (eg --web-prometheus)
# Include Config
To specify another location to look for a yaml config file, you can use the include config. This can be added in the following standard ways:
include: []in yaml config--include=/etc/simpleauth.ymlexport SA_INCLUDE=/etc/simpleauth.yml
# Default Configuration
The default config is contained purely in simpleauth.default.yml, which is embedded into the application executable. This file contains all of the defaults for the application.
production: true # Production-level optimization
verbose: false # Enable debug-level logging
staticfromdisk: false # Before looking at internal storage for static content, check disk (primarily for debugging)
include: [] # Other files that should be loaded as config
# Metadata is fed into the `tmpl` and emails to be rendered
metadata:
company: "Simple Auth" # Used in emails, site title, etc
tagline: null # Displays under the title
footer: "" # Foot text
bucket: {} # Not used by default. Can be used to customize
web:
host: "0.0.0.0:9002" # The host and port the server (API & Web) listens on
baseurl: null # Specifies the full URL the server will be at. If null, inferred from host
prometheus: false # If true, will enable /metrics endpoint (Must be compiled with prometheus support)
swagger: false # If true, enables the swagger UI and docs endpoint at /swagger (Must be compiled with swagger support)
tls:
enabled: false
certfile: null # Certificate file, if enabled (and not auto)
keyfile: null # Key file, if enabled (and not auto)
# AutoTLS (and cache) are used to leverage LetsEncrypt to acquire certificate
# Needs to be internet-facing to work
auto: true # If false, will use certfile and keyfile instead of letsencrypt
autohosts: [] # Optional list of hosts that we're allowed to issue a cert for
cache: ./tlscache # Path to cache certificates in. Will be created if doesn't exist
# Login section for setting different ways a user is allowed to login
login:
settings:
routeonlogin: null # Where to route to post-login (either login or create)
allowedcontinueurls: [] # Url regex's, in addition to local pages, allowed post-login via ?continue query param
throttleduration: 1s # How often a user can make requests to a throttled API (disrupts brute-force attacks)
cookie:
jwt:
# Key for jwt-signing
signingmethod: "hs256" # HS256, HS512, RS256, RS512
signingkey: "" # IMPORTANT: The key that will sign use credentials. this MUST be kept secret, otherwise anyone can login to your site or hack your users. If RSA key, should be PEM
issuer: "simple-auth" # Who shows up as the issuer of the token
expiresminutes: 30 # Max time (and default time) until token expiration
name: "auth" # The name of the cookie that the session will be stored in
path: / # The path the session will be stored at (mainly useful if simple-auth is at a sub-path of root)
domain: null # Override the domain of the cookie
secureonly: false # If the cookie will only be passed on https
httponly: true # If the cookie can't be accessed from javascript
onetime:
enabled: true # Allow single-use token for login (important for forgot-password email)
allowforgotpassword: false # If allowed to issue forgot-password email. Required email config
tokenduration: 1h
# Gateway allows simple-auth to act as a reverse-proxy. If the user is logged-in, they will be allowed to pass-through the proxy
# to the remote application. Intentionally left simple, only can pass to one server. If you have more than one backend server
# to pass to, I recommend looking at nginx and the vouch endpoint
gateway:
enabled: false
basicauth: false # If true, will allow basic auth for local auth to pass-through the gateway
logoutpath: "/logout" # Special path that will act as "logout" (clear session). Shouldn't conflict with any downstream URLs
targets: [] # One or more downstream servers that SA will proxy to
host: null # Override the host header
rewrite: null # Rewrite URLs upon proxying eg "/old"->"/new" or "/api/*"->"/$1"
headers: null # Write additional headers (excluding host header)
nocache: true # If true, will attempt to disable caching to gateway target
# Enable or disable recaptchav2
recaptchav2:
enabled: false
sitekey: null # site key from google
secret: null # Secret key from google
theme: 'light' # light or dark
# Email config; sends welcome, forgot password, etc
email:
engine: noop # Email engines: smtp,noop,stdout
from: null # Who the email is "from"
smtp: # If engine is "smtp", the config
host: ''
identity: null
username: null
password: null
providers:
settings:
createaccountenabled: true # If allowed to create account (under any method)
local:
emailvalidationrequired: false # If email validation is required before login
requirements:
usernameregex: '^[a-z][a-z0-9.]+$' # Valid characters for username. Make sure not to include '@', or might compete with email addresses
passwordminlength: 3
passwordmaxlength: 30
usernameminlength: 5
usernamemaxlength: 20
twofactor: # Two-factor auth 2FA / TOTP (Only impacts local-auth users, not oidc)
enabled: false # TOTP two-factor (google authenticator, and others)
keylength: 12
drift: 2 # How many tokens around the "current" token to check (Accounts for user-entry-delay)
issuer: "simple-auth" # Who the token shows up as issued-by in the 2fa app
oidc: []
# - id: google
# name: Google
# icon: google
# clientid: id-from-google
# clientsecret: super-secret-from-google
# authurl: auth-endpoint
# tokenurl: token-endpoint
# Different ways a remote service can check a user is authenticated
authenticators:
simple: # An endpoint that allows checking a username/password/totp. See docs for more details
enabled: false
sharedsecret: null
vouch: # An endpoint intended to use for nginx auth_request
enabled: false
userheader: "" # If non-empty, will set the user's ID in the header with the given name
oauth2:
webgrant: true # Whether to allow web-grant (UI) or not
settings:
codeexpiresseconds: 60 # How soon a code will expire
tokenexpiresseconds: 21600 # 6 hours
codelength: 6 # Length of "code" in the authorization_code grant
allowautogrant: true # if true, will auto grant a new request if it matches a previous and authenticated request
reusetoken: true # if true, will reuse an existing token instead of creating a new one when possible
allowcredentials: false # If the `password` grant_type is supported
issuer: "simple-auth" # Name of the OAuth2 token issuer (Using in token and JWT)
issuerefreshtoken: false # Whether or not to issue a refresh token
revokeoldtokens: true # When issuing a new token, revoke all previously issued tokens of a lessor type
clients: {}
#client-id:
# secret: client-secret
# name: Client Name
# author: Author name
# authorurl: http://example.com # Link to client website
# redirecturi: http://example.com/auth-callback
# scopes: [] # List of valid (grantable) scopes
# NOTE: Allow `settings` are allowed here as overrides to common settings
# All of the API endpoints that the UI uses are also available for API calls
# if this is enabled
api:
external: false # If true, will allow access to the API via external (non-ui) requests
sharedsecret: "" # A shared-key secret that allows making API calls via the Authorization header (see docs for more detail)
throttleduration: 1s # Throttle on public-facing APIs (even if non-external)
# Storage engine
db:
driver: "sqlite3" # Storage driver: "sqlite3", "postgres", "mysql"
url: "simpleauth.db" # Storage connection URL. See http://gorm.io/docs/connecting_to_the_database.html
debug: false # Will output query performance to log
# Advanced Config
# Persistence
If you want to use a database other than sqlite3 (local file), see database drivers