Configuration

Precedence

Approzium uses the following precedence order. Each item takes precedence over the item below it:

  • command-line flags
  • environment variables
  • config file
  • defaults

Listener Configuration

Name, shorthandEnvironment variableDefaultDescription
--hostAPPROZIUM_HOST127.0.0.1Set to 0.0.0.0 to listen on all interfaces.
--http-portAPPROZIUM_HTTP_PORT6000Port for HTTP(S) API endpoints.
--grpc-portAPPROZIUM_GRPC_PORT6001Port for authenticator endpoint for clients.

Logging Configuration

Name, shorthandEnvironment variableDefaultDescription
--log-levelAPPROZIUM_LOG_LEVELinfoSupported selections are "trace", "debug", "info", "warn", "error", "fatal", and "panic". Upper case may be used.
--log-formatAPPROZIUM_LOG_FORMATtextSupported selections are "text" and "json".
--log-rawAPPROZIUM_LOG_RAWfalseApprozium's logs mask sensitive data. Setting to "true" activates raw logs, so no sensitive values will be masked. For example, if set to "true", the AWS signed_get_caller_identity string will be fully included in logs, presenting an opportunity for a viewer to impersonate another. Should only be set to "true" in environments where logs are carefully guarded.

TLS Configuration

Name, shorthandEnvironment variableDefaultDescription
--disable-tlsAPPROZIUM_DISABLE_TLSfalseWhen false, Approzium comes up as an "https" server. When "true" disables TLS, and plain "http" is used. Setting to "true" means the Approzium authentication server will send database connection information in plain text, making it vulnerable to man-in-the-middle attacks. Do not set to "true" in production environments.
--tls-cert-pathAPPROZIUM_PATH_TO_TLS_CERTThe path to the TLS certificate the Approzium authentication server has been issued to prove its identity. Curious about how to generate a valid cert? See this walkthrough. This certificate would correspond to the service.pem generated in the walkthrough. However, ideally this would not be a certificate issued by your own Certificate Authority (CA), and instead it might be issued by your company's internal CA and/or a widely recognized one. However, even a self-created CA is better than none.
--tls-key-pathAPPROZIUM_PATH_TO_TLS_KEYThe path to the TLS key the Approzium authentication server can use to prove its identity. In the above walkthrough, this would correspond to the service.key.

Secrets Configuration

Name, shorthandEnvironment variableDefaultDescription
--secrets-managerAPPROZIUM_SECRETS_MANAGERSupported options are "vault" (Hashicorp Vault), "asm" (AWS Secrets Manager), and "local" (Local YAML file)
--vault-token-pathAPPROZIUM_VAULT_TOKEN_PATHOptional, if set it will cause the latest Vault token to always be pulled from the given file. This option takes precedence over --vaulttoken
--vault-tokenVAULT_TOKENOptional, if set it will be used as the Vault token.
--vault-addrVAULT_ADDRRequired if "vault" is set under "secrets-manager".
--assume-aws-roleAPPROZIUM_ASSUME_AWS_ROLEOptional, only valid for AWS Secrets Manager. The role Approzium should assume when retrieving secrets. This parameter is useful for AWS Lambda environments, and for local testing.
--aws-regionAWS_REGIONRequired if using AWS Secrets Manager as the secrets manager.

Misc Flags

Name, shorthandEnvironment variableDefaultDescription
--configAPPROZIUM_CONFIG_FILE_PATHfalseOptional, set it to path containing a YAML config file.
--versionfalseOutputs the current version of Approzium.
--devfalseRuns Approzium in dev mode, using a local file for storage and with TLS disabled.

Example config file, which can be passed in through approzium --config=/path/to/config.yaml:

---
listener:
grpc_port: 6001
host: "127.0.0.1"
http_port: 6000
logging:
log_format: json
log_level: info
log_raw: false
secrets:
secrets_manager: "vault"
vault_addr: "https://somewhere:8200"
vault_token_path: "/path/to/tokensink.txt"
tls:
disable_tls: false
tls_cert_path: "/path/to/approzium.pem"
tls_key_path: "/path/to/approzium.key"

Approzium Secrets Manager Backends

Hashicorp Vault Backend

See our QuickStart section for how to plant a password in Vault for Approzium.

Approzium supports Hashicorp Vault for storing database credentials. To use it, set the secretsmanager option to vault. At a minimum, the --vaultaddr must be set. Either the --vaulttoken or --vaulttokenpath must be set, with the --vaulttoken taking precedence.

We recommend using the --vaulttokenpath with the Vault agent, as described here, because that approach will allow the Vault token to be refreshed by the Vault agent, rather than eventually expiring.

Additional Vault configuration is supported, as described here.

AWS Secrets Manager Backend

Approzium supports AWS Secrets Manager for storing database credentials. To use it, set the secretsmanager option to asm. AWS credentials have to be configured on the system. If you are not sure how to do that, consult the AWS docs.

Important: For AWS Secrets Manager to work, the AWS region --awsregion has to be explicitly provided.

Example secrets section:

secrets:
secrets_manager: "asm"
aws_region: "us-east-1"

To plant a password in AWS Secrets Manager for Approzium to use, choose "Other type of secrets", and as the plaintext value, place a JSON object like this:

{
"dbuser1": {
"password": "asdfghjkl",
"iam_arns": [
"arn:aws:iam::accountid:role/rolename1",
"arn:aws:iam::accountid:role/rolename2"
]
}
}

The fields in this JSON object represent:

{
"<database_user_name>": {
"password": "<database_password_that_should_never_be_shared>",
"iam_arns": [
"<the_iam_arns_of_callers_who_should_be_allowed_access_via_this_database_user>"
]
}
}

Then, set the secret name to:

approzium/postgres-host@5432

This schema is as follows: approzium/<postgres-host-name>@<postgres-port>.

Note the Secret ARN, and use it to create an IAM policy like:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:aws:secretsmanager:us-east-1:0123456789012:secret:approzium/postgres-host@5432"
}
]
}

Create an IAM Role for the Approzium Authenticator to use, and attach the new policy to the IAM Role. Then, run the Approzium Authenticator on an EC2 instance that has been launched into this IAM Role.