Implementing OAuth2 and JWT in ASP.NET Core APIs

 

Module 1: Introduction to API Security in ASP.NET Core

API security is the foundation of modern web applications. Imagine you're developing an online banking app—unauthorized access could lead to financial losses or identity theft. ASP.NET Core provides built-in tools for security, but combining them with OAuth 2.0 and JWT elevates your protection.

Why OAuth 2.0 and JWT?

• OAuth 2.0: An open standard for authorization, allowing third-party apps to access resources without sharing credentials. Real-life example: Logging into a fitness app with your Google account.
• JWT: A compact, self-contained token for securely transmitting information. It's like a digital passport that verifies identity without constant database checks.

Pros of Using OAuth 2.0 with JWT:

• Scalable for microservices.
• Reduces password fatigue for users.
• Supports single sign-on (SSO).

Cons:

• Complexity in setup can lead to misconfigurations (e.g., token leaks).
• JWTs are stateless, so revoking them requires extra mechanisms like blacklisting.

Alternatives:

• Basic Auth: Simple but insecure (sends credentials in base64).
• API Keys: Good for machine-to-machine, but not for user auth.
• OpenID Connect (OIDC): Builds on OAuth 2.0 for authentication—consider it as an extension.

Best Practices and Standards:

• Follow RFC 6749 (OAuth 2.0) and RFC 7519 (JWT).
• Always use HTTPS to prevent man-in-the-middle attacks.
• Implement rate limiting to avoid brute-force attempts.

Interactive Element: Question: In a real-world e-commerce API, would you use OAuth for user login or just JWT? (Hint: Combine them—OAuth for flow, JWT for tokens.)

To get started, create a new ASP.NET Core Web API project:

bash

dotnet new webapi -o SecureApiDemo

cd SecureApiDemo

This sets up a basic API. Run it with dotnet run and test the default WeatherForecast endpoint via Postman or curl.

Example 1: Basic Unsecured API In Program.cs, the default setup has no auth. Add a simple GET endpoint in WeatherForecastController.cs:

csharp

[ApiController]

[Route("[controller]")]

public class WeatherForecastController : ControllerBase

{

[HttpGet]

public IEnumerable<WeatherForecast> Get()

{

// Return random weather data

return Enumerable.Range(1, 5).Select(index => new WeatherForecast

{

Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),

TemperatureC = Random.Shared.Next(-20, 55),

Summary = Summaries[Random.Shared.Next(Summaries.Length)]

});

}

}

This is unsecured—anyone can access it. In the next module, we'll lock it down.

Example 2: Real-Life Scenario - Unsecured E-Commerce Cart API Imagine an endpoint /api/cart that exposes user cart items without auth. Vulnerability: Attackers could view others' carts by guessing IDs. We'll fix this later.

This module sets the stage. Word count so far: ~500. Let's build on it.

Module 2: Deep Dive into OAuth 2.0 Fundamentals

OAuth 2.0 isn't authentication—it's authorization. It defines roles like Client (your app), Resource Owner (user), Authorization Server (e.g., Auth0), and Resource Server (your API).

Key Flows in OAuth 2.0

1. Authorization Code Flow: Secure for web apps with backend. User redirects to auth server, gets code, exchanges for token.
2. Client Credentials Flow: For server-to-server, no user involved.
3. Implicit Flow: Deprecated due to security risks—avoid it.
4. PKCE (Proof Key for Code Exchange): Enhances security for SPAs.

Real-Life Example: In a social media analytics tool, use Authorization Code Flow to let users grant access to their Twitter data without sharing passwords.

Pros:

• Delegated access control.
• Supports scopes (e.g., read:profile, write:posts).

Cons:

• Requires a trusted auth server.
• Token expiration management is tricky.

Alternatives:

• SAML: Older, XML-based, good for enterprises but verbose.
• API Gateway patterns (e.g., AWS API Gateway with Cognito).

Best Practices:

• Use short-lived access tokens (e.g., 1 hour) and refresh tokens.
• Validate tokens against the issuer's public keys.
• Adhere to OAuth 2.1 draft for improved security.

Interactive Element: Try It Yourself: Set up a free Auth0 account and create an application. Note the Client ID and Secret—they'll be used later.

Code Example 1: Setting Up OAuth in ASP.NET Core (Basic Config) Install packages:

bash

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

dotnet add package Microsoft.IdentityModel.Tokens

In Program.cs (for .NET 8+ minimal APIs or full setup):

csharp

var builder = WebApplication.CreateBuilder(args);

// Add JWT Bearer authentication

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)

.AddJwtBearer(options =>

{

options.Authority = "https://your-auth-server.com"; // e.g., Auth0 domain

options.Audience = "your-api-audience";

options.TokenValidationParameters = new TokenValidationParameters

{

ValidateIssuer = true,

ValidIssuer = "https://your-auth-server.com",

ValidateAudience = true,

ValidAudience = "your-api-audience",

ValidateLifetime = true

};

});

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();

app.UseAuthorization();

app.Run();

This configures the app to expect JWTs from an OAuth server.

Code Example 2: Realistic Scenario - OAuth for Healthcare API For a patient portal API, add scopes. In auth server config, define scopes like "read:patients". In code, protect endpoint:

csharp

[HttpGet("patients")]

[Authorize(Policy = "ReadPatients")]

public IActionResult GetPatients()

{

// Logic to fetch patients

return Ok("Secure data");

}

In services:

csharp

builder.Services.AddAuthorization(options =>

{

options.AddPolicy("ReadPatients", policy => policy.RequireClaim("scope", "read:patients"));

});

This ensures only tokens with the right scope access it.

Question for Readers: What if a token expires mid-session? (Answer: Use refresh tokens—covered in advanced modules.)

Module 3: Mastering JWT in ASP.NET Core

JWT consists of Header (algorithm), Payload (claims), and Signature. It's base64-encoded but not encrypted—don't put secrets in payload!

Generating and Validating JWTs

• Generate on auth server.
• Validate on API side.

Real-Life Example: In an e-learning platform, JWT carries user roles (student/teacher) for personalized content.

Pros:

• Stateless—no session storage needed.
• Fast validation.

Cons:

• Once issued, hard to revoke without extra logic.
• Larger than session cookies.

Alternatives:

• Opaque tokens: Require introspection calls to auth server.
• Cookies with CSRF protection for web apps.

Best Practices:

• Use RS256 (asymmetric) over HS256 for public APIs.
• Include standard claims: iss (issuer), aud (audience), exp (expiration).
• Follow JWT Best Practices RFC 8725.

Interactive Element: Decode a sample JWT at jwt.io. Paste: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Code Example 1: Generating JWT Locally (For Testing) Install System.IdentityModel.Tokens.Jwt:

csharp

using System.IdentityModel.Tokens.Jwt;

using Microsoft.IdentityModel.Tokens;

using System.Text;

var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your-secret-key-min-32-chars"));

var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

var token = new JwtSecurityToken(

issuer: "your-issuer",

audience: "your-audience",

claims: new[] { new Claim("role", "admin") },

expires: DateTime.Now.AddMinutes(30),

signingCredentials: credentials

);

var tokenHandler = new JwtSecurityTokenHandler();

var jwtString = tokenHandler.WriteToken(token);

Use this for dev testing, but in production, use an auth server.

Code Example 2: Validating JWT in API Extend Module 2's config. Add to endpoint:

csharp

[HttpGet("secure")]

[Authorize]

public IActionResult SecureEndpoint()

{

var userName = User.Identity.Name; // From JWT claims

return Ok($"Hello, {userName}! This is secure.");

}

Real-life: In a blogging API, check "role" claim for admin posts.

Example 3: Advanced JWT with Custom Claims Add custom claim for user preferences:

csharp

claims: new[]

{

new Claim("role", "user"),

new Claim("preferred_theme", "dark") // Custom

}

In API, read: User.FindFirst("preferred_theme")?.Value;

Module 4: Implementing Basic Authentication with OAuth and JWT

Now, let's integrate. We'll use Duende IdentityServer (open-source) as auth server for realism.

Setup IdentityServer

Create a separate project:

bash

dotnet new web -o IdentityServerDemo

Install Duende.IdentityServer.

In Program.cs:

csharp

builder.Services.AddIdentityServer()

.AddInMemoryClients(new List<Client>

{

new Client

{

ClientId = "api-client",

ClientSecrets = { new Secret("secret".Sha256()) },

AllowedGrantTypes = GrantTypes.Code,

RedirectUris = { "https://localhost:5001/signin-oidc" },

AllowedScopes = { "api-scope" }

}

})

.AddInMemoryApiScopes(new List<ApiScope> { new ApiScope("api-scope") })

.AddDeveloperSigningCredential(); // For dev

Run on port 5000.

Client-Side (Your API as Resource Server)

In SecureApiDemo, configure as in Module 2, with Authority = "https://localhost:5000".

Real-Life Scenario: Banking app—user logs in via OAuth, gets JWT, accesses account balance API.

Pros: Centralized auth. Cons: Dependency on auth server uptime.

Best Practices: Use HTTPS, enable CORS carefully.

Code Example 1: Protected Endpoint As above, with [Authorize].

Code Example 2: Handling Token in Client App For a console client (simulating frontend): Install IdentityModel.

csharp

using IdentityModel.Client;

var client = new HttpClient();

var disco = await client.GetDiscoveryDocumentAsync("https://localhost:5000");

var tokenResponse = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest

{

Address = disco.TokenEndpoint,

ClientId = "api-client",

ClientSecret = "secret",

Scope = "api-scope"

});

var apiClient = new HttpClient();

apiClient.SetBearerToken(tokenResponse.AccessToken);

var response = await apiClient.GetAsync("https://localhost:6001/api/secure");

Console.WriteLine(await response.Content.ReadAsStringAsync());

This fetches a token and uses it.

Interactive: Modify the scope and see access denied.

Module 5: Authorization Policies and Roles

Beyond auth, authorize based on claims/roles.

Basic Role-Based Auth

Add to policy:

csharp

options.AddPolicy("AdminOnly", policy => policy.RequireRole("admin"));

Endpoint:

csharp

[Authorize(Policy = "AdminOnly")]

Real-Life: E-commerce—admins approve orders, users view only.

Pros: Granular control. Cons: Role explosion in large systems.

Alternatives: Attribute-Based Access Control (ABAC) using claims.

Best Practices: Use claims over roles for flexibility (RFC 9061).

Code Example 1: Claim-Based

csharp

policy.RequireClaim("permission", "approve_orders");

Code Example 2: Custom Requirement Create a handler:

csharp

public class MinimumAgeRequirement : IAuthorizationRequirement { public int MinimumAge { get; } = 18; }

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>

{

protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, MinimumAgeRequirement requirement)

{

if (context.User.HasClaim(c => c.Type == "age" && int.Parse(c.Value) >= requirement.MinimumAge))

context.Succeed(requirement);

return Task.CompletedTask;

}

}

Register:

csharp

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

options.AddPolicy("AdultOnly", policy => policy.AddRequirements(new MinimumAgeRequirement()));

For age-restricted content, like in a gaming API.

Example 3: Realistic Multi-Role In JWT claims: ["roles": ["user", "moderator"]]. Policy: RequireAnyRole.

Module 6: Handling Token Expiration and Refresh

Tokens expire—use refresh tokens.

Implementing Refresh

In IdentityServer, enable RefreshTokens in client config.

Client-side:

csharp

var refreshResponse = await client.RequestRefreshTokenAsync(new RefreshTokenRequest

{

Address = disco.TokenEndpoint,

ClientId = "api-client",

ClientSecret = "secret",

RefreshToken = tokenResponse.RefreshToken

});

Real-Life: Mobile banking app—refresh in background to keep session alive.

Pros: Seamless user experience. Cons: Refresh tokens are long-lived; store securely.

Best Practices: Rotate refresh tokens (OAuth 2.0 Security Best Practices).

Code Example 1: API Side Validation Options include ClockSkew = TimeSpan.FromMinutes(5); for grace period.

Code Example 2: Blacklisting Revoked Tokens Use a cache (e.g., Redis) to store revoked JWTs. On validate, check if jti (token ID) is blacklisted.

Module 7: Advanced Scenarios - Multi-Tenancy and Federation

For enterprise: Multi-tenant APIs.

Multi-Tenancy with JWT

Add tenant claim to JWT. Policy:

csharp

policy.RequireClaim("tenant", HttpContext.Request.Headers["Tenant-Id"]);

Real-Life: SaaS platform like Slack—each workspace is a tenant.

Pros: Isolated data. Cons: Complexity in token validation.

Alternatives: Separate subdomains per tenant.

Federation: Integrate with Azure AD or Google. Config:

csharp

.AddJwtBearer(options => { options.Authority = "https://login.microsoftonline.com/{tenant}/v2.0"; });

Code Example 1: Federated Login Use MSAL library for client.

Code Example 2: Handling Scopes in Multi-Tenant Dynamic policies based on tenant claims.

Interactive: Scenario: How would you secure a shared API for multiple companies? Discuss in comments.

Module 8: Best Practices, Security Audits, and Common Pitfalls

Best Practices Recap:

• Validate all parameters.
• Use secure algorithms.
• Log auth failures.

Standards: OWASP API Security Top 10—address broken auth, injection.

Pros/Cons Summary: Pros: Robust, standard-compliant. Cons: Learning curve.

Alternatives Full List: Bearer tokens, mTLS for high-security.

Pitfalls: Forgetting to validate aud/iss, storing tokens insecurely.

Code Audit Example: Use tools like dotnet-trace for performance, or SonarQube for security scans.

Module 9: Testing and Deployment

Test with Postman: Collections for OAuth flows.

Deploy to Azure: Use App Service with managed identity.

Real-Life: CI/CD with GitHub Actions—automate security scans.

Code Example: Unit Test Using xUnit:

csharp

[Fact]

public async Task SecureEndpoint_ReturnsUnauthorized_WithoutToken()

{

var client = _factory.CreateClient();

var response = await client.GetAsync("/api/secure");

Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);

}

Module 10: Conclusion and Next Steps

You've now mastered securing ASP.NET Core APIs! Apply this to your projects.

📘Free Job Preparation Zone 🎯 Visit Free Learning Zone