The document discusses using Amazon API Gateway to implement serverless architectures. It provides examples of using API Gateway to add authentication, access S3 buckets, send emails, and implement fine-grained access control for DynamoDB. While API Gateway can implement some use cases entirely, custom code is often still needed. The document evaluates when API Gateway is a good fit and challenges associated with its use.

1. Funky Serverless Features at AWS
Doug Winter - Isotoma

2. Contents
Real-world examples of some serverless implementation patterns, using API
Gateway primarily. In particular:
■ Introduction: authentication for a serverless project for the BBC
■ Quick intro to API Gateway as a serverless toolkit
■ Example access to other serverless services using API Gateway
● S3
● Email
● DynamoDB
■ How to practically use API Gateway yourself
■ Spotting candidates for this approach

3. Me
■ Nearly 30 years professional experience
■ Dev, Ops, DevOps, Architecture, Consultancy, Strategy,
Stuff
■ Ran engineering for Online Operations at the BBC in
2000/2001
■ CTO of a dotcom during the boom (and bust)
■ Owner/Director of Isotoma since 2004
■ Still write code, mostly Python, Go and Typescript

4. Characteristics of "serverless"
1. No cost when no use, cost scales with usage
2. Provisioning decisions taken by the cloud provider
3. "Infinite" scaling capacity
Not really anything to do with servers or the lack thereof, or
FaaS

5. IDT Cloud

6. IDT Cloud Introduction
■ IDT = In Depth Toolkit ¯_(ツ)_/¯
■ BBC News journalists often need to embed charts and
other visualisations in their output
■ An existing tool, IDT, provided charting services for
journalists, using the previous generation of BBC News
delivery infrastructure, Forge, which was PHP

7. IDT Cloud Introduction
■ BBC News are moving to AWS and all services should now
be delivered from with AWS services
■ This was an opportunity to entirely rewrite IDT and make
it fit for purpose
■ We had (largely) complete freedom to choose
implementation technologies
■ The new version is called IDT Cloud

8. Particular challenges
■ BBC News audience is approx 500M people globally, in
many languages, which is quite a lot
■ Must function on a wide range of devices, including some
old phones and in both landscape and portrait
■ Which is hard for charts!
■ Lots of choices for how to fit charts onto small devices -
but often the choices depend on the size, language and
aspect ratio
■ Kind of high traffic levels sometimes

9. Architecture
Lots of moving parts
■ Datastore for chart origination material (JSON blobs
describing charts, plus ancillary artifacts like background
images)
■ Integration with other BBC News systems, including
several generations of CMS
■ Editorial interface for journalists to interact with their
charts
■ Rendering system to deliver charts in every output format
needed

10. The serverless bit

11. Authentication
■ We wanted a private application for authorized BBC Users
only
■ BBC Users are authorized by either:
● a) having a valid client X509 certificate in their
browser, or
● b) Logging into the BBC Login single sign-on system
■ API Gateway is on the public internet
■ API Gateway can't see client certs (this sucks by the way,
AWS should support X509 PKI everywhere)

12. The Authentication Proxy
Our solution:
1. require AWS_IAM authentication for the API,
● all requests to it must be signed
2. Send users via a proxy, running on EC2, that examines the
client certificate. If it is not present it goes through the
login ceremony via BBC Login
3. Authenticated users are proxied to API Gateway with
signed requests

13. Not actually overkill
Seems like an overcomplex solution
- but the proxy is entirely reusable, providing a standard way
for new applications to be delivered via API Gateway with no
authentication code needed.

14. API Gateway

15. Common perception of API Gateway
"How I get my lambda function on a URL"

16. What API Gateway really is
■ URL mapping
■ Access Control and Management
■ Validation & Error Handling
■ Request & Response Transformation
■ Access to AWS backing services
■ A bunch of other useful stuff (throttling, API keys etc.)

17. Core Anti-feature
■ Really, really, really, really annoying to configure and deploy. Even more
than usual.
■ Can be done with CloudFormation but it is bad (even for CloudFormation)
■ Can be done with Swagger, but you will need to write some tooling
■ Supported by other tools:
● SAM
● serverless.com
● But they only provide basic functionality

19. How not to do a UI

20. Resources

21. Stages

22. Use cases

23. Decoupled authentication

24. Decoupled authentication
■ Authentication is bad
● Authenticating API requests is expensive
● For microservice-based architectures it means all services need
to apply authentication, so authentication changes mean
everything needs releasing
■ Instead, authenticate within API Gateway
■ Services can assume requests are authenticated
■ For bonus points, use Cognito for authentication and you can hand off
almost everything

25. OWASP 2017
Also...

26. Supported schemes
Lambda Function
■ Bring your own authorizer
■ Called on each request
■ You examine the request to
determine if authenticated
■ Returns:
● A principal identifier
● An IAM Policy
Cognito User Pool
■ Calling client authenticates with
Cognito
■ Include the JWT Token as the
Authorization header

27. Principals & permissions
■ The principal provided is available in the context for your integrations (we
have used a custom header to deliver the principal ID)
■ Associated IAM Policies can be used to secure back-end services
■ Using the "invoke with caller credentials" option in the integration means
the IAM Policies you deliver in the authorizer are used directly
■ With Cognito, users can be placed into groups and the groups provide IAM
Roles, which specify the policies used
■ Together this means you can entirely outsource your authentication,
authorization and user management

28. Benefits
■ Federation - Cognito can federate to lots of identity providers
■ Reduced developer friction - dev environments can ignore authentication
for the most part
■ Security - it is easy to screw up roll-your-own authentication
■ Robustness - This is easily one of the most error-prone parts of a
codebase, so getting rid of it is a good thing
■ Agility - Apply a common authentication layer across heterogenous
underlying serverless and microservices

29. Static files

30. Static files
1. Web applications need static files
a. Initial HTML page
b. Javascript & CSS
c. Images etc.
2. You may wish to deliver these on URLs alongside your API
3. You can do this with API Gateway

31. Static files
■ Super simple use case
■ Two options for the Integration
● HTTP integration to the s3 HTTP endpoint
● Service integration to S3 "as a service"
■ Using the service integration allows us to access objects
in private buckets

32. Static files

33. S3 Blobs

34. S3 Blobs
1. Direct access to S3 from React etc. is a common
requirement, for both reading and writing
2. We can do this entirely in API Gateway

35. S3 Blobs
■ For the IDT project we need to store and retrieve
configuration for charts, which are just JSON blobs
■ All authorized users can load and store all blobs, so there
are no complex authorization rules
■ API Gateway can do this without the need for any
Lambda

36. PUTing

37. Sending email

38. Sending email
1. Sending Email in response to a user request means you
have to constrain at least one of:
a. To address
b. Subject and Body
2. Or it can be used as a spam factory
3. So you can't just hand out SES Access Key and Secret to
your React application (doh)
4. API Gateway to the rescue

39. Simple Email Service (SES)
■ SES is ancient and has a dreadful API
■ This is mostly hidden from you because you either use:
● the SES support in the AWS SDK (which is fine), or
● the SMTP API, which is... SMTP
■ However under the hood it is seriously old skool
■ This is a good (but simple) example of how much heavy
lifting API Gateway can do

40. The SES API
From: sender@isotoma.com
To: president@whitehouse.gov
Subject: Hello Mr President
How are you?
Content-Type: application/x-www-form-urlencoded
Action=SendRawEmail&Source=sender%40isotoma.com&Destin
ations.member.1=president%40whitehouse.gov&RawMessage.
Data=Subject%3A+Hello+Mr+President%0A%0AHow+are+you%3F
%0A'
Serialised as x-www-form-urlencoded rather than JSON or XML.
Also it is generally kind of confusing
Here is a real example that works though:

41. The API we want to provide
Model schema specified in JSON
schema
Input is validated against this
automatically
Then allows us to access named
parts of the input in processing

42. Integration with SES
Set up the integration to
SES

43. Transformations
■ Uses the Velocity templating language
■ Velocity is kind of terrible
■ all templating languages are terrible
■ but less terrible than writing code. generally.
■ there are loads of useful functions and it is actually
pretty good
■ We use "stage variables" to store constants

44. The template
Action=SendRawEmail&Source=$util.urlEncode($stageVariabl
es.SignupSource)&Destinations.member.1=$util.urlEncode($
stageVariables.SignupRecipient)&RawMessage.Data=$util.ur
lEncode($util.base64Encode("Subject:
$input.path('$.subject')
$input.path('$.body')"))

45. DynamoDB
Fine Grained Access Control

46. The feature
IAM Policies can include
conditions restricting access
to DynamoDB tables to rows
where the HASH key matches
defined strings.
We can use the authenticated
user's identifier here, so
restricting a user to only their
rows in the database.

47. How to use it
1. Use cognito
2. Add an IAM Policy like this
3. Use "invoke with caller credentials"
4. Magic
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:Query"
],
"Resource": [
"table_arn"
],
"Condition": {
"ForAllValues:StringEquals": {
"dynamodb:LeadingKeys": [
"${cognito-
identity.amazonaws.com:sub}"
]
}
}
}
]
}

48. Using API Gateway

49. Using API Gateway
1. Cloudformation does have resources to
cover API Gateway (see right)
2. You really don't want to use these!
3. Swagger (OpenAPI) is better
4. BUT it has no concept of variables
5. ALSO CloudFormation tooling for Swagger
is kind of lame

50. Workflow
1. Mock out and test features in the console
2. Export the Swagger from the stage
3. Replace hard coded literals with variables
4. Extend the Swagger to cover your whole API
5. Write something to do configuration management for you
6. Put the file in an S3 bucket
7. Run CloudFormation
8. Write something to update the API by calling the API Gateway API

53. Spotting candidates

54. Is this even a good idea?
I think these techniques deliver benefits:
1. Less code
2. Outsource and commoditise
3. Design "with the grain" of the underlying services
4. Enforce simplicity
5. Actual API-first design
But they can be challenging to exploit

55. Spotting candidates
■ Application code is generally "get a request, do some
stuff, access some backing services, return a response"
■ Only a subset can be implemented entirely in API
Gateway:
● No loops
● Single input and single output transformation

56. The challenge
■ Few developers have an in depth knowledge of more than
a couple of AWS services
■ All of the examples I've shown here can instead be
implemented in custom code
■ Organizationally it might be easier to implement in
custom code...
■ ...even if the product is worse
■ And the tooling is, at best, patchy

57. Handling change
■ Replacing these things with Lambda calls is easy
■ Your API remains stable
■ So stubbing out an API early on with simple S3 access
etc. can be a good way to get moving
■ Don't worry if you will later need more complexity

58. October 17, 2018

59. October 17, 2018
Thank You Supporters

60. October 17, 2018
Meet me in the Slack channel for Q&A
bit.ly/addo-slack