# AWS IoT Core policy variables
AWS IoT Core defines policy variables that can be used in AWS IoT Core policies in the `Resource` or `Condition` block. When a policy is evaluated, the policy variables are replaced by actual values. For example, if a device is connected to the AWS IoT Core message broker with a client ID of 100-234-3456, the `iot:ClientId` policy variable is replaced in the policy document by 100-234-3456.
AWS IoT Core policies can use wildcard characters and follow a similar convention to IAM policies. Inserting an `*` (asterik) in the string can be treated as a wildcard, matching any characters. For example, you can use `*` to describe multiple MQTT topic names in the `Resource` attribute of a policy. The characters `+` and `#` are treated as literal strings in a policy. For an example policy that shows how to use wildcards, see [Using wildcard characters in MQTT and AWS IoT Core policies](pub-sub-policy.md#pub-sub-policy-cert).
You can also use predefined policy variables with fixed values to represent characters that otherwise have special meaning. These special characters include `$(*)`, `$(?)`, and `$($)`. For more information about policy variables and the special characters, see [IAM Policy elements: Variables and tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html) and [Creating a condition with multiple keys or values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html).
**Topics**
+ [
# Basic AWS IoT Core policy variables
](basic-policy-variables.md)
+ [
# Thing policy variables
](thing-policy-variables.md)
+ [
# X.509 Certificate AWS IoT Core policy variables
](cert-policy-variables.md)
# Basic AWS IoT Core policy variables
AWS IoT Core defines the following basic policy variables:
+ `aws:SourceIp`: The IP address of the client connected to the AWS IoT Core message broker.
+ `iot:ClientId`: The client ID used to connect to the AWS IoT Core message broker.
+ `iot:DomainName`: The domain name of the client connected to AWS IoT Core.
**Topics**
+ [
## Examples of `ClientId` and `SourceIp` policy variables
](#basic-policy-variables-example)
+ [
## Examples of `iot:DomainName` policy variable
](#basic-policy-variables-example-domain)
## Examples of `ClientId` and `SourceIp` policy variables
The following AWS IoT Core policy shows a policy that uses policy variables. `aws:SourceIp` can be used in the Condition element of your policy to allow principals to make API requests only within a specific address range. For examples, see [Authorizing users and cloud services to use AWS IoT Jobs](iam-policy-users-jobs.md).
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/clientid1"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/my/topic/${iot:ClientId}"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "123.45.167.89"
}
}
}
]
}
```
In these examples, `${iot:ClientId}` is replaced by the ID of the client connected to the AWS IoT Core message broker when the policy is evaluated. When you use policy variables like `${iot:ClientId}`, you can inadvertently open access to unintended topics. For example, if you use a policy that uses `${iot:ClientId}` to specify a topic filter:
```
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/my/${iot:ClientId}/topic"
]
}
```
A client can connect using `+` as the client ID. This would allow the user to subscribe to any topic that matches the topic filter `my/+/topic`. To protect against such security gaps, use the `iot:Connect` policy action to control which client IDs can connect. For example, this policy allows only those clients whose client ID is `clientid1` to connect:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/clientid"
]
}
]
}
```
**Note**
Using the policy variable `${iot:ClientId}` with `Connect` is not recommended. There is no check on the value of `ClientId`, so an attacher with a different client's ID can pass the validation but cause disconnection. Because any `ClientId` is allowed, setting a random client ID can bypass thing group policies.
## Examples of `iot:DomainName` policy variable
You can add the `iot:DomainName` policy variable to restrict which domains are allowed to use. Adding the `iot:DomainName` policy variable allows devices to connect to only specific configured endpoints.
The following policy allows devices to connect to the specified domain.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "AllowConnectionsToSpecifiedDomain",
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": "arn:aws:iot:us-east-1:123456789012:client/clientid",
"Condition": {
"StringEquals": {
"iot:DomainName": "d1234567890abcdefghij-ats.iot.us-east-1.amazonaws.com"
}
}
}
}
```
The following policy denies devices to connect to the specified domain.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "DenyConnectionsToSpecifiedDomain",
"Effect": "Deny",
"Action": [
"iot:Connect"
],
"Resource": "arn:aws:iot:us-east-1:123456789012:client/clientid",
"Condition": {
"StringEquals": {
"iot:DomainName": "d1234567890abcdefghij-ats.iot.us-east-1.amazonaws.com"
}
}
}
}
```
For more information about policy conditional operator, see [IAM JSON policy elements: Condition operators](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_elements_condition_operators.html). For more information about domain configurations, see [What is a domain configuration?](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable.html).
# Thing policy variables
Thing policy variables allow you to write AWS IoT Core policies that grant or deny permissions based on thing properties like thing names, thing types, and thing attribute values. You can use thing policy variables to apply the same policy to control many AWS IoT Core devices. For more information about device provisioning, see [Device Provisioning](iot-provision.html).
If you use non-exclusive thing association, the same certificate can be attached to multiple things. To maintain a clear association and to avoid potential conflicts, you must match your client ID with the thing name. In this case, you obtain the thing name from the client ID in the MQTT `Connect` message sent when a thing connects to AWS IoT Core.
Keep the following in mind when using thing policy variables in AWS IoT Core policies.
+ Use the [AttachThingPrincipal](https://docs.aws.amazon.com/iot/latest/apireference/API_AttachThingPrincipal.html) API to attach certificates or principals (authenticated Amazon Cognito identities) to a thing.
+ If non-exclusive thing association is in place, when you're replacing thing names with thing policy variables, the value of `clientId` in the MQTT connect message or the TLS connection must exactly match the thing name.
The following thing policy variables are available:
+ `iot:Connection.Thing.ThingName`
This resolves to the name of the thing in the AWS IoT Core registry for which the policy is being evaluated. AWS IoT Core uses the certificate the device presents when it authenticates to determine which thing to use to verify the connection. This policy variable is only available when a device connects over MQTT or MQTT over the WebSocket protocol.
+ `iot:Connection.Thing.ThingTypeName`
This resolves to the thing type associated with the thing for which the policy is being evaluated. The client ID of the MQTT/WebSocket connection must be the same as the thing name. This policy variable is available only when connecting over MQTT or MQTT over the WebSocket protocol.
+ `iot:Connection.Thing.Attributes[attributeName]`
This resolves to the value of the specified attribute associated with the thing for which the policy is being evaluated. A thing can have up to 50 attributes. Each attribute is available as a policy variable: `iot:Connection.Thing.Attributes[attributeName]` where *attributeName* is the name of the attribute. The client ID of the MQTT/WebSocket connection must be the same as the thing name. This policy variable is only available when connecting over MQTT or MQTT over the WebSocket protocol.
+ `iot:Connection.Thing.IsAttached`
`iot:Connection.Thing.IsAttached: ["true"]` enforces that only the devices that are both registered in AWS IoT and attached to principal can access the permissions inside the policy. You can use this variable to prevent a device from connecting to AWS IoT Core if it presents a certificate that is not attached to an IoT thing in the AWS IoT Core registry.This variable has values `true` or `false` indicating that the connecting thing is attached to the certificate or Amazon Cognito identity in the registry using [AttachThingPrincipal](https://docs.aws.amazon.com/iot/latest/apireference/API_AttachThingPrincipal.html) API. Thing name is taken as client Id.
If your client ID matches your thing name, or if you attach your certificate to a thing exclusively, using policy variables in the policy definition can simplify policy management. Instead of creating individual policies for each IoT thing, you can define a single policy using the thing policy variables. This policy can be applied to all devices dynamically. The following is an example policy to show how it works. For more information, see [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md).
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Condition": {
"StringLike": {
"iot:ClientId": "*${iot:Connection.Thing.Attributes[envType]}"
}
},
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/*"
}
]
}
```
This policy example allows things to connect to AWS IoT Core if their client ID ends with the value of their `envType` attribute. Only things with a matching client ID pattern will be allowed to connect.
# X.509 Certificate AWS IoT Core policy variables
X.509 certificate policy variables assist with writing AWS IoT Core policies. These policies grant permissions based on X.509 certificate attributes. The following sections describe how to use these certificate policy variables.
**Important**
If your X.509 certificate doesn't include a particular certificate attribute but the corresponding certificate policy variable is used in your policy document, the policy evaluation might lead to unexpected behavior.
## CertificateId
In the [RegisterCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_RegisterCertificate.html) API, the `certificateId` appears in the response body. To get information about your certificate, use the `certificateId` in [DescribeCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeCertificate.html).
## Issuer attributes
The following AWS IoT Core policy variables support the allowing or denying of permissions, based on certificate attributes set by the certificate issuer.
+ `iot:Certificate.Issuer.DistinguishedNameQualifier`
+ `iot:Certificate.Issuer.Country`
+ `iot:Certificate.Issuer.Organization`
+ `iot:Certificate.Issuer.OrganizationalUnit`
+ `iot:Certificate.Issuer.State`
+ `iot:Certificate.Issuer.CommonName`
+ `iot:Certificate.Issuer.SerialNumber`
+ `iot:Certificate.Issuer.Title`
+ `iot:Certificate.Issuer.Surname`
+ `iot:Certificate.Issuer.GivenName`
+ `iot:Certificate.Issuer.Initials`
+ `iot:Certificate.Issuer.Pseudonym`
+ `iot:Certificate.Issuer.GenerationQualifier`
## Subject attributes
The following AWS IoT Core policy variables support the granting or denying of permissions, based on certificate subject attributes set by the certificate issuer.
+ `iot:Certificate.Subject.DistinguishedNameQualifier`
+ `iot:Certificate.Subject.Country`
+ `iot:Certificate.Subject.Organization`
+ `iot:Certificate.Subject.OrganizationalUnit`
+ `iot:Certificate.Subject.State`
+ `iot:Certificate.Subject.CommonName`
+ `iot:Certificate.Subject.SerialNumber`
+ `iot:Certificate.Subject.Title`
+ `iot:Certificate.Subject.Surname`
+ `iot:Certificate.Subject.GivenName`
+ `iot:Certificate.Subject.Initials`
+ `iot:Certificate.Subject.Pseudonym`
+ `iot:Certificate.Subject.GenerationQualifier`
X.509 certificates provide these attributes with the option to contain one or more values. By default, the policy variables for each multi-value attribute return the first value. For example, the `Certificate.Subject.Country` attribute might contain a list of country names, but when evaluated in a policy, `iot:Certificate.Subject.Country` is replaced by the first country name.
You can request a specific attribute value other than the first value by using a one-based index. For example, `iot:Certificate.Subject.Country.1` is replaced by the second country name in the `Certificate.Subject.Country` attribute. If you specify an index value that does not exist (for example, if you ask for a third value when there are only two values assigned to the attribute), no substitution is made and authorization fails. You can use the `.List` suffix on the policy variable name to specify all values of the attribute.
## Issuer alternate name attributes
The following AWS IoT Core policy variables support the granting or denying of permissions, based on issuer alternate name attributes set by the certificate issuer.
+ `iot:Certificate.Issuer.AlternativeName.RFC822Name`
+ `iot:Certificate.Issuer.AlternativeName.DNSName`
+ `iot:Certificate.Issuer.AlternativeName.DirectoryName`
+ `iot:Certificate.Issuer.AlternativeName.UniformResourceIdentifier`
+ `iot:Certificate.Issuer.AlternativeName.IPAddress`
## Subject alternate name attributes
The following AWS IoT Core policy variables support the granting or denying of permissions, based on subject alternate name attributes set by the certificate issuer.
+ `iot:Certificate.Subject.AlternativeName.RFC822Name`
+ `iot:Certificate.Subject.AlternativeName.DNSName`
+ `iot:Certificate.Subject.AlternativeName.DirectoryName`
+ `iot:Certificate.Subject.AlternativeName.UniformResourceIdentifier`
+ `iot:Certificate.Subject.AlternativeName.IPAddress`
## Other attributes
You can use `iot:Certificate.SerialNumber` to allow or deny access to AWS IoT Core resources, based on the serial number of a certificate. The `iot:Certificate.AvailableKeys` policy variable contains the name of all certificate policy variables that contain values.
# Using X.509 certificate policy variables
This topic provides details of how to use certificate policy variables. X.509 certificate policy variables are essential when you create AWS IoT Core policies that give permissions based on X.509 certificate attributes. If your X.509 certificate doesn't include a particular certificate attribute but the corresponding certificate policy variable is used in your policy document, the policy evaluation might lead to unexpected behavior. This is because the missing policy variable doesn't get evaluated in the policy statement.
**Topics**
+ [
## X.509 certificate example
](#certificate-example)
+ [
## Using certificate issuer attributes as certificate policy variables
](#issuer-attributes-policy)
+ [
## Using certificate subject attributes as certificate policy variables
](#subject-attributes-policy)
+ [
## Using certificate Issuer alternate name attributes as certificate policy variables
](#issuer-alternate-name-attributes-policy)
+ [
## Using certificate subject alternate name attributes as certificate policy variables
](#subject-alternate-name-attributes-policy)
+ [
## Using other certificate attribute as a certificate policy variable
](#other-attributes-policy)
+ [
## X.509 Certificate policy variable limitations
](#policy-limits)
+ [
## Example policies using certificate policy variables
](#example-attributes-policy)
## X.509 certificate example
A typical X.509 certificate might appear as follows. This example certificate includes certificate attributes. During the evaluation of AWS IoT Core policies, the following certificate attributes will be populated as certificate policy variables: `Serial Number`, `Issuer`, `Subject`, `X509v3 Issuer Alternative Name`, and `X509v3 Subject Alternative Name`.
```
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
92:12:85:cb:b7:a5:e0:86
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US, O=IoT Devices, OU=SmartHome, ST=WA, CN=IoT Devices Primary CA,
GN=Primary CA1/initials=XY/dnQualifier=Example corp,
SN=SmartHome/ title=CA1/pseudonym=Primary_CA/generationQualifier=2/serialNumber=987
Validity
Not Before: Mar 26 03:25:40 2024 GMT
Not After : Apr 28 03:25:40 2025 GMT
Subject: C=US, O=IoT Devices, OU=LightBulb, ST=NY, CN=LightBulb Device Cert,
GN=Bulb/initials=ZZ/dnQualifier=Bulb001,
SN=Multi Color/title=RGB/pseudonym=RGB Device/generationQualifier=4/serialNumber=123
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
<< REDACTED >>
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
X509v3 Key Usage:
Digital Signature, Non Repudiation, Key Encipherment
X509v3 Subject Alternative Name:
DNS:example.com, IP Address:1.2.3.4, URI:ResourceIdentifier001, email:device1@example.com, DirName:/C=US/O=IoT/OU=SmartHome/CN=LightBulbCert
X509v3 Issuer Alternative Name:
DNS:issuer.com, IP Address:5.6.7.8, URI:PrimarySignerCA, email:primary@issuer.com, DirName:/C=US/O=Issuer/OU=IoT Devices/CN=Primary Issuer CA
Signature Algorithm: sha256WithRSAEncryption
<< REDACTED >>
```
## Using certificate issuer attributes as certificate policy variables
The following table provides details of how certificate issuer attributes will be populated in an AWS IoT Core policy.
**Issuer attributes to be populated in a policy**
| Certificate issuer attributes | Certificate policy variables |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) |
## Using certificate subject attributes as certificate policy variables
The following table provides details of how certificate subject attributes will be populated in an AWS IoT Core policy.
**Subject attributes to be populated in a policy**
| Certificate subject attributes | Certificate policy variables |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) |
## Using certificate Issuer alternate name attributes as certificate policy variables
The following table provides details of how certificate issuer alternate name attributes will be populated in an AWS IoT Core policy.
**Issuer alternate name attributes to be populated in a policy**
| X509v3 Issuer Alternative Name | Attribute in a policy |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) |
## Using certificate subject alternate name attributes as certificate policy variables
The following table provides details of how certificate subject alternate name attributes will be populated in an AWS IoT Core policy.
**Subject alternate name attributes to be populated in a policy**
| X509v3 Subject Alternative Name | Attribute in a policy |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/use-policy-variables.html) |
## Using other certificate attribute as a certificate policy variable
The following table provides details of how other certificate attributes will be populated in an AWS IoT Core policy.
**Other attributes to be populated in a policy**
| Other certificate attribute | Certificate policy variable |
| --- | --- |
| `Serial Number: 92:12:85:cb:b7:a5:e0:86` | `iot:Certificate.SerialNumber = 10525622389124227206` |
## X.509 Certificate policy variable limitations
The following limitations apply to X.509 certificate policy variables:
Missing policy variables
If your X.509 certificate doesn't include a particular certificate attribute but the corresponding certificate policy variable is used in your policy document, the policy evaluation might lead to unexpected behavior. This is because the missing policy variable doesn't get evaluated in the policy statement.
Certificate SerialNumber format
AWS IoT Core treats the certificate serial number as the string representation of a decimal integer. For example, if a policy only allows connections with Client ID matching the certificate serial number, the client ID must be the serial number in decimal format.
Wildcards
If wildcard characters are present in certificate attributes, the policy variable is not replaced by the certificate attribute value. This will leave the `${policy-variable}` text in the policy document. This might cause authorization failure. The following wildcard characters can be used: `*`, `$`, `+`, `?`, and `#`.
Array fields
Certificate attributes that contain arrays are limited to five items. Additional items are ignored.
String length
All string values are limited to 1024 characters. If a certificate attribute contains a string longer than 1024 characters, the policy variable is not replaced by the certificate attribute value. This will leave the `${policy-variable}` in the policy document. This might cause authorization failure.
Special Characters
Any special character, such as `,`, `"`, `\`, `+`, `=`, `<`, `>` and `;` must be prefixed with a backslash (`\`) when used in a policy variable. For example, `Amazon Web Services O=Amazon.com Inc. L=Seattle ST=Washington C=US` becomes `Amazon Web Service O\=Amazon.com Inc. L\=Seattle ST\=Washington C\=US`.
## Example policies using certificate policy variables
The following policy document allows connections with client ID that matches the certificate serial number and publishing to the topic that matches the pattern: `${iot:Certificate.Subject.Organization}/device-stats/${iot:ClientId}/*`.
**Important**
If your X.509 certificate doesn't include a particular certificate attribute but the corresponding certificate policy variable is used in your policy document, the policy evaluation might lead to unexpected behavior. This is because the missing policy variable doesn't get evaluated in the policy statement. For example, if you attach the following policy document to a certificate that doesn't contain the `iot:Certificate.Subject.Organization` attribute, the `iot:Certificate.Subject.Organization` certificate policy variables won't be populated during the policy evaluation.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/${iot:Certificate.SerialNumber}"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/${iot:Certificate.Subject.Organization}/device-stats/${iot:ClientId}/*"
]
}
]
}
```
You can also use the [Null condition operator](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_Null) to ensure that the certificate policy variables used in a policy are populated during policy evaluation. The following policy document allows `iot:Connect` with certificates only when the Certificate Serial Number and Certificate Subject Common name attributes are present.
All of the certificate policy variables have String values, so all of the [String condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String) are supported.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/*"
],
"Condition": {
"Null": {
"iot:Certificate.SerialNumber": "false",
"iot:Certificate.Subject.CommonName": "false"
}
}
}
]
}
```