Skip to content

Add guidance on V1 and V2 STS tokens #36979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guardrex wants to merge 3 commits into
base: main
Choose a base branch
from
+62 −2
Open

Add guidance on V1 and V2 STS tokens #36979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9bde900
Add guidance on V1 and V2 STS tokens
guardrex Apr 10, 2026
c57d86e
Apply suggestions from code review
guardrex Apr 10, 2026
ea681a1
Updates
guardrex Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 52 additions & 2 deletions aspnetcore/blazor/security/blazor-web-app-with-entra.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,12 +138,22 @@ jwtOptions.Authority = "{AUTHORITY}";

The following examples use a Tenant ID of `aaaabbbb-0000-cccc-1111-dddd2222eeee` and a directory name of `contoso`.

If the app is registered in an ME-ID tenant, the authority should match the issurer (`iss`) of the JWT returned by the identity provider:
If the app is registered in an ME-ID tenant, the authority should match the issuer (`iss`) of the JWT returned by the identity provider.

V1 STS token format:

```csharp
jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";
```

V2 STS token format:

```csharp
jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";
```

For more information on V2 STS tokens, see the [STS token version](#sts-token-version) section.

If the app is registered in a Microsoft Entra External ID tenant:

```csharp
Expand Down Expand Up @@ -434,12 +444,22 @@ jwtOptions.Authority = "{AUTHORITY}";

The following examples use a Tenant ID of `aaaabbbb-0000-cccc-1111-dddd2222eeee` and a directory name of `contoso`.

If the app is registered in an ME-ID tenant, the authority should match the issurer (`iss`) of the JWT returned by the identity provider:
If the app is registered in an ME-ID tenant, the authority should match the issuer (`iss`) of the JWT returned by the identity provider.

V1 STS token format:

```csharp
jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";
```

V2 STS token format:

```csharp
jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";
```

For more information on V2 STS tokens, see the [STS token version](#sts-token-version) section.

If the app is registered in a Microsoft Entra External ID tenant:

```csharp
Expand Down Expand Up @@ -849,6 +869,8 @@ In the `MinimalApiJwt` project, add the following app settings configuration to
},
```

The preceding example uses the V1 STS token URL format. For guidance on V2 STS tokens, see the [STS token version](#sts-token-version) section.

Update the placeholders in the preceding configuration to match the values that the app uses in the `Program` file:

* `{TENANT ID (WEB API)}`: The Tenant Id of the web API.
Expand All @@ -860,6 +882,8 @@ Authority formats adopt the following patterns:
* Microsoft Entra External ID: `https://{DIRECTORY NAME}.ciamlogin.com/{TENANT ID}/v2.0`
* B2C tenant type: `https://login.microsoftonline.com/{TENANT ID}/v2.0`

The preceding example for the ME-ID tenant type uses the V1 STS token URL format. For guidance on V2 STS tokens, see the [STS token version](#sts-token-version) section.

Audience formats adopt the following patterns (`{CLIENT ID}` is the Client Id of the web API; `{DIRECTORY NAME}` is the directory name, for example, `contoso`):

* ME-ID tenant type: `api://{CLIENT ID}`
Expand Down Expand Up @@ -1157,6 +1181,32 @@ Server-side Blazor Web Apps hosted in a web farm or cluster of machines must ado

We also recommend using a shared [Data Protection](xref:security/data-protection/introduction) key ring in production, even when the app uses the Interactive WebAssembly render mode exclusively for client-side rendering (no Blazor circuits).

## STS token version

There are two types of token formats, named Version 1 (V1) and Version 2 (V2). In Azure's security token services (STS), the V1 format uses the `sts.windows.net` domain as the issuer, while the V2 format uses the `login.microsoftonline.com` domain as issuer. V2 supports additional features, such as authenticating personal accounts and OpenID protocols.

This article and its accompanying sample apps adopt V1 STS tokens. To adopt V2 tokens, make the following changes:

* The STS version must be changed in the apps' registrations in the Azure portal. Set the value of `requestedAccessTokenVersion` to `2` in the apps' manifests, both in the app's registration and the web API's (`MinimalApiJwt`) registration.
* Use the V2 authority URL format (example: `https://login.microsoftonline.com/{TENANT ID}/v2.0`, where the `{TENANT ID}` placeholder is the tenant ID).
* In the web API (`MinimalApiJwt`), explicitly validate the issuer:

```csharp
jwtOptions.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = true,
// Ensure the issuer ends with /v2.0 if using the V2 endpoint
ValidIssuer = "https://login.microsoftonline.com/{TENANT ID}/v2.0",
ValidateAudience = true,
ValidAudience = "{WEB API CLIENT ID}",
ValidateLifetime = true
};
```

The `{WEB API CLIENT ID}` placeholder in the preceding example is only the client ID, not the full value passed to the `Audience` property.

For more information, see [Access tokens in the Microsoft identity platform: Token formats](/entra/identity-platform/access-tokens#token-formats).

## Troubleshoot

[!INCLUDE[](~/blazor/security/includes/troubleshoot-server.md)]
Expand Down
10 changes: 10 additions & 0 deletions aspnetcore/blazor/security/blazor-web-app-with-oidc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,8 @@ ME-ID tenant Authority example:
jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";
```

The preceding example uses the V1 STS token URL format. For guidance on V2 STS tokens, see <xref:blazor/security/blazor-web-app-entra#sts-token-version>.

AAD B2C tenant Authority example:

```csharp
Expand Down Expand Up @@ -529,6 +531,8 @@ ME-ID tenant Authority example:
jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";
```

The preceding example uses the V1 STS token URL format. For guidance on V2 STS tokens, see <xref:blazor/security/blazor-web-app-entra#sts-token-version>.

AAD B2C tenant Authority example:

```csharp
Expand Down Expand Up @@ -876,6 +880,8 @@ ME-ID tenant Authority example:
jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";
```

The preceding example uses the V1 STS token URL format. For guidance on V2 STS tokens, see <xref:blazor/security/blazor-web-app-entra#sts-token-version>.

AAD B2C tenant Authority example:

```csharp
Expand Down Expand Up @@ -1200,6 +1206,8 @@ In the `MinimalApiJwt` project, add the following app settings configuration to
},
```

The preceding example uses the V1 STS token URL format. For guidance on V2 STS tokens, see <xref:blazor/security/blazor-web-app-entra#sts-token-version>.

Update the placeholders in the preceding configuration to match the values that the app uses in the `Program` file:

* `{TENANT ID (WEB API)}`: The Tenant Id of the web API.
Expand All @@ -1211,6 +1219,8 @@ Authority formats adopt the following patterns:
* Microsoft Entra External ID: `https://{DIRECTORY NAME}.ciamlogin.com/{TENANT ID}/v2.0`
* B2C tenant type: `https://login.microsoftonline.com/{TENANT ID}/v2.0`

The preceding example for the ME-ID tenant type uses the V1 STS token URL format. For guidance on V2 STS tokens, see <xref:blazor/security/blazor-web-app-entra#sts-token-version>.

Audience formats adopt the following patterns (`{CLIENT ID}` is the Client Id of the web API; `{DIRECTORY NAME}` is the directory name, for example, `contoso`):

* ME-ID tenant type: `api://{CLIENT ID}`
Expand Down
Loading