Protecting ASP.NET Core Web API Endpoints with JWT Bearer Authentication

Date- Jun 10,2026 270

Overview

JWT (JSON Web Token) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. JWTs are particularly useful in the context of web applications where the server needs to send information to the client in a secure manner.

The primary purpose of JWT Bearer Authentication is to ensure that only authenticated users can access certain endpoints of a Web API. This authentication method is stateless, meaning that the server does not need to store user session information, which greatly enhances scalability and performance. Real-world use cases include securing APIs in microservices architectures, protecting mobile backend services, and enabling single sign-on (SSO) capabilities across multiple applications.

Prerequisites

ASP.NET Core SDK: Ensure you have the latest version of the .NET SDK installed.
Basic knowledge of C#: Familiarity with C# programming will help you understand the examples better.
Understanding of RESTful APIs: Knowing how REST APIs work is essential for grasping the concepts presented.
Postman or Curl: Tools for testing your API endpoints will be necessary.

Understanding JWT Structure

A JWT is composed of three parts: the header, the payload, and the signature. The header typically consists of two parts: the type of the token (JWT) and the signing algorithm being used, such as HMAC SHA256 or RSA. This information is base64Url encoded to form the first part of the JWT.

The payload contains the claims, which are statements about an entity (typically, the user) and additional data. Like the header, the payload is also base64Url encoded. The final part of the JWT is the signature, which is created by taking the encoded header, the encoded payload, a secret, and the algorithm specified in the header and signing it.

public class JwtTokenHandler
{
    public string CreateToken(string username)
    {
        var claims = new[]
        {
            new Claim(JwtRegisteredClaimNames.Sub, username),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };

        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your_secret_key_here"));
        var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var token = new JwtSecurityToken(
            issuer: "yourdomain.com",
            audience: "yourdomain.com",
            claims: claims,
            expires: DateTime.Now.AddMinutes(30),
            signingCredentials: creds
        );

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

This example demonstrates a simple JwtTokenHandler class that creates a JWT. The CreateToken method first defines the claims that will be included in the token. It then generates a signing key using a secret key, creates the signing credentials, and finally constructs the token using the JwtSecurityToken class.

The expected output is a string representation of the JWT, which can be sent to the client upon successful authentication. The token will expire in 30 minutes, enhancing security by limiting the time frame in which the token can be used.

JWT Claims

Claims are essential components of the JWT, providing information about the user and the token itself. Claims can be categorized into three types: registered claims, public claims, and private claims. Registered claims are predefined claims that have specific meanings, such as iss (issuer), exp (expiration), and sub (subject). Public claims can be defined at will but should be named to avoid collisions, while private claims are custom claims created to share information between parties that agree on using them.

Configuring JWT Bearer Authentication in ASP.NET Core

To secure your ASP.NET Core Web API with JWT Bearer Authentication, you need to configure the authentication middleware in your Startup.cs file. This involves adding the necessary NuGet packages, modifying the service configuration, and setting up the middleware pipeline.

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = "yourdomain.com",
                ValidAudience = "yourdomain.com",
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your_secret_key_here"))
            }; 
        });

    services.AddControllers();
}

This code configures the JWT Bearer Authentication service in the ConfigureServices method. The AddJwtBearer method sets up the token validation parameters, which are crucial for ensuring that the incoming tokens are valid. The parameters include checks for the issuer, audience, lifetime, and signing key.

By validating these aspects, you ensure that tokens are only accepted if they are issued by your trusted server and are intended for your application. Failing any of these validations will result in a 401 Unauthorized response.

Middleware Pipeline Configuration

After configuring the authentication service, the middleware must be included in the request processing pipeline. This is done in the Configure method of Startup.cs.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

This configuration adds the authentication middleware using app.UseAuthentication() before the authorization middleware. This order is crucial because the authorization middleware needs to know whether a user is authenticated before it can authorize them to access specific resources.

Securing API Endpoints

Once JWT Bearer Authentication is set up, you can secure your API endpoints by applying the [Authorize] attribute to your controller or action methods. This instructs ASP.NET Core to enforce authentication for these endpoints.

[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    [Authorize]
    public IActionResult Get()
    {
        var forecast = new[]
        {
            new WeatherForecast { Date = DateTime.Now, TemperatureC = 25, Summary = "Warm" }
        };
        return Ok(forecast);
    }
}

This code snippet shows a simple API controller that returns weather forecasts. The [Authorize] attribute on the Get method ensures that only authenticated users can access this endpoint. If an unauthenticated request is made, the server will respond with a 401 Unauthorized status.

Testing Secured Endpoints

To test the secured endpoint, you must first obtain a JWT token by successfully authenticating a user. Once you have the token, you can include it in the Authorization header of your request to access the secured endpoint.

GET /api/weatherforecast
Authorization: Bearer your_jwt_token_here

When the request is made with a valid token, the server will respond with a 200 OK status and the forecast data. If the token is invalid or expired, you will receive a 401 Unauthorized response.

Edge Cases & Gotchas

When implementing JWT Bearer Authentication, several pitfalls can arise. One common issue is not properly validating the token's expiration. If the expiration time is not checked, clients may continue to use an expired token, leading to unauthorized access. Always ensure that ValidateLifetime is set to true in your token validation parameters.

options.TokenValidationParameters = new TokenValidationParameters
{
    ValidateLifetime = true,
    // Other parameters...
};

Another edge case involves using weak signing keys. A poorly chosen key can easily be compromised, rendering your tokens insecure. Always use a strong, randomly generated key that is sufficiently long and stored securely.

Performance & Best Practices

Performance can be impacted when using JWTs, especially if the token size becomes too large. Ensure the claims included in the token are necessary and avoid including sensitive information, as JWTs are not encrypted by default. Instead, consider using JWE (JSON Web Encryption) if sensitive data must be included.

It's also advisable to implement token blacklisting for tokens that should no longer be valid before their expiration time. This can be done by maintaining a list of invalidated tokens in a persistent store, allowing you to revoke access as needed.

Real-World Scenario: A Mini-Project

To tie all these concepts together, let's create a mini-project that consists of a simple ASP.NET Core Web API that allows user registration and login, followed by securing the API with JWT Bearer Authentication.

public class User
{
    public string Username { get; set; }
    public string Password { get; set; }
}

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly JwtTokenHandler _tokenHandler;

    public AuthController(JwtTokenHandler tokenHandler)
    {
        _tokenHandler = tokenHandler;
    }

    [HttpPost("register")]
    public IActionResult Register(User user)
    {
        // Registration logic (e.g., save user to database)
        return Ok();
    }

    [HttpPost("login")]
    public IActionResult Login(User user)
    {
        // Authentication logic (e.g., validate user)
        var token = _tokenHandler.CreateToken(user.Username);
        return Ok(new { Token = token });
    }
}

This AuthController has two endpoints: Register for user registration and Login for user authentication. Upon successful login, the user receives a JWT which they can use to access protected resources.

Testing the Mini-Project

You can test this mini-project using Postman by sending a POST request to /api/auth/login with valid credentials. The response will return a JWT token, which can then be used to access other secured endpoints by including it in the Authorization header.

Conclusion

JWT Bearer Authentication is a powerful method for securing ASP.NET Core Web APIs.
Understanding the structure and claims of a JWT is crucial for effective implementation.
Proper configuration of authentication and authorization middleware is essential for security.
Edge cases and performance considerations should be addressed to ensure a robust application.
Real-world scenarios help solidify your understanding of these concepts.