AWS IAM traits¶

IAM Policy Traits are used to describe the permission structure of a service in relation to AWS IAM. Services integrated with AWS IAM define resource types, actions, and condition keys that IAM users can use to construct IAM policies.

Actions and resource types are automatically inferred from a service model via operations and resources, respectively. Actions can also be annotated with other actions that they depend on to be invoked.

Condition keys are available for IAM users to define restrictions in IAM policies for resources in a service. Condition keys for services defined in Smithy are automatically inferred. These can be disabled or augmented. For more information, see Deriving Condition Keys.

Table of contents

aws.iam#actionPermissionDescription trait
aws.iam#conditionKeys trait
aws.iam#defineConditionKeys trait
- Condition Key Types
aws.iam#disableConditionKeyInference trait
aws.iam#requiredActions trait
Deriving Condition Keys

`aws.iam#actionPermissionDescription` trait¶

Summary: A brief description of what granting the user permission to invoke an operation would entail.
Trait selector: operation
Value type: string

namespace smithy.example

use aws.iam#actionPermissionDescription

@actionPermissionDescription("This will allow the user to Foo.")
operation FooOperation {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#FooOperation": {
            "type": "operation",
            "traits": {
                "aws.iam#actionPermissionDescription": "This will allow the user to Foo."
            }
        }
    }
}

`aws.iam#conditionKeys` trait¶

Summary: Applies condition keys, by name, to a resource or operation.
Trait selector: :test(resource, operation)
Value type: list<string>

Condition keys derived automatically can be applied to a resource or operation explicitly. Condition keys applied this way MUST be either inferred or explicitly defined via the aws.iam#defineConditionKeys trait trait.

The following example's MyResource resource has the myservice:MyResourceFoo and otherservice:Bar condition keys. The MyOperation operation has the aws:region condition key.

namespace smithy.example

use aws.api#service
use aws.iam#definedContextKeys
use aws.iam#conditionKeys

@service(sdkId: "My Value", arnNamespace: "myservice")
@defineConditionKeys("otherservice:Bar": { type: "String" })
service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

@conditionKeys(["otherservice:Bar"])
resource MyResource {
    identifiers: {foo: String},
    operations: [MyOperation],
}

@conditionKeys(["aws:region"])
operation MyOperation {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "My Value",
                    "arnNamespace": "myservice"
                },
                "aws.iam#defineConditionKeys": {
                    "otherservice:Bar": {
                        "type": "String"
                    }
                }
            }
        },
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "foo": {
                    "target": "smithy.api#String"
                }
            },
            "operations": [
                {
                    "target": "smithy.example#MyOperation"
                }
            ],
            "traits": {
                "aws.iam#conditionKeys": [
                    "otherservice:Bar"
                ]
            }
        },
        "smithy.example#MyOperation": {
            "type": "operation",
            "traits": {
                "aws.iam#conditionKeys": [
                    "aws:region"
                ]
            }
        }
    }
}

Note

Condition keys that refer to global "aws:*" keys can be referenced without being defined on the service.

`aws.iam#defineConditionKeys` trait¶

Summary: Defines the set of condition keys that appear within a service in addition to inferred and global condition keys.
Trait selector: service
Value type: map of IAM identifiers to condition key structure

The aws.iam#defineConditionKeys trait defines additional condition keys that appear within a service. Keys in the map must be valid IAM identifiers, meaning they must adhere to the following regular expression: "^([A-Za-z0-9][A-Za-z0-9-\\.]{0,62}:[^:]+)$". Each condition key structure supports the following members:

Property	Type	Description
type	`string`	Required. The type of contents of the condition key. The type must be one of: `ARN`, `Binary`, `Bool`, `Date`, `IPAddress`, `Numeric`, `String`, `ArrayOfARN`, `ArrayOfBinary`, `ArrayOfBool`, `ArrayOfDate`, `ArrayOfIPAddress`, `ArrayOfNumeric`, `ArrayOfString`. See Condition Key Types for more information.
documentation	`string`	Defines documentation about the condition key.
externalDocumentation	`string`	A valid URL that defines more information about the condition key.

namespace smithy.example

use aws.api#service
use aws.iam#defineConditionKeys

@service(sdkId: "My Value", arnNamespace: "myservice")
@defineConditionKeys(
    "otherservice:Bar": {
        type: "String",
        documentation: "The Bar string",
        externalDocumentation: "http://example.com"
    })
service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "My Value",
                    "arnNamespace": "myservice"
                },
                "aws.iam#defineConditionKeys": {
                    "otherservice:Bar": {
                        "type": "String",
                        "documentation": "The Bar string",
                        "externalDocumentation": "http://example.com"
                    }
                }
            }
        }
    }
}

Note

Condition keys that refer to global "aws:*" keys are allowed to not be defined on the service.

Condition Key Types¶

The following table describes the available types a condition key can have. Condition keys in IAM policies can be evaluated with condition operators.

Type	Description
`ARN`	A String type that contains an Amazon Resource Name (ARN).
`Binary`	A String type that contains base-64 encoded binary data.
`Bool`	A general boolean type.
`Date`	A String type that conforms to the `datetime` profile of ISO 8601.
`IPAddress`	A String type that conforms to RFC 4632.
`Numeric`	A general type for integers and floats.
`String`	A general string type.
`ArrayOfARN`	An unordered list of ARN types.
`ArrayOfBinary`	An unordered list of Binary types.
`ArrayOfBool`	An unordered list of Bool types.
`ArrayOfDate`	An unordered list of Date types.
`ArrayOfIPAddress`	An unordered list of IPAddress types.
`ArrayOfNumeric`	An unordered list of Numeric types.
`ArrayOfString`	An unordered list of String types.

`aws.iam#disableConditionKeyInference` trait¶

Summary: Declares that the condition keys of a resource should not be inferred.
Trait selector: resource
Value type: Annotation trait

A resource marked with the aws.iam#disableConditionKeyInference trait will not have its condition keys automatically inferred from its identifiers and the identifiers of its ancestors (if present.)

The following example shows a resource, MyResource, that has had its condition key inference disabled.

namespace smithy.example

use aws.api#service
use aws.iam#disableConditionKeyInference

@service(sdkId: "My Value", arnNamespace: "myservice")
service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

@disableConditionKeyInference
resource MyResource {
    identifiers: {
        foo: String,
        bar: String,
    },
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "My Value",
                    "arnNamespace": "myservice"
                }
            }
        },
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "foo": {
                    "target": "smithy.api#String"
                },
                "bar": {
                    "target": "smithy.api#String"
                }
            },
            "traits": {
                "aws.iam#disableConditionKeyInference": true
            }
        }
    }
}

`aws.iam#requiredActions` trait¶

Summary: Other actions that the invoker must be authorized to perform when executing the targeted operation.
Trait selector: operation
Value type: list<string> where each string value references condition keys defined in the closure of the service.

Defines the actions, in addition to the targeted operation, that a user must be authorized to execute in order invoke an operation. The following example indicates that, in order to invoke the MyOperation operation, the invoker must also be authorized to execute the otherservice:OtherOperation operation for it to complete successfully.

namespace smithy.example

use aws.api#service
use aws.iam#requiredActions

@service(sdkId: "My Value", arnNamespace: "myservice")
service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

resource MyResource {
    identifiers: {foo: String},
    operations: [MyOperation],
}

@requiredActions(["otherservice:OtherOperation"])
operation MyOperation {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "My Value",
                    "arnNamespace": "myservice"
                }
            }
        },
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "foo": {
                    "target": "smithy.api#String"
                }
            },
            "operations": [
                {
                    "target": "smithy.example#MyOperation"
                }
            ]
        },
        "smithy.example#MyOperation": {
            "type": "operation",
            "traits": {
                "aws.iam#requiredActions": [
                    "otherservice:OtherOperation"
                ]
            }
        }
    }
}

Deriving Condition Keys¶

Smithy will automatically derive condition key information for a service, as well as its resources and operations.

A resource's condition keys include those that are inferred from their identifiers, including the resource's ancestors, and those applied via the aws.iam#conditionKeys trait trait. Condition keys for resource identifiers are automatically inferred unless explicitly configured not to via the aws.iam#disableConditionKeyInference trait trait.

An action's condition keys, including for actions for operations bound to resources, are only derived from those applied via the aws.iam#conditionKeys trait trait.

Given the following model,

namespace smithy.example

use aws.api#service
use aws.iam#defineConditionKeys
use aws.iam#conditionKeys

@service(sdkId: "My Value", arnNamespace: "myservice")
@defineConditionKeys("otherservice:Bar": { type: "String" })
service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

@conditionKeys(["otherservice:Bar"])
resource MyResource {
    identifiers: {foo: String},
    operations: [MyOperation],
    resources: [MyInnerResource],
}

resource MyInnerResource {
    identifiers: {yum: String}
}

@conditionKeys(["aws:region"])
operation MyOperation {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "My Value",
                    "arnNamespace": "myservice"
                },
                "aws.iam#defineConditionKeys": {
                    "otherservice:Bar": {
                        "type": "String"
                    }
                }
            }
        },
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "yum": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#MyOperation": {
            "type": "operation",
            "traits": {
                "aws.iam#conditionKeys": [
                    "aws:region"
                ]
            }
        }
    }
}

The computed condition keys for the service are:

Name	Condition Keys
`MyResource`	`myservice:MyResourceFoo` `otherservice:Bar`
`MyInnerResource`	`myservice:MyResourceFoo` `otherservice:Bar` `myservice:MyInnerResourceYum`
`MyOperation`	`aws:region`

AWS IAM traits¶

aws.iam#actionPermissionDescription trait¶

aws.iam#conditionKeys trait¶

aws.iam#defineConditionKeys trait¶