RFC: API Gateway IAM (AWS_IAM) Authorizers

[brettstack]

This is an RFC for enabling IAM (AWS_IAM) auth type on APIs.

SAM Template:

Resources:
  MyApi:
    ...
    Properties:
      Auth:
        # Sets auth type for all resources+methods of this API
        # Can be overridden at method level
        DefaultAuthorizer: AWS_IAM

        # Sets integration credentials for all resources+methods to this value
        # When this value is CALLER_CREDENTIALS, it sets it to the special value of "arn:aws:iam::*:user/*"
        # Can be overridden at method level
        # Default: CALLER_CREDENTIALS (when DefaultAuthorizer=AWS_IAM; otherwise  null)
        # Alternate names: `InvokeCredentials`
        # Values: IAM Role (e.g arn:aws:iam::123456789012:role/S3Access) or CALLER_CREDENTIALS (special case)
        InvokeRole: CALLER_CREDENTIALS 

  MyFunction:
    ...
    Events:
      MyApiEvent:
        Type: Api
        Properties:
          Path: /
          Method: get

          # Override at resource+method level
          # Setting `Authorizer` to null makes this endpoint open/public
          # These properties accept the same values as DefaultAuthorizer and InvokeRole on the API resource
          Auth:
            Authorizer: null
            InvokeRole: null

CloudFormation/Swagger Output:

1. Adds a sigv4 security scheme to Swagger
2. Adds sigv4 to list of security for each resource+method using AWS_IAM
3. Adds credentials to x-amazon-apigateway-integration for each resource+method using AWS_IAM

paths:
  /:
    get:
      security:
      - sigv4: []
      x-amazon-apigateway-integration:
        # This is set to "arn:aws:iam::*:user/*" when `InvokeRole: CALLER_CREDENTIALS`; otherwise it is set to the IAM Role specified.
        credentials: "arn:aws:iam::*:user/*"

securityDefinitions:
  sigv4:
    type: "apiKey"
    name: "Authorization"
    in: "header"
    x-amazon-apigateway-authtype: "awsSigv4"

Invoking APIs with IAM auth requires requests to be signed using Signature Version 4 https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html (derived from an AWS secret access key). The generated API Gateway SDK performs Signature Version 4 signing for you. Alternatively, libraries such as https://github.com/mhart/aws4 exist to make signing requests simpler.

Resources:

• https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html
• https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html#cfn-apigateway-method-authorizationtype
• When using AWS_IAM, ensure that AWS STS regional endpoints are enabled for the region where this API is deployed for best performance https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html. This requires the user to manually set this via Console.

[jlhood]

I don't get what this part means:

          Auth:
            Authorizer: null
            InvokeRole: null

Is that showing how to override auth for a specific path using function events?

[brettstack]

@jlhood that's correct. I will update with clarification.

[jlhood]

@brettstack Ok. Would also be good to add a Path/Method? Otherwise it looks incomplete to me. Also a yaml comment to explain what this is demonstrating.

[brettstack]

We'll begin implementation based on this spec.

[keetonian]

Released with SAM v1.11.0!