ProMilesV5.SharedOps 1.4.6

ProMilesV5.SharedOps

Shared .NET 8.0 class library for ProMiles projects.

Features

• Company Services: Shared company validation and fuel tax ID operations with environment awareness
• Claims Processing: Authentication claims parsing for application access and feature management with URL resolution
• Database-Backed URL Lookup: Primary database lookup only for application URLs
• Environment Awareness: Automatic environment detection and URL resolution with database-only approach
• URL Management: Database-only URL resolution for environment-specific application URLs
• Reseller Information: Reseller code and ID extraction from authentication claims
• Common Operations: Utilities and shared functionality across ProMiles applications
• Zero Configuration: Consumer apps only need to register services - no URL configuration required
• Docker Ready: Optimized for containerized workflows

Getting Started

Build

dotnet build

Usage

Reference this library in your .NET projects:

<ItemGroup>
  <PackageReference Include="ProMilesV5.SharedOps" Version="1.4.6" />
</ItemGroup>

Dependency Injection Setup

using ProMilesV5.SharedOps.DI;

// In your Program.cs or Startup.cs
builder.Services.AddProMilesV5SharedOps();

The service automatically detects the environment and uses appropriate connection strings from your appsettings.json:

• AuthDefault - Default connection string
• AuthDev - Development environment
• AuthBeta - Beta environment
• AuthStaging - Staging environment
• AppsMasterDefault - AppsMaster database default
• AppsMasterDev - AppsMaster database development
• AppsMasterBeta - AppsMaster database beta
• AppsMasterStaging - AppsMaster database staging

Operational Notes

• The library enables managed networking for Microsoft.Data.SqlClient on Windows by default (opt-out via PROMILES_SQLCLIENT_MANAGED=0), reducing SSL/TLS handshake variability.
• The library prefers TLS 1.2 by disabling TLS 1.3 at startup. To keep platform TLS defaults, set PROMILES_KEEP_TLS=1 (or true). Ensure SQL Server supports TLS 1.2.
• If the Auth DB is temporarily unreachable, the library will use an embedded JSON fallback and set IApplicationUrlService.IsJsonFallbackUsed to true. Consider surfacing this in logs/health checks.

Claims Processing

The library provides comprehensive claims processing functionality for client applications to parse authentication claims and extract application access and feature information.

Key Components

• AuthClaimsUtility: Static utility class for parsing claims
• IClaimsService: Service interface for dependency injection
• ClaimsService: Service implementation with comprehensive claims processing and URL resolution
• IdentityInformation: Convenience container for parsed claims data
• IAppUrlResolver: Service for resolving environment-specific application URLs
• IEnvironmentResolver: Service for environment detection and normalization

Models

• FeatureAccessDto: Represents feature access claims
• FeatureValueDto: Represents feature value claims
• ResolvedFeature: Represents resolved features with precedence
• IdentityInformation: Complete parsed claims container
• ClaimsProcessingResult: Legacy result container for claims processing
• RegistrationData: User registration data extracted from claims
• SharedOpsEnvironment: Enum representing normalized environment types

Environment Awareness

The library automatically detects the current environment and resolves application URLs accordingly. No consumer configuration is required.

Environment Detection

The library normalizes environment names as follows:

• dev, development → Development
• beta → Beta
• stage, staging → Staging
• All others → Production

URL Resolution

Application URLs are automatically resolved based on the current environment using database lookup with JSON fallback:

// Get applications with their URLs (JSON-based)
var appsWithUrls = claimsService.GetApplicationAccessWithURL(user);
// Returns: { "FTO": "https://fto.promiles.com", "PMO": "https://pmo.promiles.com" }

// Get applications with database-backed URLs (NEW)
var appsWithDbUrls = await claimsService.GetApplicationAccessWithUrlDynamicAsync(user);
// Returns: Dictionary with ApplicationUrlResult containing URL and source (Database/Json)

// Get reseller information (NEW)
var identityInfo = claimsService.CreateIdentityInformation(user, companyId);
var resellerCode = identityInfo.ResellerCode; // e.g., "RES001"
var resellerId = identityInfo.ResellerId;     // e.g., "12345"

Supported Applications

The embedded URL catalog includes URLs for:

• FTO: Fuel Tax Online
• PMO: ProMiles Online
• DM: Driver Management
• FLEET: Fleet Management
• REPORTS: Reporting System

Usage Examples

Basic Claims Processing

using ProMilesV5.SharedOps.Services;
using ProMilesV5.SharedOps.Utilities;

// Using the service (recommended for DI)
var claimsService = serviceProvider.GetRequiredService<IClaimsService>();
var identityInfo = claimsService.CreateIdentityInformation(user, companyId);

// Get applications with their URLs (NEW)
var appsWithUrls = claimsService.GetApplicationAccessWithURL(user);
// Returns: { "FTO": "https://fto.promiles.com", "PMO": "https://pmo.promiles.com" }

// Using the utility directly
var apps = AuthClaimsUtility.GetApps(user);
var features = AuthClaimsUtility.GetRelevantFeatureValuesForCompany(user, companyId);

Working with IdentityInformation

var identityInfo = claimsService.CreateIdentityInformation(user, companyId);

// Access application list
foreach (var app in identityInfo.ApplicationAccess)
{
    Console.WriteLine($"User has access to: {app}");
}

// Check specific features
if (identityInfo.HasFeature("AdvancedReporting", "Enabled"))
{
    // Enable advanced reporting features
}

// Access all resolved features
foreach (var feature in identityInfo.FeaturesForCompany)
{
    Console.WriteLine($"Feature: {feature.Role}, Value: {feature.Value}");
}

Comprehensive Claims Processing

For applications that need comprehensive claims processing with registration data:

using ProMilesV5.SharedOps.Services;
using ProMilesV5.SharedOps.Models.Claims;

// Using the claims service for comprehensive processing
var claimsService = serviceProvider.GetRequiredService<IClaimsService>();
var result = claimsService.ProcessClaims(claims);

// Access results
foreach (var app in result.ApplicationAccess)
{
    Console.WriteLine($"User has access to: {app}");
}

foreach (var feature in result.ResellerFeatures)
{
    Console.WriteLine($"Feature: {feature.Key}, Value: {feature.Value}");
}

// Access registration data
var regData = result.RegistrationData;
Console.WriteLine($"User: {regData.FirstName} {regData.LastName}");
Console.WriteLine($"Company: {regData.Company}");

Claims Structure

The library expects claims in the following format:

Role Claims

• Type: ClaimTypes.Role
• Value: Application name (e.g., "App1", "App2")

Feature Access Claims

• Type: "FeatureAccess"
• Value: JSON object with role, assigned, and companyId properties

Feature Value Claims

• Type: "FeatureValue"
• Value: JSON object with role, value, companyId, and scope properties

Assignment Precedence

Features are resolved with the following precedence order:

1. User - User-specific assignments
2. Company - Company-specific assignments (exact company ID match)
3. All Users - Global user assignments
4. App - Application-level assignments

Configuration

• Place your settings in appsettings.json, appsettings.Development.json, or appsettings.Beta.json as needed.
• Files are copied to output automatically.

Docker

Build the Docker image:

docker build -t promilesv5-sharedops .

Development

• Target Framework: .NET 8.0
• Nullable enabled, implicit usings enabled

Authors

ProMiles

License

[Specify your license here]