aah Security Configuration

aah Security configuration is to configure Authentication, Authorization, Session Management, Secure Headers, Anti-CSRF, etc. The aah config syntax is very similar to HOCON. Learn configuration syntax.

security { … }

Section: security { … }

To configure application security configuration such as Auth schemes, Password Encoder, Session, Anti-CSRF, secure HTTP headers.

Section: session { … }

aah session management supports stateful and stateless.

session { ... } configuration goes under the config section security { ... }.

# -----------------------------------------------------------------------------
# Session configuration
# HTTP state management across multiple requests.
#
# Doc: https://docs.aahframework.org/security-config.html#section-session
# -----------------------------------------------------------------------------
session {
  # Session mode
  #   - `stateless` - Session data is destroyed at end of each request
  #   - `stateful` - Session data is persisted on session store
  #
  # Default value is `stateless` for API and `stateful` for Web app.
  mode = "stateful"

  # Session store is to choose where session value should be persisted.
  store {
    # aah supports `cookie` and `file` as store type out of the box.
    # And provides extensible `session.Storer` interface for implementing
    # custom session store.
    #
    # Note: While using cookie session store, be mindful about cookie size limit.
    #
    # Default value is `cookie`.
    type = "cookie"

    # Filepath is used for file session store in the file system.
    # This is only applicable when `type = "file"`, make sure application has
    # Read/Write access to the directory. Provide absolute path.
    #
    # Default value is `<app-base-dir>/sessions`.
    #filepath = "/path/to/session/directory"
  }

  # Session ID length
  # Default value is `32`.
  id_length = 32

  # Time-to-live for session data. Valid time units are "m = minutes",
  # "h = hours" and 0.
  #
  # Default value is `0`, cookie is deleted when the browser is closed.
  ttl = "0"

  # Session cookie name prefix.
  # Default value is `aah_<app-name>` For e.g.: `aah_myapp_session`
  prefix = "aah_myapp_session"

  # Default value is `empty` string.
  domain = ""

  # Default value is `/`.
  path = "/"

  # HTTP session cookie HTTPOnly value. This option is to prevents XSS
  # (Cross Site Scripting) attacks, basically it disallows access of
  # cookie to scripts like JavaScript.
  #
  # Default value is `true`.
  http_only = true

  # HTTP session cookie secure value.
  #
  # Default value is `true`. However if aah server is not configured with SSL
  # then aah sets this value as false.
  secure = true

  # HTTP session cookie value signing using `HMAC`. For server farm this
  # value should be same in all instance. For HMAC sign & verify it recommend to use
  # key size is `32` or `64` bytes.
  #
  # Default value is `64` bytes (`aah new` generates strong one using `crypto/rand`).
  sign_key = "829747ee8378bc6e84fcb226d586b98976fc4e80f90dd0df59542a553cfa3e7f"

  # HTTP session cookie value encryption and decryption using `AES`. For server
  # farm this value should be same in all instance. AES algorithm is used, valid
  # lengths are `16`, `24`, or `32` bytes to select `AES-128`, `AES-192`, or `AES-256`.
  #
  # Default value is `32` bytes (`aah new` generates strong one using `crypto/rand`).
  enc_key = "d98b1966eb94e9fa35e25e611beba369"

  # Cleanup Interval is used to clean the expired session data from session store.
  # It is only applicable for non-cookie store type.
  # Cleanup performed in dedicated goroutine. Valid time units are
  # `m -> minutes`, `h -> hours`.
  #
  # Default value is `30m`.
  cleanup_interval = "30m"
}

Section: http_header { … }

Since v0.8 aah provides response secure headers with many safe defaults. Typically non-empty header values from configuration gets added into response header.

http_header { ... } configuration goes under the config section security { ... }.

Framework writes the secure response headers appropriately based on Content-Type.

Tip:

Quick way to verify your application secure headers - https://securityheaders.io
Exclude header from writing, just put empty string as a value.

Header: X-XSS-Protection

Designed to enable the cross-site scripting (XSS) filter built into modern web browsers. This is usually enabled by default, but using this header will enforce it.

Learn more:

Encouraged to make use of header Content-Security-Policy with enhanced policy to reduce XSS risk along with header X-XSS-Protection.

Default values is 1; mode=block.

xxssp = "1; mode=block"

Header: X-Content-Type-Options

Prevents Content Sniffing or MIME sniffing.

Learn more:

Default value is nosniff.

xcto = "nosniff"

Header: X-Frame-Options

Prevents Clickjacking.

Learn more:

Default value is SAMEORIGIN.

xfo = "SAMEORIGIN"

Header: Referrer-Policy

This header governs which referrer information, sent in the Referer header, should be included with requests made.

Referrer Policy has been a W3C Candidate Recommendation since 26 January 2017.

Learn more:

Default value is no-referrer-when-downgrade.

rp = "no-referrer-when-downgrade"

Header: Strict-Transport-Security (STS, aka HSTS)

STS header that lets a web site tell browsers that it should only be communicated with using HTTPS, instead of using HTTP.

Learn more:

Note: Framework checks that application uses SSL on startup then applies this header. Otherwise it does not apply.

sts {
  # The time, in seconds, that the browser should remember that this site
  # is only to be accessed using HTTPS. Valid time units are
  # "s -> seconds", "m -> minutes", "h - hours".
  # Default value is `30 days` in hours.
  #max_age = "720h"

  # If enabled the STS rule applies to all of the site's subdomains as well.
  # Default value is `false`.
  #include_subdomains = true

  # Before enabling preload option, please read about pros and cons from above links.
  # Default value is `false`.
  #preload = false
}

Header: Content-Security-Policy (CSP)

Provides a rich set of policy directives that enable fairly granular control over the resources that a page is allowed. Prevents XSS risks.

Learn more:

Read above references and define your policy.

Note:

It is highly recommended to verify your policy directives in report only mode before enabling this header. Since its highly controls how your page is rendered.
Only applied to prod environment profile.

No default values, you have to provide it.

csp {
  # Set of directives to govern the resources load on a page.
  directives = ""

  # By default, violation reports aren't sent. To enable violation reporting,
  # you need to specify the report-uri policy directive.
  report_uri = ""

  # Puts your `Content-Security-Policy` in report only mode, so that you can verify
  # and then set `csp_report_only` value to false.
  # Don't forget to set the `report-uri` for validation.
  report_only = true
}

Header: Public-Key-Pins (PKP, aka HPKP)

This header prevents the Man-in-the-Middle Attack (MITM) with forged certificates.

Learn more:

Read above references and define your keys.

Note:

HPKP has the potential to lock out site/users for a long time if used incorrectly! The use of backup certificates and/or pinning the CA certificate is recommended.
It is highly recommended to verify your PKP in report only mode before enabling this header
Framework checks that application uses SSL on startup then applies this header. Otherwise it does not apply
Only applied to prod environment profile.

No default values, you have to provide it.

pkp {
  # The Base64 encoded Subject Public Key Information (SPKI) fingerprint.
  # These values gets added as `pin-sha256=<key1>; ...`.
  #keys = [
  #"X3pGTSOuJeEVw989IJ/cEtXUEmy52zs1TZQrU06KUKg=",
  #"MHJYVThihUrJcxW6wcqyOISTXIsInsdj3xK8QrZbHec="
  #]

  # The time that the browser should remember that this site is only to be
  # accessed using one of the defined keys.
  # Valid time units are "s -> seconds", "m -> minutes", "h - hours".
  max_age = "720h"

  # If enabled the PKP keys applies to all of the site's subdomains as well.
  # Default value is `false`.
  include_subdomains = false

  # By default, Pin validation failure reports aren't sent. To enable Pin validation
  # failure reporting, you need to specify the report-uri.
  report_uri = ""

  # Puts your `Public-Key-Pins` in report only mode, so that you can verify
  # and then set `pkp_report_only` value to false.
  # Don't forget to set the `report-uri` for validation.
  report_only = true
}

Header: X-Permitted-Cross-Domain-Policies

Restrict Adobe Flash Player’s or PDF documents access via crossdomain.xml, and this header.

Learn more:

Default value is master-only.

xpcdp = "master-only"

aah Security Configuration

Table of Contents

Section: security { … }

Section: session { … }

Section: http_header { … }

Header: X-XSS-Protection

Header: X-Content-Type-Options

Header: X-Frame-Options

Header: Referrer-Policy

Header: Strict-Transport-Security (STS, aka HSTS)

Header: Content-Security-Policy (CSP)

Header: Public-Key-Pins (PKP, aka HPKP)

Header: X-Permitted-Cross-Domain-Policies