Authorizers: Support AuthorizationScopes

[keetonian]

Description:

This was brought up in Slack:

Starting to work on a PoC using the new authorizer features in SAM and already notice one huge shortcoming I didn't think about.
AuthorizationScopes - this would have been really powerful to include so I could define required scopes for authenticating tokens at the API level instead of inside the code.

This is also necessary for using access_tokens.

Docs: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html#cfn-apigateway-method-authorizationscopes

SAM should support AuthorizationScopes.

[brysontyrrell]

This was my thread in the channel. My proposal would look something like this:

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn: !Ref CognitoUserPoolArn
            OAuthScopes:
              - scope1
              - scope2

  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./src
      Handler: lambda.handler
      MemorySize: 1024
      Runtime: nodejs8.10
      Events:
        Root:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /
            Method: GET
            Auth:
              Authorizer: MyCognitoAuthorizer
              OAuthScopes:
                - scope3

This is a swagger doc from one of my templates to show what it looks like with scopes defined:

ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      EndpointConfiguration: EDGE

      DefinitionBody:
        swagger: 2.0
        info:
          title: !Ref AWS::StackName
        securityDefinitions:
          CognitoAuth:
            type: apiKey
            name: Authorization
            in: header
            x-amazon-apigateway-authtype: cognito_user_pools
            x-amazon-apigateway-authorizer:
              type: cognito_user_pools
              providerARNs:
                - !Ref CognitoUserPoolArn

        paths:
          "/messages":
            post:
              x-amazon-apigateway-integration:
                httpMethod: post
                type: aws_proxy
                uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${SendMessage.Arn}/invocations
              responses: {}
              security:
                - CognitoAuth:
                  - "rds-worker/send_message"

          "/errors":
            get:
              x-amazon-apigateway-integration:
                httpMethod: post
                type: aws_proxy
                uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Errors.Arn}/invocations
              responses: {}
              security:
                - CognitoAuth:
                  - "rds-worker/read_errors

Edit: Noticed a bad indent.

[keetonian]

Leaving this issue open for +1's and further comments. Happy to work with anyone that wants to implement this feature.

[mau-fyayc]

+1
I find it quite an important feature to use the full power of OAuth and Cognito.

[uokitomer]

Is there any plan to include this feature in the near future?

[klmz]

I can look into implementing this. The transformation to swagger is simple enough, although I'm not sure if there are other steps that need to be implemented.
In any case, what would be the expected behavior when only a scope is specified? Without an authorizer like this:

MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn: !Ref CognitoUserPoolArn
              OAuthScopes:
                - scope1
                - scope2

  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./src
      Handler: lambda.handler
      MemorySize: 1024
      Runtime: nodejs8.10
      Events:
        Root:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /
            Method: GET
            Auth:
              OAuthScopes:
                - scope3

I would propose choosing the default authorizer in this case.

[klmz]

I also want to propose calling it AuthorizationScopes instead of OAuthScopes since it is more consistent with the naming of the AWS::ApiGateway::Method in normal CloudFormation.
Or is it better to make the naming different to ensure there is no mix up for inexperienced users?

[keetonian]

@klmz Keeping the naming the same should be fine. I think the transformation into swagger + some supporting tests are all that are needed for this feature, correct me if I'm wrong.

[klmz]

Yes, that is what I figured. I got most of it working. Is there any documentation on what is expected in terms of tests? I saw some end-to-end test that will be needed, anything else?

[keetonian]

@klmz we don't have any docs on what is expected for tests, but I would recommend some end-to-end tests like you suggested, as well as some tests for the new swagger that is generated in https://github.com/awslabs/serverless-application-model/blob/develop/tests/swagger/test_swagger.py.

[brettstack]

I would propose choosing the default authorizer in this case.

This is correct. Looking forward to the PR!