Update custom auth sample with signing params and better explanations (…

…#440)

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

samples/node/custom_authorizer_connect/README.md

@@ -37,11 +37,17 @@ 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 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) The 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 Custom Authorizer connect sample, go to the `node/custom_authorizer_connect` folder and run the following commands:
 
 ``` sh
 npm install
 node dist/index.js --endpoint <endpoint> --custom_auth_authorizer_name <custom 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/node/custom_authorizer_connect/index.ts

@@ -31,7 +31,9 @@ function build_connection(argv: Args): mqtt.MqttClientConnection {
         argv.custom_auth_username,
         argv.custom_auth_authorizer_name,
         argv.custom_auth_authorizer_signature,
-        argv.custom_auth_password);
+        argv.custom_auth_password,
+        argv.custom_auth_token_key_name,
+        argv.custom_auth_token_value);
     const config = config_builder.build();
 
     const client = new mqtt.MqttClient();

samples/util/cli_args.js

@@ -214,7 +214,7 @@ function add_custom_authorizer_arguments(yargs) {
             default: ''
         })
         .option('custom_auth_authorizer_signature', {
-            description: 'The signature to send when connecting through a custom authorizer (optional)',
+            description: 'The 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. (optional)',
             type: 'string',
             default: ''
         })
@@ -223,6 +223,16 @@ function add_custom_authorizer_arguments(yargs) {
             type: 'string',
             default: ''
         })
+        .option('custom_auth_token_key_name', {
+            description: 'The query string parameter name that the token value should be bound to in the MQTT Connect packet. (optional)',
+            type: 'string',
+            default: undefined
+        })
+        .option('custom_auth_token_value', {
+            description: 'An arbitrary value chosen by the user.  You must also submit a digital signature of this value using the private key associated with the authorizer. (optional)',
+            type: 'string',
+            default: undefined
+        })
 }
 
 /*