Authorizing direct calls to Amazon services using Amazon IoT Core credential provider

Configure the IAM role that the credentials provider assumes on behalf of your device. Attach the following trust policy to the role.

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Principal": {"Service": "credentials.iot.amazonaws.com"},
        "Action": "sts:AssumeRole"
    }
} 

For each Amazon service that you want to call, attach an access policy to the role. The credentials provider supports the following policy variables:

When the device provides the thing name in its request to an Amazon service, the credentials provider adds credentials-iot:ThingName and credentials-iot:ThingTypeName as context variables to the security token. The credentials provider provides credentials-iot:AwsCertificateId as a context variable even if the device doesn't provide the thing name in the request. You pass the thing name as the value of the x-amzn-iot-thingname HTTP request header.

These three variables work for IAM policies only, not Amazon IoT Core policies.

Make sure that the user who performs the next step (creating a role alias) has permission to pass the newly created role to Amazon IoT Core. The following policy gives both iam:GetRole and iam:PassRole permissions to an Amazon user. The iam:GetRole permission allows the user to get information about the role that you've just created. The iam:PassRole permission allows the user to pass the role to another Amazon service.

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Action": [
            "iam:GetRole",
            "iam:PassRole"
        ],
        "Resource": "arn:aws:iam::your Amazon Web Services account id:role/your role name"
    }
} 

Create an Amazon IoT Core role alias. The device that is going to make direct calls to Amazon services must know which role ARN to use when connecting to Amazon IoT Core. Hard-coding the role ARN is not a good solution because it requires you to update the device whenever the role ARN changes. A better solution is to use the CreateRoleAlias API to create a role alias that points to the role ARN. If the role ARN changes, you simply update the role alias. No change is required on the device. This API takes the following parameters:

For more information about this API, see CreateRoleAlias.

Attach a policy to the device certificate. The policy attached to the device certificate must grant the device permission to assume the role. You do this by granting permission for the iot:AssumeRoleWithCertificate action to the role alias, as in the following example.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":"iot:AssumeRoleWithCertificate",
         "Resource":"arn:aws:iot:your region:your_aws_account_id:rolealias/your role alias"
      }
   ]
}

Make an HTTPS request to the credentials provider to get a security token. Supply the following information:

Run the following command in the Amazon CLI to obtain the credentials provider endpoint for your Amazon Web Services account. For more information about this API, see DescribeEndpoint. For FIPS-enabled endpoints, see Amazon IoT Core - credential provider endpoints.

aws iot describe-endpoint --endpoint-type iot:CredentialProvider

The following JSON object is sample output of the describe-endpoint command. It contains the endpointAddress that you use to request a security token.

{
    "endpointAddress": "your_aws_account_specific_prefix.credentials.iot.your region.amazonaws.com"
} 

Use the endpoint to make an HTTPS request to the credentials provider to return a security token. The following example command uses curl, but you can use any HTTP client.

curl --cert your certificate --key your device certificate key pair -H "x-amzn-iot-thingname: your thing name" --cacert AmazonRootCA1.pem https://your endpoint /role-aliases/your role alias/credentials

This command returns a security token object that contains an accessKeyId, a secretAccessKey, a sessionToken, and an expiration. The following JSON object is sample output of the curl command.

    {"credentials":{"accessKeyId":"access key","secretAccessKey":"secret access key","sessionToken":"session token","expiration":"2018-01-18T09:18:06Z"}}
                    

You can then use the accessKeyId, secretAccessKey, and sessionToken values to sign requests to Amazon services. For an end-to-end demonstration, see How to Eliminate the Need for Hard-Coded Amazon Credentials in Devices by Using the Amazon IoT Credential Provider blog post on the Amazon Security Blog.