SAIF.Framework.Security.EnvironmentApi operations and processes

This page is the operation catalog and cross-operation hub for this 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
Retrieve a configuration setting	Resolve one configuration value, checking developer overrides, the shared cache, and an on-demand section reload in that order	Caller invokes GetConfigSetting or GetConfigSetting<T>	configKey	string, converted T, or ApplicationException	BR-001, BR-004, BR-009	—	—
Refresh configuration cache	Keep the in-memory Environment API payload current without re-downloading it on every call	Any configuration-backed operation touches Configurations or GetConfigSettingInfo	Constructor-supplied sections, derived application identity and host	Populated ConfigurationSettings cache and updated refresh interval	BR-002, BR-003	—	—
Load a configuration section	Fetch a section that is missing from the cache and merge it in without disturbing other cached entries	A cached lookup misses a non-global key	section	Section payload plus merged cached entries	BR-002	—	—
Retrieve a global configuration setting	Read one global setting directly, bypassing the shared cache entirely	Internal code needs a bootstrap setting before the cache can be trusted	configKey	Global setting value or null	BR-002	—	—
Retrieve a secure configuration setting	Read a secure, track-scoped setting using a caller-supplied system hash as proof of eligibility	Caller invokes GetSecureConfigSetting or GetSecureConfigSetting<T>	configKey, systemHashValue	Secure setting value as string or converted T	BR-002	—	—
Determine developer-machine status	Decide, once per service instance, whether the current host qualifies for developer-only behavior	Host resolution or override lookup reads IsDeveloperMachine	DNS host name, bootstrap LDAP/domain settings	Memoized bool	BR-002, BR-004, BR-005, BR-006	—	—
Authorize a machine or service account	Decide whether a machine or service account belongs to an AD group, failing closed on any error	Caller invokes MachineSecurityService.IsAuthorized	machine, groupName, isResource, isProductionResource, recurse	Authorization decision and possibly rewritten group name	BR-006, BR-007	—	—
Enumerate AD group membership	Expand direct and, when requested, nested AD membership into one deduplicated account list	MachineSecurityService or a downstream caller requests group members	groupName, ldap, domain, recurse	Distinct sorted sAMAccountName[] or null	BR-006	—	—
Query SecurityService group membership	Forward a group-membership lookup to the centralized WCF service as an alternative to local LDAP traversal	Downstream caller uses SecurityServiceClient	groupName, optional ldap, optional domain, optional recurse	Remote string[] membership result	—	—	—
Resolve an environment host name	Normalize a request host into the token the Environment API expects for configuration lookup	Web or WCF host resolution needs a lookup key	Request Uri	Normalized host string	—	—	—
Generate a system hash	Derive a system identifier from the calling assembly and optionally time-salt it for transport	Caller needs a system hash for secure-setting workflows	SystemType, optional explicit systemName	Salted or unsalted hash string	—	—	—
Validate system hash lifetime	Strip the salt from a previously issued system hash and reject it once its validity window has passed	Caller validates a previously issued system hash	systemHashValue, expireSeconds, nowBufferSeconds	Unsalted hash string or exception	BR-008	—	—

Process flow diagram

The following diagram visualizes the primary operational flow across operations.

flowchart TD
    Start([Caller requests environment or security data]) --> Config{Configuration lookup?}
    Config -->|Yes| Refresh[Refresh configuration cache]
    Refresh --> Lookup[Retrieve configuration setting]
    Lookup --> Missing{Missing section value?}
    Missing -->|Yes| Section[Load configuration section]
    Missing -->|No| ConfigDone([Return configuration value])
    Section --> ConfigDone
    Config -->|No| Dev{Developer-machine check?}
    Dev -->|Yes| DevCheck[Determine developer-machine status]
    DevCheck --> Auth[Authorize a machine or service account]
    Auth --> Members[Enumerate AD group membership]
    Members --> DevDone([Return authorization decision])
    Dev -->|No| Secure{Secure-setting or host utility?}
    Secure -->|Secure setting| SecureRead[Retrieve a secure configuration setting]
    Secure -->|Host resolution| Host[Resolve an environment host name]
    Secure -->|System hash| Hash[Generate or validate system hash]
    SecureRead --> End([Return result])
    Host --> End
    Hash --> End
    ConfigDone --> End
    DevDone --> End

Inherited operations and processes

Operations in this section originate from dependency packages consumed by this library. They are delegated, not implemented in this repository.

From SaltShaker (SAIF.HashUtil)

Operation	Intent	Provided by	Origin	Embedded in
Salt system hash value	Attach time-based salt metadata to a computed hash so its creation time can later be recovered and checked	SaltShaker	SAIF.HashUtil	Generate a system hash
Remove salt and recover hash timestamp	Reverse the salt wrapper and expose the embedded creation timestamp used for expiry checks	SaltShaker	SAIF.HashUtil	Validate system hash lifetime

Origin: These operations are provided by the external SAIF.HashUtil package. This repository does not contain package-level operation documents for that dependency, so the consuming operation pages describe only the locally observable call sequence.

Failure and edge-case behavior

• A missing EnvironmentApiUrl environment variable stops any Environment API-backed lookup with MissingEnvironmentUrlVariableException before an HTTP request is attempted.
• A missing checkforupdatedsettingsinseconds value stops cache refresh with KeyNotFoundException rather than falling back to an implicit interval.
• A configuration key that is absent from developer overrides, the cache, and a freshly loaded section stops lookup with ApplicationException once every source has been exhausted.
• AD authorization failures fail closed: MachineSecurityService catches any lookup exception and returns false instead of propagating the error.
• SecurityServiceClient.GetUsersByGroup ignores the caller-supplied recurse flag and always forwards recurse: false to the WCF service.
• SystemHashUtil.RemoveSystemHashSaltAndValidateLifetime throws SystemHashExpiredException when the recovered timestamp falls outside the buffered validity window.

Related documentation

• Index
• Overview
• Architecture
• Dependencies
• Business rules
• Configuration
• Security and authorization
• API reference

Sources

• SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs
• SAIF.Framework.Security.EnvironmentApi\Services.Common\WebEnvironmentService.cs
• SAIF.Framework.Security.EnvironmentApi\Services.Common\WindowsEnvironmentService.cs
• SAIF.Framework.Security.EnvironmentApi\Services.Common\WcfEnvironmentService.cs
• SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentHost.cs
• SAIF.Framework.Security.EnvironmentApi\Services.Common\SystemHashUtil.cs
• SAIF.Framework.Security.EnvironmentApi\Core\Services\MachineSecurityService.cs
• SAIF.Framework.Security.EnvironmentApi\Core\Services\ADService.cs
• SAIF.Framework.Security.EnvironmentApi\Core\Services\SecurityServiceClient.cs