Example: security and authorization¶

security-authorization.md records the authorization surface of a library: the Active Directory resources it consumes, where each one is enforced in code, and any data-level or segregation-of-duties checks. Doc gen produces it whenever the security analysis stage detects authorization calls or attributes in the code.

What reviewers should check¶

Every AD resource row has a real group name, a non-empty Purpose, an Enforcement point, and a repository-relative source path. Blank Purpose cells are the most common defect.
Resource names are base names only. The framework appends Resource or TestResource at runtime, so a name ending in Resource in this table is wrong.
Library-level pages number segregation-of-duties rules SOD-NNN. The SEC-APP-NNN scheme belongs to the consolidated application-level security document, not here.
Subsections that do not apply are omitted rather than filled with "None". A class library with no MVC controllers has no attribute-based subsection.
Inferred statements carry * and unknown statements carry **, with the legend in ## Notes immediately before ## Sources.
The Mermaid diagram uses a standard ```mermaid fence and reflects the actual call path, not a generic three-box flow.
## Sources is the final section and every path in it exists in the repository.

Example¶

The document below is a complete, correct security-authorization.md.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: SAIF.Framework.Validation security and authorization
summary: Authorization requirements, AD resource groups, security enforcement points, and data-level access control.
status: draft
owner: Platform Engineering
last_reviewed: 2026-08-14
library: SAIF.Framework.Validation
reference_type: package
---

# SAIF.Framework.Validation security and authorization

This page documents authorization mechanisms implemented or consumed by this
library. Authentication is handled entirely by infrastructure (NTLM/AD) and is
not application-level — all code receives a `WindowsIdentity` on the request
context.

## Authorization architecture

Authorization in this library is centralized. Rule execution never queries
Active Directory directly: `RuleAuthorization` resolves the caller's
`WindowsIdentity` from `ValidationContext`, then delegates every check to the
`ISecurityManager` implementation supplied by `SAIF.Framework.Core`, which in
turn calls the WCF `SecurityService` endpoint. Results are cached per identity
for the lifetime of a validation run, so a rule set that evaluates fifty rules
issues at most one resource lookup per distinct resource name.

```mermaid
flowchart TD
    Engine[ValidationEngine.Execute] --> Gate[RuleAuthorization.EnsureCanExecute]
    Gate --> Cache[AuthorizationResultCache]
    Cache -->|miss| Manager[SAIF.Framework.Core.SecurityManager]
    Manager --> Service[WCF SecurityService]
    Service --> AD[(Active Directory)]
    Gate --> Owner[PolicyOwnershipValidator.AssertOwnership]
    Owner --> Service
```

## AD resource catalog

| Resource name | Purpose | Enforcement point | Source |
| --- | --- | --- | --- |
| `SAIF\ClaimsIntake_Users` | Grants execution of intake-stage validation rule sets, which accept first-notice-of-loss submissions. | `RuleAuthorization.EnsureCanExecute` | src/SAIF.Framework.Validation/Security/RuleAuthorization.vb |
| `SAIF\PolicyAudit_Operators` | Grants execution of premium audit rule sets and access to audit-period override values. | `RuleAuthorization.EnsureCanExecute` | src/SAIF.Framework.Validation/Security/RuleAuthorization.vb |
| `SAIF\PolicyAudit_Approvers` | Permits approval of a completed audit result set. Held separately from `SAIF\PolicyAudit_Operators` to satisfy SOD-001. | `RuleApprovalGuard.EnsureCanApprove` | src/SAIF.Framework.Validation/Security/RuleApprovalGuard.vb |
| `SAIF\Validation_RuleAuthors` | Permits registration of custom rule types at runtime through `RuleRegistry.Register`. | `RuleRegistry.Register` | src/SAIF.Framework.Validation/Rules/RuleRegistry.vb |
| `SAIF\Validation_Diagnostics` | Permits retrieval of full rule evaluation traces, which include unmasked policyholder field values. | `ValidationTraceReader.Read` | src/SAIF.Framework.Validation/Diagnostics/ValidationTraceReader.vb |

## Authorization enforcement points

### Programmatic authorization checks

| Class | Method | Resource / Role | Check type | Source |
| --- | --- | --- | --- | --- |
| `RuleAuthorization` | `EnsureCanExecute` | `SAIF\ClaimsIntake_Users` | `IsAuthorized` | src/SAIF.Framework.Validation/Security/RuleAuthorization.vb |
| `RuleAuthorization` | `EnsureCanExecute` | `SAIF\PolicyAudit_Operators` | `IsAuthorized` | src/SAIF.Framework.Validation/Security/RuleAuthorization.vb |
| `RuleApprovalGuard` | `EnsureCanApprove` | `SAIF\PolicyAudit_Approvers` | `IsAuthorized` | src/SAIF.Framework.Validation/Security/RuleApprovalGuard.vb |
| `RuleRegistry` | `Register` | `SAIF\Validation_RuleAuthors` | `HasAccess` | src/SAIF.Framework.Validation/Rules/RuleRegistry.vb |
| `ValidationTraceReader` | `Read` | `SAIF\Validation_Diagnostics` | `IsAuthorized` | src/SAIF.Framework.Validation/Diagnostics/ValidationTraceReader.vb |
| `ValidationEngine` | `ExecuteAsSystem` | `SAIF_ValidationBatch` (service account role) | `IsInRole` | src/SAIF.Framework.Validation/Engine/ValidationEngine.vb |

## Data-level authorization

| Entity type | Validation method | Mechanism | Source |
| --- | --- | --- | --- |
| `Policy` | `PolicyOwnershipValidator.AssertOwnership` | Compares the policy's servicing branch code against the branch codes returned for the caller by `ISecurityManager.GetBranchScope`; a mismatch raises `AuthorizationException`. | src/SAIF.Framework.Validation/Security/PolicyOwnershipValidator.vb |
| `Claim` | `ClaimAccessValidator.AssertClaimVisible` | Calls the WCF `SecurityService.CanViewClaim` operation with the claim number and caller identity before any rule reads claim fields. | src/SAIF.Framework.Validation/Security/ClaimAccessValidator.vb |
| `AuditResultSet` | `RuleApprovalGuard.EnsureCanApprove` | Rejects approval when the approver identity equals the `SubmittedBy` value stored on the result set. | src/SAIF.Framework.Validation/Security/RuleApprovalGuard.vb |

## Segregation of duties

| Rule | Description | Conflicting privileges | Source |
| --- | --- | --- | --- |
| SOD-001 | Prevents the operator who submitted an audit result set from also approving it. The check compares identities in addition to group membership, so holding both groups does not defeat it. | `SAIF\PolicyAudit_Operators` + `SAIF\PolicyAudit_Approvers` | src/SAIF.Framework.Validation/Security/RuleApprovalGuard.vb |
| SOD-002 | Prevents a rule author from executing the rule set they registered in the same session; registration marks the rule set as pending review until a second identity executes it. | `SAIF\Validation_RuleAuthors` + `SAIF\PolicyAudit_Operators` | src/SAIF.Framework.Validation/Rules/RuleRegistry.vb |

## Security interfaces and contracts

| Interface / Class | Role | Consumers | Source |
| --- | --- | --- | --- |
| `IRuleAuthorization` | Contract for gating rule set execution; allows host applications to substitute an alternative authorization provider in integration tests. | `ValidationEngine`, `RuleSetLoader` | src/SAIF.Framework.Validation/Security/IRuleAuthorization.vb |
| `RuleAuthorization` | Default `IRuleAuthorization` implementation backed by `SAIF.Framework.Core.SecurityManager`. | `ValidationEngine` | src/SAIF.Framework.Validation/Security/RuleAuthorization.vb |
| `AuthorizationResultCache` | Per-run cache of resource lookup results, keyed by identity SID and base resource name. | `RuleAuthorization` | src/SAIF.Framework.Validation/Security/AuthorizationResultCache.vb |
| `AuthorizationException` | Exception type raised on a failed check; carries the resource name and the evaluated identity for audit logging. | `RuleAuthorization`, `RuleApprovalGuard`, `PolicyOwnershipValidator` | src/SAIF.Framework.Validation/Security/AuthorizationException.vb |
| `ISecurityManager` | Consumed contract that resolves resource membership and branch scope from the WCF `SecurityService`. | `RuleAuthorization`, `PolicyOwnershipValidator` | src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj |

## Inherited security

### From `SecuredComponentBase` (`SAIF.Framework.Core`)

| Field | Value |
| --- | --- |
| **Mechanism** | Windows integrated authentication; the impersonating `WindowsIdentity` is captured at construction and exposed to derived types through the protected `CurrentIdentity` property. |
| **Enforcement** | The base constructor throws `SecurityException` when `WindowsIdentity.GetCurrent()` is anonymous, so no derived component can run without an authenticated caller.* |
| **Origin** | `SAIF.Framework.Core` — `SecuredComponentBase` |
| **Source** | Retrieved from indexed documentation via Legends CLI |

## Notes
- `*` marks an inferred statement; `**` marks an unknown value. One inferred
  statement appears on this page, in the inherited enforcement description.
- AD resource names listed here use base names only. The framework appends
  `Resource` (production) or `TestResource` (non-production) at runtime.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/Security/RuleAuthorization.vb
- src/SAIF.Framework.Validation/Security/RuleApprovalGuard.vb
- src/SAIF.Framework.Validation/Security/PolicyOwnershipValidator.vb
- src/SAIF.Framework.Validation/Security/ClaimAccessValidator.vb
- src/SAIF.Framework.Validation/Security/AuthorizationResultCache.vb
- src/SAIF.Framework.Validation/Rules/RuleRegistry.vb
- src/SAIF.Framework.Validation/Diagnostics/ValidationTraceReader.vb
- src/SAIF.Framework.Validation/Engine/ValidationEngine.vb
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj