Sign In to the Console
AWS IoT
Developer Guide

AWS Documentation » AWS IoT » Developer Guide » Security and Identity for AWS IoT » Custom Authentication » Custom Authorizer Workflow

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.

Note

Some web browsers may not support custom HTTP headers.

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. 


{
"token": "some-token"
}

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

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\": \"...\" } ] }"
 ]
}

The return value of the Lambda function should be similar to the above and can be either a JSON serialized or non-serialized object.

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.

For an end-to-end example of this workflow, see How to Use Your Own Identity and Access Management Systems to Control Access to AWS IoT Resources.