---
title: Issue browser credential challenge
summary: Clear the response and emit the WWW-Authenticate headers used for internal-host browser prompts.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-07-30
library: SAIF.Framework.SecurityModule
reference_type: package
operation_id: issue-browser-credential-challenge
trigger: Internal authenticator fallback after silent cookie authentication fails.
---

# Issue browser credential challenge

This operation prepares the HTTP response returned by the internal-host fallback path once silent cookie authentication has failed. It clears any existing response content, sets a 401 status, and publishes the `WWW-Authenticate` headers that tell the browser to prompt the user for NTLM or Basic credentials on the next round-trip.

| Field | Value |
| --- | --- |
| **Operation ID** | `issue-browser-credential-challenge` |
| **Trigger** | Internal authenticator fallback after silent cookie authentication fails. |
| **Inputs** | `response As HttpResponse`, `authType As String` |
| **Outputs** | `401 Not Authorized` response with `WWW-Authenticate` headers |
| **Primary components** | `BrowserAuthenticator.Authenticate` |
| **Entry point** | `SAIF.Framework.SecurityModule\Authenticators\BrowserAuthenticator.vb` |

## Steps

1. Log `Begin BrowserAuthenticate`.
2. Set `response.BufferOutput = True` and discard any existing response body with `response.Clear()`, ensuring the challenge is the only content returned.
3. Set `response.Status = "401 Not Authorized"`, marking the response as an authentication challenge for the internal-host fallback path ([BR-002](../business-rules.md#br-002-host-classification-as-external-drives-the-authentication-fallback-path)).
4. Append a `WWW-Authenticate` header for the configured authentication type, defaulting to `NTLM` when the caller passes `Nothing`.
5. Append a second `WWW-Authenticate` header for `Basic realm="SAIF"`, so browsers that do not support NTLM can still prompt for credentials.
6. Log `End BrowserAuthenticate` and return the prepared response to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Cookie auth failed for internal host]) --> S1[Clear and buffer response]
	S1 --> S2[Set 401 Not Authorized]
	S2 --> S3[Append NTLM or configured auth type]
	S3 --> S4[Append Basic realm header]
	S4 --> EndOk([Browser challenge returned])
```

## Failure and edge-case behavior

- When `authType` is null, the operation falls back to `NTLM` rather than omitting the header.
- The operation does not end the response itself; it relies on the caller and the browser's credential round-trip to complete the challenge.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

## Sources
- `SAIF.Framework.SecurityModule\Authenticators\BrowserAuthenticator.vb`