Cleanup custom auth samples, improve associated sample readmes (#529)

* Cleanup custom auth samples, improve associated sample readmes


---------

Co-authored-by: Bret Ambrose <[email protected]>

Author: bretambrose

.github/workflows/ci_run_custom_authorizer_connect_cfg.json

@@ -8,10 +8,6 @@
             "name": "--endpoint",
             "secret": "ci/endpoint"
         },
-        {
-            "name": "--signing_region",
-            "data": "us-east-1"
-        },
         {
             "name": "--custom_auth_authorizer_name",
             "secret": "ci/CustomAuthorizer/name"

.github/workflows/ci_run_mqtt5_custom_authorizer_cfg.json

@@ -15,16 +15,6 @@
         {
             "name": "--custom_auth_password",
             "secret": "ci/CustomAuthorizer/password"
-        },
-        {
-            "name": "--cert",
-            "secret": "ci/mqtt5/us/mqtt5_thing/cert",
-            "filename": "tmp_certificate.pem"
-        },
-        {
-            "name": "--key",
-            "secret": "ci/mqtt5/us/mqtt5_thing/key",
-            "filename": "tmp_key.pem"
         }
     ]
 }

.github/workflows/ci_run_mqtt5_custom_authorizer_websockets_cfg.json

@@ -19,10 +19,6 @@
         {
             "name": "--use_websockets",
             "data": "true"
-        },
-        {
-            "name": "--signing_region",
-            "data": "us-east-1"
         }
     ]
 }

codebuild/samples/custom-auth-linux.sh

@@ -12,6 +12,6 @@ AUTH_NAME=$(aws secretsmanager get-secret-value --secret-id "ci/CustomAuthorizer
 AUTH_PASSWORD=$(aws secretsmanager get-secret-value --secret-id "ci/CustomAuthorizer/password" --query "SecretString" | cut -f2 -d":" | sed -e 's/[\\\"\}]//g')
 
 echo "Custom Authorizer test"
-python3 custom_authorizer_connect.py --endpoint $ENDPOINT --custom_auth_authorizer_name $AUTH_NAME --custom_auth_password $AUTH_PASSWORD --signing_region us-east-1
+python3 custom_authorizer_connect.py --endpoint $ENDPOINT --custom_auth_authorizer_name $AUTH_NAME --custom_auth_password $AUTH_PASSWORD
 
 popd

samples/custom_authorizer_connect.md

@@ -37,11 +37,18 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 # How to run
 
+**Note** The sample also allows passing arguments to specify additional data your custom authorizer may need. The snippet below assumes that the custom authorizer does not need these additional parameters, but in the general case, you will almost always need some of them depending on the authorizer's configuration and the associated Lambda function's internals.
+* `--custom_auth_username` - opaque string value passed to the authorizer via an MQTT Connect packet.  The authorizer's Lambda can check this value from the event JSON value it receives as input: `event.protocolData.mqtt.username`
+* `--custom_auth_password` - opaque binary value passed to the authorizer via an MQTT Connect packet.  The authorizer's Lambda can check this value from the event JSON value it receives as input: `event.protocolData.mqtt.password`
+* `--custom_auth_token_key_name` - (Signed authorizers only) The query string parameter name that the token value should be bound to in the MQTT Connect packet.
+* `--custom_auth_token_value` - (Signed authorizers only) An arbitrary value chosen by the user.  The user must also submit a digital signature of this value using the private key associated with the authorizer.
+* `--custom_auth_authorizer_signature` - (Signed authorizers only) a digital signature of the value of the `--custom_auth_token_value` parameter using the private key associated with the authorizer.  The binary signature value must be base64 encoded and then URI encoded; the SDK will not do this for you.
+
+## MQTT over TCP with TLS
+
 To run the Custom Authorizer connect sample from the `samples` folder, use the following command:
 
 ``` sh
-# For Windows: replace 'python3' with 'python' and '/' with '\'
+# For Windows: replace 'python3' with 'python'
 python3 custom_authorizer_connect.py --endpoint <endpoint> --custom_auth_authorizer_name <authorizer name>
 ```
-
-**Note** The sample also allows passing additional arguments (`--custom_auth_username`, `--custom_auth_password`, and `custom_auth_authorizer_signature`) to fullfil the additional data your custom authorizer may need. The examples above assume that the custom authorizer does not need these additional parameters.

samples/mqtt5_custom_authorizer_connect.md

@@ -41,32 +41,27 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 # How to run
 
-### Direct MQTT via mTLS
+**Note** The sample also allows passing arguments to specify additional data your custom authorizer may need. The snippets below assume that the custom authorizer does not need these additional parameters, but in the general case, you will almost always need some of them depending on the authorizer's configuration and the associated Lambda function's internals.
+* `--custom_auth_username` - opaque string value passed to the authorizer via an MQTT Connect packet.  The authorizer's Lambda can check this value from the event JSON value it receives as input: `event.protocolData.mqtt.username`
+* `--custom_auth_password` - opaque binary value passed to the authorizer via an MQTT Connect packet.  The authorizer's Lambda can check this value from the event JSON value it receives as input: `event.protocolData.mqtt.password`
+* `--custom_auth_token_key_name` - (Signed authorizers only) The query string parameter name that the token value should be bound to in the MQTT Connect packet.
+* `--custom_auth_token_value` - (Signed authorizers only) An arbitrary value chosen by the user.  The user must also submit a digital signature of this value using the private key associated with the authorizer.
+* `--custom_auth_authorizer_signature` - (Signed authorizers only) a digital signature of the value of the `--custom_auth_token_value` parameter using the private key associated with the authorizer.  The binary signature value must be base64 encoded and then URI encoded; the SDK will not do this for you.
 
-To run the MQTT5 Custom Authorizer connect sample from the `samples` folder using mTLS, use the following command:
+## MQTT over TCP with TLS
 
-``` sh
-# For Windows: replace 'python3' with 'python' and '/' with '\'
-python3 mqtt5_custom_authorizer_connect.py --endpoint <endpoint> --cert <path to certificate> --key <path to private key> --custom_auth_authorizer_name <authorizer name>
-```
-
-You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it:
+To run the MQTT5 Custom Authorizer connect sample from the `samples` folder using TCP, use the following command:
 
 ``` sh
-# For Windows: replace 'python3' with 'python' and '/' with '\'
-python3 mqtt5_custom_authorizer_connect.py --endpoint <endpoint> --cert <path to certificate> --key <path to private key> --custom_auth_authorizer_name <authorizer name> --ca_file <path to CA file>
+# For Windows: replace 'python3' with 'python'
+python3 mqtt5_custom_authorizer_connect.py --endpoint <endpoint> --custom_auth_authorizer_name <authorizer name>
 ```
 
-**Note** The sample also allows passing additional arguments (`--custom_auth_username`, `--custom_auth_password`, and `custom_auth_authorizer_signature`) to fullfil the additional data your custom authorizer may need. The examples above assume that the custom authorizer does not need these additional parameters.
-
-
-## Websockets
+## MQTT over Websockets with TLS
 
 To run the MQTT5 Custom Authorizer connect sample from the `samples` folder using Websockets, use the following command:
 
 ``` sh
-# For Windows: replace 'python3' with 'python' and '/' with '\'
+# For Windows: replace 'python3' with 'python'
 python3 mqtt5_custom_authorizer_connect.py --endpoint <endpoint> --use_websockets "true" --custom_auth_authorizer_name <authorizer name>
 ```
-
-**Note** The sample also allows passing additional arguments (`--custom_auth_username`, `--custom_auth_password`, and `custom_auth_authorizer_signature`) to fullfil the additional data your custom authorizer may need. The examples above assume that the custom authorizer does not need these additional parameters.

samples/mqtt5_custom_authorizer_connect.py

@@ -37,8 +37,6 @@ def on_lifecycle_connection_success(lifecycle_connect_success_data: mqtt5.Lifecy
         client = mqtt5_client_builder.direct_with_custom_authorizer(
             endpoint=cmdData.input_endpoint,
             ca_filepath=cmdData.input_ca,
-            cert_filepath=cmdData.input_cert,
-            pri_key_filepath=cmdData.input_key,
             auth_username=cmdData.input_custom_auth_username,
             auth_authorizer_name=cmdData.input_custom_authorizer_name,
             auth_authorizer_signature=cmdData.input_custom_authorizer_signature,
@@ -51,7 +49,6 @@ def on_lifecycle_connection_success(lifecycle_connect_success_data: mqtt5.Lifecy
     else:
         client = mqtt5_client_builder.websockets_with_custom_authorizer(
             endpoint=cmdData.input_endpoint,
-            region=cmdData.input_signing_region,
             auth_username=cmdData.input_custom_auth_username,
             auth_authorizer_name=cmdData.input_custom_authorizer_name,
             auth_authorizer_signature=cmdData.input_custom_authorizer_signature,

samples/utils/command_line_utils.py

@@ -405,20 +405,13 @@ def parse_sample_input_custom_authorizer_connect():
         cmdUtils.add_common_mqtt_commands()
         cmdUtils.add_common_logging_commands()
         cmdUtils.add_common_custom_authorizer_commands()
-        cmdUtils.register_command(CommandLineUtils.m_cmd_signing_region, "<str>",
-                                "The signing region used for the websocket signer",
-                                False, str)
-        cmdUtils.register_command(CommandLineUtils.m_cmd_region, "<str>",
-                                "The signing region used for the websocket signer",
-                                False, str)
         cmdUtils.register_command(CommandLineUtils.m_cmd_client_id, "<str>",
                                 "Client ID to use for MQTT connection (optional, default='test-*').",
                                 default="test-" + str(uuid4()))
         cmdUtils.get_args()
 
         cmdData = CommandLineUtils.CmdData()
         cmdData.input_endpoint = cmdUtils.get_command_required(CommandLineUtils.m_cmd_endpoint)
-        cmdData.input_signing_region = cmdUtils.get_command_required(CommandLineUtils.m_cmd_signing_region, CommandLineUtils.m_cmd_region)
         cmdData.input_custom_authorizer_name = cmdUtils.get_command(CommandLineUtils.m_cmd_custom_auth_authorizer_name)
         cmdData.input_custom_authorizer_signature = cmdUtils.get_command(CommandLineUtils.m_cmd_custom_auth_authorizer_signature)
         cmdData.input_custom_auth_password = cmdUtils.get_command(CommandLineUtils.m_cmd_custom_auth_password)
@@ -488,13 +481,6 @@ def parse_sample_input_mqtt5_custom_authorizer_connect():
         cmdUtils = CommandLineUtils(
             "Custom Authorizer Connect - Make a MQTT5 Client connection using a custom authorizer.")
         cmdUtils.add_common_mqtt_commands()
-        cmdUtils.register_command(CommandLineUtils.m_cmd_key_file, "<path>",
-                                "Path to your key in PEM format.", False, str)
-        cmdUtils.register_command(CommandLineUtils.m_cmd_cert_file, "<path>",
-                                "Path to your client certificate in PEM format.", False, str)
-        cmdUtils.register_command(CommandLineUtils.m_cmd_signing_region, "<str>",
-                                "The signing region used for the websocket signer",
-                                False, str)
         cmdUtils.add_common_logging_commands()
         cmdUtils.add_common_custom_authorizer_commands()
         cmdUtils.register_command(CommandLineUtils.m_cmd_client_id, "<str>",
@@ -505,9 +491,6 @@ def parse_sample_input_mqtt5_custom_authorizer_connect():
 
         cmdData = CommandLineUtils.CmdData()
         cmdData.input_endpoint = cmdUtils.get_command_required(CommandLineUtils.m_cmd_endpoint)
-        cmdData.input_signing_region = cmdUtils.get_command(CommandLineUtils.m_cmd_signing_region, None)
-        cmdData.input_cert = cmdUtils.get_command(CommandLineUtils.m_cmd_cert_file, None)
-        cmdData.input_key = cmdUtils.get_command(CommandLineUtils.m_cmd_key_file, None)
         cmdData.input_ca = cmdUtils.get_command(CommandLineUtils.m_cmd_ca_file, None)
         cmdData.input_custom_authorizer_name = cmdUtils.get_command(CommandLineUtils.m_cmd_custom_auth_authorizer_name)
         cmdData.input_custom_authorizer_signature = cmdUtils.get_command(CommandLineUtils.m_cmd_custom_auth_authorizer_signature)