#Auth

This configuration file controls the settings for user authentication, password management and token expiration configuration.

#Example File

# Will secure login cookies with `Secure` context, enable HTTS and HTTP->HTTPS redirect
requireHttps = false

# Key (all waltid-crypto supported) to sign login token - has to be key allowing signing (private key)
signingKey = {"type": "jwk", "jwk": {"kty": "OKP", "d": "L_2RuCSFUu818ZzM6Xml6uxesqTcxo8323-Q2S_qq4c", "use": "sig", "crv": "Ed25519", "x": "vvCN3xMAb0ZCt4sWIdtKDhkVHSERJZeBxybN-eSRkgw", "alg": "EdDSA"}}

# Key (all waltid-crypto supported) to verify incoming login tokens - public key is ok.
verificationKey = {"type": "jwk", "jwk": {"kty": "OKP", "d": "L_2RuCSFUu818ZzM6Xml6uxesqTcxo8323-Q2S_qq4c", "use": "sig", "crv": "Ed25519", "x": "vvCN3xMAb0ZCt4sWIdtKDhkVHSERJZeBxybN-eSRkgw", "alg": "EdDSA"}}

# Provide pepper to use for additional password salting (unique string for your deployment,
# has to be shared between instances).
pepper = "waltid-enterprise12345678"

# Hash algorithm to use for passwords for signing.
# You can choose from algorithms like: ARGON2, PBKDF2, PBKDF2_COMPRESSED, BCRYPT, SCRYPT, BALLON_HASHING, MESSAGE_DIGEST, NONE
hashAlgorithm = ARGON2

# Configure the Auth Flow (refer to: waltid-ktor-authnz)
authFlow = {
    method: email
    expiration: "7d" # optional: Set expiration time for login tokens, e.g. a week
    ok: true # Auth flow ends successfuly with this step
}


# If you previously used other (older) password hash algorithms, you
# can use this function to migrate old hashes to new hash algorithms. This
# works at login-time: When a user logs in with a password that uses a hash algorithm
# on this list, the password will be re-hashed in the specified replacement algorithm.
# If null is used as hash algorithm selector, all algorithms expect for the target
# algorithm will be converted automatically.
hashMigrations = {
    MESSAGE_DIGEST: ARGON2 # E.g.: Convert all the MD5 hashes to Argon2 hashes
}

#Signing & Verification Keys

When users log into the Enterprise Stack, authentication tokens (JWTs) are generated. These tokens are signed with a private key, referred to as the signingKey, and verified using a public key known as the verificationKey. Both keys are defined in the auth.conf (example file below).

#Why Signing & Verification Keys?

The Enterprise Stack can be deployed across multiple instances to achieve high uptime and availability. However, for authentication tokens that are issued and signed in one instance to be verified in another, all instances must share the same keys. This is where the signingKey and verificationKey are important. It is crucial that both keys remain consistent across all instances.

#Types of Singing & Verification Keys

The signingKey and verificationKey can be provided as a local type (RAW JWK) or a reference to an external Key manged by a KMS (e.g. AWS KMS)

#Examples

Local

{
  "type": "jwk",
  "jwk": {
    "kty": "OKP",
    "d": "L_2RuCSFUu818ZzM6Xml6uxesqTcxo8323-Q2S_qq4c",
    "use": "sig",
    "crv": "Ed25519",
    "x": "vvCN3xMAb0ZCt4sWIdtKDhkVHSERJZeBxybN-eSRkgw",
    "alg": "EdDSA"
  }
}

AWS

{
  "type": "aws",
  "config": {
    "auth": {
      "roleName": "AccessRole",
      "region": "eu-central-1"
    }
  },
  "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
  "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
  "_keyType": "secp256r1"
}

#Auth Flow

The Enterprise Stack utilizes the waltid-ktor-authnz library to facilitate user authentication. This library supports various authentication methods through what are known as auth flows. In our configuration for the Enterprise Stack, we specifically define the email/password authentication flow and include an expiration property. This ensures that login tokens will expire after a predetermined period.

If we do not specify an authFlow in the configuration, the system will default to the standard email/password flow, which does not include an expiration time for tokens.

You can find examples for both these flows below.

#Email / Password Auth Flow With Expiration Example

authFlow = {
  method: email
  expiration: "7d" # optional: Set expiration time for login tokens, e.g., a week
  ok: true # Auth flow ends successfully with this step
}

Set expiration times using the kotlinx.datetime Duration Syntax. Valid units are days (d), hours (h), minutes (m), and seconds (s), with finer granularity using milliseconds (ms), microseconds (us), and nanoseconds (ns). Examples include 5h, 1d 12h, and 1h 0m 30.340s.

Alternatively, you can use a simplified ISO-8601 duration format (PThHmMs.fS), such as P1DT2H3M4.058S. In this format:

• The largest non-time designator is days (D). Years (Y), weeks (W), and months (M) are not parsed. Instead, use 365d for years, 7d for weeks, and 30d for months.
• A day is always assumed to be 24 hours (24-hour clock time scale).
• There is currently no alternative week-based representation like ["P"][number]"W".

When an expiration is set, login tokens issued will have the specified expiration based on the server's current time. If the expiration is exceeded, an error will occur indicating the token expired.

#Default Email / Password Flow Example

authFlow = { method: email, ok: true }