Final Submission - Executable Tutorial: Deploying an API with a Custom Lambda Authorizer using Serverless

[oskstr]

Members

• Oskar Strömberg (oskstr@kth.se)

Proposal

I would like to create a tutorial for deploying (using serverless) a simple service protected by a Custom Lambda Authorizer.

• Create a simple Typescript service using an AWS Lambda function
• Create a Custom Lambda Authorizer (itself an AWS Lambda) - authorizing against a separate service
• Declare using serverless.yml that calls need to pass the authorizer to go through
• Deploy to AWS using serverless

When I have worked with this on a personal project I wasn't able to find anything on exactly this topic, they were mostly using JWT directly - which is fine when you're building something from scratch but wasn't possible in my case. I needed to validate API keys against a different service, but I still wanted the convenient caching provided by the Amazon API Gateway.

While it would probably look better and be more useful on Medium, I'll probably have to go with one of the browser platforms like Katacoda based on the grading criteria.

Question: Would it work if I create one version on Katacoda and one on Medium?

Submission For Feedback

I have opted to only do a version for Katacoda for now.

The tutorial can be found at katacoda.com/oskstr/scenarios/lambda-authorizer-with-serverless
and the repo can be found at oskstr/katacoda-scenarios.

Looking forward to feedback from @sfkwww as per #1162.

Executable Tutorial: Deploying an API with a Custom Lambda Authorizer using Serverless

Members

• Oskar Strömberg (oskstr@kth.se)

Proposal

I would like to create a tutorial for deploying (using serverless) a simple service protected by a Custom Lambda Authorizer.

• Create a simple Typescript service using an AWS Lambda function
• Create a Custom Lambda Authorizer (itself an AWS Lambda) - authorizing against a separate service
• Declare using serverless.yml that calls need to pass the authorizer to go through
• Deploy to AWS using serverless

When I have worked with this on a personal project I wasn't able to find anything on exactly this topic, they were mostly using JWT directly - which is fine when you're building something from scratch but wasn't possible in my case. I needed to validate API keys against a different service, but I still wanted the convenient caching provided by the Amazon API Gateway.

While it would probably look better and be more useful on Medium, I'll probably have to go with one of the browser platforms like Katacoda based on the grading criteria.

Question: Would it work if I create one version on Katacoda and one on Medium?

Submission For Feedback

I have opted to only do a version for Katacoda for now.

The tutorial can be found at katacoda.com/oskstr/scenarios/lambda-authorizer-with-serverless
and the repo can be found at oskstr/katacoda-scenarios.

Looking forward to feedback from @sfkwww as per #1162.

Final Submission

The location of the tutorial is still the same but I have made the following changes:

• 6c9ebab Change verbatim text to code blocks
• 084bc62 Format policy snippet as JSON
• 563582d Change from replace to append/insert
• aea9485 Fix typo
• ed6f7ec Add explanation to image
• f59c842 Add warning about error messages
• f1d6222 Explain bug where command isn't being run
• 7109af6 Make curl calls executable
• 64dda2c Explain which header we are looking for
• e0a040d Explain how to set up an AWS user
• 9c0e73a Add more spacing
• 2444cbf Remove space that caused graphical bug
• 85ad312 Increase expected time for scenario

Diff log: oskstr/katacoda-scenarios@756b829...85ad312

[sfkwww]

Feedback

Introduction

• (+) The introduction provides a clear explanation of the different components that the tutorial will use, ensuring that the user has enough background information before beginning the tutorial.
• (+) The project overview provides a nice outline of what the tutorial will cover which makes it easy to later understand how the steps are related to each other.

• (-) The image provided looks like a nice overview of the tutorial but without an explanation, it's mostly just confusing. Providing an explanation note underneath or something similar would be very helpful here.

Step 1

• (+) The setup is easy and straightforward, especially with the executable code snippets. They make it very easy to perform the commands and prevent accidental typos.

• (-) When installing serverless globally some errors are produced. While they don't appear to cause any harm, it would be nice to provide a note saying that it's ok to get errors, as users might get confused otherwise. Personally I was a bit confused when I first ran this command because of the errors, but since the rest of the steps worked out fine it seemed to be ok.

Step 2 & 3

• (+) The instructions are straightforward and the code is easy to understand and execute.

• (-) When running the curl request you sometimes have to click it twice for it to work properly, most likely a bug with Katacoda but could be worth writing a small note about it.

Step 4

• (+) How authorization can be handled is explained in a short and concise manner at the beginning of the step, with some examples of different alternatives that one can use.
• (+) The execution results of the different API calls are explained in an easy and understandable manner at the end.

• (-) The policy JSON example is not in a code block, which makes it a bit harder to read.
• (-) The different curl calls at the end would be more readable and easier to execute if they were in executable code snippets.

Step 5

• (+) The easter egg was unexpected and fun! The link could perhaps be a regular link instead of a shortened link since some users might not want to click on shortened URLs that might be malicious.

• (-) The AWS configuration instructions are a bit unclear and could be confusing for new AWS users. Consider giving a more detailed explanation on how to create the IAM user and where to get the AWS_ACCESS_KEY & AWS_SECRET_ACCESS_KEY.
• (-) The endpoints at the end could be placed in code snippets to make it easier to execute them.

Overall Feedback

• (+) The language is very fun and engaging. I found myself enjoying reading through each step and experimenting with new material.
• (+) Most steps are easy to follow and teach the user about the different components in a brief and concise way. Overall I had no trouble following the instructions and executing the tutorial.

• (-) Most code snippets seem to replace the entire file when using the copy to editor Katacoda function. Instead of using replace, appending code to the file would shorten the code snippets making the tutorial code changes more readable. To make this change simply change the data target from replace to append

[oskstr]

Thanks for the fast response @sfkwww ! I'll have a look at it soon 👍

[oskstr]

Thanks for some great feedback, @sfkwww !

Changes following feedback

The location of the tutorial is still the same but I have made the following changes:

• 6c9ebab Change verbatim text to code blocks
• 084bc62 Format policy snippet as JSON
• 563582d Change from replace to append/insert
• aea9485 Fix typo
• ed6f7ec Add explanation to image
• f59c842 Add warning about error messages
• f1d6222 Explain bug where command isn't being run
• 7109af6 Make curl calls executable
• 64dda2c Explain which header we are looking for
• e0a040d Explain how to set up an AWS user
• 9c0e73a Add more spacing
• 2444cbf Remove space that caused graphical bug
• 85ad312 Increase expected time for scenario

Diff log: oskstr/katacoda-scenarios@756b829...85ad312

[oskstr]

Sorry about the messy commit history. I forgot to rebase with 2021 after proposal.

[SophieHYe]

Thanks for the final tutorial submission. I am now merging your PR and we will grade your work based on the final version.

[oskstr]

@SophieHYe , just checking. You said you were merging my PR but didn't actually do it 😅

[SophieHYe]

Ah, sorry about that. Now it merged. 😅