Throttling actions in .Net Core 2.1 using AttributeFilter

I have previously written about Throttling in the pre-core times, and this is sort of the update to that post – with a bit of fixes and tweaks.

Lets get to it;

A few changes:

In my last post I did things a bit differently, for instance; I used to throw a custom exception type and handle that as a response, I have learned that this is an anti-pattern and is strongly discouraged (at least by David Fowler).
Anyway now we return a class, which is basically just my old ApiException type, just without the inherited bits of Exception. – this is both cheaper and cleaner.
Also since we are using .NET Core, we are using IMemoryCache instead of HttpRuntime.Cache – which is also nice.

services.AddMemoryCache();

On to the attribute:

There isn’t a lot to it to be honest.

  1. Check for existence of cache entry
  2. If none, create one and set allowExecute = true
  3. If allowExecute != true, return throttle response and short-circuit the pipeline.

Do note that this throttle uses IP as it’s target, but could easily be username or similar.

Usage:

[IPThrottling("GetItems", 300)]
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
    return new string[] { "value1", "value2" };
}

The above throttles for 300 seconds for the GetItems key, so you can group together functionality as well, if you really need to.

Ill talk about the custom response in a different blogpost

Easy, simple HttpRuntime.Cache

A simple to use caching function that both gets and/or sets the key depending on results.

This is a post for my future self. – Hi future self! (wave).
The following is an easy to use caching function.

The function gets or updates based on results.
The wrapper helps create different cacheExpirations based on needs.
Usage:

Versioning WebApi and documenting version with Swagger

Versioning in WebApi

Note: This post draws alot of points from https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/ – but is more about implementation and documentation through swagger.
So please go read Troy’s post and then come back :).
There are a couple of ways of versioning a restful api
among them are:
1. Url versioning e.g. GET http://example.com/api/v1/cars
2. Request-Header e.g. GET http://example.com/api/cars — Header: api-version: 1
There are pros and cons in both regards, Troy gets around them quite nicely.
Time to code!

Url Versioning

Easy – simply use either the RoutePrefix- or RouteAttribute

Read more about the Routing-Attribute here

Request-Header

Drawing from Troy’s post
We create a new attribute which uses a custom routing constraint

** Usage **

Effectively matching routes based on the “api-version” header.

Swagger

When using swashbuckle (swagger implementation for .Net).
It knows about the default Route- and RoutePrefixAttribute, so Url Versioning is taken care of, out of the box.
But Header versioning is not.
Fortunately, it’s quite easy to implement an OperationFilter that adds the header as a parameter to the endpoints in question.
This implementation uses a list of versions and the endpoints relativepaths to know when to add the parameter and when not to.


How would you implement the OperationFilter?

Documenting roles with swashbuckle

How to document attribute usage with swagger

You could basically document any attribute you have decorated your actions with, but this will focus mainly on documenting the role part of the Authorize attribute.
When using roles based authentication I like to document the roles in my swagger spec, this gives a nice indication, to the consumer, of which roles are required for different endpoints.
Here I have a basic Authorize attribute with a required role of “Admin”.

As with most other things swashbuckle related, we need to create an IOperationFilter

And that is it, you have now auto documented every role required across your API.
The swagger docs will look like the following.
BackupPortal_API

How to use the autogenerated swagger client

A detailed post on how to use an autogenerated swagger client

This blogpost will focus on the generated C# client.
To get started you basically just need 1 thing.

  1. A Swagger.Json file

Creating the client

If you already have the client you can skip this part
So you have created an API and added Swagger to it or you have been given a swagger.json file or someone else has created a swagger enable API or any combination of the above.
Now you want to create a client for, thankfully http://editor.swagger.io

Can generate a client for you.
Get your swagger.json file (if using swashbuckle the default url for the file is {your api domain}/swagger/docs/v1)
Go the http://editor.swagger.io

swaggerpaste
and paste the swagger.json file into the modal that pops up.
Note:
The editor should notify you of any errors in the schema
For this article I have used the swagger.json from the petstore example (any valid swagger will do).
If no errors arise, you are ready to generate the client.
swaggergenerateclient
Once the zip file is done downloading you should unzip and compile it using the Compile.bat file, located inside the folder.
Once compiled you can find the client and it’s dependencies inside the /bin folder.
Then just add the reference to a new project.
I will be using a basic Console Application.


Using the client

Note: The generated client has 2 dependencies namely; Newtonsoft.Json and RestSharp, these should be referenced through Nuget instead of using the ones that come with the client.
I will provide a basic run-through of how to use the client with different types of authentication, and how to use the generated client.
2 things to note about the client.

  1. All endpoints for the are located in the IO.Swagger.Api namespace
  2. All configuration options for the httpclient is located in the IO.Swagger.Client namespace
    This is where we will provide:

* Authentication
* Default Headers
* UserAgent
* etc.
3. All response models are location in the IO.Swagger.Model namespace
I will start with the configuration as this needs to be out of the way to call the API.

Client Configuration

Authentication:
The examples given are general examples and are not related to the petstore client (apart from the api naming).
I will go through 2 types of Authentication

  1. Basic Authentication
  2. APIKey authentication

Basic Authentication in the generated client is very straightforward

The above example will use the Authorization Header as transport with whatever scheme is defined in the swagger.json file.
Using an APIKey is almost as easy as Basic Authentication:
There are 2 configuration options for apiKey ApiKeyPrefix and ApiKey.
They are both directly related to the header that will be used as transport for the token.

In the above example we are using the Authorization Header as transport and we are using the Bearer Scheme (ApiKeyPrefix)
The sent header will look like the following: Authorization: Bearer {Some token value}

Endpoints

Using the endpoints is almost insanely easy. Every API endpoint is wrapped in a nice easy to use method, with input and output models.
The petstore API uses an api_key header with the value of “special-key” for authentication.
apikeyauth
The code for accessing the store inventory looks as the following

which generates the following output
clientoutput
The code for getting all pets with a particular status (to show the use of output models)

which generates the following output (as of this writing)
Petnames

End

This concludes the post, you should find that using the generated API is pretty straightforward and easy.

Handling Exceptions in WebApi globally

Handling exceptions can be such a hassle. Thankfully the WebAPI pipeline can help alot.
Utilizing the ExceptionFilterAttribute class can create
a consistent and simple way of returning great error responses for your API – like this

Lets get started.

First of all we need:

The Error Model:

The error interface:

We have 4 things here
1. ExceptionType – The type of error
2. A HttpStatusCode – Because returning the statuscode can prove useful to consumers
3. A Code – I use this for the httpstatuscode message
4. A List of Errors
1. Exception Type

Just an enum. I tend to use only Error, but it allows for a more gradient approach if needed.
2. HttpStatusCode
Thankfully the System.Net namespace provides most HttpStatusCodes as enum, so I just utilize this.
3. Code
I use this for the string interpretation of the httpStatusCode, but could be an internal code as well.
4. List of Errors

The above class consists of a Reason phrase and a message to go with this phrase
The “reasons” is also encapsulated as enums, but will be converted into their string representations in the inherited ApiException Class

The derived ApiException Class

Not alot to it. A few constructors, but it should explain itself pretty well.
“All of this is all good and fine, but how do we handle exceptions globally?” you ask.

The GlobalExceptionAttribute


it basically just checks which type of exception was thrown, and acts accordingly, notably typeof(ApiException). Any “unhandled” errors is thrown as “internal server error”. This is also where you would put any logging, as all exceptions will go through this filter. (I have left this out).
The above attribute should be applied in the WebApiConfig.cs file.

As you can see from the following part of the attribute

We check for any errors with typeof(ApiException), but we haven’t implemented the error type yet.
So in any Actions where you would normally return errors, you throw a new ApiException instead.

The above would cause our API to return a response, with a responsecode of 404 and the following body

Throttling actions in WebApi using AttributeFilter

I recently had to come up with a solution to throttle an action in an API i’ve written.
First thing I did was to see what others had used (No reason to invent the wheel right?).
I came across this stackoverflow answer – which is basically what I will use in this blog post (mostly for a reminder to myself I guess).
Full credits go to Jarrod Dixon

The Attribute

The Annotation

Since it’s an attribute, we just annote it to an action
The attribute takes a unique name, amount of seconds and the message to return.
If the action is run more often than allowed, the action will return 409 - conflict

Authorization using tokens in WebAPI

Implementing token based authorization isn’t as hard as it might seem, not with the right tools atleast.
The very brief introduction to Tokens can be derived from the following image;
Token authentication
You Authenticate with a username/password (or something else).
The Server validates the credentials and spits back a token.
The Token is then used for subsequent calls until it expires.

Note:

There are basically three ways of getting a token to the server
1. The URL GET http://tempuri.com/someendpoint?token="".
2. The payload (body) which means you will need to POST to all endpoints (not RESTful)
3. A Header of some sort (generally the Authorization header.
In this post I am going use the Authorization header.
The token type will be Json Web Tokens.
I like JWTokens because they contain everything related to the user, although they do have a significant size to them.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.

You can read more on http://jwt.io.
In this post I will also be signing the token using HMAC to secure it from tampering.
What we will be doing is the following;

  • Install needed NuGet packages.
  • Create models to hold a User and the AuthToken.
  • Create a TokenProvider interface and a Json Web Token Provider to create the token.
  • Create a controller to authenticate using Username/Password.
  • Create a Token Authorization Attribute to be used either in webapiconfig.cs or on individual controllers/actions.

Add Nuget Packages.


This could be done without the ThinkTecture one, but I feel like it adds some value.

Create a model to hold the token, this is just a poco containing the token and an expiration time


Next, I’ll create another poco to hold the username/password and Roles associated with the user.

The roles will be assigned on authenticating through the AccountController (which we will do later on).

Create a provider interface and create a JsonWebTokenProvider

The provider will need 2 methods

  • Create a token
  • Validate a token


Interface done, lets move on to the concrete implementation.
There are a few parts we need to handle.
Firstly, we need a few token specific fields namely,

  • Audience – The audience that will be accessing your API
  • Issuer – You..
  • Key – to be used as the HMAC Private Key (Should be unique and safeguarded)
  • SigningCredential – the HMAC signing credential to be used in the header of the JWT –

The signingCredential will be instantiated in the default constructor as you can see in the gist.

Now lets abide by the Interface.
The CreateToken method:
We create a token that is valid for 15 minutes based on the user claims and serialize it to a string.

The ValidateToken method:
We validate a given tokenString based on some validation parameters.

Create AccountController

Here I’ve created 1 method authenticate
Which matches a username/password and creates and returns a token based off that user. The action needs to allow anonymous-access, as we will be adding the Authorization Attribute globally.

We can now authenticate by doing a POST to /account/authenticate?username=admin&password=1235

TokenAuthorizationAttribute

The Authorization Attribute…
Let’s dive right in.
This attribute looks for the Authorization: Bearer {Token} header. If the header is present, and the Token is valid, the Principal gets set and the user is authorized, else a 401 is returned.
I’ve also allowed using the [AllowAnonymous] attribute for the account/authenticate action. and since we are already using claims, we will be able to use the [Authorize] attribute to check roles as well.

Finishing up

All that is left to do, is adding the attribute to WebApiConfig.cs and maybe decorating controller actions with [Authorize(Roles = "Admin")]
The following will make sure that ALL actions (except ones decorated with the [AllowAnonymous] attribute) is secured.

Now you can add [Authorize(Roles = "Admin")] to actions that needs to check roles as well (if needed).

Further more

Alot can be refactored from the code provided, I will leave that up to the reader to decide where and how – I have tried to keep is as simple and as short as possible, therefor I have left out refactorings that I, myself have done.

Remove 'Try it out!' buttons from Swagger-ui

This is a quick way of removing the ‘try it out’ buttons from specific operation types, when using Swagger-ui for documentation

This will be a short one.
When using Swashbuckle to create documentation, you might want to remove the Try it out buttons, maybe all of them, or maybe just the ones on Put on Post operations
Well I’ve created a small script that is injected into swagger-ui through the SwaggerConfig.cs
The following script will remove the TryItOut buttons from all Put and Post operations.

The script is injected through the SwaggerConfig.cs like so

Remember that the .js file needs to be an Embedded Resource else it won’t work.

Adding basic authentication to swashbuckle

Note: This is applies to swashbuckle 5.2.2 and below, will update post for 5.4.0.


On my recent endeavors, I’ve had the pleasure of getting to use “Swagger”, yes it is as swag as it sounds…
Swagger for .Net is thankfully packaged by a guy I only know as “DomainDriven” on github.
The .Net version is called “Swashbuckle”.
I will not go in to adding swashbuckle to your project, the README pretty much says it all.
Lets get back to basic-auth.
According to the swashbuckle docs, to add Basic-Auth to swashbuckle, you need to add the following in the SwaggerConfig.cs file

This adds the “SecurityDefinition” as per the swagger spec.
The SwashBuckler docs finishes the security segment with

NOTE: These only define the schemes and need to be coupled with a corresponding “security” property at the document or operation level to indicate which schemes are required for each operation. To do this, you’ll need to implement a custom IDocumentFilter and/or IOperationFilter to set these properties according to your specific authorization implementation

Which is what I’ll be showing you how to do.

Onwards!

Lets start with the UI.
To remove the APIKey input and replace that with a nice username/password input pair, we need to inject a new index.html.
Note: You can see the base swagger index file here
You can see the entire index.html below
[/learn_more]
What I’ve changed from the original index.html is actually not a whole lot.
I’ve removed everything that had to do with the apikey input and instead added new username and password inputs;
Now all there needs to be done is to inject the new index file into swagger-ui

Now that we have the UI in order, we move on to the actual spec implementation.
To actually live up to the swagger spec, we are still missing the Security Requirement Object on the operations.
According to the spec;

Security Requirement Object
Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes).
The name used for each property MUST correspond to a security scheme declared in the Security Definitions.

Which basically means that we need to add "security": [{"basic": []}] to all of our operations.
This only applies to the code generated by swagger, but how do we implement this through Swashbuckle?
We need to create a class that inherits from the IOperationFilter interface.
And then add the security scheme to all operation.
The security theme is basically just a “basic : []” applied under the security configuration (speaking in pure swagger spec terms).

Now we just need to apply the OperationsFilter in the SwaggerConfig

and that is it, now the “basic” security scheme will be applied to all operations.