Skip to content

Commit fb9fb82

Browse files
GitHubber17wadepickett
GitHubber17
and
wadepickett
authored
Light Freshness Edit: ASP.NET - Security AUTH (#37122)
* refresh content * edits * re-add older moniker section * link must use locale * Apply suggestions from code review Co-authored-by: Wade Pickett <wpickett@microsoft.com> * re-add anchor --------- Co-authored-by: Wade Pickett <wpickett@microsoft.com>
1 parent b4c712c commit fb9fb82

13 files changed

Lines changed: 254 additions & 209 deletions

File tree

‎aspnetcore/includes/disableVer6.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1-
<a name="ddav"></a>
2-
### Disable default account verification when Account.RegisterConfirmation has been scaffolded
1+
### Disable default account verification when Account.RegisterConfirmation is scaffolded
32

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

6-
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.
5+
> [!IMPORTANT]
6+
> If `Account.RegisterConfirmation` is **not** scaffolded, skip the following instructions and continue to the next section.
77
8-
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:
8+
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.
9+
10+
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:
911

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

12-
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).
14+
This step is necessary only when `Account.RegisterConfirmation` is scaffolded.
15+
16+
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).

‎aspnetcore/includes/dotnet-tool-install-arch-options.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
> [!NOTE]
2-
> 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).
3-
> For more information, see GitHub issue [dotnet/AspNetCore.Docs #29262](https://github.com/dotnet/AspNetCore.Docs/issues/29262).
2+
> By default, the architecture of the .NET binaries to install represents the currently running operating system architecture.
3+
> 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).
4+
> For more information, see [GitHub dotnet/aspnetcore.docs issue #29262](https://github.com/dotnet/AspNetCore.Docs/issues/29262) - _Add '-a arm64' on Apple Silicon_.

‎aspnetcore/security/authentication/accconfirm.md‎

Lines changed: 104 additions & 63 deletions
Large diffs are not rendered by default.

‎aspnetcore/security/authentication/accconfirm/_static/fb.png‎

25 KB
Loading

‎aspnetcore/security/authentication/accconfirm/_static/manage.png‎

-215 KB
Loading

‎aspnetcore/security/authentication/accconfirm/_static/rick.png‎

26.1 KB
Loading

‎aspnetcore/security/authentication/jwt-authn.md‎

Lines changed: 47 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
11
---
22
title: Generate tokens with dotnet user-jwts
33
author: tdykstra
4-
description: Learn how to set up manage JSON Web Tokens in development with dotnet user-jwts
4+
description: Learn how to generate and manage JSON Web Tokens in development with the dotnet user-jwts command.
55
monikerRange: '>= aspnetcore-7.0'
66
ms.author: tdykstra
7-
ms.date: 09/22/2018
7+
ms.date: 05/11/2026
88
ms.custom: mvc
99
uid: security/authentication/jwt
10+
11+
# 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.
1012
---
1113

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

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

16-
The `dotnet user-jwts` command line tool can create and manage app specific local [JSON Web Tokens](https://jwt.io/introduction) (JWTs).
18+
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).
19+
20+
This article provides syntax details for the command and examples.
1721

1822
## Synopsis
1923

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

3135
`PROJECT | SOLUTION`
3236

33-
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.
37+
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.
3438

35-
<!-- Once solutions are supported delete the preceding and uncomment this section
39+
<!-- When solutions are supported, delete the preceding and uncomment this section
3640
3741
```dotnetcli
3842
dotnet user-jwts [<PROJECT>|<SOLUTION>] [command]
@@ -54,33 +58,33 @@ The MSBuild project or solution to apply a command on. If a project or solution
5458
## Commands
5559

5660
| Command | Description |
57-
| ------------- | ------------- |
58-
| clear | Delete all issued JWTs for a project. |
59-
| create | Issue a new JSON Web Token. |
60-
| remove | Delete a given JWT. |
61-
| key | Display or reset the signing key used to issue JWTs. |
62-
| list | Lists the JWTs issued for the project. |
63-
| print | Display the details of a given JWT. |
61+
| -------- | ----------- |
62+
| `clear` | Delete all issued JWTs for a project. |
63+
| `create` | Issue a new JSON Web Token. |
64+
| `remove` | Delete a given JWT. |
65+
| `key` | Display or reset the signing key used to issue JWTs. |
66+
| `list` | List the JWTs issued for the project. |
67+
| `print` | Display the details of a given JWT. |
6468

65-
### Create
69+
### Options for the create command
6670

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

6973
| Option | Description |
70-
| ------------- | ------------- |
71-
| -p \| --project | The path of the project to operate on. Defaults to the project in the current directory. |
72-
| --scheme | The scheme name to use for the generated token. Defaults to 'Bearer'. |
73-
| -n \| --name | The name of the user to create the JWT for. Defaults to the current environment user. |
74-
| --audience | The audiences to create the JWT for. Defaults to the URLs configured in the project's launchSettings.json. |
75-
| --issuer | The issuer of the JWT. Defaults to 'dotnet-user-jwts'. |
76-
| --scope | A scope claim to add to the JWT. Specify once for each scope. |
77-
| --role | A role claim to add to the JWT. Specify once for each role. |
78-
| --claim | Claims to add to the JWT. Specify once for each claim in the format "name=value". |
79-
| --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. |
80-
| --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. |
81-
| --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. |
82-
| -o \| --output | The format to use for displaying output from the command. Can be one of 'default', 'token', or 'json'. |
83-
| -h \| --help | Show help information |
74+
| ------- | ----------- |
75+
| `-p \| --project` | The path of the project to operate on. Defaults to the project in the current directory. |
76+
| `--scheme` | The scheme name to use for the generated token. Defaults to `Bearer`. |
77+
| `-n \| --name` | The name of the user to create the JWT for. Defaults to the current environment user. |
78+
| `--audience` | The audiences to create the JWT for. Defaults to the URLs configured in the project's _launchSettings.json_ file. |
79+
| `--issuer` | The issuer of the JWT. Defaults to `dotnet-user-jwts`. |
80+
| `--scope` | A scope claim to add to the JWT. Specify once for each scope. |
81+
| `--role` | A role claim to add to the JWT. Specify once for each role. |
82+
| `--claim` | Claims to add to the JWT. Specify once for each claim in the format `name=value`. |
83+
| `--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. |
84+
| `--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. |
85+
| `--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. |
86+
| `-o \| --output` | The format to use for displaying output from the command: `default`, `token`, or `json`. |
87+
| `-h \| --help` | Show help information for the command. |
8488

8589
## Examples
8690

@@ -92,29 +96,21 @@ cd MyJWT
9296
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
9397
```
9498

95-
Replace the contents of `Program.cs` with the following code:
99+
Replace the contents of the _Program.cs_ file with the following code:
96100

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

99-
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.
100-
101-
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.
103+
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.
102104

103-
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:
105+
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.
104106

105-
# [Windows](#tab/windows)
107+
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.
106108

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

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

111-
# [Linux / macOS](#tab/linux+macos)
112-
113-
File system path:
114-
115-
`~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json`
116-
117-
---
113+
- **Linux/macOS**: _~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json_
118114

119115
### Create a JWT
120116

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

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

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

131-
Copy the JWT and the `ID` created in the preceding command. Use a tool like Curl to test `/secret`:
127+
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:
132128

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

137-
Where `{token}` is the previously generated JWT.
138-
139133
### Display JWT security information
140134

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

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

149-
See [Create](#create) in this topic for supported create options.
150-
151-
The following command creates a JWT for a user named `MyTestUser`:
143+
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.
152144

153145
```dotnetcli
154146
dotnet user-jwts create --name MyTestUser --scope "myapi:secrets"
155147
```
156148

157-
The preceding command has output similar to the following:
149+
The preceding command has output similar to the following example:
158150

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

169161
:::code language="csharp" source="~/security/authentication/jwt-authn/samples/MyJWT/Program.cs" id="snippet_2" highlight="11-12":::
162+
163+
## Related content
164+
165+
- [Microsoft.AspNetCore.Authentication.JwtBearer](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer)
166+
- [JSON Web Tokens](https://www.jwt.io/introduction#what-is-json-web-token)

‎aspnetcore/security/authentication/scaffold-identity.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Although the scaffolder generates most of the necessary code, you need to update
3636

3737
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.
3838

39-
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).
39+
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.
4040

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

0 commit comments

Comments
 (0)