SilverLABS.SilverSHELL.Auth

Enterprise-grade authentication client library for Blazor WebAssembly applications.

Features

• JWT Authentication - Secure token-based authentication
• Token Management - Automatic token storage and retrieval
• Session Handling - Built-in session state management
• Role-Based Authorization - Claims-based access control
• Custom Authentication State Provider - Seamless integration with Blazor's authentication system
• ✨ NEW: Scaffolded Pages - Production-ready login/register pages out of the box!
• Fixed: Port Configuration - HttpClient now properly respects configured API base URL

Installation

dotnet add package SilverLABS.SilverSHELL.Auth

Quick Start

1. Configure Services

In your Program.cs:

using SilverSHELL.Auth.Extensions;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Services.AddSilverShellAuth(options =>
{
    options.ApiBaseUrl = "https://your-api-server.com"; // NOW PROPERLY APPLIED!
    options.ApplicationName = "My Application";
    options.EnableScaffoldedPages = true; // Default: true
});

builder.Services.AddAuthorizationCore();

await builder.Build().RunAsync();

2. Add Authentication State and Register Assembly

In your App.razor:

@using SilverSHELL.Auth

<CascadingAuthenticationState>
    <Router AppAssembly="@typeof(App).Assembly"
            AdditionalAssemblies="new[] { AuthAssemblyReference.Assembly }">
        <Found Context="routeData">
            <AuthorizeRouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
        </Found>
    </Router>
</CascadingAuthenticationState>

Important: The AdditionalAssemblies parameter is required for Blazor to discover the scaffolded authentication pages.

3. Include Styles

IMPORTANT: Add this to your wwwroot/index.html before the closing </head> tag:

<link href="_content/SilverSHELL.Auth/silvershell-auth.css" rel="stylesheet" />

Troubleshooting: If the CSS doesn't load, check your browser console. The file should be at: https://your-app/_content/SilverSHELL.Auth/silvershell-auth.css

If you see a 404 error, clear your browser cache and rebuild your application:

dotnet clean
dotnet build

4. Use Built-in Pages

That's it! Your app now has production-ready authentication pages at:

• /auth/login - Beautiful login page
• /auth/register - User registration page
• /auth/logout - Logout with confirmation
• /auth/profile - User profile management
• /auth/sessions - Active sessions management
• /auth/settings - Security settings and password change
• /auth/users - User management (Admin only)
• /auth/roles - Role and permissions management (Admin only)

No need to create your own pages unless you want to customize them!

Built-in Scaffolded Pages

The library now includes fully functional, production-ready authentication pages:

Login Page (/auth/login)

• Clean, modern UI with gradient design
• Form validation, loading states, error handling
• Redirect to return URL after login
• Dark mode support and mobile responsive

Register Page (/auth/register)

• User registration with validation
• Password strength requirements
• Automatic redirect to login after success

Logout Page (/auth/logout)

• Secure logout with session cleanup
• Loading state during logout process
• Success confirmation message
• Redirect options (login or home)
• Error handling with retry option

Profile Page (/auth/profile)

• View and edit user profile information
• Avatar display with initials
• Quick links to sessions and settings
• Profile update functionality

Sessions Page (/auth/sessions)

• View all active sessions across devices
• Device and IP address information
• Revoke individual sessions
• Logout from all other devices
• Current session highlighting

Settings Page (/auth/settings)

• Change password with validation
• Two-factor authentication toggle
• Email notification preferences
• Login alerts configuration
• Danger zone (logout all, delete account)

Users Page (/auth/users) - Admin Only

• User management table with avatars
• Role badges and status indicators
• User actions (edit, activate/deactivate, delete)
• Statistics cards (total users, active, admins)
• Add new user functionality

Roles Page (/auth/roles) - Admin Only

• Role management cards with icons
• Permissions list for each role
• User count and permission statistics
• Create new role functionality
• Available permissions overview by category

Features:

• ✅ No code required - works out of the box
• ✅ Professional design with animations
• ✅ Fully responsive (mobile, tablet, desktop)
• ✅ Dark mode support
• ✅ Role-based access control ([Authorize] attributes)
• ✅ Accessibility compliant
• ✅ Customizable via CSS variables
• ✅ Query parameter support (?returnUrl=/dashboard)

Configuration Options

public class AuthOptions
{
    /// Base URL for the authentication API server
    public string ApiBaseUrl { get; set; } = "https://localhost:5001";

    /// Application name to display on auth pages
    public string ApplicationName { get; set; } = "SilverSHELL";

    /// Enable built-in scaffolded pages (/auth/login, /auth/register)
    public bool EnableScaffoldedPages { get; set; } = true;

    /// Local storage key for storing authentication token
    public string TokenStorageKey { get; set; } = "authToken";

    /// Enable automatic token refresh
    public bool EnableAutoRefresh { get; set; } = true;
}

Usage Examples

Using Built-in Pages (Recommended)

Simply configure the auth service and navigate users to /auth/login:

@if (context.User.Identity?.IsAuthenticated != true)
{
    <a href="/auth/login?returnUrl=@currentUrl">Login</a>
}

Using Components Directly (Advanced)

If you want to embed the auth components in your own pages:

@page "/custom-login"
@using SilverSHELL.Auth.Components

<Login RedirectUrl="/dashboard" OnLoginSuccess="HandleLoginSuccess" />

@code {
    private void HandleLoginSuccess(AuthResponse response)
    {
        // Custom logic after login
    }
}

API Reference

IAuthenticationService

• Task<AuthResponse?> LoginAsync(LoginRequest request)
• Task<AuthResponse?> RegisterAsync(RegisterRequest request)
• Task LogoutAsync()
• Task<string?> GetTokenAsync()
• Task<UserDto?> GetCurrentUserAsync()

Migration from v1.0.0

Fixed: Port Configuration Issue

In v1.0.0, the HttpClient might not respect the configured ApiBaseUrl. This is now fixed in v1.1.0.

Before (v1.0.0):

// ApiBaseUrl might be ignored
builder.Services.AddSilverShellAuth(options =>
{
    options.ApiBaseUrl = "https://my-api.com"; // Might not work
});

After (v1.1.0):

// ApiBaseUrl is now properly applied to HttpClient
builder.Services.AddSilverShellAuth(options =>
{
    options.ApiBaseUrl = "https://my-api.com"; // Always works!
});

New: Scaffolded Pages

You no longer need to create your own login/register pages:

Before (v1.0.0):

// Had to create your own LoginPage.razor
@page "/login"
// ... lots of code

After (v1.1.0):

// Just configure and go!
builder.Services.AddSilverShellAuth(options =>
{
    options.ApiBaseUrl = "https://my-api.com";
    // Pages automatically available at /auth/login and /auth/register
});

Customization

Custom Styling

Override the default styles by adding your own CSS:

.silvershell-auth-container {
    background: linear-gradient(135deg, #your-color 0%, #your-color 100%);
}

.silvershell-btn-primary {
    background: #your-brand-color;
}

Disable Scaffolded Pages

If you want to create custom pages:

builder.Services.AddSilverShellAuth(options =>
{
    options.EnableScaffoldedPages = false;
});

Documentation

• Full Documentation
• Integration Guide
• Demo Application

Support

• Issues: GitLab Issues
• Email: support@silverlabs.uk

Changelog

v1.2.5

• 🐛 CRITICAL FIX: Added AuthAssemblyReference helper for Blazor router assembly registration
• 🔧 IMPROVED: Consumers must now add AdditionalAssemblies parameter to Router component
• 📚 DOCS: Updated Quick Start guide with assembly registration requirement
• ⚠️ BREAKING: Router configuration must include AdditionalAssemblies="new[] { AuthAssemblyReference.Assembly }" for scaffolded pages to work

v1.2.4

• ✨ NEW: Logout page (/auth/logout) - Dedicated logout page with confirmation and error handling
• 🔧 IMPROVED: Added NotifyUserLoggedIn() and NotifyUserLoggedOut() methods to CustomAuthenticationStateProvider
• 📚 DOCS: Updated README with logout page documentation
• ✅ VERIFIED: All 8 scaffolded pages complete (Login, Register, Logout, Profile, Sessions, Settings, Users, Roles)

v1.2.3

• 📦 FIXED: Cleaned up wwwroot directory, ensured CSS properly packaged
• 📚 DOCS: Improved documentation for CSS inclusion
• 🔧 IMPROVED: Added troubleshooting guide for static assets

v1.2.2

• 📝 NEW: Comprehensive XML documentation on all public APIs
• 🐛 FIXED: Added exception logging to CustomAuthenticationStateProvider
• 🐛 FIXED: Removed compiler warnings for unused exception variables
• 🔧 IMPROVED: Storage keys now configurable via AuthOptions (TokenStorageKey, UserStorageKey)
• 🔧 IMPROVED: Added IsTokenValidAsync() method for token expiration checking
• 🔧 IMPROVED: Automatic logout on token expiration
• 🔒 SECURITY: Token expiration validation with auto-cleanup
• ⚙️ ENHANCED: Better error handling and logging throughout
• 📚 DOCS: XML IntelliSense documentation for better developer experience

v1.2.1

• 🐛 CRITICAL BUGFIX: Fixed Blazor WebAssembly compatibility
• 🐛 FIXED: LoginPage.OnInitialized() now uses async/await instead of blocking .Result
• 🐛 FIXED: RegisterPage.OnInitialized() now uses async/await instead of blocking .Result
• ✅ VERIFIED: All scaffolded pages now work correctly in Blazor WASM without PlatformNotSupportedException

v1.2.0

• ✨ NEW: Profile page (/auth/profile) - User profile viewing and editing
• ✨ NEW: Sessions page (/auth/sessions) - Active session management across devices
• ✨ NEW: Settings page (/auth/settings) - Password change, 2FA, privacy settings
• ✨ NEW: Users page (/auth/users) - Admin user management with table and statistics
• ✨ NEW: Roles page (/auth/roles) - Admin role and permissions management
• 🎨 ENHANCED: Extended CSS with comprehensive styles for all new pages
• 🎨 ENHANCED: Toggle switches, stat cards, role cards, and table components
• 🔧 IMPROVED: Complete auth management UI out of the box

v1.1.0

• ✅ FIXED: HttpClient now properly respects configured ApiBaseUrl
• ✨ NEW: Built-in scaffolded login/register pages at /auth/login and /auth/register
• ✨ NEW: ApplicationName configuration option
• ✨ NEW: Professional UI with gradient design and dark mode support
• ✨ NEW: EnableScaffoldedPages option to toggle built-in pages
• 🔧 IMPROVED: Better error messages and logging
• 🔧 IMPROVED: Mobile responsive design

v1.0.0

• Initial release

License

This project is licensed under the MIT License.

Made with ❤️ by SilverLABS