---
title: SAIF.NetCore.AuthService overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.AuthService
reference_type: package
---

# SAIF.NetCore.AuthService overview

> **Documentation context:** Pipeline-packed NuGet package, consumed as a dependency by other libraries and applications in this repository.

`SAIF.NetCore.AuthService` is the implementation-layer "Auth & Identity" library in the Framework.NCore mono-repo: it wires ASP.NET Core JWT and IIS/Windows authentication schemes, abstracts the current-user identity behind the ServiceContracts `IIdentityService`/`IIdentityServiceAccessor` contracts, provides a declarative `[SecurityApiAuthorize]` authorization pipeline, and calls a remote SecurityApi REST service for user/group lookups and for role-authorization decisions that cannot be resolved locally from the current token's role claim; it also ships an outbound OAuth client-credentials token client for calling downstream APIs.

## Purpose
- Implement `IIdentityService`/`IIdentityServiceAccessor` (ServiceContracts) with two concrete identity services — `TokenIdentityService` (JWT; user identity from the `mailid` claim) and `WinIdentityService` (IIS/NTLM; user identity from `Identity.Name`) — selected per request by `IdentityServiceAccessor` or `MultiIdentityServiceAccessor`.
- Provide declarative role authorization via `[SecurityApiAuthorize("roles")]`, which resolves to a dynamic `"SecurityAPI.{roles}"` policy evaluated by `SecurityApiPolicy`/`SecurityApiRequirement`/`SecurityApiHandler` against the remote SecurityApi.
- Expose `ISecurityClient`/`SecurityClient` for role authorization, user-profile retrieval, AD group membership, application authorization groups, and external-user data, all over HTTP.
- Acquire and cache outbound OAuth client-credentials access tokens via `OktaTokenClient`/`IAccessTokenClient` for calling downstream APIs.
- Consumed directly by other libraries and applications in this repository — most notably `SAIF.NetCore.NtlmApiAuth`, which injects `ISecurityClient` into its own authorization service.

## Responsibilities
- Wire ASP.NET Core authentication schemes (`AddJwtAuthentication`, `AddIISAuthentication`, `AddDualAuthentication`) and populate `JwtBearerOptions` from the `oauth` Environment API settings section via `ConfigureJwtBearerOptions`.
- Resolve the current user's identity and role authorization through `BaseIdentityService` and its two subclasses, falling back to the remote SecurityApi when a local check (token role claim) is unavailable.
- Translate `[SecurityApiAuthorize("roles")]` into a policy evaluated against the remote SecurityApi, with OR semantics across comma-separated roles.
- Call the remote SecurityApi through `ISecurityClient`/`SecurityClient`, including the client-side `Resource`/`TestResource` environment-suffix rewrite for role names ([BR-AUTH-010](business-rules.md#br-auth-010-environment-resource-suffix-rewrite))
- Acquire and cache outbound OAuth access tokens via `OktaTokenClient`, independent of the inbound authentication pipeline.

## Key components
- `AuthenticationServiceExtensions`: the composition surface — eight `IServiceCollection`/`AuthenticationBuilder` extension methods plus the public static `AuthenticationSchemeSelector` field.
- `ConfigureJwtBearerOptions`: populates `JwtBearerOptions` from the `oauth` Environment API settings section.
- `BaseIdentityService`, `TokenIdentityService`, `WinIdentityService`, `IdentityServiceAccessor`, `MultiIdentityServiceAccessor`: the current-user identity abstraction.
- `ISecurityClient`/`SecurityClient`, `SecurityClientException`: the remote SecurityApi client.
- `SecurityApiAuthorize`, `SecurityApiPolicy`, `SecurityApiRequirement`, `SecurityApiHandler`: the declarative authorization pipeline (namespace `SAIF.NetCore.Services.Authorization`, distinct from the library's `SAIF.NetCore.Services.Authentication` root namespace*).
- `OktaTokenClient`/`IAccessTokenClient`, `OktaToken`: the outbound OAuth client-credentials token client.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Service registration](service-registration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)
- [SAIF.NetCore.ServiceContracts overview](../saif-netcore-servicecontracts/overview.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService.csproj`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Extensions/AuthenticationServiceExtensions.cs`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/ConfigureJwtBearerOptions.cs`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Identity/BaseIdentityService.cs`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Clients/SecurityClient.cs`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Clients/OktaTokenClient.cs`
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Authorization/SecurityApiHandler.cs`
- `Architecture.md`