---
title: Configure JWT Bearer options
summary: Populates `JwtBearerOptions` for the `"Bearer"` scheme from the `oauth` Environment API settings section, including optional per-application overrides.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.AuthService
reference_type: package
operation_id: OP-01
trigger: The ASP.NET Core options framework materializes named `JwtBearerOptions` for a configured scheme.
---

# Configure JWT Bearer options

Populates `JwtBearerOptions` for the `"Bearer"` scheme from the `oauth` Environment API settings section, including optional per-application overrides.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-01 |
| **Trigger** | The ASP.NET Core options framework materializes named `JwtBearerOptions` for a configured scheme. |
| **Inputs** | Scheme `name`, the `JwtBearerOptions` instance being configured, `IEnvironmentClient` (injected). |
| **Outputs** | Populated `options.Authority`, `options.Audience`, `options.RequireHttpsMetadata` (or no change, for a non-`"Bearer"` scheme). |
| **Primary components** | `ConfigureJwtBearerOptions.Configure(string, JwtBearerOptions)` |
| **Entry point** | `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/ConfigureJwtBearerOptions.cs` |

## Steps

1. If `name != JwtBearerDefaults.AuthenticationScheme`, do nothing and return ([BR-AUTH-001](../business-rules.md#br-auth-001-jwt-options-are-only-populated-for-the-bearer-scheme))
2. Read `oauth:authority` (string), `oauth:audience` (string), and `oauth:requirehttpsmetadata` (bool) via `IEnvironmentClient.GetSettingValue`/`GetSettingValue<bool>`, and assign them to `options.Authority`, `options.Audience`, and `options.RequireHttpsMetadata`.
3. If `HasSetting("authority.{ApplicationName}", "oauth")` is true, overwrite `options.Authority` with that value; do the same for `audience.{ApplicationName}` and `options.Audience` ([BR-AUTH-002](../business-rules.md#br-auth-002-per-application-oauth-overrides-take-precedence))
4. The unnamed `Configure(JwtBearerOptions)` overload delegates to this method with `name = Options.DefaultName`, which never equals `"Bearer"`, so it never applies any configuration ([BR-AUTH-003](../business-rules.md#br-auth-003-the-unnamed-configure-overload-is-a-no-op))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Options framework materializes JwtBearerOptions]) --> Check{"name equals Bearer scheme?"}
    Check -->|No| NoOp([No configuration applied])
    Check -->|Yes| ReadBase["Read oauth:authority / oauth:audience<br>oauth:requirehttpsmetadata"]
    ReadBase --> HasAuth{"HasSetting authority.ApplicationName?"}
    HasAuth -->|Yes| OverrideAuth[Override Authority]
    HasAuth -->|No| HasAud{"HasSetting audience.ApplicationName?"}
    OverrideAuth --> HasAud
    HasAud -->|Yes| OverrideAud[Override Audience]
    HasAud -->|No| Done([JwtBearerOptions populated])
    OverrideAud --> Done
```

## Failure and edge-case behavior

- If `oauth:authority`/`oauth:audience` is absent and the registered `IEnvironmentClient` returns an empty string on a missing key, `Authority`/`Audience` are set to `""`, which causes JWT validation to fail at first token validation rather than at startup*.
- If `oauth:requirehttpsmetadata` is absent and the registered `IEnvironmentClient` throws on a missing typed key, this method throws when `JwtBearerOptions` is first materialized*.

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

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `src/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/SAIF.NetCore.AuthService/ConfigureJwtBearerOptions.cs`