Implementing JWT Bearer Authentication In ASP.NET Core Razor Pages

JSON Web Tokens (JWTs) provide a compact way to represent a user’s identity and permissions between an ASP.NET Core application and a client. In a Razor Pages solution, JWT bearer authentication is especially useful when pages call separate Web APIs, JavaScript components, mobile apps, or services hosted in Microsoft Azure.

The important design decision is understanding where the token travels. A browser does not automatically attach a bearer token when a user moves between Razor Pages. JWT authentication works cleanly when the browser deliberately sends an Authorization: Bearer header, while traditional Razor Pages navigation often suits cookie authentication better. Selecting the right model early avoids awkward security workarounds later.

Choosing The Right Authentication Shape

A Razor Pages application can use JWT bearer authentication to protect page handlers, but the request must contain a valid bearer token. This commonly happens when a JavaScript client calls a protected handler or when another application consumes an endpoint hosted by the Razor Pages project.

For a standard server-rendered website, cookie authentication is usually more natural. The user signs in once, the server issues an encrypted authentication cookie, and subsequent page requests carry that cookie automatically. JWTs become a strong option when the same identity must be accepted by an API, a React or Blazor front end, a mobile client, and background services.

A practical architecture for an Australian business might use Razor Pages for an administration portal, an ASP.NET Core API for customer data, and Azure App Service in Australia East. The portal could use cookies for its page navigation while the API validates access tokens issued by Microsoft Entra ID or another identity provider. Mixing schemes is possible, but each endpoint should clearly state which scheme it expects.

Bearer tokens are self-contained. They normally include a subject identifier, issuer, audience, expiry time, and optional roles or scopes. The API validates the token’s signature and claims rather than querying a session store for every request. This improves scalability, although revoking an already-issued token requires a short lifetime, a deny list, or an identity provider with revocation support.

Preparing The ASP.NET Core Application

Install the JWT bearer package that matches the application’s target framework:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Register authentication and authorisation in Program.cs. The signing key should come from a managed secret store, environment variable, or development secret rather than being committed to source control.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

var signingKey = builder.Configuration["Jwt:SigningKey"]
    ?? throw new InvalidOperationException("JWT signing key is missing.");

builder.Services.AddRazorPages(options =>
{
    options.Conventions.AuthorizeFolder("/Admin");
});

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(signingKey)),

        ValidateIssuer = true,
        ValidIssuer = builder.Configuration["Jwt:Issuer"],

        ValidateAudience = true,
        ValidAudience = builder.Configuration["Jwt:Audience"],

        ValidateLifetime = true,
        ClockSkew = TimeSpan.FromMinutes(1)
    };
});

builder.Services.AddAuthorization();

var app = builder.Build();

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

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

app.MapRazorPages();

app.Run();

The middleware order matters. Routing must run before authentication and authorisation can evaluate endpoint metadata. Authentication identifies the caller; authorisation then decides whether that caller can access the selected page or handler. If UseAuthentication() is omitted, HttpContext.User will not be populated from the token.

A configuration file can define the issuer and audience without exposing the signing key:

{
  "Jwt": {
    "Issuer": "https://login.example.com",
    "Audience": "customer-api"
  }
}

For an Australian deployment, Azure Key Vault is a sensible location for production secrets. Teams handling health, financial, or government-related information should also consider the hosting region, access logging, retention rules, and obligations under the Privacy Act 1988. Australia East in New South Wales and Australia Southeast in Victoria are common Azure regions, but the selected region should match contractual and data-residency requirements.

Issuing And Validating Access Tokens

The component that issues a token must authenticate the user first. A real system should normally delegate this responsibility to Microsoft Entra ID, an approved OpenID Connect provider, or a dedicated identity server. Creating a token after checking a password in a custom controller is possible, but password storage, multi-factor authentication, account recovery, lockout, and breach monitoring quickly become substantial responsibilities.

A simplified token creation example illustrates the required claims:

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;

var claims = new[]
{
    new Claim(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
    new Claim(ClaimTypes.Name, user.Email),
    new Claim(ClaimTypes.Role, "Manager")
};

var credentials = new SigningCredentials(
    new SymmetricSecurityKey(Encoding.UTF8.GetBytes(signingKey)),
    SecurityAlgorithms.HmacSha256);

var token = new JwtSecurityToken(
    issuer: configuration["Jwt:Issuer"],
    audience: configuration["Jwt:Audience"],
    claims: claims,
    expires: DateTime.UtcNow.AddMinutes(15),
    signingCredentials: credentials);

var accessToken = new JwtSecurityTokenHandler().WriteToken(token);

Use UTC for token dates and keep access tokens short-lived. A refresh token, if required, should be handled as a separate credential with stronger storage and rotation rules. Never place passwords, payment details, or unnecessary personal information inside a JWT. Anyone holding the token can decode its payload, even though they cannot alter it without invalidating the signature.

Protect a Razor Page with the Authorize attribute:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize]
public class ReportsModel : PageModel
{
    public string? CurrentUser { get; private set; }

    public void OnGet()
    {
        CurrentUser = User.Identity?.Name;
    }
}

Roles and policies provide more precise controls:

[Authorize(Policy = "Reports.Read")]
public class ReportsModel : PageModel
{
}

The policy must be registered with a matching claim requirement:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("Reports.Read", policy =>
        policy.RequireClaim("scope", "reports.read"));
});

Keep claim names consistent with the identity provider. A token containing roles is not automatically equivalent to one containing a scope claim, and a mismatch can produce confusing 403 responses after authentication has succeeded.

Calling Protected Razor Page Handlers

A client must send the token in the standard HTTP header:

GET https://localhost:5001/Admin/Reports
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

A JavaScript client can add the header when calling a handler or API endpoint:

const response = await fetch("/Admin/Reports?handler=Summary", {
    headers: {
        "Authorization": `Bearer ${accessToken}`
    }
});

The page model can expose a handler protected by the same page-level policy:

[Authorize]
public class ReportsModel : PageModel
{
    public IActionResult OnGetSummary()
    {
        var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);

        return new JsonResult(new
        {
            UserId = userId,
            Status = "Available"
        });
    }
}

When an unauthenticated request arrives, ASP.NET Core returns a challenge, commonly a 401 response for bearer authentication. An authenticated user without sufficient claims receives a 403 response. These statuses are useful diagnostics: a 401 generally points to a missing, expired, malformed, or incorrectly signed token, while a 403 usually indicates a role, scope, or policy problem.

Avoid placing long-lived access tokens in browser local storage unless the application’s risk assessment accepts the consequences. A successful cross-site scripting attack can read local storage and send the token elsewhere. In many browser applications, keeping tokens in memory and using a secure, carefully designed refresh flow reduces exposure. If a token is placed in a cookie, configure Secure, HttpOnly, and an appropriate SameSite value, then assess cross-site request forgery risks.

Razor Pages forms still need antiforgery protection when cookies authenticate the request. Bearer tokens reduce the classic cookie-based CSRF pattern because the browser does not attach the header automatically, but they do not remove the need to prevent cross-site scripting. Encode output, validate input, apply a strong Content Security Policy where practical, and keep third-party scripts under control.

Operating Securely In Australian Environments

Australian users often expect fast responses across a large geography, from Perth to Brisbane and from Melbourne to regional New South Wales. Hosting an API in an Australian Azure region can reduce latency for local customers, but performance still depends on database placement, CDN configuration, private networking, and the location of external identity services.

Australian organisations also tend to assess security against the Essential Eight, industry-specific rules, and customer procurement requirements. JWT validation supports several of these controls, but it is only one part of the design. Apply HTTPS everywhere, rotate signing keys, restrict administrator access, patch dependencies, and send security events to a monitored logging platform. Do not log complete bearer tokens; redact the Authorization header and record safe identifiers such as issuer, audience, subject, and failure reason.

Deployment checks

• Store signing keys in Azure Key Vault or an equivalent managed secret service.
• Use distinct issuers, audiences, and keys for development, testing, and production.
• Set short access-token lifetimes and rotate refresh credentials.
• Confirm that application logs and backups do not contain token payloads or passwords.

A token issued for a staging API must not be accepted by production. Validate issuer and audience explicitly, and avoid accepting several audiences simply because it makes testing easier. When using RSA or an external identity provider, validate the signing certificate or discovery document and plan for key rollover.

Operational checks

• Alert on repeated invalid-token, expired-token, and forbidden-request events.
• Review roles and scopes whenever staff change teams or leave the organisation.
• Test clock differences between servers, especially across distributed services.
• Document data handling for customers in Sydney, Melbourne, Perth, and regional areas.

Clear documentation helps support teams explain a failed sign-in without resorting to guesswork. In an Australian workplace, someone might say a request is “bung” or that a deployment needs another “arvo” to settle, but the logs should provide precise technical evidence: whether the token was absent, expired, signed by an unknown key, aimed at the wrong audience, or rejected by a policy.

JWT bearer authentication is effective when its boundary is clear. Use it for APIs and clients that deliberately carry access tokens, validate every important claim, and avoid forcing it into ordinary page navigation where secure cookies may provide a simpler and safer user experience.