ListenerAction

class aws_cdk.aws_elasticloadbalancingv2.ListenerAction(default_action_json, next=None)

Bases: object

What to do when a client makes a request to a listener.

Some actions can be combined with other ones (specifically, you can perform authentication before serving the request).

Multiple actions form a linked chain; the chain must always terminate in a (weighted)forward, fixedResponse or redirect action.

If an action supports chaining, the next action can be indicated by passing it in the next property.

(Called ListenerAction instead of the more strictly correct ListenerAction because this is the class most users interact with, and we want to make it not too visually overwhelming).

ExampleMetadata:

infused

Example:

import aws_cdk.aws_certificatemanager as acm

# certificate: acm.Certificate
# lb: elbv2.ApplicationLoadBalancer
# bucket: s3.Bucket


trust_store = elbv2.TrustStore(self, "Store",
    bucket=bucket,
    key="rootCA_cert.pem"
)

lb.add_listener("Listener",
    port=443,
    protocol=elbv2.ApplicationProtocol.HTTPS,
    certificates=[certificate],
    # mTLS settings
    mutual_authentication=elbv2.MutualAuthentication(
        ignore_client_certificate_expiry=False,
        mutual_authentication_mode=elbv2.MutualAuthenticationMode.VERIFY,
        trust_store=trust_store
    ),
    default_action=elbv2.ListenerAction.fixed_response(200, content_type="text/plain", message_body="Success mTLS")
)

Create an instance of ListenerAction.

The default class should be good enough for most cases and should be created by using one of the static factory functions, but allow overriding to make sure we allow flexibility for the future.

Parameters:

Methods

bind(scope, listener, associating_construct=None)

Called when the action is being used in a listener.

Parameters:
Return type:

None

render_actions()

Render the listener default actions in this chain.

Return type:

List[ActionProperty]

render_rule_actions()

Render the listener rule actions in this chain.

Return type:

List[ActionProperty]

Static Methods

classmethod authenticate_oidc(*, authorization_endpoint, client_id, client_secret, issuer, next, token_endpoint, user_info_endpoint, allow_https_outbound=None, authentication_request_extra_params=None, on_unauthenticated_request=None, scope=None, session_cookie_name=None, session_timeout=None)

Authenticate using an identity provider (IdP) that is compliant with OpenID Connect (OIDC).

Parameters:
  • authorization_endpoint (str) – The authorization endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

  • client_id (str) – The OAuth 2.0 client identifier.

  • client_secret (SecretValue) – The OAuth 2.0 client secret.

  • issuer (str) – The OIDC issuer identifier of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

  • next (ListenerAction) – What action to execute next.

  • token_endpoint (str) – The token endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

  • user_info_endpoint (str) – The user info endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

  • allow_https_outbound (Optional[bool]) – Allow HTTPS outbound traffic to communicate with the IdP. Set this property to false if the IP address used for the IdP endpoint is identifiable and you want to control outbound traffic. Then allow HTTPS outbound traffic to the IdP’s IP address using the listener’s connections property. Default: true

  • authentication_request_extra_params (Optional[Mapping[str, str]]) – The query parameters (up to 10) to include in the redirect request to the authorization endpoint. Default: - No extra parameters

  • on_unauthenticated_request (Optional[UnauthenticatedAction]) – The behavior if the user is not authenticated. Default: UnauthenticatedAction.AUTHENTICATE

  • scope (Optional[str]) – The set of user claims to be requested from the IdP. To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP. Default: “openid”

  • session_cookie_name (Optional[str]) – The name of the cookie used to maintain session information. Default: “AWSELBAuthSessionCookie”

  • session_timeout (Optional[Duration]) – The maximum duration of the authentication session. Default: Duration.days(7)

See:

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html#oidc-requirements

Return type:

ListenerAction

classmethod fixed_response(status_code, *, content_type=None, message_body=None)

Return a fixed response.

Parameters:
  • status_code (Union[int, float]) –

  • content_type (Optional[str]) – Content Type of the response. Valid Values: text/plain | text/css | text/html | application/javascript | application/json Default: - Automatically determined

  • message_body (Optional[str]) – The response body. Default: - No body

See:

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#fixed-response-actions

Return type:

ListenerAction

classmethod forward(target_groups, *, stickiness_duration=None)

Forward to one or more Target Groups.

Parameters:
  • target_groups (Sequence[IApplicationTargetGroup]) –

  • stickiness_duration (Optional[Duration]) – For how long clients should be directed to the same target group. Range between 1 second and 7 days. Default: - No stickiness

See:

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#forward-actions

Return type:

ListenerAction

classmethod redirect(*, host=None, path=None, permanent=None, port=None, protocol=None, query=None)

Redirect to a different URI.

A URI consists of the following components: protocol://hostname:port/path?query. You must modify at least one of the following components to avoid a redirect loop: protocol, hostname, port, or path. Any components that you do not modify retain their original values.

You can reuse URI components using the following reserved keywords:

  • #{protocol}

  • #{host}

  • #{port}

  • #{path} (the leading “/” is removed)

  • #{query}

For example, you can change the path to “/new/#{path}”, the hostname to “example.#{host}”, or the query to “#{query}&value=xyz”.

Parameters:
  • host (Optional[str]) – The hostname. This component is not percent-encoded. The hostname can contain #{host}. Default: - No change

  • path (Optional[str]) – The absolute path, starting with the leading “/”. This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}. Default: - No change

  • permanent (Optional[bool]) – The HTTP redirect code. The redirect is either permanent (HTTP 301) or temporary (HTTP 302). Default: false

  • port (Optional[str]) – The port. You can specify a value from 1 to 65535 or #{port}. Default: - No change

  • protocol (Optional[str]) – The protocol. You can specify HTTP, HTTPS, or #{protocol}. You can redirect HTTP to HTTP, HTTP to HTTPS, and HTTPS to HTTPS. You cannot redirect HTTPS to HTTP. Default: - No change

  • query (Optional[str]) – The query parameters, URL-encoded when necessary, but not percent-encoded. Do not include the leading “?”, as it is automatically added. You can specify any of the reserved keywords. Default: - No change

See:

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#redirect-actions

Return type:

ListenerAction

classmethod weighted_forward(target_groups, *, stickiness_duration=None)

Forward to one or more Target Groups which are weighted differently.

Parameters:
  • target_groups (Sequence[Union[WeightedTargetGroup, Dict[str, Any]]]) –

  • stickiness_duration (Optional[Duration]) – For how long clients should be directed to the same target group. Range between 1 second and 7 days. Default: - No stickiness

See:

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#forward-actions

Return type:

ListenerAction