From 073aae5bb058cb84a34e7ebd2b97c3015f85ccf3 Mon Sep 17 00:00:00 2001 From: Ignacio Inglese Date: Tue, 10 Dec 2024 15:50:33 +0000 Subject: [PATCH] Updated documentation --- ...nWebTokenHandler.ValidateToken.Internal.cs | 14 ++----- ...rityTokenHandler.ValidateToken.Internal.cs | 10 +++++ ...rityTokenHandler.ValidateToken.Internal.cs | 10 +++++ .../Validation/Results/ValidatedToken.cs | 36 +++++++++++++++++ .../Validation/Results/ValidationResult.cs | 39 ++++++++++--------- .../Validation/Validators.Algorithm.cs | 9 +++-- .../Validation/Validators.Audience.cs | 14 +++---- .../Validation/Validators.Issuer.cs | 9 +---- .../Validation/Validators.IssuerSigningKey.cs | 14 +++---- .../Validation/Validators.Lifetime.cs | 13 ++----- .../Validation/Validators.TokenReplay.cs | 17 ++++---- .../Validation/Validators.TokenType.cs | 11 ++++-- 12 files changed, 118 insertions(+), 78 deletions(-) diff --git a/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs b/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs index f4548d604d..b0f96f3ce4 100644 --- a/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs +++ b/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs @@ -17,22 +17,14 @@ public partial class JsonWebTokenHandler : TokenHandler { /// /// Validates a token. - /// On a validation failure, no exception will be thrown; instead, the exception will be set in the returned TokenValidationResult.Exception property. - /// Callers should always check the TokenValidationResult.IsValid property to verify the validity of the result. + /// On a validation failure, no exception will be thrown; instead, the will contain the information about the error that occurred. + /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result. /// /// The token to be validated. /// The to be used for validating the token. - /// A that contains useful information for logging. + /// A that contains call information. /// A that can be used to request cancellation of the asynchronous operation. /// A with either a if the token was validated or an with the failure information and exception otherwise. - /// - /// ValidationError.GetException() will return one of the following exceptions if the is invalid. - /// - /// Returned if is null or empty. - /// Returned if is null. - /// Returned if 'token.Length' is greater than . - /// Returned if is not a valid , - /// Returned if the validationParameters.TokenReader delegate is not able to parse/read the token as a valid , internal async Task> ValidateTokenAsync( string token, ValidationParameters validationParameters, diff --git a/src/Microsoft.IdentityModel.Tokens.Saml/Saml/SamlSecurityTokenHandler.ValidateToken.Internal.cs b/src/Microsoft.IdentityModel.Tokens.Saml/Saml/SamlSecurityTokenHandler.ValidateToken.Internal.cs index 2ddddbfd87..c48ebe8f76 100644 --- a/src/Microsoft.IdentityModel.Tokens.Saml/Saml/SamlSecurityTokenHandler.ValidateToken.Internal.cs +++ b/src/Microsoft.IdentityModel.Tokens.Saml/Saml/SamlSecurityTokenHandler.ValidateToken.Internal.cs @@ -14,6 +14,16 @@ namespace Microsoft.IdentityModel.Tokens.Saml /// public partial class SamlSecurityTokenHandler : SecurityTokenHandler { + /// + /// Validates a token. + /// On a validation failure, no exception will be thrown; instead, the will contain the information about the error that occurred. + /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result. + /// + /// The token to be validated. + /// The to be used for validating the token. + /// A that contains call information. + /// A that can be used to request cancellation of the asynchronous operation. + /// A with either a if the token was validated or an with the failure information and exception otherwise. internal async Task> ValidateTokenAsync( string token, ValidationParameters validationParameters, diff --git a/src/Microsoft.IdentityModel.Tokens.Saml/Saml2/Saml2SecurityTokenHandler.ValidateToken.Internal.cs b/src/Microsoft.IdentityModel.Tokens.Saml/Saml2/Saml2SecurityTokenHandler.ValidateToken.Internal.cs index 5cab5447cd..4d204760ee 100644 --- a/src/Microsoft.IdentityModel.Tokens.Saml/Saml2/Saml2SecurityTokenHandler.ValidateToken.Internal.cs +++ b/src/Microsoft.IdentityModel.Tokens.Saml/Saml2/Saml2SecurityTokenHandler.ValidateToken.Internal.cs @@ -15,6 +15,16 @@ namespace Microsoft.IdentityModel.Tokens.Saml2 /// public partial class Saml2SecurityTokenHandler : SecurityTokenHandler { + /// + /// Validates a token. + /// On a validation failure, no exception will be thrown; instead, the will contain the information about the error that occurred. + /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result. + /// + /// The token to be validated. + /// The to be used for validating the token. + /// A that contains call information. + /// A that can be used to request cancellation of the asynchronous operation. + /// A with either a if the token was validated or an with the failure information and exception otherwise. internal async Task> ValidateTokenAsync( string token, ValidationParameters validationParameters, diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidatedToken.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidatedToken.cs index 7eccd96c75..e4bb9474d8 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidatedToken.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidatedToken.cs @@ -48,27 +48,60 @@ ActorValidationResult is not null ); } + /// + /// The that was validated. + /// public SecurityToken SecurityToken { get; private set; } + /// + /// The that was used to validate the token. + /// public TokenHandler TokenHandler { get; private set; } + /// + /// The that were used to validate the token. + /// public ValidationParameters ValidationParameters { get; private set; } #region Validated Properties + /// + /// The result of validating the actor, if any. + /// public ValidatedToken? ActorValidationResult { get; internal set; } + /// + /// The audience that was validated, if any. + /// public string? ValidatedAudience { get; internal set; } + /// + /// The issuer that was validated. If present, it contains the source of the validation as well. + /// public ValidatedIssuer? ValidatedIssuer { get; internal set; } + /// + /// The lifetime that was validated, if any. + /// public ValidatedLifetime? ValidatedLifetime { get; internal set; } + /// + /// The expiration time of the token that was used to validate the token was not replayed, if any. + /// public DateTime? ValidatedTokenReplayExpirationTime { get; internal set; } + /// + /// The token type that was validated, if any. + /// public ValidatedTokenType? ValidatedTokenType { get; internal set; } + /// + /// The that was used to validate the token, if any. + /// public SecurityKey? ValidatedSigningKey { get; internal set; } + /// + /// The validated lifetime of the that was used to sign the token, if any. + /// public ValidatedSigningKeyLifetime? ValidatedSigningKeyLifetime { get; internal set; } #endregion @@ -177,6 +210,9 @@ private object ClaimsIdentitySyncObj #endregion #region Logging + /// + /// Internal class used for logging. + /// private static class Logger { private static readonly Action s_tokenValidationFailed = diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidationResult.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidationResult.cs index 1d5c475ba4..1c1710066e 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidationResult.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidationResult.cs @@ -17,7 +17,8 @@ namespace Microsoft.IdentityModel.Tokens readonly ValidationError? _error; /// - /// Creates a successful, valid validation result. + /// Creates a new instance of indicating a successful operation + /// and containing an object of the associated type. /// /// The value associated with the success. public ValidationResult(TResult result) @@ -28,7 +29,8 @@ public ValidationResult(TResult result) } /// - /// Creates an error, invalid validation result. + /// Creates a new instance of indicating a failed operation + /// and containing a with the error information. /// /// The error associated with the failure. public ValidationResult(ValidationError error) @@ -115,10 +117,10 @@ public TResult? Result } /// - /// + /// Determines whether the specified object is equal to the current instance of . /// - /// - /// + /// The object to compare with the current instance. + /// true if the specified object is equal to the current instance; otherwise, false. public override bool Equals(object? obj) { if (obj is ValidationResult other) @@ -130,10 +132,9 @@ public override bool Equals(object? obj) } /// - /// + /// Returns the hash code for this instance of . /// - /// - /// + /// The hash code for the current instance. public override int GetHashCode() { if (IsValid) @@ -143,32 +144,32 @@ public override int GetHashCode() } /// - /// + /// Equality comparison operator for . /// - /// - /// - /// + /// The left value to compare. + /// The right value to compare. + /// A boolean indicating whether the left value is equal to the right one. public static bool operator ==(ValidationResult left, ValidationResult right) { return left.Equals(right); } /// - /// + /// Inequality comparison operator for . /// - /// - /// - /// + /// The left value to compare. + /// The right value to compare. + /// A boolean indicating whether the left value is not equal to the right one. public static bool operator !=(ValidationResult left, ValidationResult right) { return !(left == right); } /// - /// + /// Determines whether the specified is equal to the current instance. /// - /// - /// + /// The to compare with the current instance. + /// true if the specified is equal to the current instance; otherwise, false. public bool Equals(ValidationResult other) { if (other.IsValid != IsValid) diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Algorithm.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Algorithm.cs index a9fb5b21d1..1ed23b224b 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Algorithm.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Algorithm.cs @@ -25,6 +25,9 @@ internal delegate ValidationResult AlgorithmValidationDelegate( ValidationParameters validationParameters, CallContext callContext); + /// + /// Partial class for Algorithm Validation. + /// public static partial class Validators { /// @@ -34,15 +37,15 @@ public static partial class Validators /// The that signed the . /// The being validated. /// required for validation. - /// -#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging + /// The that contains call information. internal static ValidationResult ValidateAlgorithm( string algorithm, +#pragma warning disable CA1801 SecurityKey securityKey, SecurityToken securityToken, ValidationParameters validationParameters, CallContext callContext) -#pragma warning restore CA1801 // TODO: remove pragma disable once callContext is used for logging +#pragma warning restore CA1801 { if (validationParameters == null) return ValidationError.NullParameter( diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Audience.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Audience.cs index 8b0903d3dc..3c11cf948d 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Audience.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Audience.cs @@ -35,14 +35,14 @@ public static partial class Validators /// The audiences found in the . /// The being validated. /// The to be used for validating the token. - /// - /// If 'validationParameters' is null. - /// If 'audiences' is null and is true. - /// If is null or whitespace and is null. - /// If none of the 'audiences' matched either or one of . + /// The that contains call information. /// An EXACT match is required. -#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging - internal static ValidationResult ValidateAudience(IList tokenAudiences, SecurityToken? securityToken, ValidationParameters validationParameters, CallContext callContext) + internal static ValidationResult ValidateAudience( + IList tokenAudiences, +#pragma warning disable CA1801 + SecurityToken? securityToken, + ValidationParameters validationParameters, + CallContext callContext) #pragma warning restore CA1801 { if (validationParameters == null) diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Issuer.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Issuer.cs index 51ff189a58..4772b31fc4 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Issuer.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Issuer.cs @@ -1,7 +1,6 @@ // Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. -using System.Diagnostics; using System.Threading; using System.Threading.Tasks; using Microsoft.IdentityModel.Logging; @@ -27,7 +26,7 @@ internal delegate Task> IssuerValidationDelega CancellationToken cancellationToken); /// - /// IssuerValidation + /// Partial class for Issuer Validation. /// public static partial class Validators { @@ -113,13 +112,7 @@ internal static async Task> ValidateIssuerAsyn } if (string.Equals(validationParameters.ValidIssuers[i], issuer)) - { - // TODO: Add to CallContext - //if (LogHelper.IsEnabled(EventLogLevel.Informational)) - // LogHelper.LogInformation(LogMessages.IDX10236, LogHelper.MarkAsNonPII(issuer)); - return new ValidatedIssuer(issuer!, IssuerValidationSource.IssuerMatchedValidationParameters); - } } } diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.IssuerSigningKey.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.IssuerSigningKey.cs index 7edb5ed242..1c0cfec536 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.IssuerSigningKey.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.IssuerSigningKey.cs @@ -26,9 +26,8 @@ internal delegate ValidationResult IssuerSigningKey CallContext callContext); /// - /// SigningKeyValidation + /// Partial class for Issuer Signing Key Validation. /// - public static partial class Validators { /// @@ -38,10 +37,7 @@ public static partial class Validators /// The being validated. /// The to be used for validating the token. /// The to be used for validation. - /// The to be used for logging. - /// if 'securityKey' is null and ValidateIssuerSigningKey is true. - /// if 'securityToken' is null and ValidateIssuerSigningKey is true. - /// if 'validationParameters' is null. + /// The that contains call information. internal static ValidationResult ValidateIssuerSigningKey( SecurityKey securityKey, SecurityToken securityToken, @@ -49,7 +45,7 @@ internal static ValidationResult ValidateIssuerSign #pragma warning disable CA1801 // Review unused parameters BaseConfiguration? configuration, #pragma warning restore CA1801 // Review unused parameters - CallContext? callContext) + CallContext callContext) { if (validationParameters == null) return IssuerSigningKeyValidationError.NullParameter( @@ -77,12 +73,12 @@ internal static ValidationResult ValidateIssuerSign /// /// The that signed the . /// The to be used for validating the token. - /// + /// The that contains call information. #pragma warning disable CA1801 // Review unused parameters internal static ValidationResult ValidateIssuerSigningKeyLifeTime( SecurityKey securityKey, ValidationParameters validationParameters, - CallContext? callContext) + CallContext callContext) #pragma warning restore CA1801 // Review unused parameters { DateTime utcNow = validationParameters.TimeProvider.GetUtcNow().UtcDateTime; diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Lifetime.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Lifetime.cs index f72d403310..7aa37577b3 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Lifetime.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.Lifetime.cs @@ -14,7 +14,7 @@ namespace Microsoft.IdentityModel.Tokens /// The 'expiration' time found in the . /// The that is being validated. /// The to be used for validating the token. - /// + /// The that contains call information. /// A that contains the results of validating the issuer. /// This delegate is not expected to throw. internal delegate ValidationResult LifetimeValidationDelegate( @@ -25,7 +25,7 @@ internal delegate ValidationResult LifetimeValidationDelegate CallContext callContext); /// - /// IssuerValidation + /// Partial class for Lifetime Validation. /// public static partial class Validators { @@ -36,15 +36,10 @@ public static partial class Validators /// The 'expiration' time found in the . /// The being validated. /// The to be used for validating the token. - /// + /// The that contains call information. /// A indicating whether validation was successful, and providing a if it was not. - /// If 'validationParameters' is null. - /// If 'expires.HasValue' is false. - /// If 'notBefore' is > 'expires'. - /// If 'notBefore' is > DateTime.UtcNow. - /// If 'expires' is < DateTime.UtcNow. /// All time comparisons apply . -#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging +#pragma warning disable CA1801 internal static ValidationResult ValidateLifetime( DateTime? notBefore, DateTime? expires, diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenReplay.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenReplay.cs index 3e8de4ffd9..f25292e5cb 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenReplay.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenReplay.cs @@ -3,6 +3,7 @@ using System; +#nullable enable namespace Microsoft.IdentityModel.Tokens { /// @@ -11,7 +12,7 @@ namespace Microsoft.IdentityModel.Tokens /// When does the expire.. /// The security token that is being validated. /// The to be used for validating the token. - /// + /// The that contains call information. /// A that contains the results of validating the token. /// This delegate is not expected to throw. internal delegate ValidationResult TokenReplayValidationDelegate( @@ -31,14 +32,13 @@ public static partial class Validators /// When does the security token expire. /// The being validated. /// The to be used for validating the token. - /// - /// If 'securityToken' is null or whitespace. - /// If 'validationParameters' is null or whitespace. - /// If is not null and expirationTime.HasValue is false. When a TokenReplayCache is set, tokens require an expiration time. - /// If the 'securityToken' is found in the cache. - /// If the 'securityToken' could not be added to the . + /// The that contains call information. #pragma warning disable CA1801 // Review unused parameters - internal static ValidationResult ValidateTokenReplay(DateTime? expirationTime, string securityToken, ValidationParameters validationParameters, CallContext callContext) + internal static ValidationResult ValidateTokenReplay( + DateTime? expirationTime, + string securityToken, + ValidationParameters validationParameters, + CallContext callContext) #pragma warning restore CA1801 // Review unused parameters { if (string.IsNullOrWhiteSpace(securityToken)) @@ -92,3 +92,4 @@ public static partial class Validators } } } +#nullable restore diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenType.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenType.cs index 7af2ac9ad8..2ccce42550 100644 --- a/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenType.cs +++ b/src/Microsoft.IdentityModel.Tokens/Validation/Validators.TokenType.cs @@ -14,7 +14,7 @@ namespace Microsoft.IdentityModel.Tokens /// The token type or null if it couldn't be resolved (e.g from the 'typ' header for a JWT). /// The that is being validated. /// required for validation. - /// + /// The that contains call information. /// A that contains the results of validating the token type. /// An EXACT match is required. (case sensitive) is used for comparing against . internal delegate ValidationResult TokenTypeValidationDelegate( @@ -23,6 +23,9 @@ internal delegate ValidationResult TokenTypeValidationDelega ValidationParameters validationParameters, CallContext callContext); + /// + /// Partial class for Token Type Validation. + /// public static partial class Validators { /// @@ -31,16 +34,16 @@ public static partial class Validators /// The token type or null if it couldn't be resolved (e.g from the 'typ' header for a JWT). /// The that is being validated. /// required for validation. - /// + /// The that contains call information. /// A that contains the results of validating the token type. /// An EXACT match is required. (case sensitive) is used for comparing against . -#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging +#pragma warning disable CA1801 internal static ValidationResult ValidateTokenType( string? type, SecurityToken? securityToken, ValidationParameters validationParameters, CallContext callContext) -#pragma warning restore CA1801 // TODO: remove pragma disable once callContext is used for logging +#pragma warning restore CA1801 { if (securityToken == null) return TokenTypeValidationError.NullParameter(