# Config

Config is loaded into simple-auth in the following ways (in-order):

  1. YAML configuration file, starting with simpleauth.default.yml (embedded, as seen below)
  2. Environment configuration prefixed with SA_, eg SA_PRODUCTION=true or SA_METADATA_COMPANY=SuperCorp
  3. Command line argument flags. eg --metadata-company=SuperCorp
  4. Any additional configuration specified in the include field (see below)


When translating from yaml to other formats (eg. metadata.company):

  1. When an argument, seprate with -, eg --metadata-company
  2. When an environment variable, separate with a _, eg SA_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:

  1. include: [] in yaml config
  2. --include=/etc/simpleauth.yml
  3. export 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
    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

    host: "" # 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)
        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
            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)
                # 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
            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
        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
        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
    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

        createaccountenabled: true      # If allowed to create account (under any method)
        emailvalidationrequired: false  # If email validation is required before login
            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
    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
        webgrant: true # Whether to allow web-grant (UI) or not
            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: {}
            #    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
    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
    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

# Signing Key Pair

See SigningKey RSA Pair Cookbook