aah Security Configuration

aah Security configuration is to configure Authentication, Authorization, Session Management, Secure Headers, CORS (upcoming), CSRF (upcoming), etc. The configuration syntax is used by aah framework is very similar to HOCON syntax. Learn more about configuration syntax.

Reference to App Config, Routes Config, Log Config.

Table of Contents

Section: security { … }

To configure application security related configuration in the section.

Section: auth_schemes { … }

auth_schemes section is used to configure application authentication and authorization. Out-of-the-box aah framework supports following schemes-

  • FormAuth - Register your own dynamic integration of Authentication and Authorization.
  • BasicAuth - File realm or implement your own dynamic integration of Authentication and Authorization.
  • GenericAuth - brings more possibilities.

Section: session { … }

HTTP state management across HTTP requests.

security.session.mode

Session mode is to choose whether HTTP session should be persisted or destroyed at the end of each request. Supported values are -

  • stateless - Session data is destroyed at end of each request
  • stateful - Session data is persisted based on store type config

Default value is stateless for API and stateful for Web application.

mode = "stateful"

Section: store { … }

Session store is to configure where session values should be persisted. Currently aah framework supports cookie and file as a store type. Also framework provides extensible session.Storer interface to add your custom session store.

security.session.store.type

Currently aah framework supports cookie and file as a store type.

Note: If you're using cookie session store, you have to be mindful about cookie size limit 4kb.

Default store type value is cookie.

type = "cookie"

security.session.store.filepath

Filepath is used for file store to store session data in the file system. This is only applicable for store.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/store/session/files"

security.session.id_length

Session Identifier length. Identifier(ID) is generated using random bytes from crypto/rand and HEX encoding.

Default value is 32

id_length = 32

security.session.ttl

Time-to-live value for session data expiry. Valid time units are m -> minutes, h -> hours and 0.

Default value is 0, cookie is deleted when the browser is closed.

ttl = "0"

security.session.prefix

HTTP session cookie name prefix value.

Default value is aah For e.g.: aah_session.

prefix = "aah"

security.session.domain

HTTP session cookie domain value.

Default value is empty string.

domain = ""

security.session.path

HTTP session cookie path value.

Default value is /.

path = "/"

security.session.http_only

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

security.session.secure

HTTP session cookie secure value. However, if aah server is not configured with SSL then aah framework sets this value as false.

Default value is true.

secure = true

security.session.sign_key

HTTP session cookie value signing using HMAC. For server farm this value should be same in all instance. For HMAC sign & verify it is recommend to use key size is 32 or 64 bytes.

Default value is 64 bytes (generated when application gets created using aah new command).

sign_key = "generated-value"

security.session.enc_key

HTTP session cookie value encryption and decryption using AES. For server farm this value should be same in all the instances. 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 (generated when application gets created using aah new command).

enc_key = "generated-value"

security.session.cleanup_interval

Cleanup Interval is used to clean the expired session data from the store. This 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: anti_csrf { … }

Documents the settings belongs to Anti-CSRF Protection.

security.anti_csrf.enable

Enabling Anti-CSRF Protection.

Default value is true.

enable = true

security.anti_csrf.secret_length

Anti-CSRF secret length. Salted cipher token length secret_length * 2.

Default value is 32.

secret_length = 64

security.anti_csrf.header_name

HTTP Header name for cipher token.

Default value is X-Anti-CSRF-Token.

header_name = "X-Anti-CSRF-Token"

security.anti_csrf.form_field_name

Form field name for cipher token

Default value is anti_csrf_token.

form_field_name = "anti_csrf_token"

security.anti_csrf.prefix

Anti-CSRF secure cookie prefix.

Default value is aah. Cookie name would be aah_anti_csrf.

prefix = "aah"

security.anti_csrf.domain

Default value is empty string.

domain = ""

security.anti_csrf.path

Default value is /.

path = "/"

security.anti_csrf.ttl

Time-to-live for Anti-CSRF secret. Valid time units are “m = minutes”, “h = hours” and 0.

Default value is 24h.

ttl = "24h"

security.anti_csrf.sign_key

Anti-CSRF cookie value signing using HMAC. For server farm this 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).

sign_key = "<typically generated by 'aah new' cmd>"

security.anti_csrf.sign_key

Anti-CSRF cookie value encryption and decryption using AES. For server farm this 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).

enc_key = "<typically generated by 'aah new' cmd>"

Section: http_header { … }

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

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"