---
title: SAIF.Business.Security.SystemUser architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF
last_reviewed: 2026-07-24
library: SAIF.Business.Security.SystemUser
reference_type: package
---

# SAIF.Business.Security.SystemUser architecture

`SAIF.Business.Security.SystemUser` is an Active Directory account-management library for external portal users. It wraps framework security context, directory-service helpers, and encryption utilities behind a single façade that never enters the BOF data-portal or database-access patterns used elsewhere in the repository.

## Responsibilities
- Classify authenticated users into `UserTypes` values from AD domain and group membership.
- Perform EXTERNAL-domain user lookup, create, update, delete, and group-membership operations.
- Validate login-password and payment-password constraints.
- Read elevated credentials and feature flags from XML properties files.

## Component boundaries
- `clsSystemUser`: Main façade that coordinates authentication state, directory access, and credential operations.
- `clsSystemUserTest`: Utility surface for manual verification of role-classification output.*
- `clsSecurityPrincipal`: Consumed framework security context used for `Domain`, `UserName`, `IsAuthenticated`, `Authenticate`, and `IsInRole`.
- `SAIF.DirectoryServices` types (`clsDirectoryServer`, `clsUser`, `clsUserCollection`, `clsGroup`): Active Directory abstraction boundary provided by `SAIFDirectorySvc.dll`.
- `clsSecureEncrypt`: Encryption helper used to compare payment-password values through encrypted representations.
- `clsProperties`: XML properties reader used to load elevated credentials and special-user settings.

## Interaction model
- Construction initializes the library from either XML-sourced elevated credentials or directly supplied credentials, then binds to `LDAP://SAIF` or `LDAP://EXTERNAL` according to `clsSecurityPrincipal.Domain`.
- `GetUserType()` resolves `SAIF` users immediately to `SAIFEmployee`, resolves `EXTERNAL` users through priority-ordered `IsInRole(...)` checks, and falls back to `Unauthorized` when no recognized classification applies.
- CRUD and role-management methods delegate Active Directory work to `clsDirectoryServer`, `clsUser`, and `clsGroup`.
- Payment-password methods compare encrypted candidate values to the AD `MiddleName` attribute and also reject candidates that authenticate as the user's login password.
- Configuration reads come from `PROPERTIES.XML` and `OnlineProperties.xml`, not from `appSettings` or database state.

## Architecture diagram
The following diagram shows the façade and its external service boundaries.

```mermaid
flowchart TD
    Consumer[Consuming application] --> SystemUser[clsSystemUser]
    SystemUser --> SecPrinc[clsSecurityPrincipal<br>SAIF.BOF.Framework.Security]
    SystemUser --> DirSvc[SAIF.DirectoryServices<br>clsDirectoryServer / clsUser /<br>clsUserCollection / clsGroup]
    SystemUser --> Encrypt[clsSecureEncrypt<br>SAIFEncrypt.dll]
    SystemUser --> Properties[clsProperties<br>SAIF.Framework.Common]
    Properties --> Config[PROPERTIES.XML<br>OnlineProperties.xml]
    DirSvc --> AD[(Active Directory<br>SAIF / EXTERNAL)]
    SecPrinc --> AD
```

## Sequence diagram
The following diagram shows the initialization and user-type classification sequence.

```mermaid
sequenceDiagram
    participant Caller
    participant SystemUser as clsSystemUser
    participant SecPrinc as clsSecurityPrincipal
    participant DirSvc as clsDirectoryServer
    participant AD as Active Directory
    Caller->>SystemUser: New(...)
    SystemUser->>SecPrinc: Domain / UserName
    SystemUser->>DirSvc: Connect to LDAP path
    SystemUser->>SecPrinc: IsInRole(group) [priority order]
    SecPrinc->>AD: Resolve membership
    AD-->>SecPrinc: Membership result
    SecPrinc-->>SystemUser: True / False
    SystemUser-->>Caller: Initialize UserType and user context
```

## Design constraints
- The library has no database interactions and no BOF business-object inheritance.
- `SAIFDirectorySvc.dll` and `SAIFEncrypt.dll` are committed binaries whose internal LDAP and encryption behavior cannot be inspected from this repository.**
- `clsSecurityPrincipal` supplies role checks, but the exact implementation path behind `IsInRole()` is not visible in this library.**
- `AddNewUser()` appears to return `False` even after successful work because no confirmed success path sets its return flag to `True`.**
- The AD-group names used for classification are raw EXTERNAL-domain group names, not `IsAuthorized`-style resource names.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)
- [Configuration](configuration.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
- `Business\SAIF.Business.Security.SystemUser\clsSystemUser.vb`
- `Business\SAIF.Business.Security.SystemUser\clsSystemUserTest.vb`
- `Business\SAIF.Business.Security.SystemUser\App.config`
- `Business\SAIF.Business.Security.SystemUser\packages.config`