How AWS IAM Roles Work

Background

AWS recommends using IAM roles instead of long-term access keys, and have dutifully applied this principle to their SaaS offering like Amazon OpenSearch Service. However, this has introduced usage patterns that are difficult to understand. Let's dive into the underlying principles of the official migration tutorial for Amazon OpenSearch and understand how IAM roles and OpenSearch roles are involved.

Passing an IAM role to an AWS service

To restore a snapshot from S3, the OpenSearch domain (i.e. cluster) needs access to your S3 bucket, but as an AWS service, it can not directly access resources from customer's account. To grant access, you have to create a role that allows the OpenSearch domain to assume this role to act with permissions defined by the role's policy and bounded by the role's AWS account.

During this process, two IAM actions are involved, which are sts:AssumeRole and iam:PassRole.

The STS AssumeRole API is the foundation of IAM roles. It returns temporary credentials to the caller that can be used to assume a role. sts:AssumeRole is often specified in the trust relationship of a role, which permits specified principles to assume it.

{
  "Version": "2012-10-17",
  "Statement": [{
      "Effect": "Allow",
      "Principal": {
        "Service": "es.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

For security reasons, creating a role alone does not grant permission to the specified principals. Otherwise, anyone knowing the ARN of your role could steal your data from S3 by importing your snapshot into their OpenSearch domain.

That's where iam:PassRole comes into play. Only roles passed to a service can be assumed by that service, and services can enforce further constraints on its use of the AssumeRole API using information provided in the API calls that involve iam:PassRole.

Roles in an OpenSearch domain

Amazon OpenSearch has its own access control system which accepts both IAM and HTTP basic authentication. Upon creation of an OpenSearch domain, you can use an existing IAM identity as the master user or create a new one with username and password.

Unfortunately, HTTP basic authentication carries no IAM permissions and therefore cannot pass an IAM role to the domain. You have to use IAM identities (users or roles) to both authenticate to IAM to perform iam:PassRole and to the OpenSearch domain to perform snapshot repository registration under the domain's access control.

In order to be authorized to perform snapshot repository registration, the IAM identity needs access level of at least the manage_snapshots role in OpenSearch. If you didn't use an IAM identity as the OpenSearch master user, you can grant access by mapping an IAM identity to an OpenSearch role in the domain's OpenSearch Dashboards as explained in the migration guide. Otherwise, you could simply use the master user to authenticate.

With both permissions in place, you can finally call the PUT _snapshot/my-snapshot-repo-name API to create a new snapshot registry in your OpenSearch domain and pass the IAM role with access to your S3 bucket to it.

Just like roles attached to an EC2 instance, once you have finished the setup that requires iam:PassRole permission, the service can assume this role anytime later. Further actions on the snapshot registry you've created only needs to be authenticated by the OpenSearch domain, so HTTP basic authentication will suffice, which is why at this point in the tutorial you can use the domain's master username and password to authenticate.

Conclusions

sts:AssumeRole and iam:PassRole are very tricky and dangerous permissions. I hope this blog helps you better understand the implications of passing a role to another principle and how IAM roles work in general.

My take on this is that

1. iam:PassRole permission must be granted with care. If you grant someone that permission and have an existing role with AdministratorAccess, you could risk giving out total control of your account.
2. It is up to each AWS service to enforce further constraints on how roles passed to them can be used. Given the scale of AWS, it would not surprise me if one of them has a vulnerability that allows an attacker to perform actions on others' behalf if IAM roles are passed to that service.
3. If you care about security, always apply the principle of least privilege when you write IAM policies.