How AWS IoT SiteWise works with IAM

Before you use AWS Identity and Access Management (IAM) to manage access to AWS IoT SiteWise, you should understand what IAM features are available to use with AWS IoT SiteWise.

IAM feature	Supported by AWS IoT SiteWise?
Identity-based policies with resource-level permissions	Yes
Resource-based policies	No
Access control lists (ACLs)	No
Tags-based authorization	Yes
Temporary credentials	Yes
Service-linked roles	Yes
Service roles	Yes

To get a high-level view of how AWS IoT SiteWise and other AWS services work with IAM, see AWS services that work with IAM in the IAM User Guide.

Contents

• AWS IoT SiteWise identity-based policies
  • Actions
    • BatchPutAssetPropertyValue authorization
  • Resources
  • Condition keys
  • Examples
• AWS IoT SiteWise resource-based policies
• Access control lists (ACLs)
• Authorization based on AWS IoT SiteWise tags
• AWS IoT SiteWise IAM roles
  • Using temporary credentials with AWS IoT SiteWise
  • Service-linked roles
  • Service roles
  • Choosing an IAM role in AWS IoT SiteWise

AWS IoT SiteWise identity-based policies

With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. AWS IoT SiteWise supports specific actions, resources, and condition keys. To learn about all of the elements that you use in a JSON policy, see IAM JSON policy elements reference in the IAM User Guide.

Actions

Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.

The Action element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Policy actions usually have the same name as the associated AWS API operation. There are some exceptions, such as permission-only actions that don't have a matching API operation. There are also some operations that require multiple actions in a policy. These additional actions are called dependent actions.

Include actions in a policy to grant permissions to perform the associated operation.

Policy actions in AWS IoT SiteWise use the following prefix before the action: iotsitewise:. For example, to grant someone permission to upload asset property data to AWS IoT SiteWise with the BatchPutAssetPropertyValue API operation, you include the iotsitewise:BatchPutAssetPropertyValue action in their policy. Policy statements must include either an Action or NotAction element. AWS IoT SiteWise defines its own set of actions that describe tasks that you can perform with this service.

To specify multiple actions in a single statement, separate them with commas as follows.

"Action": [
  "iotsitewise:action1",
  "iotsitewise:action2"
]

You can specify multiple actions using wildcards (*). For example, to specify all actions that begin with the word Describe, include the following action.

"Action": "iotsitewise:Describe*"

To see a list of AWS IoT SiteWise actions, see Actions Defined by AWS IoT SiteWise in the IAM User Guide.

BatchPutAssetPropertyValue authorization

AWS IoT SiteWise authorizes access to the BatchPutAssetPropertyValue action in an unusual way. For most actions, when you allow or deny access to an action, that action returns an error if permissions aren't granted. When you use BatchPutAssetPropertyValue, you can send multiple data entries to different assets and asset properties in a single API request, and AWS IoT SiteWise authorizes each data entry independently. For any individual entry that fails authorization in the request, AWS IoT SiteWise includes an AccessDeniedException in the returned list of errors. AWS IoT SiteWise receives the data for any entry that authorizes and succeeds, even if another entry in the same request fails.

Important

Before you ingest data to a data stream, do the following.

• The time-series resource must be authorized if you use a property alias to identify the data stream.

• The asset resource must be authorized if you use an asset ID to identify the asset that contains the associated asset property.

Resources

Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.

The Resource JSON policy element specifies the object or objects to which the action applies. Statements must include either a Resource or a NotResource element. As a best practice, specify a resource using its Amazon Resource Name (ARN). You can do this for actions that support a specific resource type, known as resource-level permissions.

For actions that don't support resource-level permissions, such as listing operations, use a wildcard (*) to indicate that the statement applies to all resources.

"Resource": "*"

Each IAM policy statement applies to the resources that you specify using their ARNs. An ARN has the following general syntax.

arn:${Partition}:${Service}:${Region}:${Account}:${ResourceType}/${ResourcePath}

For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS service namespaces.

For example, to specify the asset with ID a1b2c3d4-5678-90ab-cdef-22222EXAMPLE in your statement, use the following ARN.;

"Resource": "arn:aws:iotsitewise:region:123456789012:asset/a1b2c3d4-5678-90ab-cdef-22222EXAMPLE"

To specify all data streams that belong to a specific account, use the wildcard (*):

"Resource": "arn:aws:iotsitewise:region:123456789012:time-series/*"

To specify all assets that belong to a specific account, use the wildcard (*):

"Resource": "arn:aws:iotsitewise:region:123456789012:asset/*"

Some AWS IoT SiteWise actions, such as those for creating resources, can't be performed on a specific resource. In those cases, you must use the wildcard (*).

"Resource": "*"

To specify multiple resources in a single statement, separate the ARNs with commas.

"Resource": [
  "resource1",
  "resource2"
]

To see a list of AWS IoT SiteWise resource types and their ARNs, see Resources Defined by AWS IoT SiteWise in the IAM User Guide. To learn with which actions you can specify the ARN of each resource, see Actions Defined by AWS IoT SiteWise.

Condition keys

Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.

The Condition element (or Condition block) lets you specify conditions in which a statement is in effect. The Condition element is optional. You can create conditional expressions that use condition operators, such as equals or less than, to match the condition in the policy with values in the request.

If you specify multiple Condition elements in a statement, or multiple keys in a single Condition element, AWS evaluates them using a logical AND operation. If you specify multiple values for a single condition key, AWS evaluates the condition using a logical OR operation. All of the conditions must be met before the statement's permissions are granted.

You can also use placeholder variables when you specify conditions. For example, you can grant an IAM user permission to access a resource only if it is tagged with their IAM user name. For more information, see IAM policy elements: variables and tags in the IAM User Guide.

AWS supports global condition keys and service-specific condition keys. To see all AWS global condition keys, see AWS global condition context keys in the IAM User Guide.

Important

Many condition keys are specific to a resource, and some API actions use multiple resources. If you write a policy statement with a condition key, use the Resource element of the statement to specify the resource to which the condition key applies. If you don't do so, the policy might prevent users from performing the action at all, because the condition check fails for the resources to which the condition key doesn't apply. If you don't want to specify a resource, or if you've written the Action element of your policy to include multiple API actions, then you must use the ...IfExists condition type to ensure that the condition key is ignored for resources that don't use it. For more information, see ...IfExists conditions in the IAM User Guide.

AWS IoT SiteWise defines its own set of condition keys and also supports using some global condition keys. To see all AWS global condition keys, see AWS global condition context keys in the IAM User Guide.

AWS IoT SiteWise condition keys
Condition key	Description	Types
iotsitewise:isAssociatedWithAssetProperty	Whether data streams are associated with an asset property. Use this condition key to define permissions based on the existence of an associated asset property for data streams. Example value: true	String
iotsitewise:assetHierarchyPath	The asset's hierarchy path, which is a string of asset IDs each separated by a forward slash. Use this condition key to define permissions based on a subset of your hierarchy of all assets in your account. Example value: /a1b2c3d4-5678-90ab-cdef-22222EXAMPLE/a1b2c3d4-5678-90ab-cdef-66666EXAMPLE	String
iotsitewise:propertyId	The ID of an asset property. Use this condition key to define permissions based on a specified property of an asset model. This condition key applies to all assets of that model. Example value: a1b2c3d4-5678-90ab-cdef-33333EXAMPLE	String
iotsitewise:childAssetId	The ID of an asset being associated as a child to another asset. Use this condition key to define permissions based on child assets. To define permissions based on parent assets, use the resource section of a policy statement. Example value: a1b2c3d4-5678-90ab-cdef-66666EXAMPLE	String
iotsitewise:iam	The ARN of an IAM identity when listing access policies. Use this condition key to define access policy permissions for an IAM identity. Example value: arn:aws:iam::123456789012:user/JohnDoe	String, Null
iotsitewise:propertyAlias	The alias that identifies an asset property or data stream. Use this condition key to define permissions based on the alias.	String
iotsitewise:user	The ID of an IAM Identity Center user when listing access policies. Use this condition key to define access policy permissions for an IAM Identity Center user. Example value: a1b2c3d4e5-a1b2c3d4-5678-90ab-cdef-aaaaaEXAMPLE	String, Null
iotsitewise:group	The ID of an IAM Identity Center group when listing access policies. Use this condition key to define access policy permissions for an IAM Identity Center group. Example value: a1b2c3d4e5-a1b2c3d4-5678-90ab-cdef-bbbbbEXAMPLE	String, Null
iotsitewise:portal	The ID of a portal in an access policy. Use this condition key to define access policy permissions based on a portal. Example value: a1b2c3d4-5678-90ab-cdef-77777EXAMPLE	String, Null
iotsitewise:project	The ID of a project in an access policy, or the ID of a project for a dashboard. Use this condition key to define dashboard or access policy permissions based on a project. Example value: a1b2c3d4-5678-90ab-cdef-88888EXAMPLE	String, Null

To learn with which actions and resources you can use a condition key, see Actions Defined by AWS IoT SiteWise.

Examples

To view examples of AWS IoT SiteWise identity-based policies, see AWS IoT SiteWise identity-based policy examples.

AWS IoT SiteWise resource-based policies

AWS IoT SiteWise doesn't support resource-based policies.

Access control lists (ACLs)

AWS IoT SiteWise doesn't support ACLs.

Authorization based on AWS IoT SiteWise tags

You can attach tags to AWS IoT SiteWise resources or pass tags in a request to AWS IoT SiteWise. To control access based on tags, you provide tag information in the condition element of a policy using the aws:ResourceTag/key-name, aws:RequestTag/key-name, or aws:TagKeys condition keys. For more information about tagging AWS IoT SiteWise resources, see Tagging your AWS IoT SiteWise resources.

To view an example identity-based policy for limiting access to a resource based on the tags on that resource, see Viewing AWS IoT SiteWise assets based on tags.

AWS IoT SiteWise IAM roles

An IAM role is an entity within your AWS account that has specific permissions.

Using temporary credentials with AWS IoT SiteWise

You can use temporary credentials to sign in with federation, assume an IAM role, or to assume a cross-account role. You obtain temporary security credentials by calling AWS STS API operations such as AssumeRole or GetFederationToken.

AWS IoT SiteWise supports using temporary credentials.

SiteWise Monitor supports federated users to access portals. Portal users authenticate with their IAM Identity Center or IAM credentials.

Important

Users or roles must have the iotsitewise:DescribePortal permission to sign in to the portal.

When a user signs in to a portal, SiteWise Monitor generates a session policy that provides the following permissions:

• Read-only access to the assets and asset data in AWS IoT SiteWise in your account to which that portal's role provides access.

• Access to projects in that portal to which the user has administrator (project owner) or read-only (project viewer) access.

For more information about federated portal user permissions, see Using service roles for AWS IoT SiteWise Monitor.

Service-linked roles

Service-linked roles allow AWS services to access resources in other services to complete an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view but not edit the permissions for service-linked roles.

AWS IoT SiteWise supports service-linked roles. For details about creating or managing AWS IoT SiteWise service-linked roles, see Using service-linked roles for AWS IoT SiteWise.

Service roles

This feature allows a service to assume a service role on your behalf. This role allows the service to access resources in other services to complete an action on your behalf. Service roles appear in your AWS account and are owned by the account. This means that an IAM administrator can change the permissions for this role. However, doing so might break the functionality of the service.

AWS IoT SiteWise uses a service role to allow SiteWise Monitor portal users to access some of your AWS IoT SiteWise resources on your behalf. For more information, see Using service roles for AWS IoT SiteWise Monitor.

You must have required permissions before you can create AWS IoT Events alarm models in AWS IoT SiteWise. For more information, see Setting up permissions for AWS IoT Events alarms.

Choosing an IAM role in AWS IoT SiteWise

When you create a portal resource in AWS IoT SiteWise, you must choose a role to allow the federated users of your SiteWise Monitor portal to access AWS IoT SiteWise on your behalf. If you have previously created a service role, then AWS IoT SiteWise provides you with a list of roles to choose from. Otherwise, you can create a role with the required permissions when you create a portal. It's important to choose a role that allows access to your assets and asset data. For more information, see Using service roles for AWS IoT SiteWise Monitor.