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.

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.