Skip to content

Light Freshness Edit: ASP.NET - Security AUTH #37122

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

Draft
GitHubber17 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Light Freshness Edit: ASP.NET - Security AUTH #37122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
16 changes: 10 additions & 6 deletions aspnetcore/includes/disableVer6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
<a name="ddav"></a>
### Disable default account verification when Account.RegisterConfirmation has been scaffolded
### Disable default account verification when Account.RegisterConfirmation is scaffolded

This section only applies when `Account.RegisterConfirmation` is scaffolded. Skip this section if you have not scaffolded `Account.RegisterConfirmation`.
If `Account.RegisterConfirmation` is scaffolded, complete the instructions in this section.

The user is redirected to the `Account.RegisterConfirmation` where they can select a link to have the account confirmed. The default `Account.RegisterConfirmation` is used ***only*** for testing, automatic account verification should be disabled in a production app.
> [!IMPORTANT]
> If `Account.RegisterConfirmation` is **not** scaffolded, skip the following instructions and continue to the next section.

To require a confirmed account and prevent immediate login at registration, set `DisplayConfirmAccountLink = false` in the scaffolded `/Areas/Identity/Pages/Account/RegisterConfirmation.cshtml.cs` file:
The user is redirected to the `/Identity/Account/RegisterConfirmation` page where they can select a link to have the account confirmed. The default `Account.RegisterConfirmation` is used ***only*** for testing. Automatic account verification should be disabled in a production app.

To require a confirmed account and prevent immediate sign in at registration, set `DisplayConfirmAccountLink = false` in the scaffolded _/Areas/Identity/Pages/Account/RegisterConfirmation.cshtml.cs_ file:

[!code-csharp[](~/security/authentication/accconfirm/sample/RegisterConfirmation.cshtml.cs?highlight=63)]

This step is only necessary when `Account.RegisterConfirmation` is scaffolded. The non-scaffolded [RegisterConfirmation](https://github.com/dotnet/aspnetcore/blob/1dcf7acfacf0fe154adcc23270cb0da11ff44ace/src/Identity/UI/src/Areas/Identity/Pages/V4/Account/RegisterConfirmation.cshtml.cs#L74-L87) automatically detects when an [IEmailSender](https://github.com/dotnet/aspnetcore/blob/1dcf7acfacf0fe154adcc23270cb0da11ff44ace/src/Identity/UI/src/Areas/Identity/Services/EmailSender.cs) has been implemented and registered with the [dependency injection container](xref:fundamentals/dependency-injection).
This step is necessary only when `Account.RegisterConfirmation` is scaffolded.

The non-scaffolded [RegisterConfirmation](https://github.com/dotnet/aspnetcore/blob/1dcf7acfacf0fe154adcc23270cb0da11ff44ace/src/Identity/UI/src/Areas/Identity/Pages/V4/Account/RegisterConfirmation.cshtml.cs#L74-L87) automatically detects when an [IEmailSender](https://github.com/dotnet/aspnetcore/blob/1dcf7acfacf0fe154adcc23270cb0da11ff44ace/src/Identity/UI/src/Areas/Identity/Services/EmailSender.cs) is implemented and registered with the [dependency injection container](xref:fundamentals/dependency-injection).
5 changes: 3 additions & 2 deletions aspnetcore/includes/dotnet-tool-install-arch-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
> [!NOTE]
> By default the architecture of the .NET binaries to install represents the currently running OS architecture. To specify a different OS architecture, see [dotnet tool install, --arch option](/dotnet/core/tools/dotnet-tool-install#options).
> For more information, see GitHub issue [dotnet/AspNetCore.Docs #29262](https://github.com/dotnet/AspNetCore.Docs/issues/29262).
> By default, the architecture of the .NET binaries to install represents the currently running operating system architecture.
> To specify a different architecture, review how to use the `dotnet tool install` command with the ['--arch' option](/dotnet/core/tools/dotnet-tool-install#options).
> For more information, see [GitHub dotnet/aspnetcore issue #29262](https://github.com/dotnet/AspNetCore.Docs/issues/29262) - _Add '-a arm64' on Apple Silicon_.
159 changes: 96 additions & 63 deletions aspnetcore/security/authentication/accconfirm.md
View file
Open in desktop

Large diffs are not rendered by default.

Binary file modified aspnetcore/security/authentication/accconfirm/_static/fb.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified aspnetcore/security/authentication/accconfirm/_static/manage.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified aspnetcore/security/authentication/accconfirm/_static/rick.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
97 changes: 47 additions & 50 deletions aspnetcore/security/authentication/jwt-authn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,23 @@
---
title: Generate tokens with dotnet user-jwts
author: tdykstra
description: Learn how to set up manage JSON Web Tokens in development with dotnet user-jwts
description: Learn how to generate and manage JSON Web Tokens in development with the dotnet user-jwts command.
monikerRange: '>= aspnetcore-7.0'
ms.author: tdykstra
ms.date: 09/22/2018
ms.date: 05/11/2026
ms.custom: mvc
uid: security/authentication/jwt

# customer intent: As an ASP.NET developer, I want to use the dotnet user-jwts command, so I can generate and manage JSON Web Tokens in development.
---

# Manage JSON Web Tokens in development with dotnet user-jwts

By [Rick Anderson](https://twitter.com/RickAndMSFT)

The `dotnet user-jwts` command line tool can create and manage app specific local [JSON Web Tokens](https://jwt.io/introduction) (JWTs).
The `dotnet user-jwts` command line tool can create and manage app specific local [JSON Web Tokens](https://www.jwt.io/introduction#what-is-json-web-token) (JWTs).

This article provides syntax details for the command and examples.

## Synopsis

Expand All @@ -30,9 +34,9 @@ Creates and manages project specific local JSON Web Tokens.

`PROJECT | SOLUTION`

The MSBuild project to apply a command on. If a project is not specified, MSBuild searches the current working directory for a file that has a file extension that ends in *proj* and uses that file.
The MSBuild project to apply a command on. If a project isn't specified, MSBuild searches the current working directory for a file that has a file extension that ends in *proj*. It then uses that file to obtain the project information for the command.

<!-- Once solutions are supported delete the preceding and uncomment this section
<!-- When solutions are supported, delete the preceding and uncomment this section

```dotnetcli
dotnet user-jwts [<PROJECT>|<SOLUTION>] [command]
Expand All @@ -54,33 +58,33 @@ The MSBuild project or solution to apply a command on. If a project or solution
## Commands

| Command | Description |
| ------------- | ------------- |
| clear | Delete all issued JWTs for a project. |
| create | Issue a new JSON Web Token. |
| remove | Delete a given JWT. |
| key | Display or reset the signing key used to issue JWTs. |
| list | Lists the JWTs issued for the project. |
| print | Display the details of a given JWT. |
| -------- | ----------- |
| `clear` | Delete all issued JWTs for a project. |
| `create` | Issue a new JSON Web Token. |
| `remove` | Delete a given JWT. |
| `key` | Display or reset the signing key used to issue JWTs. |
| `list` | List the JWTs issued for the project. |
| `print` | Display the details of a given JWT. |

### Create
### Options for the create command

Usage: `dotnet user-jwts create [options]`

| Option | Description |
| ------------- | ------------- |
| -p \| --project | The path of the project to operate on. Defaults to the project in the current directory. |
| --scheme | The scheme name to use for the generated token. Defaults to 'Bearer'. |
| -n \| --name | The name of the user to create the JWT for. Defaults to the current environment user. |
| --audience | The audiences to create the JWT for. Defaults to the URLs configured in the project's launchSettings.json. |
| --issuer | The issuer of the JWT. Defaults to 'dotnet-user-jwts'. |
| --scope | A scope claim to add to the JWT. Specify once for each scope. |
| --role | A role claim to add to the JWT. Specify once for each role. |
| --claim | Claims to add to the JWT. Specify once for each claim in the format "name=value". |
| --not-before | The UTC date & time the JWT should not be valid before in the format 'yyyy-MM-dd [[HH:mm[[:ss]]]]'. Defaults to the date & time the JWT is created. |
| --expires-on | The UTC date & time the JWT should expire in the format 'yyyy-MM-dd [[[ [HH:mm]]:ss]]'. Defaults to 6 months after the --not-before date. Do not use this option in conjunction with the --valid-for option. |
| --valid-for | The period the JWT should expire after. Specify using a number followed by duration type like 'd' for days, 'h' for hours, 'm' for minutes, and 's' for seconds, for example 365d'. Do not use this option in conjunction with the --expires-on option. |
| -o \| --output | The format to use for displaying output from the command. Can be one of 'default', 'token', or 'json'. |
| -h \| --help | Show help information |
| ------- | ----------- |
| `-p \| --project` | The path of the project to operate on. Defaults to the project in the current directory. |
| `--scheme` | The scheme name to use for the generated token. Defaults to `Bearer`. |
| `-n \| --name` | The name of the user to create the JWT for. Defaults to the current environment user. |
| `--audience` | The audiences to create the JWT for. Defaults to the URLs configured in the project's _launchSettings.json_ file. |
| `--issuer` | The issuer of the JWT. Defaults to `dotnet-user-jwts`. |
| `--scope` | A scope claim to add to the JWT. Specify once for each scope. |
| `--role` | A role claim to add to the JWT. Specify once for each role. |
| `--claim` | Claims to add to the JWT. Specify once for each claim in the format `name=value`. |
| `--not-before` | The UTC date and time at which the JWT becomes valid, in the format `yyyy-MM-dd [[HH:mm[[:ss]]]]`. Defaults to the date and time the JWT is created. |
| `--expires-on` | The UTC date and time at which the JWT expires, in the format `yyyy-MM-dd [[[ [HH:mm]]:ss]]`. Defaults to six months after the `--not-before` date. Don't use this option with the `--valid-for` option. |
| `--valid-for` | The amount of time the JWT remains valid. When the time is reached, the JWT expires. Specify a number followed by the duration type (`d` days, `h` hours, `m` minutes, `s` seconds), such as `365d`. Don't use this option with the `--expires-on` option. |
| `-o \| --output` | The format to use for displaying output from the command: `default`, `token`, or `json`. |
| `-h \| --help` | Show help information for the command. |

## Examples

Expand All @@ -92,29 +96,21 @@ cd MyJWT
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

Replace the contents of `Program.cs` with the following code:
Replace the contents of the _Program.cs_ file with the following code:

:::code language="csharp" source="~/security/authentication/jwt-authn/samples/MyJWT/Program.cs" id="snippet_1":::

In the preceding code, a GET request to `/secret` returns an `401 Unauthorized` error. A production app might get the JWT from a [Security token service](/azure/active-directory/develop/security-tokens) (STS), perhaps in response to logging in via a set of credentials. For the purpose of working with the API during local development, the `dotnet user-jwts` command line tool can be used to create and manage app-specific local JWTs.

The `user-jwts` tool is similar in concept to the [user-secrets](xref:security/app-secrets) tool, it can be used to manage values for the app that are only valid for the developer on the local machine. In fact, the user-jwts tool utilizes the `user-secrets` infrastructure to manage the key that the JWTs are signed with, ensuring it’s stored safely in the user profile.
In the preceding code, a GET request to the `/secret` endpoint returns a `401 Unauthorized` error. A production app might get the JWT from a [Security token service](/entra/identity-platform/security-tokens), perhaps in response to signing in with credentials. When you use the API during local development, the `dotnet user-jwts` command line tool can be used to create and manage app-specific local JWTs.

The `user-jwts` tool hides implementation details, such as where and how the values are stored. The tool can be used without knowing the implementation details. The values are stored in a JSON file in the local machine's user profile folder:
The `user-jwts` tool is similar in concept to the [user-secrets](xref:security/app-secrets) tool. It can be used to manage values for the app that are valid only for the developer on the local machine. In fact, the `user-jwts` tool utilizes the `user-secrets` infrastructure to manage the key that the JWTs are signed with. This approach ensures the key is stored safely in the user profile.

# [Windows](#tab/windows)
The `user-jwts` tool hides implementation details, such as where and how the values are stored. The tool can be used without knowing the implementation details.

File system path:
The values are stored in a JSON file in the local machine's user profile folder:

`%APPDATA%\Microsoft\UserSecrets\<secrets_GUID>\user-jwts.json`
- **Windows**: _%APPDATA%\Microsoft\UserSecrets\<secrets_GUID>\user-jwts.json_

# [Linux / macOS](#tab/linux+macos)

File system path:

`~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json`

---
- **Linux/macOS**: _~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json_

### Create a JWT

Expand All @@ -124,18 +120,16 @@ The following command creates a local JWT:
dotnet user-jwts create
```

The preceding command creates a JWT and updates the project’s `appsettings.Development.json` file with JSON similar to the following:
The preceding command creates a JWT and updates the project `appsettings.Development.json` file with JSON similar to the following example:

:::code language="csharp" source="~/security/authentication/jwt-authn/samples/MyJWT/appsettings.Development.json" highlight="7-19":::

Copy the JWT and the `ID` created in the preceding command. Use a tool like Curl to test `/secret`:
Copy the JWT and the `ID` created in the preceding command. Use a tool like Curl to test the `/secret` endpoint, where `{token}` is the previously generated JWT:

```dotnetcli
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/secret
```

Where `{token}` is the previously generated JWT.

### Display JWT security information

The following command displays the JWT security information, including expiration, scopes, roles, token header and payload, and the compact token:
Expand All @@ -146,15 +140,13 @@ dotnet user-jwts print {ID} --show-all

### Create a token for a specific user and scope

See [Create](#create) in this topic for supported create options.

The following command creates a JWT for a user named `MyTestUser`:
The following command creates a JWT for a user named `MyTestUser`. For the supported `create` options, see the [Options for the create command](#options-for-the-create-command) section.

```dotnetcli
dotnet user-jwts create --name MyTestUser --scope "myapi:secrets"
```

The preceding command has output similar to the following:
The preceding command has output similar to the following example:

```dotnetcli
New JWT saved with ID '43e0b748'.
Expand All @@ -167,3 +159,8 @@ Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}
The preceding token can be used to test the `/secret2` endpoint in the following code:

:::code language="csharp" source="~/security/authentication/jwt-authn/samples/MyJWT/Program.cs" id="snippet_2" highlight="11-12":::

## Related content

- [Microsoft.AspNetCore.Authentication.JwtBearer](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer)
- [JSON Web Tokens](https://www.jwt.io/introduction#what-is-json-web-token)
2 changes: 1 addition & 1 deletion aspnetcore/security/authentication/scaffold-identity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Although the scaffolder generates most of the necessary code, you need to update

We recommend using a source control system that shows file differences and allows you to back out of changes. Inspect the changes after running the Identity scaffolder.

Services are required when using [Two Factor Authentication](xref:security/authentication/identity-enable-qrcodes), [Account confirmation and password recovery](xref:security/authentication/accconfirm), and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually. For example, see [Require Email Confirmation](xref:security/authentication/accconfirm#require-email-confirmation).
Services are required when using [Two Factor Authentication](xref:security/authentication/identity-enable-qrcodes), [Account confirmation and password recovery](xref:security/authentication/accconfirm), and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually. For example, see [Configure an email provider](xref:security/authentication/accconfirm#configure-an-email-provider) so the app can require email confirmation.

Typically, apps created with individual accounts should ***not*** create a new data context.

Expand Down
Loading
Loading