Developer Guide

Custom Authorizer Workflow

For a device to authenticate with the AWS IoT device gateway using a custom authorizer, it needs both a token and a signature used by AWS to validate the tokens before invoking the authorizer.

When a device attempts to connect to AWS IoT, it sends the following information in HTTP headers:

  • A token generated by your authentication service.

  • The signature generated by your authentication service.

  • The authorizer used to authenticate the token. If omitted, the default authorizer is used.

The following is an example HTTP request to connect to AWS IoT over the WebSocket protocol.

GET /mqtt HTTP/1.1 Host: <your-iot-endpoint> Upgrade: WebSocket Connection: Upgrade x-amz-customauthorizer-name: <authorizer-name> x-amz-customauthorizer-signature: <token-signature> <token-key-name>: <some-token> sec-WebSocket-Key: <any random base64 value> sec-websocket-protocol: mqtt sec-WebSocket-Version: <websocket version>

In this example, the x-amz-customauthorizer-name header specifies the custom authorizer to use, the x-amz-customauthorizer-signature header contains the digital signature used to verify the token, and the token-key-name is the token key name specified by the --token-key-name passed to the create-authorizer API.

The AWS IoT device gateway validates the digital signature and if valid, calls the specified authorizer. The following is an example payload AWS IoT sends to the custom authenticator's Lambda function.

{ "type":"TOKEN", "authorizationToken":"<caller-supplied-token>", "authorizerId":<authorizer-id>, "endpoint":"<your-iot-endpoint>" }

The authorizer validates the token and returns a principal ID, its associated AWS IoT/IAM policy, time-to-live (TTL) information for the connection, and any additional context generated by the authorizer.

The following is an example of the response from a custom authorizer.

{ "isAuthenticated":true, "principalId": "xxxxxxxx", "disconnectAfterInSeconds": 86400, "refreshAfterInSeconds", 300, "policyDocuments": [ "{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Action\": \"...\", \"Effect\": \"Allow|Deny\", \"Resource\": \"...\" } ] }" ], "context": { "username" : "foo", "city" : "Seattle", "country" : "USA" } }

(Your Lambda function should return the above response as is (non-serialized). The Lambda function will serialize it for you.)

The AWS IoT device gateway then establishes the WebSocket connection. AWS IoT caches the policies associated with the principal so subsequent calls can be authorized without having to reauthenticate the device. Any failure that occurs during custom authentication results in authentication failure and connection termination.