---
title: Register authentication and authorization services
summary: "The composition surface of the library: eight `IServiceCollection`/`AuthenticationBuilder` extension methods a consumer calls to wire identity, authorization, and authentication scheme registrations."
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.AuthService
reference_type: package
operation_id: OP-14
trigger: A consuming application's `Startup`/composition code calls one or more `AuthenticationServiceExtensions` extension methods.
---

# Register authentication and authorization services

The composition surface of the library: eight `IServiceCollection`/`AuthenticationBuilder` extension methods a consumer calls to wire identity, authorization, and authentication scheme registrations.

For the consumer-facing service/lifetime catalog, required external registrations, and the JWT-bearer-handler caveat, see [Service registration](../service-registration.md).

| Field | Value |
| --- | --- |
| **Operation ID** | OP-14 |
| **Trigger** | A consuming application's `Startup`/composition code calls one or more `AuthenticationServiceExtensions` extension methods. |
| **Inputs** | The `IServiceCollection` being configured. |
| **Outputs** | DI registrations for identity services, the SecurityApi client, the outbound token client, and/or authentication/authorization building blocks; for the `Add*Authentication` methods, an `AuthenticationBuilder`. |
| **Primary components** | `AuthenticationServiceExtensions.*` (eight extension methods) |
| **Entry point** | `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/Extensions/AuthenticationServiceExtensions.cs` |

## Steps

1. `AddAccessTokenClient()` registers `IAccessTokenClient` → `OktaTokenClient` (Singleton).
2. `AddTokenIdentityService()` registers `ISecurityClient` → `SecurityClient` (Singleton), `IIdentityService` → `TokenIdentityService` (Scoped), `IIdentityServiceAccessor` → `IdentityServiceAccessor` (Transient).
3. `AddWinIdentityService()` registers the same three services, substituting `WinIdentityService` (Scoped) for the `IIdentityService`.
4. `AddIdentityAccessor()` registers `ISecurityClient` → `SecurityClient` (Singleton), both `WinIdentityService` and `TokenIdentityService` as self (Scoped), and `IIdentityServiceAccessor` → `MultiIdentityServiceAccessor` (Transient).
5. `AddJwtAuthentication()`/`AddIISAuthentication()`/`AddDualAuthentication()` each call `AddAuthentication` with the corresponding default scheme(s) and return the resulting `AuthenticationBuilder`; `AddDualAuthentication` additionally installs the `"dual"` policy scheme with `ForwardDefaultSelector = AuthenticationSchemeSelector`.
6. `AddSecurityApiAuthorizeAttribute()` registers `IAuthorizationPolicyProvider` → `SecurityApiPolicy` (Transient) and `IAuthorizationHandler` → `SecurityApiHandler` (Singleton).
7. All registrations use `Add*`, not `TryAdd*`, so chaining several identity-registration methods registers `ISecurityClient` more than once (last one wins; harmless but redundant)*.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Consumer calls extension methods]) --> Token[AddAccessTokenClient]
    Start --> TokenId[AddTokenIdentityService]
    Start --> WinId[AddWinIdentityService]
    Start --> MultiId[AddIdentityAccessor]
    Start --> Jwt[AddJwtAuthentication]
    Start --> Iis[AddIISAuthentication]
    Start --> Dual[AddDualAuthentication]
    Start --> Authz[AddSecurityApiAuthorizeAttribute]
    Dual --> Policy["dual scheme: ForwardDefaultSelector =<br>AuthenticationSchemeSelector"]
    Authz --> Pipeline["SecurityApiPolicy + SecurityApiHandler registered"]
```

## Failure and edge-case behavior

- `SecurityApiHandler` is registered Singleton while a consumer may register `ISecurityClient` as Transient elsewhere (e.g. `AppStartup`), creating a lifetime mismatch where the Singleton handler captures one `SecurityClient` instance for the process lifetime*.
- A consumer that registers `MultiIdentityServiceAccessor` manually without also calling `AddIdentityAccessor` will find `GetService` returns `null` for `TokenIdentityService`/`WinIdentityService`, since only `AddIdentityAccessor` registers them as self*.

## Related documentation
- [Service registration](../service-registration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.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/Extensions/AuthenticationServiceExtensions.cs`