Documentation updates for custom auth connections (#516)

Co-authored-by: Bret Ambrose <bambrose@amazon.com>

MQTT5-UserGuide.md

@@ -360,9 +360,9 @@ If your custom authenticator does not use signing, you don't specify anything re
     let client : Mqtt5Client = new mqtt5.Mqtt5Client(builder.build());
 ```
 
-If your custom authorizer uses signing, you must specify the three signed token properties as well.  The token signature must be
-the URI-encoding of the base64 encoding of the digital signature of the token value via the private key associated with the public key
-that was registered with the custom authorizer.  It is your responsibility to URI-encode the token signature:
+If your custom authorizer uses signing, you must specify the three signed token properties as well.  The token signature should be
+the base64 encoding of the digital signature of the token value via the private key associated with the public key
+that was registered with the custom authorizer:
 
 ```typescript
     let customAuthConfig : MqttConnectCustomAuthConfig = {
@@ -371,7 +371,7 @@ that was registered with the custom authorizer.  It is your responsibility to UR
         password: <Binary data value of the password field to be passed to the authorizer lambda>,
         tokenKeyName: "<Name of the username query param that will contain the token value>",
         tokenValue: "<Value of the username query param that holds the token value that has been signed>",
-        tokenSignature: "<URI-encoded base64-encoded digital signature of tokenValue>"
+        tokenSignature: "<base64-encoded digital signature of tokenValue>"
     };
     let builder = AwsIotMqtt5ClientConfigBuilder.newDirectMqttBuilderWithCustomAuth(
         "<account-specific endpoint>",

lib/browser/aws_iot.ts

@@ -248,13 +248,13 @@ export class AwsIotMqttConnectionConfigBuilder {
      *                 check to see if a username has already been set (via WithUsername function). If no
      *                 username is set then no username will be passed with the MQTT connection.
      * @param authorizer_name The name of the custom authorizer. If an empty string is passed, then
-     *                       'x-amz-customauthorizer-name' will not be added with the MQTT connection.
+     *                       'x-amz-customauthorizer-name' will not be added with the MQTT connection.  It is strongly
+     *                       recommended to URL-encode this value; the SDK will not do so for you.
      * @param authorizer_signature The signature of the custom authorizer. If an empty string is passed, then
      *                            'x-amz-customauthorizer-signature' will not be added with the MQTT connection.
      *                            The signature must be based on the private key associated with the custom authorizer.
      *                            The signature must be base64 encoded.
-     *                            Required if the custom authorizer has signing enabled.  It is strongly suggested to URL-encode
-     *                            this value; the SDK will not do so for you.
+     *                            Required if the custom authorizer has signing enabled.
      * @param password The password to use with the custom authorizer. If null is passed, then no password will
      *                 be set.
      * @param token_key_name Key used to extract the custom authorizer token from MQTT username query-string properties.

lib/common/aws_iot_shared.ts

@@ -81,20 +81,19 @@ export function populate_username_string_with_custom_authorizer(
     if (is_string_and_not_empty(input_authorizer) && input_authorizer) {
         username_string = add_to_username_parameter(username_string, input_authorizer, "x-amz-customauthorizer-name=");
     }
+
+    if (is_string_and_not_empty(input_signature) || is_string_and_not_empty(input_token_value) || is_string_and_not_empty(input_token_key_name)) {
+        if (!input_token_value || !input_token_key_name || !input_signature) {
+            throw new Error("Signing-based custom authentication requires all token-related properties to be set");
+        }
+    }
+
     if (is_string_and_not_empty(input_signature) && input_signature) {
         username_string = add_to_username_parameter(username_string, input_signature, "x-amz-customauthorizer-signature=");
-        if ((is_string_and_not_empty(input_token_key_name) && input_token_key_name) || (is_string_and_not_empty(input_token_value) && input_token_value))
-        {
-            console.log("Warning: Signed custom authorizers with signature will not work without a token key name and " +
-                        "token value. Your connection may be rejected/stalled on the IoT Core side due to this. Please " +
-                        "set the token key name and token value to connect to a signed custom authorizer.");
-        }
     }
 
-    if (is_string_and_not_empty(input_signature) || is_string_and_not_empty(input_token_value) || is_string_and_not_empty(input_token_key_name)) {
-        if (!input_token_value || !input_token_key_name) {
-            throw new Error("Token-based custom authentication requires all token-related properties to be set");
-        }
+    if (is_string_and_not_empty(input_token_value) && is_string_and_not_empty(input_token_key_name)) {
+        // @ts-ignore
         username_string = add_to_username_parameter(username_string, input_token_value, input_token_key_name + "=");
     }
 
@@ -157,8 +156,7 @@ export interface MqttConnectCustomAuthConfig {
      * The digital signature of the token value in the {@link tokenValue} property.  The signature must be based on
      * the private key associated with the custom authorizer.  The signature must be base64 encoded.
      *
-     * Required if the custom authorizer has signing enabled.  It is strongly suggested to URL-encode this value; the
-     * SDK will not do so for you.
+     * Required if the custom authorizer has signing enabled.
      */
     tokenSignature?: string;
 };

lib/native/aws_iot.ts

@@ -388,13 +388,13 @@ export class AwsIotMqttConnectionConfigBuilder {
      *                 check to see if a username has already been set (via WithUsername function). If no
      *                 username is set then no username will be passed with the MQTT connection.
      * @param authorizer_name The name of the custom authorizer. If an empty string is passed, then
-     *                       'x-amz-customauthorizer-name' will not be added with the MQTT connection.
+     *                       'x-amz-customauthorizer-name' will not be added with the MQTT connection.  It is strongly
+     *                       recommended to URL-encode this value; the SDK will not do so for you.
      * @param authorizer_signature The signature of the custom authorizer. If an empty string is passed, then
      *                            'x-amz-customauthorizer-signature' will not be added with the MQTT connection.
      *                            The signature must be based on the private key associated with the custom authorizer.
      *                            The signature must be base64 encoded.
-     *                            Required if the custom authorizer has signing enabled.  It is strongly suggested to URL-encode
-     *                            this value; the SDK will not do so for you.
+     *                            Required if the custom authorizer has signing enabled.
      * @param password The password to use with the custom authorizer. If null is passed, then no password will
      *                 be set.
      * @param token_key_name Key used to extract the custom authorizer token from MQTT username query-string properties.