skip to content

With Hangfire on ASP.NET Core, why does the dashboard work on a developer machine but return 401 once deployed, and how do you secure it properly?

level: middleimportance: must knowfreq 52%

answer

  1. default filter: LocalRequestsOnlyAuthorizationFilter
  2. 401 when anonymous, 403 when signed in
  3. DashboardOptions.Authorization replaces the default
  4. MapHangfireDashboardWithAuthorizationPolicy
  5. IsReadOnlyFunc and DisplayStorageConnectionString

basics

~10 s

DashboardOptions.Authorization defaults to LocalRequestsOnlyAuthorizationFilter, which admits only loopback or same-IP requests, so a deployed dashboard answers 401. Replace it with your own IDashboardAuthorizationFilter, or map it with MapHangfireDashboardWithAuthorizationPolicy and an ASP.NET Core policy.

solid answer

~40 s

`app.MapHangfireDashboard()` with default `DashboardOptions` runs `LocalRequestsOnlyAuthorizationFilter`: it allows a request only when the remote IP is loopback (`127.0.0.1`, `::1`) or equals the local IP. On a laptop that is true; behind a load balancer or in a container it never is, so every request fails and Hangfire writes **401** for an anonymous user or **403** for a signed-in one. The fix is to say who may see it: set `DashboardOptions.Authorization` to your own `IDashboardAuthorizationFilter` (or `AsyncAuthorization` with `IDashboardAsyncAuthorizationFilter`) that reads `context.GetHttpContext().User`, or call `app.MapHangfireDashboardWithAuthorizationPolicy("HangfireAdmins")`, which clears Hangfire's filters and applies `RequireAuthorization` to the endpoint. Also set `IsReadOnlyFunc` for viewers who must not requeue or delete jobs, and `DisplayStorageConnectionString = false`, which is `true` by default. Never 'fix' it with a filter that returns `true`.

code

csharp · 23 lines
csharp
using Hangfire;
using Hangfire.Dashboard;

// Option 1: Hangfire filters
app.MapHangfireDashboard("/ops/jobs", new DashboardOptions
{
    Authorization = [new OpsRoleFilter()],          // replaces LocalRequestsOnlyAuthorizationFilter
    IsReadOnlyFunc = ctx => !ctx.GetHttpContext().User.IsInRole("ops-admin"),
    DisplayStorageConnectionString = false
});

public sealed class OpsRoleFilter : IDashboardAuthorizationFilter
{
    public bool Authorize(DashboardContext context)
    {
        var user = context.GetHttpContext().User;
        return user.Identity?.IsAuthenticated == true
            && (user.IsInRole("ops") || user.IsInRole("ops-admin"));
    }
}

// Option 2 instead: an ASP.NET Core policy registered with AddAuthorization
// app.MapHangfireDashboardWithAuthorizationPolicy("HangfireAdmins", "/ops/jobs");

go deeper

for a junior

Remember that the Hangfire dashboard allows only local requests by default, so a deployed one answers 401 until you configure authorization.

for a middle

Explain LocalRequestsOnlyAuthorizationFilter, the 401 versus 403 rule, and the two ways to secure it: an IDashboardAuthorizationFilter or MapHangfireDashboardWithAuthorizationPolicy.

for a senior

Harden the dashboard: role-based read-only access through IsReadOnlyFunc, a hidden connection string, antiforgery on actions, and no personal data in job arguments.

for a principal

Treat the dashboard as a privileged operations console: who may run destructive actions on production jobs, and how that access is granted and audited.

## What the dashboard is The **Hangfire dashboard** is a small web UI served by your own application, from Hangfire.AspNetCore. It lists jobs by state, shows exceptions and arguments, lists servers and recurring jobs, and lets the user **requeue, delete and trigger** jobs. That last part makes it an admin surface over production work, which is why Hangfire ships it locked down. It is mounted with `app.MapHangfireDashboard(pattern = "/hangfire", options)` (endpoint routing) or the older `app.UseHangfireDashboard(pathMatch, options)` (middleware branch). ## Why it returns 401 after deployment `DashboardOptions.Authorization` defaults to a single `LocalRequestsOnlyAuthorizationFilter`. For every dashboard request it checks the connection's remote IP: - allowed: `127.0.0.1`, `::1`, an IPv4-mapped loopback, or a remote IP equal to the local IP; - denied: everything else, including an unknown remote IP. Running locally, the browser is on loopback. Deployed, the request arrives from a load balancer, an ingress controller or the internet, and the check fails. Hangfire then sets the status code itself: | User state | Status | |---|---| | not authenticated | **401 Unauthorized** | | authenticated but rejected by a filter | **403 Forbidden** | | POST without a valid antiforgery token | **403 Forbidden** | The antiforgery check applies to the dashboard's actions (requeue, delete) when `IAntiforgery` is registered and `IgnoreAntiforgeryToken` is `false`, the default. ## Securing it: two supported ways **1. A Hangfire authorization filter.** Implement `IDashboardAuthorizationFilter.Authorize(DashboardContext)` (or `IDashboardAsyncAuthorizationFilter.AuthorizeAsync` when the decision needs I/O). `context.GetHttpContext()` returns the ASP.NET Core `HttpContext`, so the filter can check `User.Identity.IsAuthenticated`, a role or a claim. Assigning `Authorization` **replaces** the default list; every filter in it must pass. **2. An ASP.NET Core authorization policy.** `app.MapHangfireDashboardWithAuthorizationPolicy("HangfireAdmins")` calls `MapHangfireDashboardWithNoAuthorizationFilters` (which empties both filter lists) and then `.RequireAuthorization("HangfireAdmins")` on the endpoint. Authentication schemes, challenges and the policy itself are then ordinary ASP.NET Core authorization, so an unauthenticated browser gets the scheme's normal challenge. Either way, authentication middleware must have populated `HttpContext.User` before the dashboard runs. ## Hardening the options - **`IsReadOnlyFunc`** (default `_ => false`): return `true` for support staff so the dashboard hides requeue, delete and trigger. - **`DisplayStorageConnectionString`** (default `true`): set `false`; the servers page otherwise shows storage connection details. - **`AppPath`** (default `"/"`): the back-link target; point it at the admin area or set `null` to hide it. - Job arguments are visible in the dashboard, which is one more reason to pass ids rather than personal data. ## Mapping details - `MapHangfireDashboard` throws at startup if `AddHangfire` was not called, because it needs the registered `JobStorage`. - A custom path such as `/ops/jobs` is fine; the dashboard builds its links relative to it. - Map it after authentication is configured, and remember that in a split deployment the dashboard can run in any process that has the storage configured, even one without `AddHangfireServer`. ## What not to do 1. A filter that returns `true` unconditionally publishes job control to anyone who finds `/hangfire`. 2. `MapHangfireDashboardWithNoAuthorizationFilters` without `RequireAuthorization` does the same. 3. Relying on the URL being obscure is not access control.

  • Why would forwarded-headers configuration not be a good fix for the 401?
    Restoring the client's real IP only makes `LocalRequestsOnlyAuthorizationFilter` evaluate the user's address, which is still not loopback. The filter exists to keep the dashboard local; production needs an identity-based filter or policy instead.
  • A signed-in operator gets 403 when clicking Requeue but can browse pages; what is likely wrong?
    Browsing passed the authorization filters, so the 403 on the POST points at the antiforgery check (missing or invalid token, often from a cached page or a proxy stripping cookies) or at an `IsReadOnlyFunc` that marks the user read-only. Check whether the request carries a valid antiforgery token before loosening anything.

  • The dashboard is open to everyone by default, so it must be removed in production.
  • Returning true from a custom filter is fine because the URL is not linked anywhere.
  • Adding a filter to Authorization keeps LocalRequestsOnlyAuthorizationFilter as well.
  • Hangfire returns 404 for an unauthorized dashboard request.
  • MapHangfireDashboardWithNoAuthorizationFilters is a safe default for internal apps.