:doc:`ElasticLoadBalancingv2 <../../elbv2>` / Client / describe_listeners

******************
describe_listeners
******************



.. py:method:: ElasticLoadBalancingv2.Client.describe_listeners(**kwargs)

  

  Describes the specified listeners or the listeners for the specified Application Load Balancer, Network Load Balancer, or Gateway Load Balancer. You must specify either a load balancer or one or more listeners.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/elasticloadbalancingv2-2015-12-01/DescribeListeners>`_  


  **Request Syntax**
  ::

    response = client.describe_listeners(
        LoadBalancerArn='string',
        ListenerArns=[
            'string',
        ],
        Marker='string',
        PageSize=123
    )
    
  :type LoadBalancerArn: string
  :param LoadBalancerArn: 

    The Amazon Resource Name (ARN) of the load balancer.

    

  
  :type ListenerArns: list
  :param ListenerArns: 

    The Amazon Resource Names (ARN) of the listeners.

    

  
    - *(string) --* 

    

  :type Marker: string
  :param Marker: 

    The marker for the next set of results. (You received this marker from a previous call.)

    

  
  :type PageSize: integer
  :param PageSize: 

    The maximum number of results to return with this call.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Listeners': [
              {
                  'ListenerArn': 'string',
                  'LoadBalancerArn': 'string',
                  'Port': 123,
                  'Protocol': 'HTTP'|'HTTPS'|'TCP'|'TLS'|'UDP'|'TCP_UDP'|'GENEVE'|'QUIC'|'TCP_QUIC',
                  'Certificates': [
                      {
                          'CertificateArn': 'string',
                          'IsDefault': True|False
                      },
                  ],
                  'SslPolicy': 'string',
                  'DefaultActions': [
                      {
                          'Type': 'forward'|'authenticate-oidc'|'authenticate-cognito'|'redirect'|'fixed-response'|'jwt-validation',
                          'TargetGroupArn': 'string',
                          'AuthenticateOidcConfig': {
                              'Issuer': 'string',
                              'AuthorizationEndpoint': 'string',
                              'TokenEndpoint': 'string',
                              'UserInfoEndpoint': 'string',
                              'ClientId': 'string',
                              'ClientSecret': 'string',
                              'SessionCookieName': 'string',
                              'Scope': 'string',
                              'SessionTimeout': 123,
                              'AuthenticationRequestExtraParams': {
                                  'string': 'string'
                              },
                              'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate',
                              'UseExistingClientSecret': True|False
                          },
                          'AuthenticateCognitoConfig': {
                              'UserPoolArn': 'string',
                              'UserPoolClientId': 'string',
                              'UserPoolDomain': 'string',
                              'SessionCookieName': 'string',
                              'Scope': 'string',
                              'SessionTimeout': 123,
                              'AuthenticationRequestExtraParams': {
                                  'string': 'string'
                              },
                              'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate'
                          },
                          'Order': 123,
                          'RedirectConfig': {
                              'Protocol': 'string',
                              'Port': 'string',
                              'Host': 'string',
                              'Path': 'string',
                              'Query': 'string',
                              'StatusCode': 'HTTP_301'|'HTTP_302'
                          },
                          'FixedResponseConfig': {
                              'MessageBody': 'string',
                              'StatusCode': 'string',
                              'ContentType': 'string'
                          },
                          'ForwardConfig': {
                              'TargetGroups': [
                                  {
                                      'TargetGroupArn': 'string',
                                      'Weight': 123
                                  },
                              ],
                              'TargetGroupStickinessConfig': {
                                  'Enabled': True|False,
                                  'DurationSeconds': 123
                              }
                          },
                          'JwtValidationConfig': {
                              'JwksEndpoint': 'string',
                              'Issuer': 'string',
                              'AdditionalClaims': [
                                  {
                                      'Format': 'single-string'|'string-array'|'space-separated-values',
                                      'Name': 'string',
                                      'Values': [
                                          'string',
                                      ]
                                  },
                              ]
                          }
                      },
                  ],
                  'AlpnPolicy': [
                      'string',
                  ],
                  'MutualAuthentication': {
                      'Mode': 'string',
                      'TrustStoreArn': 'string',
                      'IgnoreClientCertificateExpiry': True|False,
                      'TrustStoreAssociationStatus': 'active'|'removed',
                      'AdvertiseTrustStoreCaNames': 'on'|'off'
                  }
              },
          ],
          'NextMarker': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Listeners** *(list) --* 

        Information about the listeners.

        
        

        - *(dict) --* 

          Information about a listener.

          
          

          - **ListenerArn** *(string) --* 

            The Amazon Resource Name (ARN) of the listener.

            
          

          - **LoadBalancerArn** *(string) --* 

            The Amazon Resource Name (ARN) of the load balancer.

            
          

          - **Port** *(integer) --* 

            The port on which the load balancer is listening.

            
          

          - **Protocol** *(string) --* 

            The protocol for connections from clients to the load balancer.

            
          

          - **Certificates** *(list) --* 

            [HTTPS or TLS listener] The default certificate for the listener.

            
            

            - *(dict) --* 

              Information about an SSL server certificate.

              
              

              - **CertificateArn** *(string) --* 

                The Amazon Resource Name (ARN) of the certificate.

                
              

              - **IsDefault** *(boolean) --* 

                Indicates whether the certificate is the default certificate. Do not set this value when specifying a certificate as an input. This value is not included in the output when describing a listener, but is included when describing listener certificates.

                
          
        
          

          - **SslPolicy** *(string) --* 

            [HTTPS or TLS listener] The security policy that defines which protocols and ciphers are supported.

            
          

          - **DefaultActions** *(list) --* 

            The default actions for the listener.

            
            

            - *(dict) --* 

              Information about an action.

               

              Each rule must include exactly one of the following routing actions: ``forward``, ``fixed-response``, or ``redirect``, and it must be the last action to be performed.

               

              Optionally, a rule for an HTTPS listener can also include one of the following user authentication actions: ``authenticate-oidc``, ``authenticate-cognito``, or ``jwt-validation``.

              
              

              - **Type** *(string) --* 

                The type of action.

                
              

              - **TargetGroupArn** *(string) --* 

                The Amazon Resource Name (ARN) of the target group. Specify only when ``Type`` is ``forward`` and you want to route to a single target group. To route to multiple target groups, you must use ``ForwardConfig`` instead.

                
              

              - **AuthenticateOidcConfig** *(dict) --* 

                [HTTPS listeners] Information about an identity provider that is compliant with OpenID Connect (OIDC). Specify only when ``Type`` is ``authenticate-oidc``.

                
                

                - **Issuer** *(string) --* 

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

                  
                

                - **AuthorizationEndpoint** *(string) --* 

                  The authorization endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

                  
                

                - **TokenEndpoint** *(string) --* 

                  The token endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

                  
                

                - **UserInfoEndpoint** *(string) --* 

                  The user info endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

                  
                

                - **ClientId** *(string) --* 

                  The OAuth 2.0 client identifier.

                  
                

                - **ClientSecret** *(string) --* 

                  The OAuth 2.0 client secret. This parameter is required if you are creating a rule. If you are modifying a rule, you can omit this parameter if you set ``UseExistingClientSecret`` to true.

                  
                

                - **SessionCookieName** *(string) --* 

                  The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.

                  
                

                - **Scope** *(string) --* 

                  The set of user claims to be requested from the IdP. The default is ``openid``.

                   

                  To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.

                  
                

                - **SessionTimeout** *(integer) --* 

                  The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).

                  
                

                - **AuthenticationRequestExtraParams** *(dict) --* 

                  The query parameters (up to 10) to include in the redirect request to the authorization endpoint.

                  
                  

                  - *(string) --* 
                    

                    - *(string) --* 
              
            
                

                - **OnUnauthenticatedRequest** *(string) --* 

                  The behavior if the user is not authenticated. The following are possible values:

                   

                  
                  * deny  - Return an HTTP 401 Unauthorized error.
                   
                  * allow  - Allow the request to be forwarded to the target.
                   
                  * authenticate  - Redirect the request to the IdP authorization endpoint. This is the default value.
                  

                  
                

                - **UseExistingClientSecret** *(boolean) --* 

                  Indicates whether to use the existing client secret when modifying a rule. If you are creating a rule, you can omit this parameter or set it to false.

                  
            
              

              - **AuthenticateCognitoConfig** *(dict) --* 

                [HTTPS listeners] Information for using Amazon Cognito to authenticate users. Specify only when ``Type`` is ``authenticate-cognito``.

                
                

                - **UserPoolArn** *(string) --* 

                  The Amazon Resource Name (ARN) of the Amazon Cognito user pool.

                  
                

                - **UserPoolClientId** *(string) --* 

                  The ID of the Amazon Cognito user pool client.

                  
                

                - **UserPoolDomain** *(string) --* 

                  The domain prefix or fully-qualified domain name of the Amazon Cognito user pool.

                  
                

                - **SessionCookieName** *(string) --* 

                  The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.

                  
                

                - **Scope** *(string) --* 

                  The set of user claims to be requested from the IdP. The default is ``openid``.

                   

                  To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.

                  
                

                - **SessionTimeout** *(integer) --* 

                  The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).

                  
                

                - **AuthenticationRequestExtraParams** *(dict) --* 

                  The query parameters (up to 10) to include in the redirect request to the authorization endpoint.

                  
                  

                  - *(string) --* 
                    

                    - *(string) --* 
              
            
                

                - **OnUnauthenticatedRequest** *(string) --* 

                  The behavior if the user is not authenticated. The following are possible values:

                   

                  
                  * deny  - Return an HTTP 401 Unauthorized error.
                   
                  * allow  - Allow the request to be forwarded to the target.
                   
                  * authenticate  - Redirect the request to the IdP authorization endpoint. This is the default value.
                  

                  
            
              

              - **Order** *(integer) --* 

                The order for the action. This value is required for rules with multiple actions. The action with the lowest value for order is performed first.

                
              

              - **RedirectConfig** *(dict) --* 

                [Application Load Balancer] Information for creating a redirect action. Specify only when ``Type`` is ``redirect``.

                
                

                - **Protocol** *(string) --* 

                  The protocol. You can specify HTTP, HTTPS, or #{protocol}. You can redirect HTTP to HTTP, HTTP to HTTPS, and HTTPS to HTTPS. You can't redirect HTTPS to HTTP.

                  
                

                - **Port** *(string) --* 

                  The port. You can specify a value from 1 to 65535 or #{port}.

                  
                

                - **Host** *(string) --* 

                  The hostname. This component is not percent-encoded. The hostname can contain #{host}.

                  
                

                - **Path** *(string) --* 

                  The absolute path, starting with the leading "/". This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}.

                  
                

                - **Query** *(string) --* 

                  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.

                  
                

                - **StatusCode** *(string) --* 

                  The HTTP redirect code. The redirect is either permanent (HTTP 301) or temporary (HTTP 302).

                  
            
              

              - **FixedResponseConfig** *(dict) --* 

                [Application Load Balancer] Information for creating an action that returns a custom HTTP response. Specify only when ``Type`` is ``fixed-response``.

                
                

                - **MessageBody** *(string) --* 

                  The message.

                  
                

                - **StatusCode** *(string) --* 

                  The HTTP response code (2XX, 4XX, or 5XX).

                  
                

                - **ContentType** *(string) --* 

                  The content type.

                   

                  Valid Values: text/plain | text/css | text/html | application/javascript | application/json

                  
            
              

              - **ForwardConfig** *(dict) --* 

                Information for creating an action that distributes requests among multiple target groups. Specify only when ``Type`` is ``forward``.

                 

                If you specify both ``ForwardConfig`` and ``TargetGroupArn``, you can specify only one target group using ``ForwardConfig`` and it must be the same target group specified in ``TargetGroupArn``.

                
                

                - **TargetGroups** *(list) --* 

                  The target groups.

                  
                  

                  - *(dict) --* 

                    Information about how traffic will be distributed between multiple target groups in a forward rule.

                    
                    

                    - **TargetGroupArn** *(string) --* 

                      The Amazon Resource Name (ARN) of the target group.

                      
                    

                    - **Weight** *(integer) --* 

                      The weight. The range is 0 to 999.

                      
                
              
                

                - **TargetGroupStickinessConfig** *(dict) --* 

                  The target group stickiness for the rule.

                  
                  

                  - **Enabled** *(boolean) --* 

                    Indicates whether target group stickiness is enabled.

                    
                  

                  - **DurationSeconds** *(integer) --* 

                    [Application Load Balancers] The time period, in seconds, during which requests from a client should be routed to the same target group. The range is 1-604800 seconds (7 days). You must specify this value when enabling target group stickiness.

                    
              
            
              

              - **JwtValidationConfig** *(dict) --* 

                [HTTPS listeners] Information for validating JWT access tokens in client requests. Specify only when ``Type`` is ``jwt-validation``.

                
                

                - **JwksEndpoint** *(string) --* 

                  The JSON Web Key Set (JWKS) endpoint. This endpoint contains JSON Web Keys (JWK) that are used to validate signatures from the provider.

                   

                  This must be a full URL, including the HTTPS protocol, the domain, and the path. The maximum length is 256 characters.

                  
                

                - **Issuer** *(string) --* 

                  The issuer of the JWT. The maximum length is 256 characters.

                  
                

                - **AdditionalClaims** *(list) --* 

                  Additional claims to validate. The maximum size of the list is 10. We validate the ``exp``, ``iss``, ``nbf``, and ``iat`` claims by default.

                  
                  

                  - *(dict) --* 

                    Information about an additional claim to validate.

                    
                    

                    - **Format** *(string) --* 

                      The format of the claim value.

                      
                    

                    - **Name** *(string) --* 

                      The name of the claim. You can't specify ``exp``, ``iss``, ``nbf``, or ``iat`` because we validate them by default.

                      
                    

                    - **Values** *(list) --* 

                      The claim value. The maximum size of the list is 10. Each value can be up to 256 characters in length. If the format is ``space-separated-values``, the values can't include spaces.

                      
                      

                      - *(string) --* 
                  
                
              
            
          
        
          

          - **AlpnPolicy** *(list) --* 

            [TLS listener] The name of the Application-Layer Protocol Negotiation (ALPN) policy.

            
            

            - *(string) --* 
        
          

          - **MutualAuthentication** *(dict) --* 

            The mutual authentication configuration information.

            
            

            - **Mode** *(string) --* 

              The client certificate handling method. Options are ``off``, ``passthrough`` or ``verify``. The default value is ``off``.

              
            

            - **TrustStoreArn** *(string) --* 

              The Amazon Resource Name (ARN) of the trust store.

              
            

            - **IgnoreClientCertificateExpiry** *(boolean) --* 

              Indicates whether expired client certificates are ignored.

              
            

            - **TrustStoreAssociationStatus** *(string) --* 

              Indicates a shared trust stores association status.

              
            

            - **AdvertiseTrustStoreCaNames** *(string) --* 

              Indicates whether trust store CA certificate names are advertised.

              
        
      
    
      

      - **NextMarker** *(string) --* 

        If there are additional results, this is the marker for the next set of results. Otherwise, this is null.

        
  
  **Exceptions**
  
  *   :py:class:`ElasticLoadBalancingv2.Client.exceptions.ListenerNotFoundException`

  
  *   :py:class:`ElasticLoadBalancingv2.Client.exceptions.LoadBalancerNotFoundException`

  
  *   :py:class:`ElasticLoadBalancingv2.Client.exceptions.UnsupportedProtocolException`

  

  **Examples**

  This example describes the specified listener.
  ::

    response = client.describe_listeners(
        ListenerArns=[
            'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2',
        ],
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'Listeners': [
            {
                'DefaultActions': [
                    {
                        'TargetGroupArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067',
                        'Type': 'forward',
                    },
                ],
                'ListenerArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2',
                'LoadBalancerArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188',
                'Port': 80,
                'Protocol': 'HTTP',
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  