> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & Auditing

> How TAMS authenticates unlock requests, secures transport, validates input, and produces audit and observability signals.

TAMS is designed so that the caller can never influence which account is unlocked, all transport is encrypted, and every operation is observable. This page describes those controls and the assumptions the deployment relies on.

## Token-Based Authentication

Every account unlock request must include a valid **OAuth2 Bearer token** in the request body (`token` field). TAMS validates the token by calling the TruU Identity Server's `/api/v1/user/info` endpoint using the token as a Bearer credential:

<Steps>
  <Step title="Forward the token">
    The token is forwarded to the Identity Server with `Authorization: Bearer <token>`.
  </Step>

  <Step title="Reject invalid tokens">
    If the Identity Server returns HTTP 401, TAMS returns **HTTP 401 Unauthorized** to the caller and the operation is aborted.
  </Step>

  <Step title="Extract the verified identity">
    On a successful response, the user's GUID and UserPrincipalName (UPN) are extracted from the Identity Server response.
  </Step>

  <Step title="Use only the verified UPN">
    The UPN extracted from the token response is the **only** identity used for AD lookup. The caller cannot supply or influence which account is unlocked.
  </Step>
</Steps>

## Transport Security

| Control                  | Detail                                                                      |
| ------------------------ | --------------------------------------------------------------------------- |
| HTTPS enforced           | Kestrel is configured with a TLS certificate (production only)              |
| Certificate source       | Windows Certificate Store; certificate must have friendly name `TRUU-HTTPS` |
| HSTS                     | HTTP Strict Transport Security enforced in production (`UseHsts`)           |
| Server header suppressed | `AddServerHeader = false` (Kestrel)                                         |
| Request body size limit  | 1 MB maximum (`MaxRequestBodySize = 1 MB`)                                  |

## Input Validation

| Control                   | Detail                                                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| UPN format validation     | `MailAddress.TryCreate()` validates the UPN before any AD operation                                                   |
| LDAP injection prevention | All user-supplied values are escaped via `LdapFilter.EscapeLdapFilter()` before being included in LDAP search filters |
| Ambiguous user prevention | If more than one AD user matches the UPN, the operation is rejected (`MultipleUsersWithSameUpn`)                      |
| Pre-unlock state check    | The account is verified to be locked before the unlock is attempted (`UserNotLocked` error if already unlocked)       |
| Required request fields   | `token`, `assetId`, and `assetName` are all marked `[Required]` in the DTO                                            |

## Audit Logging & Observability

TAMS emits operational and security-relevant signals across Windows, the TruU platform, and local logs.

| Mechanism        | Detail                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Windows Security | Windows logs unlock requests to the local machine Security log. Relevant event IDs: **4767** — a user account was unlocked (primary AD confirmation after a successful unlock); **4740** — a user account was locked out (preceding signal in the lock/unlock lifecycle); **4625** — an account failed to log on (often correlated with lockout scenarios). The record contains the target account Security ID, Account Name, and Account Domain. AD event availability depends on Domain Controller audit policy (especially Account Management and Logon auditing). |
| Health checks    | `/health` and `/health/base` endpoints expose AD reachability and SSL certificate status                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| NLog             | Structured logs written to disk under `%ProgramData%\TruU Inc\AccountManagement\Logs\`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

### Events

TAMS emits the following operational/security-relevant events for both unlock-flow failures and service health/runtime issues:

| Event type                                                    | When it is sent                                                                 | What it contains                                                                                 |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| ClientAccountUnlockUserInfo (Failure)                         | Identity Server call fails during processing                                    | Asset ID, asset name, failure error code in additional description                               |
| ClientAccountUnlock (Success)                                 | AD unlock operation completes successfully                                      | User GUID/UPN (from validated token), asset ID, asset name                                       |
| ClientAccountUnlock (Failure)                                 | AD unlock operation fails (e.g., user not found / locked state / AD error)      | User GUID/UPN when available, asset ID, asset name, failure error code in additional description |
| TamsHealthcheck (Success for degraded, Failure for unhealthy) | Daily background health check detects a degraded or unhealthy result            | Health check description as event reason/message                                                 |
| TamsStartup (Failure)                                         | Service startup fails (e.g., HTTPS cert load failure, unexpected startup error) | Startup failure reason/message                                                                   |

## Security Boundaries & Assumptions

The deployment relies on the following assumptions. Review each before going to production.

1. **Trusted network placement.** TAMS is deployed inside your trusted network. Network-layer access to the listening port should be restricted via firewall rules to only the Windows Authenticator host(s).
2. **Identity authority.** TAMS trusts the TruU Identity Server as the authoritative source of user identity. The UPN used for AD operations comes exclusively from the IDS `/userinfo` response.
3. **Certificate lifecycle.** The `TRUU-HTTPS` TLS certificate must be managed and renewed by your team. Expired certificates cause startup failure and are surfaced via the health check endpoint.
4. **Configuration integrity.** Registry-based configuration (`HKLM\SOFTWARE\TruU\AccountManagement`) should be protected with appropriate ACLs to prevent tampering by non-administrative users.