Stax.UserAgentBasedRouteBlocking 1.0.1-beta

User Agent Based Route Blocking

Summary

This NuGet library allows you to block certain routes based on whether or not they have a certain user agent. It is a very simple way of doing API based authorisation. It also has the ability to allow certain referrers through, which can help enable your swagger to work for example, or help limit user agents coming from a certain site.

An example might be you want to limit anyone from hitting https://api.example.com/v1/create-user.json unless they have the user agent EXAMPLE.COM-FRONTEND which your front end client sends. You could then also only allow requests with that user agent from https://example.com and also https://api.example.com (the latter which would allow your swagger to work for example).

Why I made this

I wanted a simple way to ensure only my frontend and certain clients could call my API. As a quick and easy way, getting my frontend and API consumers to send a custom user agent was a simple way to solve the problem without using full blown authentication.

How to use

Configuration is set through your appsettings.json (or you can inject as environment variables). Examples on how to configure your appsettings.json to make this work are below.

To enable, you then need to add app.UseUserAgentBasedRouteBlocking(); in your Configure method in your Program.cs/Startup.cs file.

Some how to use notes

• The path check does a "starts with" check. Meaning to protect https://api.example.com/v1 you would enter in UserAgentBasedRouteBlocking:Paths "/v1". This also means it acts like a wildcard meaning anything which starts with "/v1" is protected. Eg: /v1/create.json, /v1/upload.json etc
• User agent does a contains check, meaning Mozilla would cover Mozilla 5.0 - Linux for example.
• Referrer does a "contains" check, meaning https://example.com/a-page would be covered by setting https://example.com in your config

To use this, you need to

appsettings json configuration

In your appsettings.json you need a structure of:

{
  "UserAgentBasedRouteBlocking": {
    "Paths": [
      LIST
      OF
      PATHS
      TO
      CHECK
    ],
    "Referrer": {
      "AllowAll": bool - optional defaults to false. If true the Allowed list below is ignored.
      "Allowed": [
        LIST
        OF
        ALLOWED
        REFERRERS
      ]
    },
    "UserAgent": {
      "AllowAll": bool - optional defaults to false. If true the Allowed list below is ignored.
      "Allowed": [
        LIST
        OF
        ALLOWED
        USER
        AGENTS
      ]
    }
  }
}

Below is an example which:

• Checks the paths, /v1/hello-world.json, /v1/diagnostics and /v2
  • It is important to note that this checks the start of the route, so for example /v2/api.json would be covered by /v2
• Allows requests from https://google.com, https://facebook.com, https://apiconsumer.com
• Allows requests from user agents API Consumer User Agent and API Consumer2 User Agent

{
  "UserAgentBasedRouteBlocking": {
    "Paths": [
      "/v1/hello-world.json",
      "/v1/diagnostics",
      "/v2/"
    ],
    "Referrer": {
      "AllowAll": false,
      "Allowed": [
        "https://google.com",
        "https://facebook.com",
        "https://apiconsumer.com"
      ]
    },
    "UserAgent": {
      "AllowAll": false,
      "Allowed": [
        "API Consumer User Agent",
        "API Consumer2 User Agent"
      ]
    }
  }
}

As you have provided allowed lists for user agents and referrers, you do not need to set the AllowAll property for each.

Startup.cs/Program.cs

In your public void Configure(IApplicationBuilder app, IWebHostEnvironment env) you need to add:

app.UseUserAgentBasedRouteBlocking();

So your Configure method may look like:

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseUserAgentBasedRouteBlocking(); <--- added
        
        app.UseSwagger();
        app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger"));
        
        app.UseRouting();

        app.UseCors();

        app.UseAuthorization();
    }