---
title: SAIF.Framework.Security operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: <owner>
last_reviewed: 2026-07-30
library: SAIF.Framework.Security
reference_type: package
---

# SAIF.Framework.Security operations and processes

SAIF.Framework.Security supplies the identity and authorization primitives that SAIF BOF applications build on: it establishes who the current caller is, authenticates explicit credentials, and routes every yes/no access decision to one of two backing services — a modern WCF `SecurityService` or a legacy ASMX AD web service that the framework is gradually retiring. This page is the operation catalog and cross-operation hub for the library. Each operation's detailed, step-by-step logic lives in its own page under `operations/`.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Principal identity initialization](operations/principal-identity-initialization.md) | Determine whether the caller is a Forms-authenticated web user or a Windows identity, and populate the principal accordingly | `clsSecurityPrincipal` construction or `Instance` access | `HttpContext`, `Thread.CurrentPrincipal`, current platform, Forms authentication cookie | Populated principal fields and an impersonation context when authentication succeeds | [BR-004](business-rules.md#br-004-aspnet-and-anonymous-identities-are-never-authenticated-on-web) | — | — |
| [Explicit credential authentication](operations/explicit-credential-authentication.md) | Validate a username, domain, and password against Windows and replace the active thread principal on success | Caller sets `UserName` / `Domain` / `Password` and calls `Authenticate()` | Principal credential fields | `True`/`False`, an impersonated `WindowsIdentity` on success | [BR-006](business-rules.md#br-006-changing-identity-properties-logs-the-principal-out) | — | — |
| [Resource authorization check](operations/resource-authorization-check.md) | Decide whether the current principal may access a named resource, using the environment-suffixed WCF `SecurityService` path | Caller invokes `IsAuthorized` | Base resource name, optional explicit environment | Boolean authorization decision | [BR-001](business-rules.md#br-001-wcf-resource-names-are-environment-suffixed) | — | — |
| [Role or group membership check](operations/role-or-group-membership-check.md) | Decide whether the current principal belongs to a named AD role or group through the same WCF path used for resource checks | Caller invokes `IsInRole` | Role name (bare or fully qualified) | Boolean membership decision | [BR-005](business-rules.md#br-005-unqualified-role-names-are-domain-qualified-before-an-isinrole-check) | — | — |
| [Machine or service-account authorization](operations/machine-or-service-account-authorization.md) | Confirm that a named machine or service account belongs to an AD group, for use by batch jobs and infrastructure callers | Caller invokes `MachineSecurityService.IsAuthorized` | Machine name, group name, resource flags | Boolean authorization decision, possibly mutated group name | [BR-003](business-rules.md#br-003-machine-security-group-names-use-testresource-suffixing), [BR-008](business-rules.md#br-008-machine-authorization-fails-closed-on-service-error) | — | — |
| [Legacy resource access validation](operations/legacy-resource-access-validation.md) | Decide resource access through the pre-migration ASMX AD web service, for callers that have not moved to the WCF path | Caller invokes a `ResourceAccessValid*` method | Mail ID, base resource name | Boolean authorization decision | [BR-002](business-rules.md#br-002-legacy-asmx-resource-checks-use-a-plain-test-suffix) | — | — |
| [Legacy resource membership enumeration](operations/legacy-resource-membership-enumeration.md) | Retrieve the full list of accounts currently granted access to a legacy resource | Caller invokes `GetWhoHasAccess` | Base resource name | Member account array | [BR-002](business-rules.md#br-002-legacy-asmx-resource-checks-use-a-plain-test-suffix) | — | — |
| [Web login and cookie issuance](operations/web-login-and-cookie-issuance.md) | Authenticate a web user's submitted credentials and issue the cookies needed to recognize them on subsequent requests | Caller invokes `clsSAIFLoginInfo.Login()` | User ID, password, optional domain, HTTP context | Login success flag plus `SAIFAUTH` and Forms authentication cookies | [BR-006](business-rules.md#br-006-changing-identity-properties-logs-the-principal-out) | — | — |
| [Automated-login credential packaging and restoration](operations/automated-login-credential-packaging-and-restoration.md) | Encrypt a user's credentials for unattended reuse, or decrypt a stored payload back into usable login fields | Caller invokes `getEncryptedCredentials()` or `setDecryptedCredentials()` | User ID, password field, encrypted payload | Encrypted credential string, or restored user ID and password fields | — | — | — |
| [Explicit-credential impersonation and process launch](operations/explicit-credential-impersonation-and-process-launch.md) | Impersonate a stored domain identity on the current thread, or launch a child process running as that identity | Caller invokes `Impersonate()` or `RunAs()` | Username, domain, secure password, optional process start information | Boolean impersonation result, or a started process | — | — | — |

## Process flow diagram
The following diagram visualizes how a caller's request moves from principal resolution to an authorization or login decision.

```mermaid
flowchart TD
	Start([Caller request]) --> Principal[Initialize or retrieve principal]
	Principal --> Choice{Operation type}
	Choice -->|Resource or role check| WCF[Call WCF SecurityService path]
	Choice -->|Legacy lookup| ASMX[Call legacy ASMX AD path]
	Choice -->|Web login| Login[Authenticate and issue cookies]
	Choice -->|Machine or service account| Machine[Enumerate AD group members]
	WCF --> Decision{Authorized?}
	ASMX --> Decision
	Machine --> Decision
	Login --> LoginDecision{Authenticated?}
	Decision -->|Yes| EndYes([Access granted or membership confirmed])
	Decision -->|No| EndNo([Access denied or no match])
	LoginDecision -->|Yes| EndLogin([Cookies issued])
	LoginDecision -->|No| EndLoginFail([Login rejected])
```

## Failure and edge-case behavior
- Forms-identity initialization depends on a readable Forms authentication cookie. A missing cookie leaves the principal uninitialized, and a ticket-decryption failure is not caught locally — it propagates to the caller.
- Authorization calls made from `clsSecurityPrincipal` (resource and role checks) let WCF endpoint or transport errors propagate unchanged. `MachineSecurityService` is the one exception: it converts any service failure into a fail-closed `False` result under [BR-008](business-rules.md#br-008-machine-authorization-fails-closed-on-service-error).
- The legacy ASMX authorization and enumeration methods create a new proxy on every call and do not retry or wrap service exceptions locally.
- `clsSAIFLoginInfo.Login()` only issues cookies after `Authenticate()` succeeds; a failed authentication attempt returns `False` and leaves both cookies unset.
- Automated-login credential restoration fails silently — an empty or malformed encrypted payload simply leaves the target fields blank rather than raising an error.
- `SAIFCredentials.RunAs()` temporarily drops any active impersonation before launching the child process, then restores it afterward only if it had been active beforehand.

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

## Sources
- `SAIF.Framework.Security\clsSecurityPrincipal.vb`
- `SAIF.Framework.Security\clsAccountMaintProxy.vb`
- `SAIF.Framework.Security\Utilities\MachineSecurityService.vb`
- `SAIF.Framework.Security\clsSAIFLoginInfo.vb`
- `SAIF.Framework.Security\SAIFCredentials.vb`
- `SAIF.Framework.Security\clsElevateImpersonate.vb`
- `SAIF.Framework.Security\DAPIEncrypt.vb`
- `SAIF.Framework.Security\AppGlobal.vb`