TELS Auth Service - Project Overview

Solution Structure

The solution (TELS.Auth.Api.sln) contains 6 projects:

Application Projects

Project	Type	Framework	Description
TELS.Auth.Api	Web API	.NET 10.0	Core authentication service — issues, refreshes, and validates JWT tokens for the TELS platform
TELS.Auth.Contracts	Library	.NET 8.0	Shared DTOs and contract definitions for Auth domain consumers
TELS.Auth.Sdk	Library	.NET 8.0 / 10.0	Multi-targeted SDK for service consumers — JWT validation, resilience, auth middleware
TELS.WebServices.Auth.Contracts	Library	.NET Standard 2.0	Obsolete — legacy WebServices contracts, replaced by TELS.Auth.Contracts

Test Projects

Project	Type	Description
TELS.Auth.Api.Tests	xUnit (.NET 10.0)	Integration tests for controllers, logic, and data layers
TELS.Auth.Sdk.Tests	xUnit (.NET 8.0)	Unit tests for SDK components

Other Components

Component	Type	Description
src/dbup/	SQL Migrations	DbUp-based schema migrations for Auth database objects
src/k6tests/	Load Tests	K6 (TypeScript) functional and smoke tests
terraform/	Infrastructure	Terraform IaC for AWS ECS deployment

Architecture

Purpose

The TELS Auth Service is the centralized authentication and authorization gateway for the TELS platform. It provides:

Token Issuance — Issues JWT access tokens (24h lifetime) and refresh tokens (365d lifetime) via multiple authentication flows: username/password, service-to-service trust, bearer token exchange, SSO/OpenID Connect, and Windows Authentication.
Token Validation — Validates and exchanges tokens across multiple signing algorithms (HS256, RS256, ES256), supporting both legacy HMAC-signed tokens and modern asymmetric key pairs.
Identity Resolution — Resolves user identity across multiple legacy databases (CONTACT, DSI_APP, MDID_BTRIEVE, DSHE_APP, TELS) to build comprehensive JWT claims including personas, facility access, and security group membership.
Token Revocation — Maintains a revocation registry supporting user-level and token-level revocations.
Authorization Queries — Provides role membership and access-point authorization checks for internal administration.

Layering Pattern

┌─────────────────────────────────────────────────────┐
│  Controllers (V1)                                    │
│  TokenController, AuthorizationController,           │
│  RevocationsController, DiagnosticController,        │
│  BusinessUnitController                              │
├─────────────────────────────────────────────────────┤
│  Logic Layer                                         │
│  TokenResponseService, TokenGenerator,               │
│  JsonWebTokenService, ExternalIdentityService,       │
│  TrustService, TokenAuthorityService,                │
│  RevocationsService, SecurityEditorService,          │
│  SecurityKeyManager, UserIdentityFactory,            │
│  Identity/* (resolution & validation)                │
├─────────────────────────────────────────────────────┤
│  Data Layer (Dapper + Stored Procedures)             │
│  IdentityDataProvider, RevocationsDataProvider,      │
│  SecurityEditorDataProvider                          │
├─────────────────────────────────────────────────────┤
│  SQL Server Databases                                │
│  TELS.Auth schema (owned), CONTACT.dbo,              │
│  DSI_APP.dbo, MDID_BTRIEVE.dbo, DSHE_APP.dbo,       │
│  TELS.dbo, TELS.Customers, TELS.LocalServices        │
└─────────────────────────────────────────────────────┘

Data Access

ORM: Dapper 2.1.66 (micro-ORM)
Database: SQL Server (Internal + External catalogs)
Pattern: Stored procedures via CommandType.StoredProcedure
Migrations: DbUp with retirement queueing system
Auth Schema: TELS.Auth — owns Revocations table + 14 stored procedures + 2 views
Cross-DB Reads: CONTACT, DSI_APP, MDID_BTRIEVE, DSHE_APP, TELS

Key Features

1. Multi-Flow Token Issuance

Supports 7 distinct authentication flows: - Refresh (POST /auth/token/refresh) — Exchange refresh token for new access + refresh tokens - User/Password (POST /auth/token/user) — Direct credential authentication - Trust (HMAC) (POST /auth/token/trust) — Service-to-service auth with HMAC-signed requests - Trust (Simple) (POST /auth/token/trust-simple) — Service-to-service auth with shared secret - Bearer Exchange (POST /auth/token/bearer) — Exchange an existing bearer token - SSO/OpenID (POST /auth/token/openId, GET /auth/token/sso/initiate) — Microsoft Entra ID (Azure AD) integration - Windows Auth (GET /auth/token/user/winauth) — IWA-based authentication (deprecated)

2. Multi-Algorithm JWT Signing

HS256 — HMAC symmetric signing (legacy compatibility)
RS256 — RSA asymmetric signing
ES256 — Elliptic curve signing
Configurable per token profile with key rotation support

3. Identity Resolution Across Legacy Databases

Builds comprehensive user identity from 5+ databases
Resolves personas: DirectSupplyPartner, Customer, ServiceProvider, Resident, Owner
Computes facility access lists dynamically
Maps between UserAccount, DsUser, Person, and Contact records

4. Token Revocation

Domain-based revocation (tels-personid, ds-mtolympus, jti)
User-level and token-level granularity
Date-based bulk retrieval for cache invalidation

5. Security Group Authorization

Recursive group hierarchy traversal
Access-point level authorization checks
Internal administrator role gates

API Surface

5 controllers exposing 15 endpoints under auth/:

Authentication & Authorization

Auth: JWT Bearer tokens
Personas: DirectSupplyPartner (1), Customer (2), ServiceProvider (4), Resident (8), Owner (16)
Internal Admin: [AuthorizeInternalAdministrator] — requires DirectSupplyPartner persona OR CustomerGlobalAdministrator role
Token Claims: Custom [FromAuth] model binding for ITokenClaims

See API Documentation for full endpoint details.

Key Technology Stack

Category	Technology
Runtime	.NET 10.0
Web Framework	ASP.NET Core 10.0 with API Versioning
Data Access	Dapper 2.1.66
Database	SQL Server (Internal + External catalogs)
Authentication	JWT Bearer (Microsoft.IdentityModel 8.15.0)
SAML Support	Microsoft.IdentityModel.Tokens.Saml 8.15.0
Resilience	Polly 8.6.5 (via Microsoft.Extensions.Http.Polly)
API Docs	Swashbuckle 10.1.0 (Swagger/OpenAPI)
Monitoring	New Relic Agent API 10.48.0
Testing	xUnit 2.9.3, Moq 4.20.72, K6 (load tests)
Formatting	CSharpier
Versioning	Nerdbank.GitVersioning 3.9.50

Deployment

Docker Containers

TELS.Auth.Api — Single container deployed to AWS ECS

Environments

Environment	URL	SQL Server (Transactional)	SQL Server (DW)
DEV	https://devservices.tels.net/auth/	SQL-DSHE-DEV-TRAN	SQL-DSI-I-DW
QA	https://qaservices.tels.net/auth/	SQL-DSHE-QE-TRAN	SQL-DSI-I-DW
PROD	https://services.tels.net/auth/	SQL-DSHE-PE-TRAN	SQL-DSI-I-DW

CI/CD Pipeline

Stage	Jobs
Build	dotnet-build, container-build, terraform-verify
Test	dotnet-test, security scans (SAST, dependency, container), K6 functional tests
Publish	NuGet push (Contracts, Sdk, WebServices.Auth.Contracts) to ProGet
Deploy	Terraform plan → Container push → Terraform apply → DbUp → K6 smoke tests

Rollout Strategy

Parallel deployment: WebFarm (legacy) + ECS (new) running simultaneously
Header-based routing: x-use-ecs: true header directs traffic to ECS
Response marker: X-Hosted-By: ECS response header identifies new deployment
Enables gradual cutover without disruption

Infrastructure

Platform: AWS ECS (container port 8080)
Load Balancer: ALB with host/path routing + header-based routing
Secrets: HashiCorp Vault + AWS Secrets Manager
Monitoring: CloudWatch (7-day log retention), New Relic APM
IaC: Terraform (in /terraform/ directory)

Configuration

Configuration Group	Key Variables
Database	Internal + External SQL Server connection strings (IWA auth)
JWT	Issuer/audience validation, signing keys (symmetric, RSA, ECC)
Token Profiles	Algorithm selection, access token lifetime (24h), refresh token lifetime (365d)
External Identity	Microsoft Entra ID OAuth2 (client ID, tenant, authority)
Trust	Shared secrets per application key, trusted batch identities
Endpoints	Platform service URL, Customers service URL
Feature Flags	IncludeKeyIdInHeader, DsUserAsPartnerPersona, AlwaysPerformAccessChecks

External Integrations

Integration	Mechanism	Description
Microsoft Entra ID	OAuth2/OIDC	External identity provider for SSO and OpenID Connect flows
Customers Service	HTTP API (v2)	Facility access lookups (`GET v2/businessUnits/{id}/facilityAccess`) and facility search
Platform Service	HTTP API	Platform-level operations (endpoint configured)
CONTACT Database	Cross-DB SQL	User accounts, password lockout, person records, email routing
DSI_APP Database	Cross-DB SQL	DS user records, AD integration, contact relationships
MDID_BTRIEVE Database	Cross-DB SQL	Customer/supplier contact records and email addresses
DSHE_APP Database	Cross-DB SQL	Security groups, company/team/department hierarchy
TELS Database	Cross-DB SQL	Facility access views, customer schemas, service providers

Business Logic Patterns

Token Issuance Flow

Controller receives authentication request (credentials, trust, bearer, SSO)
Logic layer validates credentials/tokens via appropriate service
Identity resolution queries multiple databases to build user profile
TokenGenerator creates JWT with claims (persona, roles, facility access)
Access token (24h) + optional refresh token (365d) returned

Trust Authentication (HMAC)

Calling service creates HMAC signature using shared secret + timestamp
Auth API validates signature, timestamp freshness, and application key
Issues token with requested persona and identity
Used for service-to-service communication (e.g., Tasks, BusProxy)

Identity Resolution

Lookup starts from UserAccount or DsUser entry point
Two comprehensive SQL views join 15+ tables across 5 databases
Resolves: person details, email, personas, facility access, contact keys
Result cached in JWT claims for downstream service consumption

Database Retry Pattern

Polly-based retry: 5 attempts maximum
Targets: SQL transient errors, timeouts, Win32 exceptions
Exponential backoff with jitter
Uses SqlServerTransientExceptionDetector for transient classification

Testing Strategy

Test Type	Project	Execution
Unit/Integration Tests	TELS.Auth.Api.Tests	xUnit — controllers, logic, data providers
SDK Tests	TELS.Auth.Sdk.Tests	xUnit — JWT validation, resilience
Load/Functional Tests	src/k6tests/	K6 (TypeScript) — smoke tests per environment
Security Scanning	CI/CD pipeline	SAST, dependency scan, container scan

NuGet Packages Published

Package	Target	Published To
TELS.Auth.Contracts	.NET 8.0	ProGet (proget.directsupply.cloud)
TELS.Auth.Sdk	.NET 8.0 / 10.0	ProGet
TELS.WebServices.Auth.Contracts	.NET Standard 2.0	ProGet (obsolete)

Key Files & Locations

Controllers: - src/TELS.Auth.Api/Controllers/V1/TokenController.cs - src/TELS.Auth.Api/Controllers/V1/AuthorizationController.cs - src/TELS.Auth.Api/Controllers/V1/RevocationsController.cs - src/TELS.Auth.Api/Controllers/V1/DiagnosticController.cs - src/TELS.Auth.Api/Controllers/V1/BusinessUnitController.cs

Logic: - src/TELS.Auth.Api/Logic/TokenResponseService.cs - src/TELS.Auth.Api/Logic/TokenGenerator.cs - src/TELS.Auth.Api/Logic/JsonWebTokenService.cs - src/TELS.Auth.Api/Logic/TrustService.cs - src/TELS.Auth.Api/Logic/Identity/

Data: - src/TELS.Auth.Api/Data/IdentityDataProvider.cs - src/TELS.Auth.Api/Data/RevocationsDataProvider.cs - src/TELS.Auth.Api/Data/SecurityEditorDataProvider.cs

Database Migrations: - src/dbup/scripts/

Contracts: - src/TELS.Auth.Contracts/V1/ - src/TELS.WebServices.Auth.Contracts/

SDK: - src/TELS.Auth.Sdk/V1/

Notes

The TELS.WebServices.Auth.Contracts project is marked obsolete and is being replaced by TELS.Auth.Contracts. Both are still published to ProGet for backward compatibility.
The Auth service has heavy cross-database dependencies — identity resolution spans 5+ databases via SQL views with 15+ table joins.
The parallel ECS/WebFarm deployment strategy means both hosting models serve traffic simultaneously during rollout. The x-use-ecs header controls routing.
Trust authentication is the primary mechanism for service-to-service calls. Each consuming service has its own application key and shared secret.
The BusinessUnitController is deprecated — proxies to Customers service and should be called directly.
Token lifetimes are configurable per profile: 24h access tokens, 365d refresh tokens are the defaults.
Database connections use Integrated Windows Authentication (IWA) via the TELSSRVC_Auth service account.