Secure the API
Out of the box the API runs wide open, and there’s no authentication code in it at all. That’s lovely on a laptop and less lovely in production, so here’s how to close the door.
Turn it on
Section titled “Turn it on”-
Create the solution with
--include-auth, and tell it who issues tokens and who they’re for:Terminal window dotnet new cleangraphqlapi --name WorksOnMyMachine.Movies \--include-auth --authority https://login.example.com --audience https://movies.example.com--authorityis required with--include-auth, sodotnet newstops and says so if it’s missing. To point each environment at its own server, override the settings inappsettings.jsonor with environment variables:Terminal window Authentication__Authority=https://login.example.comAuthentication__Audience=https://movies.example.com -
Get a token from the authority for that audience, and send it.
Terminal window curl -X POST "https://localhost:7331/graphql" -H "Authorization: Bearer eyJhbGciOi..." \-H "Content-Type: application/json" -d '{"query":"{ movies { totalCount } }"}'In Nitro, open the connection settings and add the token under Authentication.
Add it to a solution you already have
Section titled “Add it to a solution you already have”Created the solution without --include-auth? The code isn’t hiding behind a setting, it isn’t there at all, so it goes in by hand. The quickest way to see every line is to let the template show you. Create a second solution with the same name and --include-auth next to yours, then compare the two:
dotnet new cleangraphqlapi --name WorksOnMyMachine.Movies --output ../with-auth \ --include-auth --authority https://login.example.com --audience https://movies.example.comgit diff --no-index src ../with-auth/srcgit diff --no-index tests ../with-auth/testsCopy across what’s new: the Microsoft.AspNetCore.Authentication.JwtBearer package reference, the Authentication folder and its section in appsettings.json, the authentication regions in startup, [Authorize] on the queries and mutations, the Hot Chocolate authorization package, the ApplyPolicy enum in the schema snapshot, and the authentication tests, so coverage stays where it was. The optional-token-auth skill in .agents/skills walks your coding agent through the same steps.
What changes
Section titled “What changes”-
The protected fields answer with an error instead of data when the token is missing, from the wrong issuer or for the wrong audience. The HTTP status stays
200, because that’s how GraphQL does it.{ "errors": [ { "message": "The current user is not authorized to access this resource.", "extensions": { "code": "AUTH_NOT_AUTHENTICATED" } } ] } -
The
versionquery needs one too. The schema, Nitro,/health/liveand/health/readystay open, so load balancers and curious humans can still check the lights are on. -
Tokens are validated against the authority’s published keys, so there’s no secret to store and nothing to rotate on your side.
How it works
Section titled “How it works”AuthenticationSettings reads the Authentication section, and the API registers the JWT bearer handler, the normal authorization services and Hot Chocolate’s authorization. Every movie, author and review query, every mutation and the version query carry [Authorize]. An empty authority still lets every request through, which is how the tests run, so make sure every environment you deploy to sets one.
Beyond a bearer token
Section titled “Beyond a bearer token”Scopes, roles and per-field policies are a short step from here: add policies to AddAuthorization and ask for them with [Authorize(Policy = "policy")]. Which claims to check depends entirely on your identity provider, so the template stops at the door and lets you decide who gets past it.