Changes in the IAM Policy Builder API from version 1 to version 2 - Amazon SDK for Java 2.x
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Changes in the IAM Policy Builder API from version 1 to version 2

This topic details the changes in the IAM Policy Builder API from version 1 (v1) to version 2 (v2).

High-level changes

Change v1 v2

Maven dependencies

<dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-bom</artifactId> <version>1.12.5871</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-core</artifactId> </dependency> </dependencies>
<dependencyManagement> <dependencies> <dependency> <groupId></groupId> <artifactId>bom</artifactId> <version>2.21.212</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId></groupId> <artifactId>iam-policy-builder</artifactId> </dependency> </dependencies>
Package name com.amazonaws.auth.policy
Class names





1 Latest version. 2 Latest version.

API changes

Setting v1 v2

Instantiate a policy
Policy policy = new Policy();
IamPolicy.Builder policyBuilder = IamPolicy.builder(); ... IamPolicy policy =;

Set id

policy.withtId(...); policy.setId(...);;

Set version

N/A - uses default version of 2012-10-17

Create statement

Statement statement = new Statement(Effect.Allow) .withActions(...) .withConditions(...) .withId(...) .withPrincipals(...) .withResources(...);
IamStatement statement = IamStatement.builder() .effect(IamEffect.ALLOW) .actions(...) .notActions(...) .conditions(...) .sid(...) .principals(...) .notPrincipals(...) .resources(...) .notResources(...) .build()

Set statement

policy.withStatements(statement); policy.setStatements(statement);

Differences in building a statement



The v1 SDK has enum types for service actions that represent Action elements in a policy statement. The following enum types are some examples.

The following example shows the SendMessage constant for SQSActions.

Action action = SQSActions.SendMessage;

You cannot specify a NotAction element to a statement in v1.


In v2, the IamAction interface represents all actions. To specify a service-specific action element, pass a string to the create method as shown in the following code.

IamAction action = IamAction.create("sqs:SendMessage");

You can specify a NotAction for a statement with v2 as shown in the following code.

IamAction action = IamAction.create("sqs:SendMessage"); IamStatement.builder().addNotAction(action);



To represent statement conditions, the v1 SDK uses subclasses of Condition.

Each Condition subclass defines a comparison enum type to help define the condition. For example, the following shows a not like string comparison for a condition.

Condition condition = new StringCondition(StringComparisonType.StringNotLike, "key", "value");


In v2, you build a condition for a policy statement by using IamCondition and provide an IamConditionOperator, which contains enums for all types.

IamCondition condition = IamCondition.create(IamConditionOperator.STRING_NOT_LIKE, "key", "value");



A policy statement's Resource element is represented by the SDK's Resource class. You supply the ARN as a string in the constructor. The following subclasses provide convenience constructors.

In v1, you can specify a NotResource element for a Resource by calling the withIsNotType method as shown in the following statement.

Resource resource = new Resource("arn:aws:s3:::mybucket").withIsNotType(true);


In v2, you create a Resource element by passing an ARN to the IamResource.create method.

IamResource resource = IamResource.create("arn:aws:s3:::mybucket");

An IamResource can be set as NotResource element as shown in the following snippet.

IamResource resource = IamResource.create("arn:aws:s3:::mybucket"); IamStatement.builder().addNotResource(resource);

IamResource.ALL represents all resources.



The v1 SDK offers the following Principal classes to represent types of principals that include all members:

  • AllUsers

  • AllServices

  • AllWebProviders

  • All

You cannot add a NotPrincipal element to a statement.


In v2, IamPrincipal.ALL represents all principals:

To represent all members in other types of principals, use the IamPrincipalType classes when you create a IamPrincipal.

  • IamPrincipal.create(IamPrincipalType.AWS,"*") for all users.

  • IamPrincipal.create(IamPrincipalType.SERVICE,"*") for all services.

  • IamPrincipal.create(IamPrincipalType.FEDERATED,"*") for all web providers.

  • IamPrincipal.create(IamPrincipalType.CANONICAL_USER,"*") for all canonical users.

You can use the addNotPrincipal method to represent a NotPrincipal element when you create a policy statement as shown in the following statement.

IamPrincipal principal = IamPrincipal.create(IamPrincipalType.AWS, "arn:aws:iam::444455556666:root"); IamStatement.builder().addNotPrincipal(principal);