Difficulties understanding custom authorizer example

[abarke]

Hi everyone,

We are implementing a custom authorizer and would like to better understand the parameters needed for token validation as the documentation is not very clear.

I read the tutorial here and I'm on Step 4: Test the authorizer by calling test-invoke-authorizer

It's a shame that in this example the AWS CLI is used as this does not align with e.g. aws-iot-device-sdk-js-v2 documentation. When I look at the example in this repo it mentions "If your custom authorizer uses signing, you must specify the three signed token properties as well."

I'm stuck on the tokenValue property. What is the difference between the tokenValue and the tokenSignature? It would be great to extend this example with a clear example of what is expected here.

authorizerName: "<Name of your custom authorizer>",
username: "<Value of the username field that should be passed to the authorizer's lambda>",
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: "<base64-encoded digital signature of tokenValue>"

In the following example from the tutorial, I assume the tokenValue is the tokenKeyValue but where is the tokenKeyName?

aws iot test-invoke-authorizer \
--authorizer-name my-new-authorizer \
--token tokenKeyValue \
--token-signature dBwykzlb+fo+JmSGdwo

The code gives a bit more detail, but some developers may not find this immediately.

/**
 * Configuration options specific to
 * [AWS IoT Core custom authentication](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)
 * features.  For clients constructed by an {@link AwsIotMqtt5ClientConfigBuilder}, all parameters associated
 * with AWS IoT custom authentication are passed via the username and password properties in the CONNECT packet.
 */
export interface MqttConnectCustomAuthConfig {
    /**
     * Name of the custom authorizer to use.
     *
     * Required if the endpoint does not have a default custom authorizer associated with it.  It is strongly suggested
     * to URL-encode this value; the SDK will not do so for you.
     */
    authorizerName?: string;
    /**
     * The username to use with the custom authorizer.  Query-string elements of this property value will be unioned
     * with the query-string elements implied by other properties in this object.
     *
     * For example, if you set this to:
     *
     * 'MyUsername?someKey=someValue'
     *
     * and use {@link authorizerName} to specify the authorizer, the final username would look like:
     *
     * `MyUsername?someKey=someValue&x-amz-customauthorizer-name=<your authorizer's name>&...`
     */
    username?: string;
    /**
     * The password to use with the custom authorizer.  Becomes the MQTT5 CONNECT packet's password property.
     * AWS IoT Core will base64 encode this binary data before passing it to the authorizer's lambda function.
     */
    password?: mqtt5_packet.BinaryData;
    /**
     * Key used to extract the custom authorizer token from MQTT username query-string properties.
     *
     * 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.
     */
    tokenKeyName?: string;
    /**
     * An opaque token value. This value must be signed by the private key associated with the custom authorizer and
     * the result placed in the {@link tokenSignature} property.
     *
     * Required if the custom authorizer has signing enabled.
     */
    tokenValue?: string;
    /**
     * 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.
     */
    tokenSignature?: string;
}

What we are trying to achieve is leveraging the already existing accessToken provided by AWS Cognito. The idea is to use the public certificates provided by Cognito Identity Pool to verify the incoming accessToken signed by Cognito. Then we will do some database lookups based on the userId/JWT sub in order to apply the correct dynamic policies.

[abarke]

If I use the existing JWT accessToken from Cognito, should I simply split up the JWT like this?

const jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.NFvYpuwbF6YWbPyaNAGEPw9wbhiQSovvSrD89B8K7Ng";

const jwtParts = jwt.split(".");
const jwtHeader = jwtParts[0];
const jwtPayload = jwtParts[1];
const jwtSignature = jwtParts[2];

const mqttConnectCustomAuthConfig = {
  tokenKeyName: "t",
  tokenValue: `${jwtHeader}.${jwtPayload}`,
  tokenSignature: jwtSignature,
};

console.log(mqttConnectCustomAuthConfig);
// {
//   tokenKeyName: 't',
//   tokenValue: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ',
//   tokenSignature: 'NFvYpuwbF6YWbPyaNAGEPw9wbhiQSovvSrD89B8K7Ng'
// }

[abarke]

would be nice if the example would be updated using a JWT. or simply give an example of using a Cognito JWT as a form of Authentication with Token Validation enabled.

[bretambrose]

I'll try to walk through a basic example and hopefully that will make things clearer (square brackets denotes substitution).

You want to make a signed custom authorizer.

Start with a key pair: (PubKey, PrivKey)

Create a signing custom authorizer. Ignoring Lambda configuration, a signed custom authorizer is configured with the public key and the token-key-name value. token-key-name is the name of the query parameter that you (well, the SDK) will stick the unsigned token value in . In other words, the custom authorizer service expects the query param pair [token-key-name]=[unsigned-token-value] to appear in the username field of the CONNECT packet whenever you try to connect

[My-Authorizer-Name] = CreateSigningAuthorizer(..., PubKey, [token-key-name])

Choose a value for unsigned-token-value (any valid utf-8 string will do). You can vary it dynamically, but it doesn't need to. If you want to make it an encoding of a JWT, you're welcome to. If the unsigned-token-value contains characters that would be URI-encoded over http, you must URI encode the value when initializing the custom auth parameters.

With that, configure the SDK custom auth parameters as follows:

let config : MqttConnectCustomAuthConfig = {
  authorizerName: [My-Authorizer-Name],
  username: [Whatever username you want to pass to your lambda],
  password: [Whatever password you want to pass to your lambda],
  tokenKeyName: [token-key-name],  // MUST match what the authorizer was created with
  tokenValue: UriEncode([unsigned-token-value]),
  tokenSignature: UriEncode(Base64(DigitalSignature([unsigned-token-value], PrivKey)))
};

This leads to the SDK building a final username field for the CONNECT packet that looks like this:

[Whatever username you want to pass to your lambda]?[token-key-name]=[unsigned-token-value]:x-amz-customauthorizer-name=[My-Authorizer-Name]:x-amz-customauthorizer-signature=UriEncode(Base64(DigitalSignature([unsigned-token-value], PrivKey)))

After this, you may find yourself asking "Why does [token-key-name] need to be a (confusing) parameter when you're already using reserved names like x-amz-custom-authorizer in the query param encoding? Why couldn't the service just also use x-amz-unsigned-token-value ? I don't have a good answer for this; it feels unnecessarily complicated.

One other thing. I'm not certain, but it does seem like you might be conflating two completely unrelated notions of token (unsigned-token-value). In custom auth, token is just some arbitrary value you pick. It has nothing to do with Cognito or JWT.

[abarke]

Many thanks. I think that's clearer now. Some last questions:

1. Does there need to be a username? Could it be an empty string? I suppose this could be the same as the clientId?
2. Does there need to be a password?
3. In the case of using an existing JWT from Cognito, does tokenValue need to be ${jwtHeader}.${jwtPayload} or is it just the entire JWT?
4. Is using a JWT from Cognito a secure way to authenticate?
5. Im using the public certificates for the identity pool we are using. How often are these public certificates changing? As you cannot edit the public keys once an authorizer is created, it would be awesome to be able to provide a URL in the custom authorizer to the jwks.json that caches the certificates automatically
   https://cognito-idp.eu-central-1.amazonaws.com/${identityPoolId}/.well-known/jwks.json
6. If I add a Custom Authorizer, does this effect devices that are authenticating with mTLS? How would I go about that?

[bretambrose]

1. No. Yes. Sure.
2. No.
3. The SDK/Custom-authorizers impose no structure or constraints on the token value beyond what is required by the MQTT protocol relative to the username property on the connect packet (the final value must be a utf-8 string)
4. No one on our team has either the expertise or legal permission to provide any guidance there. If you're working with an AWS solutions architect, they would be your best point of contact.
5. No idea. That would be a question for the Cognito service.
6. It has no effect on devices using mTLS. There is no way to have one affect the other. Assuming port 443, custom auth vs mtls is determined at TLS handshake time via ALPN.

[abarke]

Many thanks