Chapter 25: Authentication and authorization for APIs

Introduction

This chapter introduces how API authentication differs from cookie-based web-app authentication and previews JWT-based authentication, testing, OpenAPI integration, and authorization for minimal APIs.

• API authentication landscape: Describe how authentication for API applications differs from traditional web applications and why APIs often need different solutions. State that traditional web apps commonly use encrypted cookies decoded by AuthenticationMiddleware, whereas APIs may need to support users across traditional, client-side, and mobile applications.
  Why it matters: This distinction explains why API security commonly relies on tokens instead of the browser-cookie approach used by traditional web apps.
• JWT authentication workflow: Trace the chapter's planned JWT authentication workflow: learn API authentication patterns and protocols, add JWT bearer authentication to a minimal API, and create JWTs locally with the .NET CLI to test it. Identify OAuth 2.0 and OpenID Connect as protocols introduced for API and distributed-application authentication, and JWTs as the typical access tokens discussed.
  Why it matters: This is the practical path the chapter uses to secure and locally test a minimal API.
• API security integration: Describe the remaining integration steps for an authenticated minimal API: declare authentication requirements in an OpenAPI document so Swagger UI can send authenticated requests, and apply authorization policies to restrict which users can call endpoints. Explain that API authorization uses the same claims, requirements, handlers, and policies introduced for Razor Pages.
  Why it matters: Authentication identifies a caller, but OpenAPI tooling and authorization policies make that security usable and enforce endpoint access rules.

Key terms: encrypted cookies, AuthenticationMiddleware, API applications, traditional web apps, OAuth 2.0, OpenID Connect, JSON Web Tokens, JWTs, JWT bearer authentication, .NET CLI

25.1 Authentication for APIs and distributed applications

Introduces why API authentication differs from traditional web-app authentication and previews common distributed-application patterns and protocols.

• API authentication overview: Describe that this section introduces authentication for API applications, including why it commonly differs from authentication in traditional web apps and the patterns and protocols involved.
  Why it matters: This overview frames the authentication approaches used for APIs and distributed applications in the following sections.

Key terms: authentication, API applications, traditional web apps, distributed applications

25.1.1 Extending authentication to multiple apps

This section explains why cookie-based authentication suits a single traditional web app but becomes difficult to manage when one user interacts with multiple apps and APIs.

• Cookie authentication request flow: Trace the traditional web-app authentication flow: signing in creates an encrypted cookie containing a serialized ClaimsPrincipal with the user's ID and claims, and later browser requests send that cookie back. Explain that AuthenticationMiddleware decodes and deserializes it to set the current user for the request.
  Why it matters: This establishes the cookie-based approach whose limits become apparent in distributed applications.
• Single-app cookie suitability: Describe the kind of traditional application for which the cookie authentication flow works well: one web app handles user authentication and management, serves application data, executes business logic, and generates the user interface.
  Why it matters: Cookie authentication is straightforward when one application owns the whole user-facing experience and its user management.
• Distributed authentication challenges: Explain why independently managed authentication becomes unmanageable across multiple apps and APIs serving the same logical user. Include the duplicated sign-in logic, shared user-data need, repeated sign-ins, and the limitations of domain-bound cookies for mobile clients or requests spanning multiple domains; state that authentication should move to a separate service.
  Why it matters: A separate authentication service avoids making every application independently solve identity and sign-in for the same users.

Key terms: encrypted cookie, ClaimsPrincipal, claims, AuthenticationMiddleware, traditional web app, authentication, user management, business logic, mobile applications, single-page applications

25.1.2 Centralizing authentication in an identity provider

This section explains how a centralized identity provider authenticates users for multiple applications and APIs, why this architecture is valuable, and the trade-offs between third-party and self-built providers.

• Centralized identity-provider flow: Describe how authentication moves from individual applications to a central identity provider. Explain that an app redirects the user to the provider, the provider authenticates the user and returns bearer tokens to the client, and the client presents those tokens to APIs without the APIs managing users or reauthenticating them.
  Why it matters: This architecture lets multiple applications trust a common authentication service instead of each implementing sign-in themselves.
• Bearer token purpose: State that bearer tokens are strings containing authentication details about a user or application, typically signed to prevent tampering, and that JWT is their most common format. Explain that the tokens communicate who the user is and what they may access.
  Why it matters: Bearer tokens are the information APIs use to identify authenticated callers without directly managing their sign-in.
• Centralization benefits: Explain why centralizing authentication can provide single sign-on across services, eliminate duplicated sign-in logic, isolate user management in a service with a single responsibility, and allow new external sign-in mechanisms to be added in one place.
  Why it matters: Centralization can make a multi-application system easier to maintain while giving users a smoother sign-in experience.
• Identity provider choices: Distinguish using a third-party identity provider from building one yourself. Explain why the section recommends reputable third-party providers where possible, and why self-hosted options such as OpenIddict or Duende IdentityServer still require the developer to implement user profiles, password validation, claims, and account-management and MFA user interfaces.
  Why it matters: Authentication bugs can become serious security vulnerabilities, so choosing who operates identity management is a major architectural and security decision.

Key terms: identity provider, bearer tokens, client, APIs, authentication, authorization, JWTs, signed, tampering, authentication details

25.1.3 OpenID Connect and OAuth 2.0

This section distinguishes OAuth 2.0 authorization from OpenID Connect authentication, illustrating their flows, common grant types, and relevance to API builders.

• OAuth 2.0 delegated authorization: Explain how OAuth 2.0 lets a user delegate an application's access to a protected resource without sharing their credentials or unnecessary identity information.
  Why it matters: This distinction prevents treating permission to access an API as proof of who the user is.
• Authorization code flow: Trace the authorization-code OAuth 2.0 flow in the dogphotos.com example, from redirection and user consent through code exchange and use of the access token to call the Facebook API.
  Why it matters: Knowing the flow clarifies how a third-party application obtains limited API access while the identity provider keeps the user's credentials.
• OpenID Connect identity extension: Describe how OpenID Connect builds on OAuth 2.0 to add authentication and retrieval of identity information, treating identity as a protected resource that requires user consent.
  Why it matters: OpenID Connect supplies the missing answer to which user made a request when an application needs identity as well as delegated API access.
• OAuth grant type choices: State the common OAuth 2.0 grant types named in this section and distinguish their intended scenarios: authorization code, PKCE, and client credentials.
  Why it matters: Choosing a flow suited to the scenario is safer than inventing a custom token exchange.

Key terms: OAuth 2.0, authorization protocol, delegated access, protected resource, identity provider, authorization code, access token, consent screen, secret, Facebook API

25.2 Understanding bearer token authentication

This section explains bearer-token authentication for APIs, focusing on JWT structure, token types and trade-offs, and how ASP.NET Core validates a JWT into an authenticated user.

• Bearer token security: Explain what a bearer token is and why possession alone grants access to a protected resource. Describe why bearer tokens must be protected like passwords, including avoiding URL query strings because they may be logged.
  Why it matters: Anyone who obtains a bearer token can use it, so accidental exposure can become an account or API-access breach.
• JWT composition and visibility: Describe a JSON Web Token (JWT) as base64-encoded header, payload, and signature parts joined by periods. Explain that the signature prevents tampering when validated with shared key material, but that a normal JWT is not encrypted and its contents can be read.
  Why it matters: Understanding both signature validation and readable payloads prevents trusting altered tokens or placing secrets in JWT claims.
• JWT claim meanings: Describe the purpose of the sub, aud, scope, and exp JWT claims. Explain that an API should check that its domain is in aud, scopes express the permissions consented to and are interpreted by the API, and exp limits how long a token is valid.
  Why it matters: These claims determine who or what the token represents, which API may accept it, what access it grants, and when that access ends.
• Access-token trade-offs: Distinguish self-contained access tokens from reference tokens, including their validation, privacy, revocation, and performance trade-offs. State that self-contained JWTs can be validated offline but generally cannot be revoked, whereas reference tokens require an identity-provider round trip but can be revoked and do not expose claims to the client.
  Why it matters: Choosing a token format balances API performance against revocation capability and claim privacy.
• JWT authentication pipeline: Trace how ASP.NET Core authenticates a request containing a JWT bearer token: the authentication middleware reads the Authorization header, decodes and validates the signature, audience, and expiration, then creates a ClaimsPrincipal and assigns it to HttpContext.User when valid. Distinguish middleware before authentication, which sees an unauthenticated request, from middleware after it, which sees an authenticated request.
  Why it matters: Middleware order determines whether later endpoint and authorization code receives an authenticated ClaimsPrincipal.

Key terms: bearer token, security token, protected resource, JWT, JSON Web Token, header, payload, claims, signature, sub

25.3 Adding JWT bearer authentication to minimal APIs

This section shows how to add JWT bearer authentication to a minimal API, protect an endpoint with authorization, and understand how authentication schemes select cookie or bearer-token behavior.

• JWT bearer API setup: Describe how to add JWT bearer authentication to an existing minimal API by installing the Microsoft.AspNetCore.Authentication.JwtBearer package and registering the required JWT authentication services. State that the same overall process applies to web API controller applications.
  Why it matters: Registering JWT bearer authentication lets an API validate bearer tokens sent by its clients.
• Endpoint authentication requirement: Explain that RequireAuthorization() adds a simple authenticated-user policy to a minimal API endpoint, analogous to applying [Authorize] to an MVC or web API controller. Describe that an unauthenticated request to that endpoint is rejected by authorization middleware with a 401 Unauthorized response.
  Why it matters: Authentication configuration does not protect an API endpoint until authorization is required for that endpoint.
• Authentication scheme selection: Explain that an authentication scheme has an ID and an authentication handler, which determines how a user is authenticated and how authentication or authorization failures are handled. Distinguish the JWT bearer handler, which reads a token from the Authorization header and returns 401 or 403, from the cookie handler, which reads a cookie and can redirect to login or access-denied pages.
  Why it matters: Authentication schemes explain why an API looks for a bearer token rather than a browser-oriented login cookie.
• Default scheme behavior: State that when an application registers only one authentication scheme, ASP.NET Core automatically makes it the default scheme. Explain that multiple schemes can be registered, but their selection and interaction must then be configured carefully.
  Why it matters: Knowing the default-scheme rule prevents unnecessary configuration in simple APIs and highlights the complexity of mixed authentication setups.

Key terms: Microsoft.AspNetCore.Authentication.JwtBearer, JWT bearer authentication, JWT bearer authentication scheme, minimal API, RequireAuthorization(), authorization policy, Is authenticated, [Authorize], 401 Unauthorized, authorization middleware

25.4 Using the user-jwts tool for local JWT testing

This section introduces the built-in user-jwts .NET CLI tool as a lightweight local identity provider for generating JWTs to test protected APIs.

• Local JWT testing purpose: Explain why a locally generated JWT is needed to test an API protected by JWT authentication, and contrast this with obtaining tokens from a production identity provider.
  Why it matters: You need a valid token to exercise authenticated and authorized API endpoints during local development.
• user-jwts local identity provider: Describe how the built-in user-jwts .NET CLI tool acts as a mini identity provider by generating JWTs with needed claims and signing material that the API can validate.
  Why it matters: The tool lets you create tokens that match the claims and signatures your locally configured API expects.
• User Secrets signing storage: State that user-jwts stores its signing key material in User Secrets, that the application uses that material to validate JWT signatures, and that the tool can enable User Secrets for the project when needed.
  Why it matters: Sharing the local signing material through User Secrets allows generated tokens and the API validator to work together without an extra installation step.

Key terms: JWT, JWT authentication, authorization policy, identity provider, OpenID Connect, user-jwts, .NET CLI, mini identity provider, claims, signing key material

25.4.1 Creating JWTs with the user-jwts tool

This section shows how to generate a development JWT with user-jwts and send it as a bearer token when testing a local API.

• Local JWT creation: Describe what running dotnet user-jwts create inside an API project does: it enables User Secrets if needed, stores signing-key material there, configures development JWT validation, and prints a newly created token.
  Why it matters: Creating a local token lets you test an API's authentication and authorization without setting up an external identity provider.
• Generated token defaults: State the default claims and matching validation values in a user-jwts token: sub and unique_claim use the operating-system username, aud contains each launchSettings.json application URL, and iss is dotnet-user-jwts.
  Why it matters: These defaults explain why a locally generated token is accepted whichever launch profile and application URL you use.
• Bearer authorization header: Explain how to send the generated JWT to the API by adding an Authorization header in the exact form Bearer <token>, with a space after Bearer, and relate malformed or missing header details to a 401 Unauthorized response.
  Why it matters: The API can authenticate the request only when the client sends the token in the required bearer-header format.

Key terms: user-jwts, dotnet user-jwts create, User Secrets, signing key material, appsettings.Development.json, JWT bearer authentication, sub, unique_claim, aud, iss

25.4.2 Customizing your JWTs

This section shows how to customize locally generated JWT claims and choose command output formats that suit interactive use or scripts.

• JWT claim customization: Describe how dotnet user-jwts create can customize a generated JWT with a name, additional claims, and scopes. State that --name sets the sub and unique_name claims, while --claim and --scope can each be supplied multiple times.
  Why it matters: Custom claims and scopes let local test tokens represent the users and permissions your API expects.
• JWT command output formats: Explain the --output choices for dotnet user-jwts create and when to use them. Distinguish the default summary-plus-token output from token-only output for easy script parsing and JSON output containing creation configuration details, with the token in the Token field rather than the JSON being the JWT payload.
  Why it matters: Choosing a machine-friendly output format makes automated local-token scripts easier and less error-prone.

Key terms: dotnet user-jwts create, --name, sub claim, unique_name claim, --claim, --scope, --output, default, token, json

25.4.3 Managing your local JWTs

This section explains where user-jwts stores local JWT configuration, how to manage those tokens safely, and why they are limited to development testing.

• Local JWT storage and scope: Describe where the user-jwts tool stores its JWT configuration and why those JWTs are intended only for local testing. Explain how development-only configuration helps prevent locally generated tokens from being used in production.
  Why it matters: Keeping test tokens out of production configuration reduces the risk of accidentally relying on insecure local credentials.
• JWT management commands: Describe how to manage JWTs saved for a project with the user-jwts tool, including inspecting, removing, and clearing tokens. Explain the consequence of resetting the stored signing key material.
  Why it matters: These commands let you inspect and clean up local test credentials without manually editing their configuration file.
• JWT use in API testing: State that a locally generated JWT must be included with API test requests, and distinguish the straightforward Postman setup from the additional OpenAPI description needed for Swagger UI.
  Why it matters: A valid local token has no effect unless the API client sends it with each request that needs authentication.

Key terms: user-jwts.json, User Secrets, <UserSecretsId>, appsettings.Development.json, appsettings.json, identity provider, dotnet user-jwts, list, clear, remove

25.5 Describing your authentication requirements to OpenAPI

This section shows how to describe API authentication in OpenAPI so Swagger UI can send JWT bearer tokens when testing protected endpoints.

• OpenAPI security definitions: Describe the two OpenAPI security configuration steps: define the security scheme used by the API and declare which endpoints use that scheme. Explain that, with Swashbuckle, AddSecurityDefinition() defines a scheme and AddSecurityRequirement() can declare the whole API protected by it.
  Why it matters: Accurate security metadata lets OpenAPI-based tools understand how callers must authenticate to your API.
• Swagger UI bearer tokens: Explain how Swagger UI uses the OpenAPI security requirement to let a tester authorize requests: choose Authorize, enter `Bearer <token>` with the prefix and a space, authorize, and Swagger UI sends the value in the Authorization header.
  Why it matters: This enables testing secured API endpoints in Swagger UI without manually constructing authorization headers for every request.
• Early authentication testing: Justify adding real authentication and authorization as soon as the API requirements are understood rather than disabling security for local testing or postponing it until late in development. Describe how user-jwts reduces local testing friction by generating suitable tokens, optionally with a long expiration.
  Why it matters: Testing with real security early exposes security-related bugs before late changes become costly and difficult.

Key terms: OpenAPI document, security scheme, OpenApiSecurityScheme, AddSecurityDefinition(), AddSecurityRequirement(), JWT bearer authentication, Swagger UI, Authorize, Bearer <token>, Authorization header

25.6 Applying authorization policies to minimal API endpoints

This section explains how to protect minimal API endpoints with declarative policies, resource-based authorization, and scope-based policies.

• Minimal API policy application: Describe how to apply authorization requirements and named policies to minimal API endpoints or route groups using RequireAuthorization(), and explain its equivalence to the [Authorize] attribute.
  Why it matters: Declarative authorization prevents requests from reaching endpoints unless the caller meets the required policy.
• Anonymous endpoint exceptions: State how AllowAnonymous() or [AllowAnonymous] excludes an endpoint from authentication requirements despite broader authorization requirements.
  Why it matters: Explicit anonymous access lets a public endpoint remain available when surrounding endpoints or groups require authorization.
• Resource authorization workflow: Trace resource-based authorization in a minimal API handler: load the resource, inject IAuthorizationService, call AuthorizeAsync() with HttpContext.User, the resource, and a policy, then continue or return 403 Forbidden based on the result.
  Why it matters: Resource checks enforce rules such as allowing users to edit or delete only recipes they created.
• Authorization placement trade-offs: Explain the trade-offs among leaving resource authorization in endpoint handlers, extracting it to endpoint filters, or moving it into domain services, including duplication, endpoint simplicity, complexity, and dependence on ASP.NET Core abstractions.
  Why it matters: Choosing where checks live affects whether authorization is consistently enforced and whether endpoint code stays maintainable.
• Scope-based API policies: Explain that scopes in bearer tokens have no inherent enforcement behavior, so an API defines their meaning by creating authorization policies, such as requiring the recipe.edit scope, and can use scopes for whole-API access or client partitioning.
  Why it matters: Scope policies let an API express which token permissions are required for particular operations or categories of clients.

Key terms: RequireAuthorization(), [Authorize], policy, route group, minimal API endpoint, AllowAnonymous(), [AllowAnonymous], authentication requirements, resource-based authorization, AuthorizationHandler<TRequirement, TResource>

25.7 Summary

This summary recaps centralized identity, JWT bearer authentication and testing, and how to document and enforce API authorization in ASP.NET Core.