Skip to content
Docs sslbrain sslbrain.com

AWS ELB & API Gateway

Copy link to the page “AWS ELB & API Gateway”

← All integrations

Cloud service · Load balancer

Installs certificates on ALB/NLB and API Gateway with ACM import, TLS verification and rollback.

The appliance runs the package and connects to AWS ELB & API Gateway through AWS ELBv2 / API Gateway API over HTTPS on port 443. No agent is installed on AWS ELB & API Gateway.

What happens

  1. The appliance connects to AWS ELB & API Gateway through AWS ELBv2 / API Gateway API on port 443.
  2. Discovery reads ALB HTTPS and NLB TLS listeners, their default certificate and SNI list, and API Gateway domains. It shows ACM certificate type and associations and selects the API Gateway v1 or v2 path from the discovered domain.
  3. The package validates the PEM certificate, unencrypted key and chain and imports them as a new ACM ARN. It saves the selected bindings and public certificates for rollback. The previous certificate and key remain in AWS.
  4. Only the selected binding changes: the listener default, selected SNI entry or custom domain certificate. A default also present in the SNI list changes in both roles. An SNI-only entry leaves the default certificate unchanged. If it fails: On failure the package automatically attempts to restore the previous ARN in its changed bindings and verifies the previous served certificate. The snapshot is retained even if rollback fails.
  5. Verification reads back ACM content and the selected binding, then uses fresh TLS connections to check the served leaf, hostname and complete chain. A default-only listener is checked without SNI; a binding with both default and SNI roles is checked with and without SNI. The root certificate need not be served.

Technical details

Connection
The package runs on the appliance, which connects over HTTPS to AWS ELBv2 / API Gateway API, port 443. No agent is installed.
You need
AWS access key ID and secret access key, with a session token when needed, or a configured AWS CLI v2 profile/role on the appliance. ACM: acm:ImportCertificate and acm:GetCertificate; acm:DescribeCertificate adds discovery metadata. ALB/NLB: elasticloadbalancing:DescribeLoadBalancers, DescribeListeners and DescribeListenerCertificates plus ModifyListener, AddListenerCertificates and RemoveListenerCertificates with the same IAM prefix. API Gateway: apigateway:GET and apigateway:PATCH on the domains, plus apigateway:AddCertificateToDomain for mTLS certificate management. EDGE also requires cloudfront:UpdateDistribution on Resource *. Scope permissions to selected resources where AWS permits and to the ACM regions in use.
Platform
Appliance 0.4.44+ with Bash, Python 3 and OpenSSL 1.1.1+. AWS CLI v2 is required only for profiles or CLI role providers.
Actions
Discovery, Installation, Verification, Rollback
Packages
aws-elb-api 1.0.0
Note
  • Select one destination per rule: AWS_REGION and AWS_LISTENER_ARN for a listener, or AWS_DOMAIN_NAME for a custom domain. Omit AWS_CERTIFICATE_ARN to use the current listener default; set the existing ARN for a specific SNI entry. AWS_CERTIFICATE_ARN selects listener certificates only; domain rules follow their current binding on each renewal. Retain the appliance backup directory across renewals so the rule follows the package's replacement ARN even when the SNI selector still names the first one.
  • API Gateway covers EDGE, REGIONAL and PRIVATE. Private domains use AWS_DOMAIN_NAME_ID to distinguish them from a public domain with the same name. AWS_ENDPOINT_TYPE selects the type if a domain has several. AWS_API_GENERATION defaults to auto; v1 or v2 can be selected per rule. EDGE uses ACM in us-east-1; Regional, private domains and listeners use their AWS region.
  • AWS_REGION selects the regional management endpoints, including eusc-de-east-1 in AWS European Sovereign Cloud under amazonaws.eu. A wildcard domain rule is verified using sslbrain-probe under the selected domain; AWS_VERIFY_SERVER_NAME can select another covered hostname.
  • ALB and EDGE support sslbrain's five issuance choices: RSA 2048/3072/4096 and ECDSA P-256/P-384. NLB: RSA 2048/3072 and ECDSA P-256/P-384. Regional and private API Gateway domains: RSA 2048 and ECDSA P-256/P-384. Regional limits public keys to 2048 bits. NLB also accepts imported RSA 1024 and ECDSA P-521, outside sslbrain's issuance choices.
  • The appliance must reach the AWS API over HTTPS 443 and the selected service over TLS. Internal listeners and private domains need network access from the appliance. AWS_VERIFY_HOST, AWS_VERIFY_PORT and AWS_VERIFY_SERVER_NAME can override the reachable TLS address, port and certificate hostname for SNI. Verification uses the supplied CA chain as the trust boundary for private PKI.
  • Activation is polled every 15 seconds for up to 50 minutes for EDGE, 20 minutes for PRIVATE and 5 minutes for other destinations. AWS_VERIFY_TIMEOUT and AWS_POLL_INTERVAL are optional per-rule overrides. Temporary CLI-provider credentials refresh before expiry during long operations.
  • AWS management TLS verifies certificates and hostnames by default. MANAGEMENT_TLS_PIN_SHA256 pins a leaf fingerprint; MANAGEMENT_TLS_CA_BUNDLE selects a CA file while retaining hostname checks. MANAGEMENT_TLS_INSECURE disables verification when explicitly selected for this connection.
  • Snapshots contain public certificates, ARNs and bindings, with no private keys or credentials. CERTOPS_BACKUP_DIR overrides ~/.sslbrain/aws-elb-backups. Retain the previous ACM certificate for rollback. The package never reimports a shared ARN or deletes certificate objects; unused imports can be cleaned up under your retention policy.
  • Discovery shows ACM-issued and imported certificates and their other associations. Only the rule's selected binding is taken over; other SNI entries, certificate managers and services remain. Rollback does not overwrite a binding later changed to a third ARN. Agree who manages this exact binding if another manager also writes to it.
  • Regional mTLS retains the existing ownership-verification ARN. If absent, AWS_OWNERSHIP_CERTIFICATE_ARN can supply the ACM ownership certificate. Truststore, routing, DNS, access policies and other TLS settings remain. The package restarts no services and does not change Classic ELB or separate CloudFront distributions.

Get started