How do I grant IAM permissions to a Lambda function using an AWS SAM template?

4 minute read

I want to grant permissions to AWS Lambda functions in my AWS Serverless Application Model (AWS SAM) application. How do I define a Lambda execution role with scoped permissions in an AWS SAM template?

Short description

To define a Lambda execution role in an AWS SAM template, you can use the following AWS::Serverless::Function resource properties:

Policies—Allow you to create a new execution role using predefined policies that can be scoped to your Lambda function.
Role—Allows you to define an AWS Identity and Access Management (IAM) role to use as the function's execution role.
PermissionsBoundary—Allows you to set an IAM permissions boundary for the execution role that you create.

Note: The Policies and Roles properties can't be used together. Using the Role property is helpful when your execution role requires permissions that are too specific to use predefined policies.

Resolution

Specify policies for a new Lambda execution role

For the Policies property, enter any combination of the following:

The name of an AWS managed policy
The name of an AWS SAM policy template
An inline policy document

Note: AWS SAM policy templates are scoped to specific AWS resources. See Policy template table for a list of policy templates and the permissions that they give to your Lambda functions.

The following are some example AWS SAM YAML templates with Policies defined:

Example AWS SAM YAML template with an AWS managed policy named

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31' b
Resources:
  MyFunction:
    Type: 'AWS::Serverless::Function'
    Properties:
      Handler: index.handler
      Runtime: nodejs8.10
      CodeUri: 's3://my-bucket/function.zip'
      Policies:
      # Give the Lambda service access to poll your DynamoDB Stream
      - AmazonDynamoDBFullAccess

Example AWS SAM YAML template with an AWS SAM policy template (SQSPollerPolicy) defined

MyFunction:
  Type: 'AWS::Serverless::Function'
  Properties:
    CodeUri: ${codeuri}
    Handler: hello.handler
    Runtime: python2.7
    Policies:
      - SQSPollerPolicy:
          QueueName:
            !GetAtt MyQueue.QueueName

Example AWS SAM YAML template with an inline policy document defined

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
  MyFunction:
    Type: 'AWS::Serverless::Function'
    Properties:
      Handler: index.handler
      Runtime: nodejs8.10
      CodeUri: 's3://my-bucket/function.zip'
      Policies:
      - Statement:
        - Sid: SSMDescribeParametersPolicy
          Effect: Allow
          Action:
          - ssm:DescribeParameters
          Resource: '*'
        - Sid: SSMGetParameterPolicy
          Effect: Allow
          Action:
          - ssm:GetParameters
          - ssm:GetParameter
          Resource: '*'

(Optional) Specify an IAM permissions boundary

To set the maximum permissions allowed for your Lambda function's execution role, use an IAM permissions boundary.

To set an IAM permissions boundary, do the following in your AWS SAM YAML template:

Specify the Amazon Resource Name (ARN) of a permissions boundary

For the PermissionsBoundary property, enter the ARN of a permissions boundary. For example:

Properties:
  PermissionsBoundary: arn:aws:iam::123456789012:policy/LambdaBoundaries

Note: You can define PermissionsBoundary only if you're creating a new role with your AWS SAM template. You can't set a permissions boundary for an existing Role that you specify.

Specify a Lambda execution role

For the Role property, enter one of the following:

The ARN of a Lambda execution role that has an IAM permissions policy attached.
A reference to a Role resource that you've defined in the same AWS SAM template.

Note: If you don't specify a Role in your AWS SAM template, then an execution role is created when you deploy your application. This execution role includes any Policies that you define.

Example AWS SAM YAML template with the Role property defined

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources: 
  MyFunction:
    Type: 'AWS::Serverless::Function' 
    Properties:
      Handler: index.handler
      Runtime: nodejs8.10
      CodeUri: 's3://my-bucket/function.zip' 
      Role: arn:aws:iam::111111111111:role/SAMPolicy