Skip to content

Commit 8b741bd

Browse files
pranavkmpranavkm
authored
Add docs for Negotiate, OAuth, OpenIdConnect (#26610)
* Add docs for Negotiate, OAuth, OpenIdConnect Contributes to #26397
1 parent fda7d1d commit 8b741bd

38 files changed

+416
-61
lines changed

‎src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<Project Sdk="Microsoft.NET.Sdk">
1+
<Project Sdk="Microsoft.NET.Sdk">
22

33
<PropertyGroup>
44
<Description>ASP.NET Core middleware that enables an application to support the Microsoft Account authentication workflow.</Description>

‎src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,7 @@ public class AuthenticatedContext : ResultContext<NegotiateOptions>
1313
/// <summary>
1414
/// Creates a new <see cref="AuthenticatedContext"/>.
1515
/// </summary>
16-
/// <param name="context"></param>
17-
/// <param name="scheme"></param>
18-
/// <param name="options"></param>
16+
/// <inheritdoc />
1917
public AuthenticatedContext(
2018
HttpContext context,
2119
AuthenticationScheme scheme,

‎src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,7 @@ public class AuthenticationFailedContext : RemoteAuthenticationContext<Negotiate
1414
/// <summary>
1515
/// Creates a <see cref="AuthenticationFailedContext"/>.
1616
/// </summary>
17-
/// <param name="context"></param>
18-
/// <param name="scheme"></param>
19-
/// <param name="options"></param>
17+
/// <inheritdoc />
2018
public AuthenticationFailedContext(
2119
HttpContext context,
2220
AuthenticationScheme scheme,

‎src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,7 @@ public class ChallengeContext : PropertiesContext<NegotiateOptions>
1414
/// <summary>
1515
/// Creates a new <see cref="ChallengeContext"/>.
1616
/// </summary>
17-
/// <param name="context"></param>
18-
/// <param name="scheme"></param>
19-
/// <param name="options"></param>
20-
/// <param name="properties"></param>
17+
/// <inheritdoc />
2118
public ChallengeContext(
2219
HttpContext context,
2320
AuthenticationScheme scheme,
@@ -26,7 +23,8 @@ public ChallengeContext(
2623
: base(context, scheme, options, properties) { }
2724

2825
/// <summary>
29-
/// If true, will skip any default logic for this challenge.
26+
/// Gets a value that determines if this challenge was handled.
27+
/// If <see langword="true"/>, will skip any default logic for this challenge.
3028
/// </summary>
3129
public bool Handled { get; private set; }
3230

‎src/Security/Authentication/Negotiate/src/Events/LdapContext.cs

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,7 @@ public class LdapContext : ResultContext<NegotiateOptions>
1313
/// <summary>
1414
/// Creates a new <see cref="LdapContext"/>.
1515
/// </summary>
16-
/// <param name="context"></param>
17-
/// <param name="scheme"></param>
18-
/// <param name="options"></param>
19-
/// <param name="settings"></param>
16+
/// <inheritdoc />
2017
public LdapContext(
2118
HttpContext context,
2219
AuthenticationScheme scheme,

‎src/Security/Authentication/Negotiate/src/LdapSettings.cs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,9 @@ public class LdapSettings
7676

7777
internal MemoryCache ClaimsCache { get; set; }
7878

79+
/// <summary>
80+
/// Validates the <see cref="LdapSettings"/>.
81+
/// </summary>
7982
public void Validate()
8083
{
8184
if (EnableLdapClaimResolution)

‎src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<PropertyGroup>
44
<Description>ASP.NET Core authentication handler used to authenticate requests using Negotiate, Kerberos, or NTLM.</Description>
55
<TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
6+
<NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
67
<GenerateDocumentationFile>true</GenerateDocumentationFile>
78
<PackageTags>aspnetcore;authentication;security</PackageTags>
89
</PropertyGroup>

‎src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,23 @@ namespace Microsoft.Extensions.DependencyInjection
1717
public static class NegotiateExtensions
1818
{
1919
/// <summary>
20-
/// Adds Negotiate authentication.
20+
/// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
21+
/// using the default scheme from <see cref="NegotiateDefaults.AuthenticationScheme"/>.
22+
/// <para>
23+
/// This authentication handler supports Kerberos on Windows and Linux servers.
24+
/// </para>
2125
/// </summary>
2226
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
2327
/// <returns>The original builder.</returns>
2428
public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder builder)
2529
=> builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, _ => { });
2630

2731
/// <summary>
28-
/// Adds and configures Negotiate authentication.
32+
/// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
33+
/// using the default scheme. The default scheme is specified by <see cref="NegotiateDefaults.AuthenticationScheme"/>.
34+
/// <para>
35+
/// This authentication handler supports Kerberos on Windows and Linux servers.
36+
/// </para>
2937
/// </summary>
3038
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
3139
/// <param name="configureOptions">Allows for configuring the authentication handler.</param>
@@ -34,7 +42,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil
3442
=> builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, configureOptions);
3543

3644
/// <summary>
37-
/// Adds and configures Negotiate authentication.
45+
/// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
46+
/// using the specified authentication scheme.
47+
/// <para>
48+
/// This authentication handler supports Kerberos on Windows and Linux servers.
49+
/// </para>
3850
/// </summary>
3951
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
4052
/// <param name="authenticationScheme">The scheme name used to identify the authentication handler internally.</param>
@@ -44,7 +56,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil
4456
=> builder.AddNegotiate(authenticationScheme, displayName: null, configureOptions: configureOptions);
4557

4658
/// <summary>
47-
/// Adds and configures Negotiate authentication.
59+
/// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
60+
/// using the specified authentication scheme.
61+
/// <para>
62+
/// This authentication handler supports Kerberos on Windows and Linux servers.
63+
/// </para>
4864
/// </summary>
4965
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
5066
/// <param name="authenticationScheme">The scheme name used to identify the authentication handler internally.</param>

‎src/Security/Authentication/Negotiate/src/NegotiateHandler.cs

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,7 @@ public class NegotiateHandler : AuthenticationHandler<NegotiateOptions>, IAuthen
3434
/// <summary>
3535
/// Creates a new <see cref="NegotiateHandler"/>
3636
/// </summary>
37-
/// <param name="options"></param>
38-
/// <param name="logger"></param>
39-
/// <param name="encoder"></param>
40-
/// <param name="clock"></param>
37+
/// <inheritdoc />
4138
public NegotiateHandler(IOptionsMonitor<NegotiateOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
4239
: base(options, logger, encoder, clock)
4340
{ }
@@ -63,7 +60,7 @@ public NegotiateHandler(IOptionsMonitor<NegotiateOptions> options, ILoggerFactor
6360
/// <summary>
6461
/// Intercepts incomplete Negotiate authentication handshakes and continues or completes them.
6562
/// </summary>
66-
/// <returns>True if a response was generated, false otherwise.</returns>
63+
/// <returns><see langword="true" /> if a response was generated, otherwise <see langword="false"/>.</returns>
6764
public async Task<bool> HandleRequestAsync()
6865
{
6966
AuthPersistence persistence = null;

‎src/Security/Authentication/Negotiate/src/NegotiateOptions.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,15 @@ public class NegotiateOptions : AuthenticationSchemeOptions
2424
/// <summary>
2525
/// Indicates if Kerberos credentials should be persisted and re-used for subsquent anonymous requests.
2626
/// This option must not be used if connections may be shared by requests from different users.
27-
/// The default is false.
2827
/// </summary>
28+
/// <value>Defaults to <see langword="false"/>.</value>
2929
public bool PersistKerberosCredentials { get; set; } = false;
3030

3131
/// <summary>
3232
/// Indicates if NTLM credentials should be persisted and re-used for subsquent anonymous requests.
3333
/// This option must not be used if connections may be shared by requests from different users.
34-
/// The default is true.
3534
/// </summary>
35+
/// <value>Defaults to <see langword="true"/>.</value>
3636
public bool PersistNtlmCredentials { get; set; } = true;
3737

3838
/// <summary>

‎src/Security/Authentication/OAuth/src/ClaimAction.cs

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,13 @@ public ClaimAction(string claimType, string valueType)
2323
}
2424

2525
/// <summary>
26-
/// The value to use for Claim.Type when creating a Claim.
26+
/// Gets the value to use for <see cref="Claim.Value"/>when creating a Claim.
2727
/// </summary>
2828
public string ClaimType { get; }
2929

30-
// The value to use for Claim.ValueType when creating a Claim.
30+
/// <summary>
31+
/// Gets the value to use for <see cref="Claim.ValueType"/> when creating a Claim.
32+
/// </summary>
3133
public string ValueType { get; }
3234

3335
/// <summary>

‎src/Security/Authentication/OAuth/src/ClaimActionCollection.cs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) .NET Foundation. All rights reserved.
1+
// Copyright (c) .NET Foundation. All rights reserved.
22
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
33

44
using System;
@@ -39,6 +39,7 @@ public void Add(ClaimAction action)
3939
Actions.Add(action);
4040
}
4141

42+
/// <inheritdoc />
4243
public IEnumerator<ClaimAction> GetEnumerator()
4344
{
4445
return Actions.GetEnumerator();
@@ -49,4 +50,4 @@ IEnumerator IEnumerable.GetEnumerator()
4950
return Actions.GetEnumerator();
5051
}
5152
}
52-
}
53+
}

‎src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,16 @@
88

99
namespace Microsoft.AspNetCore.Authentication
1010
{
11+
/// <summary>
12+
/// Extension methods for <see cref="ClaimActionCollection"/>.
13+
/// </summary>
1114
public static class ClaimActionCollectionMapExtensions
1215
{
1316
/// <summary>
1417
/// Select a top level value from the json user data with the given key name and add it as a Claim.
1518
/// This no-ops if the key is not found or the value is empty.
1619
/// </summary>
17-
/// <param name="collection"></param>
20+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
1821
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
1922
/// <param name="jsonKey">The top level key to look for in the json user data.</param>
2023
public static void MapJsonKey(this ClaimActionCollection collection, string claimType, string jsonKey)
@@ -26,7 +29,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai
2629
/// Select a top level value from the json user data with the given key name and add it as a Claim.
2730
/// This no-ops if the key is not found or the value is empty.
2831
/// </summary>
29-
/// <param name="collection"></param>
32+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
3033
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
3134
/// <param name="jsonKey">The top level key to look for in the json user data.</param>
3235
/// <param name="valueType">The value to use for Claim.ValueType when creating a Claim.</param>
@@ -39,7 +42,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai
3942
/// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim.
4043
/// This no-ops if the keys are not found or the value is empty.
4144
/// </summary>
42-
/// <param name="collection"></param>
45+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
4346
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
4447
/// <param name="jsonKey">The top level key to look for in the json user data.</param>
4548
/// <param name="subKey">The second level key to look for in the json user data.</param>
@@ -52,7 +55,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c
5255
/// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim.
5356
/// This no-ops if the keys are not found or the value is empty.
5457
/// </summary>
55-
/// <param name="collection"></param>
58+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
5659
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
5760
/// <param name="jsonKey">The top level key to look for in the json user data.</param>
5861
/// <param name="subKey">The second level key to look for in the json user data.</param>
@@ -66,7 +69,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c
6669
/// Run the given resolver to select a value from the json user data to add as a claim.
6770
/// This no-ops if the returned value is empty.
6871
/// </summary>
69-
/// <param name="collection"></param>
72+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
7073
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
7174
/// <param name="resolver">The Func that will be called to select value from the given json user data.</param>
7275
public static void MapCustomJson(this ClaimActionCollection collection, string claimType, Func<JsonElement, string> resolver)
@@ -78,7 +81,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c
7881
/// Run the given resolver to select a value from the json user data to add as a claim.
7982
/// This no-ops if the returned value is empty.
8083
/// </summary>
81-
/// <param name="collection"></param>
84+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
8285
/// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
8386
/// <param name="valueType">The value to use for Claim.ValueType when creating a Claim.</param>
8487
/// <param name="resolver">The Func that will be called to select value from the given json user data.</param>
@@ -90,7 +93,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c
9093
/// <summary>
9194
/// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding duplicates.
9295
/// </summary>
93-
/// <param name="collection"></param>
96+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
9497
public static void MapAll(this ClaimActionCollection collection)
9598
{
9699
collection.Clear();
@@ -100,8 +103,8 @@ public static void MapAll(this ClaimActionCollection collection)
100103
/// <summary>
101104
/// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding the specified types.
102105
/// </summary>
103-
/// <param name="collection"></param>
104-
/// <param name="exclusions"></param>
106+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
107+
/// <param name="exclusions">The types to exclude.</param>
105108
public static void MapAllExcept(this ClaimActionCollection collection, params string[] exclusions)
106109
{
107110
collection.MapAll();
@@ -111,8 +114,8 @@ public static void MapAllExcept(this ClaimActionCollection collection, params st
111114
/// <summary>
112115
/// Delete all claims from the given ClaimsIdentity with the given ClaimType.
113116
/// </summary>
114-
/// <param name="collection"></param>
115-
/// <param name="claimType"></param>
117+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
118+
/// <param name="claimType">The claim type to delete</param>
116119
public static void DeleteClaim(this ClaimActionCollection collection, string claimType)
117120
{
118121
collection.Add(new DeleteClaimAction(claimType));
@@ -121,8 +124,8 @@ public static void DeleteClaim(this ClaimActionCollection collection, string cla
121124
/// <summary>
122125
/// Delete all claims from the ClaimsIdentity with the given claimTypes.
123126
/// </summary>
124-
/// <param name="collection"></param>
125-
/// <param name="claimTypes"></param>
127+
/// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
128+
/// <param name="claimTypes">The claim types to delete.</param>
126129
public static void DeleteClaims(this ClaimActionCollection collection, params string[] claimTypes)
127130
{
128131
if (claimTypes == null)

‎src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,16 @@ public TimeSpan? ExpiresIn
108108
/// </summary>
109109
public ClaimsIdentity Identity => Principal?.Identity as ClaimsIdentity;
110110

111+
/// <summary>
112+
/// Examines <see cref="User"/>, determine if the requisite data is present, and optionally add it
113+
/// to <see cref="Identity"/>.
114+
/// </summary>
111115
public void RunClaimActions() => RunClaimActions(User);
112116

117+
/// <summary>
118+
/// Examines the specified <paramref name="userData"/>, determine if the requisite data is present, and optionally add it
119+
/// to <see cref="Identity"/>.
120+
/// </summary>
113121
public void RunClaimActions(JsonElement userData)
114122
{
115123
foreach (var action in Options.ClaimActions)

‎src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,14 @@ namespace Microsoft.AspNetCore.Authentication.OAuth.Claims
1313
/// </summary>
1414
public class MapAllClaimsAction : ClaimAction
1515
{
16+
/// <summary>
17+
/// Initializes a new instance of <see cref="MapAllClaimsAction"/>.
18+
/// </summary>
1619
public MapAllClaimsAction() : base("All", ClaimValueTypes.String)
1720
{
1821
}
1922

23+
/// <inheritdoc />
2024
public override void Run(JsonElement userData, ClaimsIdentity identity, string issuer)
2125
{
2226
foreach (var pair in userData.EnumerateObject())

‎src/Security/Authentication/OAuth/src/Microsoft.AspNetCore.Authentication.OAuth.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<Description>ASP.NET Core middleware that enables an application to support any standard OAuth 2.0 authentication workflow.</Description>
55
<TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
66
<IsAspNetCoreApp>true</IsAspNetCoreApp>
7-
<NoWarn>$(NoWarn);CS1591</NoWarn>
7+
<NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
88
<GenerateDocumentationFile>true</GenerateDocumentationFile>
99
<PackageTags>aspnetcore;authentication;security</PackageTags>
1010
<IsPackable>false</IsPackable>

0 commit comments

Comments
 (0)