DEV Community: Kayes Islam

Integrating OpenID Connect to your application stack (Asp.Net Core, Angular)

Kayes Islam — Tue, 29 Jun 2021 11:17:13 +0000

Today I wanted to write about how you can integrate OpenID Connect JWT token based authentication in your application stack, Asp.net Core Web API for the back-end and Angular for the front-end. Even if you don't use these technologies, I hope the article will give you some idea of the steps involved.

Most code I have included here comes from the github repo that I have reference at the end of the article.

JWT

JWT (JSON Web Token) is a critical piece in OpenID Connect. The client application (such as an Angular SPA), obtains a JWT access token from the authentication server using one of the pre-defined OAuth flows. It then passes the token with requests to the Resource Server (such as Asp.net Core Web API). The resource server evaluates the token and accepts/rejects the request based on it. Given the importance of JWT, Let's start with a quick introduction of JWT tokens. The JWT Introduction explains it very well, but here are some of the points as summary.

JWT is a self contained token, meaning it carries it's own signature to verify it's validity. This means that to validate a JWT token, the resource server does not need to query the Auth server asking if the token is valid. It just needs to validate the signature that is carried within the token. Here's a sample JWT token:

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0ZWFSLVJTS2QwdHhXejZSWnR2TVROazByVkVncFR2Qnd0QlhLbGlKMVF3In0.eyJleHAiOjE2MjQzNzYwODIsImlhdCI6MTYyNDM3NTQ4MiwiYXV0aF90aW1lIjoxNjI0Mzc0Mjc2LCJqdGkiOiJmZjQ2YzJmNy1hNjkxLTQzNTQtOTUzNC1lODY4YTA4YzkzNGQiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvQXV0aERlbW9SZWFsbSIsImF1ZCI6ImF1dGgtZGVtby13ZWItYXBpIiwic3ViIjoiYjEyMWEzNDMtYTk1OC00MTJhLTg3YzAtNzFhNGE3NmRmNTBhIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYXV0aC1kZW1vLXNwYSIsIm5vbmNlIjoiNjgzNTY3YWVmZjk5NDcyYmRlNzJiZDgyMDk4MGE0NTY2N3RSQWRrMTgiLCJzZXNzaW9uX3N0YXRlIjoiNTMyZDExZWEtZTU1My00Mjc2LWFiMDItYThkNjRjOWU2OWE5IiwiYWNyIjoiMCIsInNjb3BlIjoib3BlbmlkIGVtYWlsIHByb2ZpbGUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwibmFtZSI6IkRlbW8gVXNlciIsInByZWZlcnJlZF91c2VybmFtZSI6ImRlbW8udXNlciIsImdpdmVuX25hbWUiOiJEZW1vIiwiZmFtaWx5X25hbWUiOiJVc2VyIiwiZW1haWwiOiJkZW1vLnVzZXJAZW1haWwuY29tIn0.U3qv-ujxq5axhLYeEON4ofDmd2CH_RLDhY3KBK8gNJkAYIx3dhCMI-4mNjIPxkpXjXdF1Ci7fX2zM9AN8_d2nVhYQB7dusdvjxRAfzu_IzAPhl4hZXNxEIJYd2f6KBVU_gnSKgJyEi5LJ89blYIllbyN5KfPke_DIZgL3CfhUiAGqE5eW7UY1weOTjcGsV29u5vv_FcONmk2z_uTDH9qN7g-xTVkEv3tr-u7osK4T8fwoxWA62TlTyxefr_ZsDDyy3nGCL_YhDTdzqASs5_Xc60vaP0x3BmdAHXM4-p0xgei6qOv9g4FYy_3u1DUAnoXY6g-Nls-MVs1K18f8H2ZfA

JWT tokens are separated into three parts by dots (.):

JWT Header

The first part is the JWT header. This is just Base64Url encoded, not encrypted, which means anyone can decode it, for example using an online tool such as this one. Therefore, it does not contain any secret, which is important to note. If you put the first part of the token (separated by .) in the tool and decode you get the following JSON:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "4eaR-RSKd0txWz6RZtvMTNk0rVEgpTvBwtBXKliJ1Qw"
}

Other than the obvious typ (type) JWT, the header tells us that the token is signed using RS256 algorithm and a kid (Key ID) of the token. Both of these come into play when we need to validate the token with the signature. More on this below.

JWT Payload

The second part of the JWT token is the payload which is also just Base64Url encoded, which means anyone can decode it. (Online decoding tool). If you copy the 2nd part of the token above decode it you get the following JSON payload:

{
  "exp": 1624376082,
  "iat": 1624375482,
  "auth_time": 1624374276,
  "jti": "ff46c2f7-a691-4354-9534-e868a08c934d",
  "iss": "http://localhost:8080/auth/realms/AuthDemoRealm",
  "aud": "auth-demo-web-api",
  "sub": "b121a343-a958-412a-87c0-71a4a76df50a",
  "typ": "Bearer",
  "azp": "auth-demo-spa",
  "nonce": "683567aeff99472bde72bd820980a45667tRAdk18",
  "session_state": "532d11ea-e553-4276-ab02-a8d64c9e69a9",
  "acr": "0",
  "scope": "openid email profile",
  "email_verified": true,
  "name": "Demo User",
  "preferred_username": "demo.user",
  "given_name": "Demo",
  "family_name": "User",
  "email": "demo.user@email.com"
}

Each of these properties of the payload is called claims. There are some standard claims such as iss (issuer), aud (audience) etc. Some of these are mandatory claims such as the exp (expiry) which must be present. I usually go to the JWT Spec here to look up the standard claims and what they mean, the document is easy to read and understand.

Other than the standard claims the payload may have custom claims. In the above example email_verified and preferred_username are such custom claims handing out by Keycloak with the out of the box configuration.

Important to note here again, there are no secrets in the payload. But for an access token, it should contain enough information for the resource owner (Web API backend in our case) to evaluate if access to data should be granted.

The scope claim is a special one that needs a bit of attention. A scope is a grouping claims and it's requested by the client app. In the example above given_name and family_name claims are present because the client app requested the profile scope. Just because the client requested a scope doesn't mean the auth server will provide the claims for that scope in the payload, it depends on many factors. For example the scope maybe configured on the authorisation server in a way that it requires to present consent screen to the user and will only be provided if user has given consent. The scope claim in the JWT payload basically tells us which scopes have been provided in the payload, in this case openid (which is the standard scope for OpenID Connect, must be preset), email and profile.

It's a very common practice to have custom resource oriented scopes. Let's elaborate a little further with an example. Let's say you are working with an Auth server that logs in tradies to use your application. The auth server provides a trade_license scope, which adds claims trade_license_number and trade_license_expiry to the token. When the clien app requests for the trade_license scope, user is asked during login:

This application wants to access your trade license information. Do you accept? [yes | no].

If user selects no, the trade_license scope is not provided as part of the scope claim, trade_license_number and trade_license_expiry claims are not provided with the payload. If user answers yes these claims are provided.

In asp.net core you can enable policy based authentication allowing you to check wether a scope exists or if a claim has an expected value. More on that later.

JWT Signature

The third part of the JWT token is the signature which ensures that the token has originated from the auth server and it has not been tinkered with. The signature is constructed with the first two parts and a secret. As a result the generated signature is only valid for the header and payload data of the token, which ensures that no one can change the content of the header and payload. The use of secret to create the token ensures that only the server can generate a signature. There are two types of algorithms for creating the token signature, symetric and asymetric.

Symetric Algorithms

The symetric algorithoms use a secret, along with the first two parts of the token to generate the signature. To validate the token, the receiver of the token would then need to use the same secret. The fact that the secret has to be known by the auth server as well as the resource server poses a few limitations such as:

Automatically changing the secret is not easy. If the secret is exposed and you need to change it, you'd have to do that on all the resource servers.
You cant use the secret on "untrusted" applications where the source code is open or can easily be reversed-engineered, such as a browser app or a mobile app.

Asymetric Algorithms

Because of the limitations above, usually asymatric algorithoms are used to create JWT signature. Asymetric algorithms use a private key to sign the token, and exposes a public key that can be used to verify the token. So the private key used to create the token is never exposed. The public key is available to retrieve from an .well-known endpoint called jwks_uri. Since the resource server is not dependent on a shared key, this enables a key-rotation mechanism, ensuring that the private-public keys are rotated regularly to ensure extra security against key leaks.

Resource Server - Validating the Token

Now let's see what we need to do to validate that token we've been provided on the resource server. You'll need to do these steps below:

Check to see if the token has been expired.
Check the iss (issuer) claim to ensure that the token has been issued by the right auth server.
(Optional) Check the aud (audience) claim to ensure that the resource server is one of the audiences.
Check to see if the token has a valid signature.
1. Download the public key for from jwks_uri.
2. Validate the token with the public key.
(Optional) Check required scopes are present.

When using Asp.net core (3.1/5) we're just going to use the provided middleware that does it all. This is how you can configure it as a minimum:

services
    .AddAuthentication()
    .AddJwtBearer(x =>
    {
        x.MetadataAddress = "http://keycloak:8080/auth/realms/AuthDemoRealm/.well-known/openid-configuration";
        x.TokenValidationParameters = new TokenValidationParameters
        {
            ValidAudience = "auth-demo-web-api"                    
        };
    });

And that's it! MetadataAddress is set to the .well-known endpoint. The middleware can retrieve the following required properties from the .well-known edn-point:

The issuer
The jwks_uri from where it needs retrieve the public key to validate the token signature.

Now that you have a valid token configuration you can configure claims based authorisation for default authorisation policy:

services.AddAuthorization(o =>
{
    o.DefaultPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .RequireClaim("email_verified", "true")
        .Build();
});

What we are saying there in effect is that the default Authorize attribute on a controller or action will return unauthorised if the token doesn't have the claim email_verified with value true. Here's an example of a controller that's using the default plicy to authorise:

[ApiController]
[Route("[controller]")]
[Authorize]
public class EamilController : ControllerBase
{
    // ...
}

You could have different named policies as well along with the default policy:

services.AddAuthorization(o =>
{
    o.DefaultPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .RequireClaim("email_verified", "true")
        .Build();

    var tradieAuthorizerPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .RequireClaim("trade_license_number")
        .Build();
    o.AddPolicy("TradieOnly", tradieAuthorizerPolicy);
});

You could then apply the named policy by setting Policy value of the Authorization attribute. In the example below anyone can post a job, but only tradies, with a trade_license_number as per the policy configuration above, are authorised to apply:

[ApiController]
[Route("[controller]")]
[Authorize()]
public class JobsController : ControllerBase
{
    [Authorize( Policy = "TradieOnly")]
    public async Task Apply(JobApplication jobApplication)
    {
        // ...
    }

    public async Task PostJob(Job job)
    {
        // ...
    }
}

Checkout the Authorisation section for Asp.net core for more information on claims based and policy based authorisation.

Client App - Obtaining the Token

There are a number of flows defined in OAuth2 to obtain the access token. For untrusted clients it's Authorisation Code Flow with Proof Key for Code Exchange (PKCE). In a nutshell these are the steps from when user clicks login button to obtaining the access token:

Client app creates a random Code Verifier and a Code Challenge hash from it.
Redirects to the auth server's authorisation endpoint. This endpoint is usually published in .well-known JSON for the auth server. The client app passes the following parameters as a minimum with the redirect:
- Redirect URL: The URL where the auth server will redirect back to once the authorisation is complete (successful or failed)
- Code Challenge: This is part of the PKCE flow. Later we pass in the code verifier for the challenge when we request access code. see below.
The server performs N number of steps as required to authenticate the user. These steps usually include:
- Username+password prompt
- Password change prompt when password has expired
- Accept new terms and conditions prompt
- Setting up some another MFA, etc
At the end of it all, once the user is authorized, the server redirects back to the Redirect URL we passed in Step 2. The server provides an Authorisation Code with the redirect, which is a one time code that can be used by the client app to obtain the Access Token.
The client app requests for the access token at the /token endpoint using the provided Authorization Code and the Code Verifier created in step 1. The endpoint to obtain the token is usually published in the .well-known JSON.

If all is successful, the client app will have an access token that it can be pass in with the authorization header for restricted resources.

Even tough all the steps above maybe easy to write by yourself, I recommend against it. My suggestion is that you use a client library that does these steps for you. I always prefer using code written by the experts, well tested and possibly improved over time based on other users experiences, specially when it comes to security. On the same note avoid libraries that are not quite OpenID Connect compatible, not easy to configure or requires you to do some steps manually. For example the MSAL library, avoid if you are implementing an OIDC client.

If you are using Angular, I highly recommend using angular-auth-oidc-client npm package. The library is OpenID Certified. Below is my client configuration and angular-auth-oidc-client does all of the above steps to ensure the the access token is available:

oidcConfigService.withConfig({
  authWellknownEndpoint: 'http://localhost:8080/auth/realms/AuthDemoRealm/.well-known/openid-configuration',
  redirectUrl: `${window.location.origin}/home`,
  clientId: 'auth-demo-spa',
  scope: 'openid profile email',
  responseType: 'code',
  triggerAuthorizationResultEvent: true,
  postLogoutRedirectUri: `${window.location.origin}/home`,
  startCheckSession: false,
  postLoginRoute: '',
  unauthorizedRoute: '/unauthorized',
  logLevel: LogLevel.Debug
});

The first 5 lines in the configuration are really the most important ones:

authWellKnownEndpoint: We're setting the .well-known URI here. The client library should know the following important endpoints from here:
- authorisation URL where it should redirect to to start the auth process
- Token endpoint where it can request the access token using the authorisation code (at the end of a successful flow).
redirectUrl: The URL where the auth server will redirect back to once authentication is successful. Usually you need to configure this on the Auth server as well, otherwise you'll get an error. clientId: You must configure a client on the auth server and pass in the configured client's client-id here.
scope: Scopes requested. You must have openid for OpenID Connect claims.
responseType: Should be set to code for Authorisation Code Flow.

Below are my login() and logout() methods hooked to the login/logout buttons.

login() {
  this.oidcSecurityService.authorize();
}

logout() {
  this.oidcSecurityService.logoff();
}

The library ensures that the access code is refreshed using refresh token automatically. Below is the code that gets the access token that is already available if the user has logged in:

let apiUrl = `${environment.baseApiUrl}/weatherforecast`;
let accessToken = this.oidcSecurityService.getToken();
let headers = {};
if(accessToken)
  headers['authorization'] = `Bearer ${accessToken}`;
this.data = await this.httpClient
  .get(apiUrl, {
    headers: headers
  })
  .pipe(take(1))
  .toPromise();

Authentication Responsibility Separation

Developing your application layers to work with OpenID Connect as in the example above means that you are separating the authentication responsibility from your application code. For example, if you have configured Azure B2C for your auth provider, you can just change the configuration on your asp.net core app:

services
    .AddAuthentication()
    .AddJwtBearer(x =>
    {
        x.MetadataAddress = "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration";
        x.TokenValidationParameters = new TokenValidationParameters
        {
            ValidAudience = "auth-demo-web-api"                    
        };
    });

... and your Angular app as:

oidcConfigService.withConfig({
  authWellknownEndpoint: 'https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration',
  redirectUrl: `${window.location.origin}/home`, // need to configure
  clientId: 'auth-demo-spa', // need to configure
  scope: 'openid profile email',
  responseType: 'code',
  triggerAuthorizationResultEvent: true,
  postLogoutRedirectUri: `${window.location.origin}/home`,
  startCheckSession: false,
  postLoginRoute: '',
  unauthorizedRoute: '/unauthorized',
  logLevel: LogLevel.Debug
});

... and it now works with Microsoft Login. If want to use AWS Cognito as your auth provider, set-up a user-pool, find out how to get the .well-known endpoint, configure the server and the client and you're good to go.

Conclusion

There are a number of good libraries out there to help you integrate the authentication mechanism for whatever framework you are using and you should resort to these libraries to do the heavy lifting for you. Because the last thing you want is to leave a security whole trying to write it all by yourself. Oh and stay away from MSAL.

Source Code

Here's the github repo from one of my earlier posts that has Keycloak as auth server, Asp.net Core Web API as resource server and Angular client app. This should give you a starting point if you would like to play with even some other auth server configurations:
Kayes-Islam / keycloak-demo

Keycloak - highly customisable auth server

Kayes Islam — Tue, 15 Jun 2021 11:01:06 +0000

I have recently been working with Keycloak as an identity solution for our project. Keycloak is an open source auth server written in Java distributed with Apache 2 license. In the past I have worked with Azure B2C, AWS Cognito and Identity Server 4. Compared with those, even though some are in different categories, I have been quite impressed with Keycloak. It has a good set of documentation and customisation options available making it suitable for any greenfield project as well as an existing application where you feel the need to upgrade your old authentication mechanism to Open ID Connect (OIDC).

DEMO

I've put together a demo that you can run with docker compose so that you can try out the features.

Get the source from here: Kayes-Islam / keycloak-demo
Run docker compose up --build.

This exposes three services, Keycloak on port 8080, and Angular SPA on port 4200 and an asp.net core web-api on 5000. Note that the Keycloak service takes half a minute or so to get up an running so wait for it to start up.

Open up the client app at http://localhost:4200. Click the Call API button without logging in and you'll see the web-api returning 401 un-authorized error. But if you login using the demo account below and then click "Call API" you'll see successful response with JSON data.
Demo User:
U: demo.user
P: P@ssw0rd

NOTE: If you are having an issue logging in check the console logs from the SPA. It should have an error entry that says "iat time too far in the past". "iat" is issued at time. This happens when your container's time is not in sync with your host machines time. This is an issue on WSL/WSL2 on windows, specially if you have a laptop that is set to sleep after inactivity, because when windows wakes up, it doesn't re-sync the time on the WSL.
FIX: Open WSL console on windows then run hwclock -s.

Features

Now that you've got a demo up and running, let's talk about a few reasons I would recommend anyone to consider Keycloak as an auth solution.

Easy to use admin portal

Keycloak has a great admin portal that is easy to configure out of the box. If you are running the demo, open up http://localhost:8080 and login as admin user to have a look around:
U: admin
P: admin

Here are a few screenshots of how I have configured the client-app:

Customizable Themes

From sing-up page to admin portal, you can customize pretty much any part of the UI using custom themes. Themes are developed using Freemarker Templates and it's all documented here.

Extensible with Service Provider Interfaces (SPIs)

Everything in Keycloak has been implemented using injectable providers. You can register custom implementations of the provider interfaces in Java, drop the jar file in the deployments directory and it's available to be configured. There are many extensible SPIs available in Keycloak, but below are two of the most important one's in my opinion:

Storage SPI

Do you have an existing user database that does not currently have OpenID Connect capabilities? Keycloaks User Storage SPI allows you to extend the storage and retrieval of user data. You basically extend the UserStorageProvider class and implement a bunch of interfaces in Java with methods such as getUserById(), isValid() etc. The benefits you get is an OIDC solution on top of your existing infrastructure, with all the capabilities that come with it such as OAuth2, discovery, user registration, client registration, account management, admin portal etc just to name a few. Here are the docs. I have recently worked on such a project to create a Storage SPI for existing user database and it works very well.

Authentication SPI

Using the authentication SPI you can create a custom challenge, add an extra authentication step, or replace the entire flow if that's what your requirement is. Maybe you are creating an auth solution is for the tradies. So when users sign up, you want them to enter a their trade license number. Maybe you want to validate the trade license every-time they log in to ensure it's not expired. You can implement all that using a custom Authentication SPI and configure it as part of the flows for your realm. See here for more.

LDAP and Kerberos integration

Although I haven't tried these features yet, they look really good on the documentation. These stood out to me at first glance because I have worked with some applications in the past that rely on Active Directory for authentication. Keycloak comes with an LDAP provider which is just an implementation of User Storage SPI. Therefore when configured can it retrieve user information or validate user credentials with Active Directory. See here for more info.

Keycloak also allows you to configure Kerberos authentication. Note that both LDAP and Kerberos integration are separate pieces, you can configure only one or both. This let's Keycloak deal with LDAP/Kerberos hand-shake providing an OIDC solution on top. I think this is a great separation to have since it frees your application, the resource server (back-end) and the client app (front-end), to be developed against the OIDC standard. That way you can just plug in the auth server. You may have one deployment of your application configured with your clients LDAP running in intranet with Active Directory, another perhaps deployed on cloud using social login, and another maybe with a different auth provider all together B2C/Cognito/Auth0. More info on Kerberos integration.

Configurable with a wide variety of databases

Since Keycloak works on top of JDBC, it can be configured to use any database that has JDBC driver, which is a wide range of databases, including Postgresql, SQL Server and MySql.

Authorisation services

In addition to the standards based protocols, Keycloak provides a number of additional features and one of these is authorisation services. It gives you fine grained control on permissions that can be allocated on resources from the admin console. These permissions are exposed to the resource server as a set of RESTful APIs. Docs here.

Account Management Console

Keycloak has a built in account management console that can be accessed by every logged in user. You could redirect users to their account management console from the client application where they can update their profile information, change password, check session history etc.

Having Keycloak provide the account management functionality is great since the OIDC provider is the custodian of this information. Like all other user interface elements in Keycloak, you can customise the Account Management Console anyway you like.

Support for wide range of external Identity Providers

If you want to provide users options to login with the popular platforms such as Facebook, GitHub etc, Keycloak supports a wide range of external identity providers including any provider that supports OpenID Connect.

Conclusion

So in conclusion I would highly recommend you check out Keycloak for the following project types:

You are creating a new application and you need an identity solution.
You have an existing application with and existing users database that is not OAuth2 or OpenID Connect and you'd like to create an OpenID Connect solution on top of the existing database.
You want to create a multi-tenant application. Multi-tenancy can be achieved via realms or groups, based on your requirements.
You host different instances of you application and would like to provide different types of Authentication for these instances based on your client requirements, eg. one with custom Storage SPI reading/writing to/from existing database, one with federated login with Microsoft and Google, One with simple username and password based authentication, etc.
You need to provide windows integrated or Active Directory based authentication.

AWS Cognito Hosted UI cannot be customised!

Kayes Islam — Thu, 03 Jun 2021 14:06:42 +0000

I'm currently investigating which auth provider I should use for my new web-api project. The requirements are:

We need an OIDC solution with Authorization Code Flow with PKCE as we will have third party client applications (SPA/Mobile) developed by external vendors.
We need to give users options to login using an existing external OIDC provider.

These are quite a generic set of requirements that are commonly available in most OIDC providers. It was also quite easy to set-up in AWS Cognito as I expected. After everything is configured my login page looks like below:

The only problem is... you can't customize the UI. You can change some aspects, but only a handful of styles and colours (see here). But what if you want to change the text "Sign in with your corporate ID". As it stands today, you can't.

The screenshot above is what AWS calls the "Hosted UI". If you are doing a Authorization Code Flow with PKCE then you need a hosted UI where the client application can redirect to. And if you're using a hosted UI 90% of the time you'd like to theme it to suite your brand needs. In fact, other than some demo application, I think any hosted UI by the OIDC providers should be themable.

Azure B2C is superior in this regard, they allow ways to fully customize your hosted pages. See here for more information.information.

So if you're considering AWS Cognito for an identity solution and plan to use standard OIDC flows for public apps, keep that in mind.

Serverless Microservices in Asp.net with AWS API Gateway

Kayes Islam — Wed, 02 Jun 2021 08:43:52 +0000

For the project I am currently working on, I have been introduced to a whole array of services provided by AWS. We are going to embark on creating serverless Web APIs in AWS Lambda and Api Gateway. There are a few ways to achieve this and we needed to evaluate which way would work the best for our solution.

Lambda Functions

One of the AWS serverless project templates provided by Amazon.Lambda.Templates has straight up lambda functions written in C# like this:

public class Functions
{
    public APIGatewayProxyResponse Get(
        APIGatewayProxyRequest request,
        ILambdaContext context
    )
    {
        context.Logger.LogLine("Get Request\n");
        var response = new APIGatewayProxyResponse
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = "Hello AWS Serverless",
            Headers = new Dictionary<string, string>
            {
                { "Content-Type", "text/plain"}
            }
        };


        return response;
    }
}

This is then put together with a SAM template file to define the AWS API Gateway:

 "GetLambda": {
   "Type": "AWS::Serverless::Function",
   "Properties": {
     "Handler": "AwsServerless.Lambda::AwsServerless.Lambda.Functions::Get",
     "Runtime": "dotnetcore3.1",
     "CodeUri": "",
     "MemorySize": 256,
     "Timeout": 30,
     "Role": null,
     "Policies": [
       "AWSLambdaBasicExecutionRole"
     ],
     "Events": {
       "RootGet": {
         "Type": "Api",
         "Properties": {
           "Path": "/",
           "Method": "GET"
         }
       }
     }
   }
 }

This creates an API endpoint that invokes the Get() method of our Function class when a GET request event occurs on our API's path "/".
For local development, it comes with a Mock Lambda Test Tool. So if you hit F5 on your Visual Studio it opens this on localhost:5050:

The tool forwards the request to the lambda so that it could be executed/debugged with test JSON data in the local development environment. You can also invoke the tool from the command line without the UI and pass in a payload file.
One thing to say here is that I'm quite unimpressed that there's no way to debug the lambda as an API service so that requests to a localhost:port endpoint are forwarded to the designated lambda. As a full stack developer, one of the common workflows for me is to open the API project in Visual Studio, open the client app project in VS Code and run the entire stack together. I didn't easily find any way to do that with a lambda project for .net. There's step through debugging available using AWS provided sam command line tool for nodejs, python and golang, but the documentation is missing for .net.
Another issue here is that there's a lot of boilerplate code that we will need to put together for services we take for granted out of the box when we start-up a basic asp.net core project - CORS, JWT Auth, Authorization, HTTPS Redirection, Model Binding. None of this is present here. Sure how hard is it to hook it up together in a base class, but still it's work that needs to be done here.
Using the lambda template straight out of the box also means your code base is strongly tied to AWS Lambda, not platform agnostic.

Asp.net Core

Another project template that is provided by the Amazon.Lambda.Templates is an Asp.net core project configured to run as one lambda.

There are two notable files here: LocalEntryPoint.cs and LambdaEntryPoint.cs. LocalEntyPoint has the typical asp.net core main function for when you want to run it locally:

 public class LocalEntryPoint
 {
     public static void Main(string[] args)
     {
         CreateHostBuilder(args).Build().Run();
     }


     public static IHostBuilder CreateHostBuilder(string[] args) =>
         Host.CreateDefaultBuilder(args)
             .ConfigureWebHostDefaults(webBuilder =>
             {
                 webBuilder.UseStartup<Startup>();
             });
 }

LambdaEntryPoint derives from APIGatewayProxyFunction which ensures that for each API gateway call the web-api's startup is invoked and the API Gateway request is marshalled into Asp.net core's request.

 public class LambdaEntryPoint : 
    Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
 {
     protected override void Init(IWebHostBuilder builder)
     {
         builder
             .UseStartup<Startup>();
     }


     protected override void Init(IHostBuilder builder)
     {
     }
 }

The SAM template then uses a /{proxy+} path to ensure that all requests to the root of the Api Gateway just invoke the Asp.net core application.

 "AspNetCoreFunction": {
   "Type": "AWS::Serverless::Function",
   "Properties": {
     "Handler": "AWSServerless.Aspnet::AWSServerless.Aspnet.LambdaEntryPoint::FunctionHandlerAsync",
     "Runtime": "dotnetcore3.1",
     "CodeUri": "",
     "MemorySize": 256,
     "Timeout": 30,
     "Role": null,
     "Policies": [
       "AWSLambda_FullAccess"
     ],
     "Events": {
       "ProxyResource": {
         "Type": "Api",
         "Properties": {
           "Path": "/{proxy+}",
           "Method": "ANY"
         }
       },
       "RootResource": {
         "Type": "Api",
         "Properties": {
           "Path": "/",
           "Method": "ANY"
         }
       }
     }
   }
 }

In this configuration that routing is handled by asp.net core, not Api Gateway.

This configuration is familiar to any asp.net developer, which means new developers assigned to the project can hit the ground running. Full stack debug workflow I mentioned earlier is also a great advantage. Comes with all the benefits of Asp.net core, microsoft driven standard framework, available middlewares, libraries, community support and all the rest of it.
The solution is also platform agnostic. All we need to do is write an entrypoint for Azure Functions or Google Cloud Function and the solution is potentially deployable on these platforms.
The problem here is that this is a lambda monolith and not quite the microservices we are opting for. The benefits of microservices are lost here. Loading a lambda monolith would also have some performance impact.
Another point to note here is that this is not a traditional asp.net core app, different environment, different lifecycle, hence some components won't work. For example, you won't be able to host SignalR, or a scheduler component as you could on your traditional asp.net core app. If you are investing into AWS however, you are probably looking at replacing these components with AWS provided services anyway, but it's just something to keep in mind.

Other Frameworks

We did have a look at some other similar frameworks that could be used.

Nancy

A web framework similar to Asp.net core, with possibly less plumbing. Although it lacks the support and familiarity as Asp.net core does, it is indeed a very promising framework for microservices that I am keeping my eye on.

Serverless Framework

Another very promising framework that enables writing serverless microservices in a platform agnostic way. At a first glance, I found most of the examples and libraries are for nodejs. I'm sure it has the libraries that provide sufficient middlewares to create a Restful API, but at a first glance, it just didn't give us the confidence for .net development.

Our Pick

We decided to stick with the Asp.net core framework, but rather than having one monolith web-api, we decided to break it up into multiple web-api projects, each having their own Startup.

There's a shared Infrastructure where we can encapsulate start-up behaviour common to all services. There's a LocalDev project which is the only place we have a LocalEntryPoint. This is set as the start-up project for local development only, not deployed to AWS. This project doesn't have any controllers. The Starup may have some extra configuration to set-up local dev environment. For example you may want to use Lambda Authorizer in production environment, but for local-dev you could enable Auth middleware.
The other projects, each focused on a particular service: customers, orders and products. Each of these projects potentially deals with one type of resource (or related sub-resource). These projects have a Startup and a LambdaEntryPoint each as they will be deployed as to run as Lambda behind API Gateway.

The SAM templates then ensure that for a given base path, we invoke the correct LambdaEntryPoint. Below is an example for just the definition for product service as an example:

 "ProductsServiceLambda": {
   "Type": "AWS::Serverless::Function",
   "Properties": {
     "Handler": "AWSServerlessDemo.Aspnet::AWSServerlessDemo.Products.LambdaEntryPoint::FunctionHandlerAsync",
     "Runtime": "dotnetcore3.1",
     "CodeUri": "./AWSServerlessDemo.Products/",
     "MemorySize": 256,
     "Timeout": 30,
     "Role": null,
     "Policies": [
       "AWSLambda_FullAccess"
     ],
     "Events": {
       "ProductsProxyResource": {
         "Type": "Api",
         "Properties": {
           "Path": "/products/{proxy+}",
           "Method": "ANY"
         }
       },
       "ProductsRootResource": {
         "Type": "Api",
         "Properties": {
           "Path": "/products/",
           "Method": "ANY"
         }
       }
     }
   }
}

Note here that we're setting the "CodeUri": "./AWSServerlessDemo.Products/". This ensures that when the dotnet lambda tool will build and deploy just the source code for AWSServerlessDemo.Products, keeping the size of the deployment to a minimum, a contributing factor to lambda performance.

Future of Asp.net as Microservices’ Framework

.Net Core 5 has introduced some promising new features:

These are experimental at this stage but have real potential. Currently the asp.net core lifecycle has a lot of dependency on reflection, slowing down the start-up time. But imagine the source generators replacing all the code dependent on reflection, then member level trimming reducing app size down to only the methods that are called! I'm excited to see how it unfolds!