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

<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>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.21.212</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>iam-policy-builder</artifactId>
    </dependency>
</dependencies>

¹ Latest version. ² Latest version.

API changes

Policy policy = new Policy();

IamPolicy.Builder policyBuilder = IamPolicy.builder();
...
IamPolicy policy = policyBuilder.build();

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

policyBuilder.id(...);

policyBuilder.version(...);

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()

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

policyBuilder.addStatement(statement);

Differences in building a statement

Actions

v1

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.

v2

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);

Conditions

v1

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");

v2

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");

Resources

v1

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);

v2

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.

Principals

v1

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

You cannot add a NotPrincipal element to a statement.

v2

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.

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);