:doc:`IoT <../../iot>` / Client / test_authorization

******************
test_authorization
******************



.. py:method:: IoT.Client.test_authorization(**kwargs)

  

  Tests if a specified principal is authorized to perform an IoT action on a specified resource. Use this to test and debug the authorization behavior of devices that connect to the IoT device gateway.

   

  Requires permission to access the `TestAuthorization <https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-actions-as-permissions>`__ action.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/iot-2015-05-28/TestAuthorization>`_  


  **Request Syntax**
  ::

    response = client.test_authorization(
        principal='string',
        cognitoIdentityPoolId='string',
        authInfos=[
            {
                'actionType': 'PUBLISH'|'SUBSCRIBE'|'RECEIVE'|'CONNECT',
                'resources': [
                    'string',
                ]
            },
        ],
        clientId='string',
        policyNamesToAdd=[
            'string',
        ],
        policyNamesToSkip=[
            'string',
        ]
    )
    
  :type principal: string
  :param principal: 

    The principal. Valid principals are CertificateArn (arn:aws:iot:*region*:*accountId*:cert/*certificateId*) and CognitoId (*region*:*id*).

    

  
  :type cognitoIdentityPoolId: string
  :param cognitoIdentityPoolId: 

    The Cognito identity pool ID.

    

  
  :type authInfos: list
  :param authInfos: **[REQUIRED]** 

    A list of authorization info objects. Simulating authorization will create a response for each ``authInfo`` object in the list.

    

  
    - *(dict) --* 

      A collection of authorization information.

      

    
      - **actionType** *(string) --* 

        The type of action for which the principal is being authorized.

        

      
      - **resources** *(list) --* **[REQUIRED]** 

        The resources for which the principal is being authorized to perform the specified action.

        

      
        - *(string) --* 

        
    
    

  :type clientId: string
  :param clientId: 

    The MQTT client ID.

    

  
  :type policyNamesToAdd: list
  :param policyNamesToAdd: 

    When testing custom authorization, the policies specified here are treated as if they are attached to the principal being authorized.

    

  
    - *(string) --* 

    

  :type policyNamesToSkip: list
  :param policyNamesToSkip: 

    When testing custom authorization, the policies specified here are treated as if they are not attached to the principal being authorized.

    

  
    - *(string) --* 

    

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

    
    ::

      {
          'authResults': [
              {
                  'authInfo': {
                      'actionType': 'PUBLISH'|'SUBSCRIBE'|'RECEIVE'|'CONNECT',
                      'resources': [
                          'string',
                      ]
                  },
                  'allowed': {
                      'policies': [
                          {
                              'policyName': 'string',
                              'policyArn': 'string'
                          },
                      ]
                  },
                  'denied': {
                      'implicitDeny': {
                          'policies': [
                              {
                                  'policyName': 'string',
                                  'policyArn': 'string'
                              },
                          ]
                      },
                      'explicitDeny': {
                          'policies': [
                              {
                                  'policyName': 'string',
                                  'policyArn': 'string'
                              },
                          ]
                      }
                  },
                  'authDecision': 'ALLOWED'|'EXPLICIT_DENY'|'IMPLICIT_DENY',
                  'missingContextValues': [
                      'string',
                  ]
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **authResults** *(list) --* 

        The authentication results.

        
        

        - *(dict) --* 

          The authorizer result.

          
          

          - **authInfo** *(dict) --* 

            Authorization information.

            
            

            - **actionType** *(string) --* 

              The type of action for which the principal is being authorized.

              
            

            - **resources** *(list) --* 

              The resources for which the principal is being authorized to perform the specified action.

              
              

              - *(string) --* 
          
        
          

          - **allowed** *(dict) --* 

            The policies and statements that allowed the specified action.

            
            

            - **policies** *(list) --* 

              A list of policies that allowed the authentication.

              
              

              - *(dict) --* 

                Describes an IoT policy.

                
                

                - **policyName** *(string) --* 

                  The policy name.

                  
                

                - **policyArn** *(string) --* 

                  The policy ARN.

                  
            
          
        
          

          - **denied** *(dict) --* 

            The policies and statements that denied the specified action.

            
            

            - **implicitDeny** *(dict) --* 

              Information that implicitly denies the authorization. When a policy doesn't explicitly deny or allow an action on a resource it is considered an implicit deny.

              
              

              - **policies** *(list) --* 

                Policies that don't contain a matching allow or deny statement for the specified action on the specified resource.

                
                

                - *(dict) --* 

                  Describes an IoT policy.

                  
                  

                  - **policyName** *(string) --* 

                    The policy name.

                    
                  

                  - **policyArn** *(string) --* 

                    The policy ARN.

                    
              
            
          
            

            - **explicitDeny** *(dict) --* 

              Information that explicitly denies the authorization.

              
              

              - **policies** *(list) --* 

                The policies that denied the authorization.

                
                

                - *(dict) --* 

                  Describes an IoT policy.

                  
                  

                  - **policyName** *(string) --* 

                    The policy name.

                    
                  

                  - **policyArn** *(string) --* 

                    The policy ARN.

                    
              
            
          
        
          

          - **authDecision** *(string) --* 

            The final authorization decision of this scenario. Multiple statements are taken into account when determining the authorization decision. An explicit deny statement can override multiple allow statements.

            
          

          - **missingContextValues** *(list) --* 

            Contains any missing context values found while evaluating policy.

            
            

            - *(string) --* 
        
      
    
  
  **Exceptions**
  
  *   :py:class:`IoT.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`IoT.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`IoT.Client.exceptions.ThrottlingException`

  
  *   :py:class:`IoT.Client.exceptions.UnauthorizedException`

  
  *   :py:class:`IoT.Client.exceptions.ServiceUnavailableException`

  
  *   :py:class:`IoT.Client.exceptions.InternalFailureException`

  
  *   :py:class:`IoT.Client.exceptions.LimitExceededException`

  