Pilgrim.SSO 1.1.0

Pilgrim.SSO

A reusable SSO (Single Sign-On) package for ASP.NET Zero projects, providing comprehensive OIDC authentication, refresh token management, and CSRF protection.

Features

• OIDC Authentication: Full OpenID Connect implementation with Microsoft Entra ID support
• Refresh Token Management: Automatic token rotation with theft detection
• CSRF Protection: Double-submit cookie pattern with DataProtection encryption
• Security Best Practices: Server-side state, httpOnly cookies, PKCE, nonce validation
• Multi-tenancy Support: Built-in ABP tenant resolution and management
• ASP.NET Zero Integration: Seamless integration with ABP framework

Installation

Install via NuGet Package Manager:

dotnet add package Pilgrim.SSO

Or via Package Manager Console:

Install-Package Pilgrim.SSO

Quick Start

1. Configure Services

In your Startup.cs or Program.cs, configure SSO:

services.Configure<SsoOptions>(Configuration.GetSection("Sso"));
services.AddSingleton<ICsrfTokenService, CsrfTokenService>();
services.AddScoped<IOidcStateService, OidcStateService>();
services.AddScoped<IRefreshTokenManager, RefreshTokenManager>();

2. Add OIDC Authentication

services.AddAuthentication()
    .AddOpenIdConnect("YourProvider", options =>
    {
        options.Authority = "https://login.microsoftonline.com/{tenant-id}";
        options.ClientId = "your-client-id";
        options.ClientSecret = "your-client-secret";
        // Additional configuration...
    });

3. Use CSRF Middleware

app.UseMiddleware<CsrfValidationMiddleware>();

4. Extend the Base Controller

public class SsoTokenAuthController : SsoTokenAuthControllerBase
{
    // Your SSO implementation
}

Configuration

Add to your appsettings.json:

{
  "Sso": {
    "Authority": "https://login.microsoftonline.com/{tenant-id}",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "RedirectUri": "https://yourapp.com/signin-oidc",
    "PostLogoutRedirectUri": "https://yourapp.com/signout-callback-oidc"
  }
}

Components

Controllers

• SsoTokenAuthControllerBase: Base controller for SSO token authentication endpoints

CSRF Protection

• ICsrfTokenService: Interface for CSRF token generation and validation
• CsrfTokenService: Implementation using ASP.NET Core Data Protection
• CsrfValidationMiddleware: Middleware for automatic CSRF validation

OIDC State Management

• IOidcStateService: Interface for OIDC state management
• OidcStateService: Redis-backed state storage with encryption

Refresh Token Management

• IRefreshTokenManager: Interface for refresh token operations
• RefreshTokenManager: Secure refresh token storage and rotation
• IRefreshTokenRepository: Repository interface for token persistence

Security Features

• Token Theft Detection: Automatic detection of refresh token replay attacks
• Secure Storage: Encrypted tokens with httpOnly cookies
• PKCE Support: Proof Key for Code Exchange for enhanced security
• State Validation: Server-side OIDC state validation
• CSRF Protection: Double-submit cookie pattern with encryption

Requirements

• .NET 10.0 or later
• ASP.NET Zero / ABP Framework 10.3.0+
• Redis (for distributed state management)

Documentation

For detailed documentation and implementation examples, visit the repository.

License

MIT License - see LICENSE file for details

Support

For issues and questions, please use the Bitbucket issue tracker.

About

Developed by Pilgrim Consulting for ASP.NET Zero projects requiring enterprise-grade SSO capabilities.