AWS IAM Roles and policies in simple English?

Question

I've been working with the AWS PHP SDK and I seem to get everything except the IAM Roles and permissions.

Can someone please explain to me in the simplest term how the IAM roles work and explain the following terms: StatementId, Action, ARN and most importantly Principal in simple English?

To give you the source of my confusion, here is a problem I recently faced. I'm trying to create an API Gateway in which a Resource's method triggers a Lambda function. It wasn't working until I copy pasted this bit:

$lambdaClient->addPermission([
                'FunctionName' => 'fn name',
                'StatementId' => 'ManagerInvokeAccess',
                'Action' => 'lambda:InvokeFunction',
                'Principal' => 'apigateway.amazonaws.com',
            ]);

But in some other thread someone suggested to use the following for the same:

const permissions = {
    FunctionName: target,
    StatementId: 'api-gateway-execute',
    Action: 'lambda:InvokeFunction',
    Principal: 'apigateway.amazonaws.com',
    SourceArn: 'arn:aws:execute-api:' + nconf.get('awsRegion') + ':' + nconf.get('awsAccountId') + ':' + nconf.get('apiGatewayId') + '/*'};

How come the the first one doesn't contain any account info but The second one does? Also then there is another person who has pasted something totally different to get the same working for him. There are so many keys in the last example (like "Fn::Join"), I don't even know where to begin and what it does.

How does one figure out where to find these policies? Do we just copy-paste them from somewhere is there is a way to ascertain them. If so what keys must always be specified.

Any help will be appreciated because I'm totally confused right now.

Deepseated

Answer 1

First of all, Welcome to the world of AWS !!! :-D

Let me try to explain your doubts about how to understand IAM(in general) with an analogy.

Think that there is an organization called ORG1.

Deparments of ORG1: HR-dept, Test-dept, DEV-dept

Employees of ORG1: EMP1, EMP2, EMP3 ... EMP10

Members of HR dept: HR1, HR2, HR3

Now I want to create a role for HR dept to give them permission to hire/suspend an employee. The policy will look like below:

{
    "Version": "2012-10-17", // This is version of the template. Don't change this. This is NOT a date field for your use.
    "Statement": [
        {
            "Sid": "SOME-RANDOM-ID-WITH-NUMBER-1P1PP43EZUVRM", // This is used as ID in some cases to identify different statments
            "Principal": HR-dept, // the dept who is allowed to assume this role or the one who is allowed to invoke this role
            "Effect": "Allow", // has only 2 values: ALLOW/DENY. Either You want to provided the below privileges or you want to striped off these privileges.
            "Action": [
                "hire",
                "suspend",
            ],  // these are privileges which are granted
            "Resource": "EMP1", // the entity on whom do you want to apply those actions on. In this case employee EMP1.
            "Condition": {
                "ArnLike": {
                    "AWS:SourceArn": "HR*" // You want anyone from HR-dept whose id starts with HR to be able to execute the action.ie HR1,HR2 or HR3 .
                }
            }
        }
    ]
}

Now try to understand the below code from the same perspective(Internally this code creates a template similar to above):

const permissions = {
        FunctionName: target,
        StatementId: 'api-gateway-execute', // This is just an ID. Dont sweat about it.
        Principal: 'apigateway.amazonaws.com', //which entity group the invoker belongs to
        Action: 'lambda:InvokeFunction', // The privilege you are giving to API gateway api's
        SourceArn: 'arn:aws:execute-api:.. blah blah blah' // ie. the exact  Id of api-gateway which all has rights to invoke lambda function
}; 

In AWS ARN is a unique ID of a resource. Kind of like EmployeeId in a company.This is unique globally.

Believe me, At first it may seem that what you are trying to do in AWS is difficult to comprehend, But at some point you will start getting comfortable as you go on crossing each hurdle you face. And then you will admire at how customizable AWS features are.

Infrasonic

wow.. this was just amazing! Thank you for explaining it in such simple terms. It makes a lot more sense now. I will be coming back to analogy a lot! Okay, just one or two more things, what is this "Fn::Join" business? And what does it mean when it says 'Action' => 'sts:AssumeRole'. Does that have any special meaning? – Deepseated

Fn::Join is a concat method which concats the list of strings you provide as input with the delimiter of your choice. Check this [link].(docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/…) ex: "Fn::Join" : [ "-", [ "us", "east", "1" ] ] will give you "us-east-1". – Infrasonic

'Action' => 'sts:AssumeRole' gives your lambda function access to use security Token Service(sts)'s AssumeRole api, which generates and returns temporary credentials to access the resources defined in the policy. – Infrasonic

Answer 2

How does one figure out where to find these policies?

You need to refer the AWS Documentation for specific service to find out what are the principals, actions and statements they support. For example if you need to find out policies for DynamoDB, check DynamoDB API Permissions. It can be confusing at first, since AWS Need to cater using IAM to authorize all of their services, but it becomes straight forward over time.

Let me explain each part of the policy

• StatementId(Sid) - Its just and optional statement identifier (e.g 1, 2, abcd & etc.) and for some services(e.g SQS, SNS) it requires uniqueness.

• Action - What your policy allows to do on a AWS Service. e.g For DynamoDB you can allow creating Tables, Putting new items & etc. For EC2 instance, it can allow starting and stopping.

• ARN(Amazon Resource Name) - This is a unique name to uniquely identify AWS resources like a EC2 server, S3 bucket, DynamoDB table and even IAM policy, Role & etc.

• Principal - Principal is to restrict who is allowed to use this policy. It can be a user (IAM user, federated user, or assumed-role user), AWS account, AWS service, or other principal entity that is allowed or denied access to a resource.

In addition you need to include Resource parameter, where you can either use a wildcard '*' or a ARN with Account ID within it.

Wringer

Thanks, that does clarify things a bit. When creating a lambda function I want it to have full access to an S3 bucket (say bucket). How do I create a policy for that (I mean i know where to copy-paste the policy for that, i.e. how do I create it from scratch with full understanding of it). thanks! – Deepseated

When it comes to S3, you need to understand few more concepts. Access to S3 can be granted by IAM Policies, Bucket Policies and Access Control Lists. When using Lambda to access S3 bucket, You need to have a IAM policy not only granting access to S3, but also allowing Lambda to Assume the IAM Role that has the policy. To do this, in the role in addition to the policy, you need to add Trust Relationship. Trust Relationship is created automatically if you select, Lambda in the wizard when creating a Role. – Wringer

Answer 3

I think most of the answers are correct but here it is from the horse's mouth/the great AWS document (full credit)

Role: An IAM role is an IAM identity that you can create in your account that has specific permissions.

Policies: IAM policies define permissions for an action regardless of the method that you use to perform the operation

Typically you have a role and you assign polices to your role.

To answer last part of your question "How does one figure out where to find these policies". This is all depends on what you are trying to do but always start with the least amount of permission (same concept as linux file permission don't give 777 ). How do you define your policies there are standard one already defined in your AWS account but you can use a tool to customize yours policies using the below tool

https://awspolicygen.s3.amazonaws.com/policygen.html

Recede