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

# 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](operations/retrieve-configuration-setting.md) | 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](business-rules.md#br-001-configuration-key-must-resolve-or-fail-loudly), [BR-004](business-rules.md#br-004-developer-settings-override-requires-developer-machine-status), [BR-009](business-rules.md#br-009-global-section-is-the-sole-non-custom-section) | — | — |
| [Refresh configuration cache](operations/refresh-configuration-cache.md) | 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](business-rules.md#br-002-environment-api-base-url-must-be-present), [BR-003](business-rules.md#br-003-configuration-payload-must-declare-a-refresh-interval) | — | — |
| [Load a configuration section](operations/load-configuration-section.md) | 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](business-rules.md#br-002-environment-api-base-url-must-be-present) | — | — |
| [Retrieve a global configuration setting](operations/retrieve-global-configuration-setting.md) | 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](business-rules.md#br-002-environment-api-base-url-must-be-present) | — | — |
| [Retrieve a secure configuration setting](operations/retrieve-secure-configuration-setting.md) | 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](business-rules.md#br-002-environment-api-base-url-must-be-present) | — | — |
| [Determine developer-machine status](operations/determine-developer-machine-status.md) | 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](business-rules.md#br-002-environment-api-base-url-must-be-present), [BR-004](business-rules.md#br-004-developer-settings-override-requires-developer-machine-status), [BR-005](business-rules.md#br-005-developer-machine-classification-requires-tag-number-host-and-ad-membership), [BR-006](business-rules.md#br-006-machineservice-account-authorization-via-ad-group-membership) | — | — |
| [Authorize a machine or service account](operations/authorize-a-machine-or-service-account.md) | 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](business-rules.md#br-006-machineservice-account-authorization-via-ad-group-membership), [BR-007](business-rules.md#br-007-production-vs-non-production-ad-resource-name-convention) | — | — |
| [Enumerate AD group membership](operations/enumerate-ad-group-membership.md) | 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](business-rules.md#br-006-machineservice-account-authorization-via-ad-group-membership) | — | — |
| [Query SecurityService group membership](operations/query-securityservice-group-membership.md) | 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](operations/resolve-environment-host-name.md) | 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](operations/generate-system-hash.md) | 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](operations/validate-system-hash-lifetime.md) | 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](business-rules.md#br-008-system-hash-must-not-be-expired) | — | — |

## Process flow diagram
The following diagram visualizes the primary operational flow across operations.

```mermaid
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](operations/generate-system-hash.md) |
| 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](operations/validate-system-hash-lifetime.md) |

> **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](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.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