How does an EC2 instance assume an IAM Role?

Question

I am working through the Security Learning Plan and was recently watching the video about AWS Secrets Manager.

The real question that concerns me is why using AWS Secrets Manager is better than say, store encrypted credentials in a config file. I know that there are a couple of aspects where Secrets Manager is obviously a lot better than a config file (credential rotation, central point of maintenance of credentials) but these don't answer my question.

To clarify, let me give you an example. Let's say I have an EC2 instance running Tomcat and Tomcat needs credentials to connect to a DB. I store the creds in Secrets Manager and use the Java API to let Tomcat retrieve them. I guess (I didn't try it out yet) I need to grant the required permissions to the EC2 instance by assigning it an IAM role with appropriate permissions (maybe this assumption is incorrect, if so, how would I do it instead?). And now come my questions:

1. How does Secrets Manager know the credential request is legimitate? 
2. How will the HTTP Query Tomcat sends authenticate against Secrets Manager?
3. Will Secrets Manager see that a Java process is querying or will it only see a request coming from instance i-something?
4. If the answer of 3 is "Secrets Manager sees only the instance querying" then how can I prevent another process on the same box querying the DB creds? If I chose the solution with the config file one of the major security drawbacks is that any intruder on the box can read the files, reverse the code the encrypts the creds and decrypt them. I would like to know if Secrets Manager provides a good solution for this fundamental problem.

I didn't find any posts discussing this in the required detail (e.g. [https://repost.aws/questions/QUAsOpdhR-QAKVZEL0nRGTkw/aws-secrets-manager-with-boto-3-in-python](https://repost.aws/questions/QUAsOpdhR-QAKVZEL0nRGTkw/aws-secrets-manager-with-boto-3-in-python)).

I hope I explained the problem well enough. Thanks for every answer.

Dmitry Balabanov · Accepted Answer

Here is a great explanation of how an EC2 instance assumes the role using instance profiles: [Using an IAM role to grant permissions to applications running on Amazon EC2 instances](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html).

You can also read about the [advantages of using IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) instead of distributing the credentials manually.

And now back to your questions.

You are correct: you need to grant the required permissions to the EC2 instance by assigning it an IAM role with appropriate permissions (for accessing the Secrets Manager service and obtaining the stored secrets).

1.  Checking if a request is legitimate is not something that will be done specifically by the Secrets Manager service. This is a core functionality of AWS - every API call will be checked for validity. Every API request must be signed with credentials to access the AWS services. AWS will check if the credentials are valid and if they grant permissions to call that specific API.
2. When you use the Java SDK and make a call to the Secrets Manager from an instance with a role assigned, the SDK will first call the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) and obtain the credentials for you. This call will happen under the hood if you attach a role to your EC2 instance. The AWS STS will issue temporary credentials that will expire after some time. Those credentials will sign the subsequential request sent to the Secrets Manager, so this is how the call will be authenticated. For more information, you can read [this blog post](https://aws-blog.de/2021/08/iam-what-happens-when-you-assume-a-role.html) explaining what exactly happens on assuming a role.
3. The Secrets Manager service will observe an API call coming from the EC2 service. There is no way to restrict the access to a single process only. All processes running on the EC2 instance with attached role will have all permissions that role grants.
4. By using resource-based permission policies, you control [which IAM roles and services have access to your secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html) in Secrets Manager. However, this won't prevent the intruder from accessing the secrets if an instance with role assigned will be compromised. In that case, follow the [security incident response best practices](https://docs.aws.amazon.com/whitepapers/latest/aws-security-incident-response-guide/infrastructure-domain-incidents.html) and isolate the instance. Since you haven't stored any long-term credentials on that instance, the compromised temporary credentials will soon expire, so the intruder will not be able to access the services anymore. You can also configure an automatic [secrets rotation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in Secrets Manager, so your database passwords will automatically change too (without needing to distribute them to all your instances).

kentrad · Answer

1. The API call to Secrets Manager will be signed by the credentials (Access Key Id/Secret Key) that link back to the role assigned to the instance. 
2. Not sure specifically about Tomcat, but the API signing is built into the AWS SDKs. And the SDKs know to check the instance metadata service to retrieve the credentials.
3. It will just see the request signed by credentials asserting the role that was assumed by the instance and then have the policies that allow it to retrieve the secret.
4. Yes, any process on that instance can call APIs with the credentials of the role assigned to the instance.

No, I don't think there is a solution to the problem you are describing, at some point your app needs the plaintext credentials. However, using Secrets Manager and EC2 Instance Profiles keeps your secrets and encryption keys out of config files and therefore out of any code repo. Focus on making sure the policy assigned to the role follows least privilege and restricting access to instance via network controls and login permissions.

How does an EC2 instance assume an IAM Role?

Relevant content