Configuration Schema Reference¶

This section provides the complete JSON schema for CredProxy configuration.

The schema is automatically validated when CredProxy starts, ensuring your configuration is correct before attempting to assume roles or start the service.

Schema Location¶

The JSON schema is located at credproxy/config-schema.json in the repository.

You can view it at: https://github.com/johnpreston/credproxy/blob/main/credproxy/config-schema.json

Schema Overview¶

Required Fields¶

The only required top-level field is services, which must contain at least one service configuration.

{
  "required": ["services"]
}

Top-Level Properties¶

server - Server configuration (host, port, debug, log_health_checks)
credentials - Global credential management settings
aws_defaults - Default AWS credentials applied to all services
services - Service-specific configurations (required)
dynamic_services - Dynamic service file monitoring configuration
metrics - Prometheus metrics configuration

Service Configuration¶

Each service must have:

auth_token (string, required) - Unique token for client authentication
source_credentials (object, required) - AWS credentials to use for assuming the role
assumed_role (object, required) - IAM role configuration including RoleArn

Example service configuration:

services:
  my-app:
    auth_token: "secure-token-here"
    source_credentials:
      region: "us-west-2"
      iam_profile:
        profile_name: "default"
    assumed_role:
      RoleArn: "arn:aws:iam::123456789012:role/MyAppRole"
      RoleSessionName: "my-app-session"
      DurationSeconds: 3600

Source Credentials Options¶

You can configure source credentials in three ways:

Default AWS SDK chain

Leave source_credentials minimal to use EC2/ECS roles, environment variables, or AWS CLI config:
```
source_credentials:
  region: "us-west-2"
```

IAM Profile

Specify a profile from ~/.aws/config:

source_credentials:
  region: "us-west-2"
  iam_profile:
    profile_name: "my-profile"
    config_file: "/path/to/config"  # optional

IAM Keys

Provide access key ID and secret access key:

source_credentials:
  region: "us-west-2"
  iam_keys:
    aws_access_key_id: "AKIAIOSFODNN7EXAMPLE"
    aws_secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    session_token: "optional-session-token"  # for temporary credentials

Role Assumption Parameters¶

The assumed_role section supports all AWS STS AssumeRole parameters:

RoleArn (required) - ARN of the role to assume
RoleSessionName - Name for the session (default: “credproxy”)
DurationSeconds - Session duration 900-43200 seconds (default: 900)
ExternalId - External ID for third-party access
Additional STS parameters as needed

assumed_role:
  RoleArn: "arn:aws:iam::123456789012:role/MyRole"
  RoleSessionName: "my-session"
  DurationSeconds: 3600
  ExternalId: "unique-external-id"

Validation Rules¶

Pattern Properties¶

Service names must match ^[a-zA-Z0-9_-]+$ (alphanumeric, underscore, hyphen).

All configuration objects support x- prefixed properties for custom extensions that will be ignored by the validator.

AWS Access Key Format¶

aws_access_key_id must match ^[A-Z0-9]{20}$
aws_secret_access_key must be exactly 40 characters

Role ARN Format¶

Role ARNs must match the pattern:

^arn:aws:iam::[0-9]{12}:role/[a-zA-Z0-9+=,.@_/-]*[a-zA-Z0-9+=,.@_-]$

Port Ranges¶

server.port: 1-65535
metrics.prometheus.port: 1024-65535

Duration Ranges¶

credentials.refresh_buffer_seconds: 0-3600
credentials.retry_delay: 1-300
credentials.request_timeout: 1-300
assumed_role.DurationSeconds: 900-43200
dynamic_services.reload_interval: 1-60

Dynamic Services Configuration¶

The dynamic_services section enables automatic monitoring of configuration files for hot-reloading services without restarting CredProxy.

New Per-Directory Format (Recommended):

dynamic_services:
  enabled: true
  directories:
    - path: "/credproxy/dynamic"
      include_patterns: [".*\\.yaml$", ".*\\.yml$"]
      exclude_patterns: ["^\\..*", ".*~$", ".*\\.bak$"]
    - path: "/credproxy/dynamic-dev"
      include_patterns: ["^dev-.*\\.yaml$"]
      exclude_patterns: ["^\\..*"]
  reload_interval: 5

Directory Configuration Properties:

path (string, required) - Directory path to monitor
include_patterns (array, optional) - List of regex patterns to include files. If empty, all non-excluded files are included
exclude_patterns (array, optional) - List of regex patterns to exclude files

Pattern Matching Rules:

Exclude first, then include - Files matching exclude patterns are always ignored
Empty include_patterns means include all files that don’t match exclude patterns
Patterns are applied to full file paths (supports directory-based matching)
Regex patterns use Python re.match() (matches from start of string)
Cross-platform paths are normalized with forward slashes

Pattern Examples:

# Include only YAML files, exclude hidden and backup files
include_patterns: [".*\\.yaml$", ".*\\.yml$"]
exclude_patterns: ["^\\..*", ".*~$", ".*\\.bak$"]

# Include only dev-prefixed files
include_patterns: ["^dev-.*\\.yaml$"]
exclude_patterns: []

# Include all files except hidden ones
include_patterns: []
exclude_patterns: ["^\\..*"]

# Include files in specific subdirectories
include_patterns: [".*/testing/.*\\.yaml$", ".*/staging/.*\\.yaml$"]
exclude_patterns: []

Backward Compatibility:

The old format is still supported for existing configurations:

# Old format (still works)
dynamic_services:
  enabled: true
  directory: "/credproxy/dynamic"
  reload_interval: 5

This is automatically converted to the new format internally.

Environment Variable Substitution¶

Any string value in the configuration can use substitution:

${fromEnv:VARIABLE_NAME} - Replace with environment variable value
${fromFile:/path/to/file} - Replace with file contents (trimmed)

The substitution tags themselves can be customized via environment variables. See Environment Variables Reference for details.

Full Schema Reference¶

For the complete JSON schema definition with all properties, types, and constraints, see the schema file: https://github.com/johnpreston/credproxy/blob/main/credproxy/config-schema.json

Example Configurations¶

See Configuration for complete example configurations demonstrating various features.