Secret Server ×
AWS Key Manager

The hybrid integration positions Secret Server as the authoritative source of record for privileged credentials, while AWS Key Manager provides cryptographic key material, envelope encryption, and native AWS-service secret delivery. The sync connector bridges these systems with a configurable, conflict-aware replication engine.

The architecture respects a zero-trust boundary between on-premises and cloud environments. Secret Server manages access policy, rotation schedules, and dependency tracking. AWS KMS handles cryptographic operations and native AWS service delivery. The connector handles protocol translation, field mapping, and sync-state bookkeeping.

Before configuring the connector, ensure all prerequisites are met in both environments. Incomplete prerequisites are the leading cause of failed initial syncs.

The sync connector is configured in two phases: IAM trust relationship setup in AWS, followed by connector registration and endpoint configuration in Secret Server.

Phase 1 — IAM Trust Relationship

Create an IAM role that the connector will assume using STS. This role follows least-privilege and trusts the Secret Server engine's instance profile or static credentials.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT_ID:role/SecretServerEngine"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "SS_CONNECTOR_EXTERNAL_ID"  // set in SS UI
        }
      }
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue",
        "secretsmanager:CreateSecret",
        "secretsmanager:UpdateSecret",
        "secretsmanager:DescribeSecret",
        "secretsmanager:ListSecrets",
        "secretsmanager:TagResource"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:ss-sync/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT:key/CMK_KEY_ID"
    }
  ]
}

Phase 2 — Connector Registration in Secret Server

1. 1
   Navigate to Sync Connector Settings

   Go to Admin → Configuration → Sync Connectors → New Connector. Select AWS Key Manager from the connector type dropdown.
2. 2
   Enter IAM Credentials

   Input the ARN of the SecretServerSyncRole and the External ID you defined in the trust policy. For EC2-hosted engines, prefer instance profile — leave the Access Key fields empty.
3. 3
   Configure Region & KMS Key

   Set the target AWS region and paste the CMK ARN or alias. This key will be used for all envelope encryption operations during sync. The connector validates key access on save.
4. 4
   Set Sync Mode & Interval

   Choose between Push-Only, Pull-Only, or Bidirectional. Set the polling interval (minimum 60 seconds recommended for production; 300s default). Enable Incremental Sync to reduce API call volume.
5. 5
   Test & Activate

   Click Test Connection. The system performs an STS AssumeRole call, a KMS DescribeKey, and a Secrets Manager list operation. All three must succeed. Click Activate Connector to begin syncing.

Secret Server's template system uses structured field definitions. AWS Secrets Manager stores secrets as JSON key-value documents (or plaintext strings). The mapping layer handles serialization, field aliasing, and type coercion between these two data models.

Default Template Mappings

Mappings tagged BIDI support bidirectional sync. Mappings tagged PUSH are push-only because Secret Server maintains canonical metadata (rotation history, expiry) that has no AWS equivalent.

Custom Template Mapping Configuration

template_mappings:
  - ss_template_name: "Oracle Service Account"
    aws_secret_prefix: "oracle/"
    direction: bidirectional
    kms_key_override: "arn:aws:kms:us-east-1:123:key/oracle-cmk"
    field_map:
      - ss_field: "Username"
        aws_key: "username"
      - ss_field: "Password"
        aws_key: "password"
        sensitive: true
      - ss_field: "Server"
        aws_key: "host"
      - ss_field: "Port"
        aws_key: "port"
        type_coerce: integer
    tags:
      environment: "production"
      managed_by: "secret-server-sync"
      template: "oracle-service-account"

The sync engine applies a deterministic rule set to decide when, what, and how to synchronize secrets between platforms. Understanding these rules is critical for predicting system behavior during edge cases.

# Mapped fields only — unmapped SS fields are NEVER pushed
# Metadata synced as AWS secret tags:
Tags:
  ss_secret_id:      "<secret_id>"
  ss_folder_path:    "<folder>/<subfolder>"
  ss_last_modified:  "<ISO8601 timestamp>"
  ss_template:       "<template_name>"
  ss_sync_version:   "<sync_sequence_number>"

# /etc/ss-connector/throttle.ini
[aws_api_limits]
max_requests_per_second = 50       # AWS SM default quota
burst_multiplier        = 1.5      # burst headroom
retry_backoff_base      = 2        # exponential base (seconds)
retry_max_attempts      = 5
batch_size              = 20       # secrets per sync batch
batch_delay_ms          = 500      # ms pause between batches

[kms_limits]
max_decrypt_per_second  = 5000     # default KMS CryptographicOperations quota
cache_data_key_ttl_secs = 300      # reuse envelope data key for 5 min

Conflicts occur when a secret is modified in both Secret Server and AWS Secrets Manager between sync cycles. The connector detects conflicts via version vector comparison using ss_sync_version tags and Secret Manager's VersionStages.

conflict_resolution:
  default_winner: secret_server
  field_override_rules:
    - fields: ["password", "private_key", "api_key"]
      winner: secret_server
    - fields: ["host", "port", "database"]
      winner: aws
  on_unresolvable: quarantine_and_alert

Quarantine Queue

Secrets that cannot be automatically resolved are placed in the quarantine queue, visible at Admin → Sync Connectors → Conflicts. Operators must manually resolve or dismiss each item. Quarantined secrets are not synced until resolved.

The integration's security model is built on layered encryption, zero standing access, and auditable data flows. No plaintext credential material ever crosses system boundaries unencrypted.

Shared Responsibility Model

┌──────────────────────────────┬────────────────────────┬────────────────────────┐
│ Responsibility               │ Secret Server          │ AWS KMS / SM           │
├──────────────────────────────┼────────────────────────┼────────────────────────┤
│ Credential lifecycle mgmt   │ ✓ Owner                │ Replication            │
│ Access policy enforcement   │ ✓ Owner                │ IAM complement         │
│ Cryptographic key custody   │ AES-256 at-rest        │ ✓ Owner (CMK)          │
│ Native AWS service delivery │ Via sync only          │ ✓ Owner                │
│ Rotation scheduling         │ ✓ Owner                │ Triggered by push      │
│ Compliance audit trail      │ SS Audit Log           │ CloudTrail             │
└──────────────────────────────┴────────────────────────┴────────────────────────┘

Test your understanding of key integration concepts before deploying.

Complete all items before going live. This checklist is tracked per session — check items off as you verify them.

Security Hardening

• ExternalId set on IAM trust policy and matches SS connector configuration
• IAM role permissions scoped to ss-sync/* resource prefix only
• CMK key policy restricts kms:Decrypt to sync role ARN exclusively
• SCP in place to prevent unauthorized Secrets Manager access from other accounts
• VPC endpoint deployed for Secrets Manager and KMS (no public egress)
• CloudTrail and SS audit logs shipped to immutable S3 bucket with Object Lock

Operational Readiness

• Template mappings tested with sample secrets in non-production environment
• Conflict resolution policy documented and approved by security team
• SNS alerts configured for quarantine queue events
• Runbook created for manual conflict resolution procedures
• Rollback procedure documented (disable connector, clear sync state)
• AWS API quotas validated for expected secret volume and sync frequency
• Monitoring dashboard created for sync latency, error rates, and conflict counts