---
title: Capture external user information
summary: Looks up the external user's type once and remembers it in the context cookie.
status: draft
owner: SAIF IT Core Services
last_reviewed: 2026-10-12
library: BolMiddleware
reference_type: package
operation_id: OP-05
trigger: External user request with cookie state New
---

# Capture external user information

Policyholder and agency users are external to the SAIF domain. Their type is needed to filter policy associations, so the library asks the security client (`ISecurityClient.GetExternalUser`) once and keeps the answer in the short-lived context cookie.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-05 |
| **Trigger** | External user request where the cookie user state is New |
| **Inputs** | Authenticated identity |
| **Outputs** | Updated `contextCookie.userType` and `contextCookie.userState` |
| **Primary components** | `BolContextModel.OnPageHandlerExecuting`, `BolContextModel.GetExternalUserInformationForContext`, `SecurityService.GetCurrentExternalUserAsync`, `SecurityService.IsUserExternal` |
| **Entry point** | `src/BolMiddleware/Models/BolContextModel.cs` |

## Steps

1. Decide whether the user is external: the domain part of the identity name is not `SAIF` ([BR-BOLMIDDLEWARE-005](../business-rules.md#br-bolmiddleware-005-external-user-detection)).
2. If the user is external and the cookie user state is New, call `GetCurrentExternalUserAsync`, which calls `ISecurityClient.GetExternalUser` from `OnPageHandlerExecuting` (not the Policy Core API, which is used only for policy access validation) ([BR-BOLMIDDLEWARE-006](../business-rules.md#br-bolmiddleware-006-external-user-information-lookup-once)).
3. Store the returned user type in `contextCookie.userType` and set `userState` to Validated.
   - If the state is already Validated: skip the call and reuse the stored values.
   - If the user is internal: no lookup is made.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Handler executing]) --> D1{External user?}
	D1 -->|No| EndSkip([Skip])
	D1 -->|Yes| D2{State is New?}
	D2 -->|No| EndSkip
	D2 -->|Yes| S1[Call ISecurityClient GetExternalUser]
	S1 --> S2[Store user type and set Validated]
	S2 --> EndOk([Cookie updated])
```

## Failure and edge-case behavior

- The lookup is read once per cookie lifetime of ten seconds, so a user whose association changes is reflected only after the cookie expires.
- A user type held in an unsigned cookie can be altered by the client.

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

## Sources
- src/BolMiddleware/Models/BolContextModel.cs
- src/BolMiddleware/Services/Security/SecurityService.cs
- src/BolMiddleware/Models/ContextCookie.cs
- src/BolMiddleware/Enums/UserStateTypes.cs