HTTP headers

This topic describes the additional HTTP headers supported by Application Load Balancer (ALB) and explains how to configure them for a listener. You can use these headers to implement specific features based on your requirements.

Supported ALB headers

HTTP headers are fields in the header section of an HTTP request or response message. You can customize headers for specific needs, which can result in the use of additional HTTP headers by web servers and browsers. The following table describes the additional HTTP headers that ALB supports and their functions.

Header field

Description

Listener protocols

X-Forwarded-For

Enables the listener to use theX-Forwarded-For header to retrieve the client IP address.

When theX-Forwarded-For header is enabled:

ALB adds or removes theX-Forwarded-For header from a request before forwarding it to a backend server.
- Add (Default)
  
  By default, ALB saves the client IP address in the X-Forwarded-For header field and sends this header field to the backend server. If the original request does not contain an X-Forwarded-For header field, ALB creates an X-Forwarded-For header field that contains the client IP address. Otherwise, ALB appends the client IP address to the existing X-Forwarded-For header field, and then sends the header field to the backend server. The X-Forwarded-For request header field may contain multiple comma-separated IP addresses.
- Remove
  
  ALB removes theX-Forwarded-For header from the request before forwarding it to the backend server.
When theX-Forwarded-For header is disabled:

ALB does not modify theX-Forwarded-For header in the request before forwarding it to the backend server.

Format:

X-Forwarded-For: <client-ip-address>, <proxy1>, <proxy2>, …

Click to see an example of theX-Forwarded-For header received by the backend server based on the selected action (Add, Remove, or Disable).

In this example, the client IP address that connects to ALB is127.0.0.1.

Request description	Sample request	Enable `X-Forwarded-For` header field		Disable`X-Forwarded-For` header field
Request description	Sample request	Add	Remove	Disable`X-Forwarded-For` header field
The original request does not contain an`X-Forwarded-For` header	GET /index.html HTTP/1.1 Host: example.com	X-Forwarded-For: 127.0.0.1	None	None
The original request contains an`X-Forwarded-For` header with one client IP address	GET /index.html HTTP/1.1 Host: example.com X-Forwarded-For: 127.0.0.2	X-Forwarded-For: 127.0.0.2, 127.0.0.1	None	X-Forwarded-For: 127.0.0.2
The original request contains an`X-Forwarded-For` header with multiple client IP addresses	GET /index.html HTTP/1.1 Host: example.com X-Forwarded-For: 127.0.0.2, 127.0.0.3	X-Forwarded-For: 127.0.0.2, 127.0.0.3, 127.0.0.1	None	X-Forwarded-For: 127.0.0.2, 127.0.0.3

For instructions on how to retrieve the real client IP address, see Retrieve the client IP on a backend server.

HTTP
HTTPS
QUIC (supported only by ALB upgraded instances)

SLB-ID

Adds theSLB-ID header, which contains the ID of the ALB instance.

HTTP
HTTPS
QUIC

X-Forwarded-Proto

Adds theX-Forwarded-Proto header, which contains the protocol the client used to connect to the listener. Your application can use the protocol stored in theX-Forwarded-Proto header to redirect requests to the target URL.

Format:

X-Forwarded-Proto: <originatingProtocol>

A typical use case: An ALB instance uses an HTTPS listener, and the communication between the listener and its backend server group uses HTTP. In this scenario, the backend server receives the request with the HTTP protocol. If the backend server is configured with a rule to automatically redirect HTTP to HTTPS, it might incorrectly determine that the client is using HTTP, causing a redirection loop. By enabling theX-Forwarded-Proto header, the backend server can retrieve the original request protocol from the client, preventing this mis-triggered redirection. We recommend also enabling theX-Forwarded-Port header so the backend server can obtain the original request port of the client.

HTTP
HTTPS
QUIC

X-Forwarded-Port

Adds theX-Forwarded-Port header, which contains the listener port that received the request.

Format:

X-Forwarded-Port: <port>

HTTP
HTTPS
QUIC

X-Forwarded-Host

Adds theX-Forwarded-Host header, which contains the original host requested by the client.

Format:

X-Forwarded-Host: <host>

HTTP
HTTPS
QUIC

X-Forwarded-Client-srcport

Adds theX-Forwarded-Client-srcport header, which contains the source port of the client.

Format:

X-Forwarded-Client-srcport: <port>

HTTP
HTTPS
QUIC (supported only by ALB upgraded instances)

X-Forwarded-Clientcert-subjectdn

Enable the X-Forwarded-Clientcert-subjectdn header field to obtain the owner information of the client certificate used to access the ALB instance.

After you enable this header, you must enter a custom HTTP header name.

HTTPS

X-Forwarded-Clientcert-issuerdn

Enable the X-Forwarded-Clientcert-issuerdn header field to retrieve the issuer information of the client certificate used to access the ALB instance.

After you enable this header, you must enter a custom HTTP header name.

HTTPS

X-Forwarded-Clientcert-fingerprint

Enable the X-Forwarded-Clientcert-fingerprint header field to obtain the fingerprint value of the client certificate used to access the ALB instance.

After you enable this header, you must enter a custom HTTP header name.

HTTPS

X-Forwarded-Clientcert-clientverify

Enable the X-Forwarded-Clientcert-clientverify header field to obtain the verification result of the client certificate used to access the ALB instance.

After you enable this header, you must enter a custom HTTP header name.

HTTPS

The additional HTTP headers mentioned above are configured using switches at the listener level. When enabled, ALB automatically adds the corresponding headers to requests forwarded to the backend server. If you need to customize header values, such as specifying the original request protocol or port, you can manually set them by using the Insert Header action in a forwarding rule. The listener-level switches are suitable for most pass-through scenarios, while forwarding rules are ideal for scenarios that require fine-grained control over header values. These settings are located in the Advanced Settings section of the listener configuration and the forwarding rule editor, respectively.

Note

We recommend that your backend servers follow the HTTP specification and treat HTTP header keys as case-insensitive.
- TheX-Forwarded-For header that ALB forwards to backend servers always starts with an uppercase letter.
- For the other additional HTTP headers, if the client request already contains one of these headers, ALB preserves its original capitalization when forwarding it. Otherwise, ALB adds the header using the capitalization shown in the table above.
When you enableX-Forwarded-Clientcert-subjectdn, X-Forwarded-Clientcert-issuerdn, X-Forwarded-Clientcert-fingerprint, orX-Forwarded-Clientcert-clientverify, you cannot set the custom HTTP header name to any of the following reserved fields: slb-id, slb-ip, x-forwarded-for, x-forwarded-proto, x-forwarded-eip, x-forwarded-port, x-forwarded-client-srcport, x-forwarded-host, connection, upgrade, content-length, transfer-encoding, keep-alive, te, host, cookie, remoteip, or authority.
Description of additional HTTP headers related to client certificates
The following additional HTTP headers take effect only when mutual authentication is enabled for an HTTPS listener.
X-Forwarded-Clientcert-subjectdn
- Purpose: Contains the Subject Distinguished Name (DN) from the client certificate.
- Content: The identity information of the certificate owner.
- Example format: X-Forwarded-Clientcert-Subjectdn: CN=client.example.com,O=Example Corp,C=US
- Includes:
  
  CN (Common Name)
  
  O (Organization)
  
  OU (Organizational Unit)
  
  C (Country)
  
  ST (State)
  
  L (Locality)
X-Forwarded-Clientcert-issuerdn
- Purpose: Contains the Issuer Distinguished Name (DN) from the client certificate.
- Content: Information about the Certificate Authority (CA) that issued the certificate.
- Example format: X-Forwarded-Clientcert-Issuerdn: CN=Example CA,O=Example Corp,C=US
- Use case: Verify whether the certificate was issued by a trusted CA.
X-Forwarded-Clientcert-fingerprint
- Purpose: Contains the digital fingerprint of the client certificate.
- Content: The certificate fingerprint. This is a fixed-length hash value computed from the entire certificate content by using a hash algorithm, such as SHA-1 or SHA-256. It serves as a unique identifier for the certificate.
- Example format: X-Forwarded-Clientcert-Fingerprint: SHA256=1234567890abcdef...
- Use case: Uniquely identify a certificate for validation and auditing.
X-Forwarded-Clientcert-clientverify
- Purpose: Contains the verification result of the client certificate.
- Content: The certificate verification status.
- Possible values:
  
  SUCCESS: The certificate is verified.
  
  FAILED: Certificate verification failed.
  
  NONE: No client certificate was presented.
  
  EXPIRED: The certificate has expired.
  
  REVOKED: The certificate has been revoked.

Add a header in the console

Add a header during listener creation

Log on to the ALB console.
In the top navigation bar, select the region where the ALB instance is deployed.
Use one of the following methods to open the listener configuration wizard:
- On the Instances page, find the instance that you want to manage and click Create Listener in the Actions column.
- On the Instances page, click the ID of the target instance. On the Listener tab, click Create Listener.

In the Configure Listener wizard, configure the following parameters and click Next.

Parameter	Description
Listener Protocol	Select a protocol for the listener.
Advanced Settings	Click Modify to expand the advanced settings.
Custom HTTP Header	Select the additional HTTP headers that you want to enable based on your business requirements.

Note

This section describes only the parameters related to headers. For more information about other parameters, see the following topics:

Follow the on-screen instructions to finish creating the listener.

Add a header to an existing listener

Log on to the ALB console.
In the top navigation bar, select the region where the ALB instance is deployed.
On the Instances page, click the ID of the target instance.
On the Listener tab, find the target listener and choose >Modify Listener in the Actions column.
In the Modify Listener dialog box, click Modify to the right of Advanced Settings.
In the Custom HTTP Header section, enable or disable headers as required, and then click Save.

Add a header by using an API

You can configure additional headers when you create a listener, or modify the header configuration for an existing listener.

Create a listener: Call the CreateListener API operation and configure the XForwardedForConfig parameter.
Modify an existing listener: Call the UpdateListenerAttribute API operation to update the XForwardedForConfig parameter.

References

Console

To forward HTTP requests through an ALB instance, see Add an HTTP listener.
To forward HTTPS requests through an ALB instance, see Add an HTTPS listener.
To forward QUIC requests through an ALB instance, see Add a QUIC listener.

API

CreateListener: Creates an HTTP, HTTPS, or QUIC listener. You can add HTTP headers by setting the XForwardedForConfig parameter.
UpdateListenerAttribute: Updates the configuration of a listener. You can update the XForwardedForConfig parameter to modify the header configuration.