Originally published at imrantech.hashnode.dev
The Honest Starting Point
When my tech lead told me to implement JWT for our HRMS portal with refresh token rotation for our HRMS portal, I nodded confidently and immediately opened Google. I had a rough idea of what JWT was. A token. You send it with every request. The server validates it. Simple enough right? Wrong. The moment I started actually building it, questions hit me one after another. Where do I store the refresh token? How short should the access token be? What happens when the refresh token expires? How do I actually revoke a token? After building it from scratch and getting it working in production, I want to walk you through the complete implementation — every file, every decision, and why I made it.
What Are We Actually Building?
Before code, let me explain the flow simply:
`User logs in
↓
Server returns TWO tokens:
→ Access Token (short-lived — expires in minutes)
→ Refresh Token (long-lived — expires in days)
↓
Client uses Access Token for every API request
↓
Access Token expires?
→ Client sends Refresh Token to get a NEW Access Token
→ No need to login again!
↓
Refresh Token expires?
→ User must login again`
Why two tokens? Because if your access token gets stolen, it expires quickly anyway. The refresh token lives in your database and can be revoked instantly if needed.
Project Structure
Here's how I structured the authentication across my project layers:
HRMS/
├── Controllers/
│ └── AuthController.cs ← API endpoints
├── HRMS.DAL/
│├── AuthService.cs ← Business logic
│ └── Interfaces/
│└── IAuthService.cs ← Contract
└── HRMS.EF/
├── Models/
│ ├── User.cs
│ └── RefreshToken.cs ← Stores refresh tokens in DB
└── DTOs/
└── AuthResponseDto.cs
Step 1 — The RefreshToken Model
First I created a database table to store refresh tokens:
// HRMS.EF/Models/RefreshToken.cs.
public class RefreshToken {
public int Id { get; set; }
public string Token { get; set; }
public DateTime Expires { get; set; }
public bool IsRevoked { get; set; }
public int UserId { get; set; } }
Three important fields here:
- Expires — when does this refresh token die?
- IsRevoked — did we manually invalidate it? (logout, security breach)
- UserId — which user does this token belong to?
Step 2 — The Auth Response DTO
//HRMS.EF/DTOs/AuthResponseDto.cs
public class AuthResponseDto {
public string AccessToken { get; set; }
public string RefreshToken { get; set; }
}
Simple. Login returns both tokens together.
Step 3 — The AuthService
This is where the real logic lives.
//HRMS.DAL/AuthService.cs
public class AuthService : IAuthService {
private readonly AppDbContext _context;
private readonly IConfiguration _config;
public AuthService(AppDbContext context, IConfiguration config)
{
_context = context;
_config = config;
}
public async Task<string> Register(RegisterDto dto)
{
var exists = await _context.Users
.AnyAsync(x => x.Email == dto.Email);
if (exists) return "User exists";
var user = new User
{
Email = dto.Email,
PasswordHash = BCrypt.Net.BCrypt.HashPassword(dto.Password),
Role = "Employee"
};
_context.Users.Add(user);
await _context.SaveChangesAsync();
return "Registered";
}
public async Task<object> Login(LoginDto dto)
{
var user = await _context.Users
.FirstOrDefaultAsync(x => x.Email == dto.Email);
if (user == null) return "Invalid";
if (!BCrypt.Net.BCrypt.Verify(dto.Password, user.PasswordHash))
return "Invalid";
// Generate both tokens
var accessToken = GenerateToken(user);
var refreshToken = GenerateRefreshToken();
// Save refresh token to database
var entity = new RefreshToken
{
Token = refreshToken,
Expires = DateTime.Now.AddDays(7),
IsRevoked = false,
UserId = user.Id
};
_context.RefreshTokens.Add(entity);
await _context.SaveChangesAsync();
return new
{
accessToken,
refreshToken
};
}
private string GenerateToken(User user)
{
var claims = new[]
{
new Claim("UserId", user.Id.ToString()),
new Claim(ClaimTypes.Role, user.Role)
};
var key = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(_config["Jwt:Key"])
);
var creds = new SigningCredentials(
key, SecurityAlgorithms.HmacSha256
);
var token = new JwtSecurityToken(
claims: claims,
expires: DateTime.Now.AddMinutes(15),
signingCredentials: creds
);
return new JwtSecurityTokenHandler().WriteToken(token);
}
private string GenerateRefreshToken()
{
return Guid.NewGuid().ToString();
}
}
A few things worth noting:
BCrypt for passwords — never store plain passwords. BCrypt.HashPassword() on register, BCrypt.Verify() on login.
Access token expiry — I set this to 15 minutes in production. During development I actually set it to 25 seconds to test the refresh flow quickly without waiting! If your token expires almost immediately while testing — that's why. 😄
Refresh token — I'm using Guid.NewGuid().ToString() which generates a unique random string. Simple and works perfectly for this use case.
Step 4 — The AuthController
//HRMS/Controllers/AuthController.cs
[ApiController]
[Route("api/auth")]
public class AuthController : ControllerBase {
private readonly IAuthService _service;
private readonly AppDbContext _context;
private readonly IConfiguration _config;
public AuthController(
IAuthService service,
AppDbContext context,
IConfiguration config)
{
_service = service;
_context = context;
_config = config;
}
[HttpPost("register")]
public async Task<IActionResult> Register(RegisterDto dto)
{
return Ok(await _service.Register(dto));
}
[HttpPost("login")]
public async Task<IActionResult> Login(LoginDto dto)
{
return Ok(await _service.Login(dto));
}
[HttpPost("refresh")]
public async Task<IActionResult> Refresh(string refreshToken)
{
// Find the token in database
var token = await _context.RefreshTokens
.FirstOrDefaultAsync(x => x.Token == refreshToken);
// Three checks before issuing new access token
if (token == null || token.IsRevoked || token.Expires < DateTime.Now)
return Unauthorized("Invalid refresh token");
var user = await _context.Users.FindAsync(token.UserId);
var newAccessToken = GenerateToken(user);
return Ok(new { accessToken = newAccessToken });
}
private string GenerateToken(User user)
{
var claims = new[]
{
new Claim("UserId", user.Id.ToString()),
new Claim(ClaimTypes.Role, user.Role)
};
var key = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(_config["Jwt:Key"])
);
var creds = new SigningCredentials(
key, SecurityAlgorithms.HmacSha256
);
var token = new JwtSecurityToken(
claims: claims,
expires: DateTime.Now.AddMinutes(15),
signingCredentials: creds
);
return new JwtSecurityTokenHandler().WriteToken(token);
}
}
The Refresh endpoint does three critical checks:
if (token == null || token.IsRevoked || token.Expires < DateTime.Now) return Unauthorized("Invalid refresh token");
- token == null — doesn't exist in DB (fake token?)
- token.IsRevoked — we manually revoked it (user logged out)
- token.Expires < DateTime.Now — it's expired
All three must pass before we issue a new access token. This is the security layer.
Step 5 — Program.cs Configuration
//JWT Bearer setup
builder.Services.AddAuthentication(options => { options.DefaultAuthenticateScheme = "Bearer";
options.DefaultChallengeScheme = "Bearer";
})
.AddJwtBearer("Bearer", options =>
{
options.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = false,
ValidateAudience = false,
ValidateLifetime = true,
ValidateIssuerSigningKey = true,
RoleClaimType = System.Security.Claims.ClaimTypes.Role,
ClockSkew = TimeSpan.Zero, // ← Important!
IssuerSigningKey = new SymmetricSecurityKey( Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
};
});
//Swagger with Bearer support
builder.Services.AddSwaggerGen(options =>
{
options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.Http,
Scheme = "bearer",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "Enter your JWT token only (without 'Bearer' prefix)."
});
options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}
});
});
//Middleware order matters!
app.UseAuthentication();
app.UseAuthorization();
The most important line here:
ClockSkew = TimeSpan.Zero
By default ASP.NET Core adds a 5-minute buffer to token expiry. So a token set to expire at 3:00 PM actually expires at 3:05 PM. That drives me crazy when testing. Setting ClockSkew = TimeSpan.Zero makes tokens expire exactly when you set them — no surprises.
Step 6 — appsettings.json
{
"Jwt":
{
"Key": "YourSuperSecretKeyHereMustBe32CharsMin!"
},
"ConnectionStrings":
{
"Default": "Server=...;Database=HRMS;..."
}
}
Important: Never commit your real JWT key to GitHub! Add appsettings.json to .gitignore or use environment variables in production.
The Before vs After Story
When I first implemented login, it looked like this:
// OLD — Simple JWT, no refresh token
public async Task<string> Login(LoginDto dto)
{
var user = await _context.Users .FirstOrDefaultAsync(x => x.Email dto.Email);
if (user null) return "Invalid";
if (!BCrypt.Net.BCrypt.Verify(dto.Password, user.PasswordHash))
return "Invalid";
return GenerateToken(user); // Just returns access token
}
The problem: When the access token expired, users got logged out and had to log in again. For an HRMS portal where HR managers are working all day — that's really annoying.
The refresh token approach fixes this silently in the background. The Angular frontend detects a 401 response, automatically calls /api/auth/refresh, gets a new access token, and retries the original request — all without the user ever knowing their token expired.
Complete Flow Summary:
POST /api/auth/login
→ Returns: { accessToken, refreshToken }
Every API request:
→ Header: Authorization: Bearer {accessToken}
Access token expires (401 response):
→ POST /api/auth/refresh?refreshToken={refreshToken}
→ Returns: { accessToken } (new one)
User logs out:
→ Set IsRevoked = true on refresh token in DB
→ Both tokens now dead
Key Takeaways:
Always use two tokens — short access token for security, long refresh token for user experience.
Store refresh tokens in DB — this is what allows you to revoke them instantly. If you store them only on the client side, you can never invalidate them.
Set ClockSkew to Zero — unless you enjoy debugging token expiry issues at weird times.
BCrypt for passwords — never plain text, never MD5, never SHA1. BCrypt only.
Check three things on refresh — token exists, not revoked, not expired. Skip any one of these and you have a security hole.
Conclusion
JWT with refresh tokens sounds complicated until you break it down step by step. The actual code isn't that large — it's just understanding why each piece exists.
The access token is your fast key. The refresh token is your backup key stored in a safe. Short-lived tokens keep you secure. Long-lived refresh tokens keep your users happy.
If this helped you, subscribe for 3 practical .NET articles every week — all from real production code just like this! 🚀