Token-based authentication in ASP.NET Web API is a security mechanism that involves the use of tokens to authenticate and authorize users when accessing resources or performing actions within a web API. It is commonly used in modern web applications and APIs to provide secure and stateless authentication.
Here’s how token-based authentication typically works in ASP.NET Web API:
- User Authentication: When a user logs in or provides valid credentials, the server generates a token for that user. The token contains information such as the user’s identity and any relevant user roles or permissions.
- Token Issuance: The server issues the token to the client (usually a web browser or a mobile app) in the response after successful authentication. The token is typically sent in the HTTP response header, such as the “Authorization” header.
- Token Storage: The client (web browser or app) stores the received token securely. Commonly, the token is stored in a client-side storage mechanism, such as local storage or a cookie.
- Token Usage: Subsequent requests from the client to the server include the token in the request header, typically in the “Authorization” header. This informs the server that the client has been authenticated and authorized to access protected resources.
- Token Validation: The server receives the token in the request header and verifies its authenticity and integrity. It checks if the token is valid, has not expired, and is issued by a trusted authority. If the token is valid, the server extracts the user identity and proceeds with the requested operation.
- Authorization: After successful token validation, the server performs authorization checks to determine if the user associated with the token has sufficient privileges to access the requested resource or perform the requested action.
- Response: The server processes the request, generates the appropriate response, and sends it back to the client.
Advantages
Token-based authentication offers several advantages, including statelessness, scalability, and the ability to support distributed systems. It enables secure API access without the need for session management on the server-side, which simplifies the overall architecture.
Images: Bearer Token workflow diagram
What is Bearer Token ?
Bearer token is a type of access token used in token-based authentication schemes, including OAuth 2.0 and JSON Web Tokens (JWT). It is commonly used in web APIs and provides a means of authorizing and authenticating requests made by clients.
What is OAuth 2.0 ?
OAuth 2.0 is an open standard framework that allows users to grant limited access to their resources on one website (known as the “resource server”) to another website or application (known as the “client”) without sharing their credentials, such as passwords. It is commonly used for authentication and authorization purposes in web applications, mobile apps, and APIs.
OAuth 2.0 defines a set of roles, grant types, and protocols to facilitate the secure delegation of access rights
What is OpenId Connect?
OpenID Connect (OIDC) is an authentication layer built on top of the OAuth 2.0 framework. It provides a standardized and secure way for clients (such as web applications or mobile apps) to authenticate users using an identity provider (IdP) and obtain identity information about the authenticated users. OIDC adds identity-related features on top of OAuth 2.0, making it a complete identity protocol.
Now let’s create Bearer Token based Authentication demo
Step 1: Create the Web API Core application like this
Step 2: Install the given package on your project as given below
- Microsoft.EntityFrameworkCore.SqlServer
- Microsoft.EntityFrameworkCore.Tools
- Microsoft.AspNetCore.Identity.EntityFrameworkCore
- Microsoft.AspNetCore.Authentication.JwtBearer
Step 3: Change the connection string and JWT details in appsettings.json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"ConnStr": "Data Source=.;Initial Catalog=JWTRefreshTokenDB;Integrated Security=SSPI;Encrypt=False"
},
"JWT": {
"ValidAudience": "https://localhost:7262",
"ValidIssuer": "https://localhost:7262/",
"Secret": "PleaseHoldthisValue_on_AWS_OR_Azure",
"TokenValidityInMinutes": 1,
"RefreshTokenValidityInDays": 7
}
}
Step 4: Create the Auth Folder and inside Auth Folder create the ApplicationDbContext.cs class
We are using Identity Framework for creating all required tables for us for managing security on our application, we need to configure ApplicationDbContext like this.
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
namespace BearerTokenDemo.Auth
{
public class ApplicationDbContext: IdentityDbContext<ApplicationUser>
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
{
}
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
}
}
}
Step 5: Create Application User class like this
using Microsoft.AspNetCore.Identity;
namespace BearerTokenDemo.Auth
{
public class ApplicationUser: IdentityUser
{
public string? RefreshToken { get; set; }
public DateTime RefreshTokenExpiryTime { get; set; }
}
}
Step 6: Create User Role Class like this
namespace BearerTokenDemo.Auth
{
public static class UserRoles
{
public const string Admin = "Admin";
public const string User = "User";
}
}
Step 7: Go to the Model folder and Create Login Model like this
using System.ComponentModel.DataAnnotations;
namespace BearerTokenDemo.Model
{
public class LoginModel
{
[Required(ErrorMessage = "User Name is required")]
public string? Username { get; set; }
[Required(ErrorMessage = "Password is required")]
public string? Password { get; set; }
}
}
RegisterModel
using System.ComponentModel.DataAnnotations;
namespace BearerTokenDemo.Model
{
public class RegisterModel
{
[Required(ErrorMessage = "User Name is required")]
public string? Username { get; set; }
[EmailAddress]
[Required(ErrorMessage = "Email is required")]
public string? Email { get; set; }
[Required(ErrorMessage = "Password is required")]
public string? Password { get; set; }
}
}
Response Model:
namespace BearerTokenDemo.Model
{
public class Response
{
public string? Status { get; set; }
public string? Message { get; set; }
}
}
Token Model
namespace BearerTokenDemo.Model
{
public class TokenModel
{
public string? AccessToken { get; set; }
public string? RefreshToken { get; set; }
}
}
Step 7: Go to the Controller Folder and Create AuthenticateController like this
using BearerTokenDemo.Auth;
using BearerTokenDemo.Model;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Security.Cryptography;
using System.Text;
namespace BearerTokenDemo.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class AuthenticateController : ControllerBase
{
private readonly UserManager<ApplicationUser> _userManager;
private readonly RoleManager<IdentityRole> _roleManager;
private readonly IConfiguration _configuration;
public AuthenticateController(
UserManager<ApplicationUser> userManager,
RoleManager<IdentityRole> roleManager,
IConfiguration configuration)
{
_userManager = userManager;
_roleManager = roleManager;
_configuration = configuration;
}
[HttpPost]
[Route("login")]
public async Task<IActionResult> Login([FromBody] LoginModel model)
{
var user = await _userManager.FindByNameAsync(model.Username);
if (user != null && await _userManager.CheckPasswordAsync(user, model.Password))
{
var userRoles = await _userManager.GetRolesAsync(user);
var authClaims = new List<Claim>
{
new Claim(ClaimTypes.Name, user.UserName),
new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
};
foreach (var userRole in userRoles)
{
authClaims.Add(new Claim(ClaimTypes.Role, userRole));
}
var token = CreateToken(authClaims);
var refreshToken = GenerateRefreshToken();
_ = int.TryParse(_configuration["JWT:RefreshTokenValidityInDays"], out int refreshTokenValidityInDays);
user.RefreshToken = refreshToken;
user.RefreshTokenExpiryTime = DateTime.Now.AddDays(refreshTokenValidityInDays);
await _userManager.UpdateAsync(user);
return Ok(new
{
Token = new JwtSecurityTokenHandler().WriteToken(token),
RefreshToken = refreshToken,
Expiration = token.ValidTo
});
}
return Unauthorized();
}
[HttpPost]
[Route("register")]
public async Task<IActionResult> Register([FromBody] RegisterModel model)
{
var userExists = await _userManager.FindByNameAsync(model.Username);
if (userExists != null)
return StatusCode(StatusCodes.Status500InternalServerError, new Response { Status = "Error", Message = "User already exists!" });
ApplicationUser user = new()
{
Email = model.Email,
SecurityStamp = Guid.NewGuid().ToString(),
UserName = model.Username
};
var result = await _userManager.CreateAsync(user, model.Password);
if (!result.Succeeded)
return StatusCode(StatusCodes.Status500InternalServerError, new Response { Status = "Error", Message = "User creation failed! Please check user details and try again." });
return Ok(new Response { Status = "Success", Message = "User created successfully!" });
}
[HttpPost]
[Route("register-admin")]
public async Task<IActionResult> RegisterAdmin([FromBody] RegisterModel model)
{
var userExists = await _userManager.FindByNameAsync(model.Username);
if (userExists != null)
return StatusCode(StatusCodes.Status500InternalServerError, new Response { Status = "Error", Message = "User already exists!" });
ApplicationUser user = new()
{
Email = model.Email,
SecurityStamp = Guid.NewGuid().ToString(),
UserName = model.Username
};
var result = await _userManager.CreateAsync(user, model.Password);
if (!result.Succeeded)
return StatusCode(StatusCodes.Status500InternalServerError, new Response { Status = "Error", Message = "User creation failed! Please check user details and try again." });
if (!await _roleManager.RoleExistsAsync(UserRoles.Admin))
await _roleManager.CreateAsync(new IdentityRole(UserRoles.Admin));
if (!await _roleManager.RoleExistsAsync(UserRoles.User))
await _roleManager.CreateAsync(new IdentityRole(UserRoles.User));
if (await _roleManager.RoleExistsAsync(UserRoles.Admin))
{
await _userManager.AddToRoleAsync(user, UserRoles.Admin);
}
if (await _roleManager.RoleExistsAsync(UserRoles.Admin))
{
await _userManager.AddToRoleAsync(user, UserRoles.User);
}
return Ok(new Response { Status = "Success", Message = "User created successfully!" });
}
[HttpPost]
[Route("refresh-token")]
public async Task<IActionResult> RefreshToken(TokenModel tokenModel)
{
if (tokenModel is null)
{
return BadRequest("Invalid client request");
}
string? accessToken = tokenModel.AccessToken;
string? refreshToken = tokenModel.RefreshToken;
var principal = GetPrincipalFromExpiredToken(accessToken);
if (principal == null)
{
return BadRequest("Invalid access token or refresh token");
}
string username = principal.Identity.Name;
var user = await _userManager.FindByNameAsync(username);
if (user == null || user.RefreshToken != refreshToken || user.RefreshTokenExpiryTime <= DateTime.Now)
{
return BadRequest("Invalid access token or refresh token");
}
var newAccessToken = CreateToken(principal.Claims.ToList());
var newRefreshToken = GenerateRefreshToken();
user.RefreshToken = newRefreshToken;
await _userManager.UpdateAsync(user);
return new ObjectResult(new
{
accessToken = new JwtSecurityTokenHandler().WriteToken(newAccessToken),
refreshToken = newRefreshToken
});
}
[Authorize]
[HttpPost]
[Route("revoke/{username}")]
public async Task<IActionResult> Revoke(string username)
{
var user = await _userManager.FindByNameAsync(username);
if (user == null) return BadRequest("Invalid user name");
user.RefreshToken = null;
await _userManager.UpdateAsync(user);
return NoContent();
}
[Authorize]
[HttpPost]
[Route("revoke-all")]
public async Task<IActionResult> RevokeAll()
{
var users = _userManager.Users.ToList();
foreach (var user in users)
{
user.RefreshToken = null;
await _userManager.UpdateAsync(user);
}
return NoContent();
}
private JwtSecurityToken CreateToken(List<Claim> authClaims)
{
var authSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration["JWT:Secret"]));
_ = int.TryParse(_configuration["JWT:TokenValidityInMinutes"], out int tokenValidityInMinutes);
var token = new JwtSecurityToken(
issuer: _configuration["JWT:ValidIssuer"],
audience: _configuration["JWT:ValidAudience"],
expires: DateTime.Now.AddMinutes(tokenValidityInMinutes),
claims: authClaims,
signingCredentials: new SigningCredentials(authSigningKey, SecurityAlgorithms.HmacSha256)
);
return token;
}
private static string GenerateRefreshToken()
{
var randomNumber = new byte[64];
using var rng = RandomNumberGenerator.Create();
rng.GetBytes(randomNumber);
return Convert.ToBase64String(randomNumber);
}
private ClaimsPrincipal? GetPrincipalFromExpiredToken(string? token)
{
var tokenValidationParameters = new TokenValidationParameters
{
ValidateAudience = false,
ValidateIssuer = false,
ValidateIssuerSigningKey = true,
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration["JWT:Secret"])),
ValidateLifetime = false
};
var tokenHandler = new JwtSecurityTokenHandler();
var principal = tokenHandler.ValidateToken(token, tokenValidationParameters, out SecurityToken securityToken);
if (securityToken is not JwtSecurityToken jwtSecurityToken || !jwtSecurityToken.Header.Alg.Equals(SecurityAlgorithms.HmacSha256, StringComparison.InvariantCultureIgnoreCase))
throw new SecurityTokenException("Invalid token");
return principal;
}
}
}
Next Keep Authorize attributes like this.
Step 8: Go to the Program.cs file and configure the middleware like this
using BearerTokenDemo.Auth;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using Microsoft.IdentityModel.Tokens;
using Microsoft.OpenApi.Models;
using System.Text;
var builder = WebApplication.CreateBuilder(args);
ConfigurationManager configuration = builder.Configuration;
// For Entity Framework
builder.Services.AddDbContext<ApplicationDbContext>(options => options.UseSqlServer(configuration.GetConnectionString("ConnStr")));
// For Identity
builder.Services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
// Adding Authentication
builder.Services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
})
// Adding Jwt Bearer
.AddJwtBearer(options =>
{
options.SaveToken = true;
options.RequireHttpsMetadata = false;
options.TokenValidationParameters = new TokenValidationParameters()
{
ValidateIssuer = true,
ValidateAudience = true,
ValidateLifetime = true,
ValidateIssuerSigningKey = true,
ClockSkew = TimeSpan.Zero,
ValidAudience = configuration["JWT:ValidAudience"],
ValidIssuer = configuration["JWT:ValidIssuer"],
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["JWT:Secret"]))
};
});
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
//Adding Bearer token option on swagger
builder.Services.AddSwaggerGen(option =>
{
option.SwaggerDoc("v1", new OpenApiInfo { Title = "BearerToken Demo API", Version = "v1" });
option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "Please enter a valid token",
Name = "Authorization",
Type = SecuritySchemeType.Http,
BearerFormat = "JWT",
Scheme = "Bearer"
});
option.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type=ReferenceType.SecurityScheme,
Id="Bearer"
}
},
new string[]{}
}
});
});
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
// Authentication & Authorization
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();
Step 9: You can run this two command to update schema in database using package manager console.
add-migration Initial
update-database
Step 10: Run the application and verify it.
Now test the Login functionalities like this
You can download the source code from GitHub and play with it.
Chandradev's Blog 