Serverless-application-model: RFC: Usage Plans for Auth

[ShreyaGangishetty]

Resources
Api keys, create and use Api keys with Usage Plans, Auth

Associated Issues
#248, #547

Description
Api keys can be generated by creating a Usage Plan or by using existing Usage Plan.

The template for Usage plans in SAM would look like:

  ...
      UsagePlan:  
        CreateUsagePlan: SHARED  # Accepted values: SHARED | NONE | SINGLE # Required field
        UsagePlanId: !Ref usageplanId # Optional field
  ...

• SAM creates three resources, AWS::ApiGateway::ApiKey with name ServerlessApiKey, AWS::ApiGateway::UsagePlan with name ServerlessUsagePlan, and AWS::ApiGateway::UsagePlanKey with name ServerlessUsagePlanKey for a stack when CreateUsagePlan is set to SHARED in Globals / Api.
• SAM creates three resources, AWS::ApiGateway::ApiKey with name <ApiName>ApiKey, AWS::ApiGateway::UsagePlan with name <ApiName>UsagePlan, and AWS::ApiGateway::UsagePlanKey with name <ApiName>UsagePlanKey for an Api when CreateUsagePlan is set to SINGLE in Globals / Api.
• SAM creates AWS::ApiGateway::ApiKey and AWS::ApiGateway::UsagePlanKey when UsagePlanId is given. SAM will not create/update AWS::ApiGateway::UsagePlan resource and expects ApiStages to be defined by the user seperately.

Input to SAM

Globals:
  Api:
    Auth:
      ApiKeyRequired: true
      UsagePlan:
        CreateUsagePlan: SHARED

Resources:
  ...
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod

  MyDifferentApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Dev
  ...

CloudFormation Template generated by SAM for Usage Plans

Globals:
  Api:
    Auth:
      ApiKeyRequired: true
      CreateUsagePlan: true

Resources:
  ...
  # resources created by SAM
  ServerlessApiKey: 
    Type: AWS::ApiGateway::ApiKey
    DependsOn:
      - ServerlessUsagePlan
    Properties:
      Enabled: true

  ServerlessUsagePlan:
    Type: AWS::ApiGateway::UsagePlan
    DependsOn:
      - MyApi
      - MyDifferentApi
    Properties:
      ApiStages:
        - ApiId: !Ref MyApi
          Stage: !Ref MyApi.Stage
        - ApiId: !Ref MyDifferentApi
          Stage: !Ref MyDifferentApi.Stage

  ServerlessUsagePlanKey: 
    Type: AWS::ApiGateway::UsagePlanKey
    Properties:
      KeyId: !Ref ServerlessApiKey
      UsagePlanId: !Ref ServerlessUsagePlan
      KeyType: API_KEY

Outputs:
  # Output added by SAM
  ServerlessKeyId:
    Description: "ID of the API Key"
    Value: !Ref ServerlessApiKey

[mvanbaak]

I would like to add a +1 to suggestion 1 to create one Usage Plan if the CreateUsagePlan: true is set in the Globals section, and create multiple if that config is set on an API.
Besides that I like the RFC.

[studds]

I like this, it would definitely work for our use case. It seems well thought out, and has reasonable defaults with the ability to override as necessary.

We'd not be impacted by shared vs individual usage plans, as our templates each only have one API. I like the flexibility of the proposal to be able to create a shared or individual usage plan, depending on where the option is specified. My only small concern there is that it could be a little bit counter-intuitive.

TBH, we'd be happy just to be able to require the API key without diving into swagger; we'd be happy to explicitly define the usage plan etc, especially as requirements there are likely to be very divergent. Would it be possible to use ApiKeyRequired: true without either of the other two options?

One final thought: usage plan and key names are very short, the generated names are often not too helpful, eg 'rfc-a-Serve-BDPXKE2ZILLS'. We've found that we need to specify them explicitly for them to be useful.

[praneetap]

Thanks for the input!
@studds ApiKeyRequired: true will do the same as today, it won't create UsagePlans or UsagePlanKeys or ApiKeys. This is to maintain backward compatibility.

[ShreyaGangishetty]

I have updated the RFC to be able to create a single Usage Plan or multiple Usage Plans based on the requirement. Please let us know your thoughts

[keetonian]

Released!