Skip to content

Enhance ConfigurationManager with event handling #3254

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

Merged
merged 28 commits into from
Jun 3, 2025
Merged

Enhance ConfigurationManager with event handling #3254

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
5bdf7bd
Core fo the work
GeoK May 29, 2025
9f833bc
Additional logic
GeoK May 29, 2025
bd3d063
more refinements
GeoK May 29, 2025
f0fe8f8
Add telemetry, logging, and fix overall logic
GeoK May 30, 2025
952b02c
Fix mock telemetry client
GeoK May 30, 2025
08f6f7e
Fix tests 1/2
GeoK May 30, 2025
7c494ee
Fix tests
GeoK May 30, 2025
95e87de
Make jsonData public
GeoK May 30, 2025
35e0a23
Fix a bug
GeoK May 30, 2025
5b40ec8
fix formatting
GeoK May 30, 2025
32513d3
Add tests
GeoK May 30, 2025
1c81f72
remove usings
GeoK May 30, 2025
4c2e06d
Add more tests
GeoK May 30, 2025
b444412
Rename telemetry related variables
GeoK May 30, 2025
b0cb9b5
Improve comments and logic
GeoK May 30, 2025
5a1d0a1
Fix a couple of tests
GeoK May 30, 2025
461dd04
Address merge conflicts
GeoK May 30, 2025
be8f1f9
address merge conflicts
GeoK May 30, 2025
9169ec6
Merge branch 'dev' into geok/config-events
GeoK May 30, 2025
fb39ebb
PR feedback
GeoK May 30, 2025
1e96cde
Refactor to streamline differences between two code paths
GeoK May 30, 2025
533bccb
Revert "Refactor to streamline differences between two code paths"
GeoK May 31, 2025
66f0554
Improve clarity on blocking scenarios and telemetry
GeoK May 31, 2025
bca7813
Ensure backcompat in case of mismatched assembly versions
GeoK Jun 2, 2025
60182fa
Remove empty line
GeoK Jun 2, 2025
8bad815
Address PR feedback
GeoK Jun 2, 2025
66416fe
Address a nit
GeoK Jun 2, 2025
9d5b69b
Merge branch 'dev' into geok/config-events
GeoK Jun 2, 2025
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
3 changes: 2 additions & 1 deletion src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -521,7 +521,8 @@ await ValidateJWEAsync(jsonWebToken, validationParameters, currentConfiguration)
{
_telemetryClient.IncrementConfigurationRefreshRequestCounter(
validationParameters.ConfigurationManager.MetadataAddress,
TelemetryConstants.Protocols.Lkg);
TelemetryConstants.Protocols.Lkg,
TelemetryConstants.Protocols.ConfigurationSourceUnknown);

validationParameters.ConfigurationManager.RequestRefresh();
validationParameters.RefreshBeforeValidation = true;
Expand Down
159 changes: 150 additions & 9 deletions src/Microsoft.IdentityModel.Protocols/Configuration/ConfigurationManager.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
using System.Threading.Tasks;
using Microsoft.IdentityModel.Logging;
using Microsoft.IdentityModel.Protocols.Configuration;
using Microsoft.IdentityModel.Tokens;
using Microsoft.IdentityModel.Telemetry;
using Microsoft.IdentityModel.Tokens;

namespace Microsoft.IdentityModel.Protocols
{
Expand Down Expand Up @@ -41,6 +41,11 @@ public partial class ConfigurationManager<T> : BaseConfigurationManager, IConfig
internal TimeProvider TimeProvider = TimeProvider.System;
internal ITelemetryClient TelemetryClient = new TelemetryClient();

/// <summary>
/// Gets or sets the optional configuration event handler.
/// </summary>
public IConfigurationEventHandler<T> ConfigurationEventHandler { get; set; }

/// <summary>
/// Instantiates a new <see cref="ConfigurationManager{T}"/> that manages automatic and controls refreshing on configuration data.
/// </summary>
Expand Down Expand Up @@ -135,6 +140,25 @@ public ConfigurationManager(string metadataAddress, IConfigurationRetriever<T> c
_configValidator = configValidator;
}

/// <summary>
/// Instantiates a new <see cref="ConfigurationManager{T}"/> with configuration validator that manages automatic and controls refreshing on configuration data.
/// </summary>
/// <param name="metadataAddress">The address to obtain configuration.</param>
/// <param name="configRetriever">The <see cref="IConfigurationRetriever{T}"/></param>
/// <param name="docRetriever">The <see cref="IDocumentRetriever"/> that reaches out to obtain the configuration.</param>
/// <param name="configValidator">The <see cref="IConfigurationValidator{T}"/></param>
/// <param name="lkgCacheOptions">The <see cref="LastKnownGoodConfigurationCacheOptions"/></param>
/// <param name="configurationEventHandler"> The <see cref="IConfigurationEventHandler{T}"/> that handles configuration events.</param>
/// <exception cref="ArgumentNullException">If 'configValidator' is null.</exception>
public ConfigurationManager(string metadataAddress, IConfigurationRetriever<T> configRetriever, IDocumentRetriever docRetriever, IConfigurationValidator<T> configValidator, LastKnownGoodConfigurationCacheOptions lkgCacheOptions, IConfigurationEventHandler<T> configurationEventHandler)
: this(metadataAddress, configRetriever, docRetriever, configValidator, lkgCacheOptions)
{
if (configurationEventHandler == null)
throw LogHelper.LogArgumentNullException(nameof(configurationEventHandler));

ConfigurationEventHandler = configurationEventHandler;
}

/// <summary>
/// Obtains an updated version of Configuration.
/// </summary>
Expand Down Expand Up @@ -203,6 +227,25 @@ private async Task<T> GetConfigurationNonBlockingAsync(CancellationToken cancel)

try
{
// Check if event handler can provide configuration
if (ConfigurationEventHandler != null)
{
var configurationRetrieved = await HandleBeforeRetrieveAsync(cancel).ConfigureAwait(false);

// replicate the behavior of successful retrieval from endpoint
if (configurationRetrieved != null && configurationRetrieved.Configuration != null)
{
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.FirstRefresh,
TelemetryConstants.Protocols.ConfigurationSourceHandler
);

UpdateConfiguration(configurationRetrieved.Configuration, configurationRetrieved.RetrievalTime);
return _currentConfiguration;
}
}

// Don't use the individual CT here, this is a shared operation that shouldn't be affected by an individual's cancellation.
// The transport should have its own timeouts, etc.
T configuration = await _configRetriever.GetConfigurationAsync(
Expand All @@ -227,9 +270,11 @@ private async Task<T> GetConfigurationNonBlockingAsync(CancellationToken cancel)

TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.FirstRefresh);
TelemetryConstants.Protocols.FirstRefresh,
TelemetryConstants.Protocols.ConfigurationSourceRetriever
);

UpdateConfiguration(configuration);
UpdateConfiguration(configuration, TimeProvider.GetUtcNow().UtcDateTime);
}
#pragma warning disable CA1031 // Do not catch general exception types
catch (Exception ex)
Expand All @@ -238,6 +283,7 @@ private async Task<T> GetConfigurationNonBlockingAsync(CancellationToken cancel)
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.FirstRefresh,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
ex);

LogHelper.LogExceptionMessage(
Expand All @@ -260,7 +306,8 @@ private async Task<T> GetConfigurationNonBlockingAsync(CancellationToken cancel)
{
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.Automatic);
TelemetryConstants.Protocols.Automatic,
TelemetryConstants.Protocols.ConfigurationSourceUnknown);

_ = Task.Run(UpdateCurrentConfiguration, CancellationToken.None);
}
Expand Down Expand Up @@ -291,6 +338,19 @@ private void UpdateCurrentConfiguration()

try
{
// Check if event handler can provide configuration
if (ConfigurationEventHandler != null)
{
var configurationRetrieved = HandleBeforeRetrieveAsync().ConfigureAwait(false).GetAwaiter().GetResult();
if (configurationRetrieved != null && configurationRetrieved.Configuration != null)
{
UpdateConfiguration(configurationRetrieved.Configuration, configurationRetrieved.RetrievalTime);

_onBackgroundTaskFinish?.Invoke();
return;
}
}

T configuration = _configRetriever.GetConfigurationAsync(
MetadataAddress,
_docRetriever,
Expand All @@ -299,11 +359,12 @@ private void UpdateCurrentConfiguration()
var elapsedTime = TimeProvider.GetElapsedTime(startTimestamp);
TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
elapsedTime);

if (_configValidator == null)
{
UpdateConfiguration(configuration);
UpdateConfiguration(configuration, TimeProvider.GetUtcNow().UtcDateTime);
}
else
{
Expand All @@ -316,7 +377,7 @@ private void UpdateCurrentConfiguration()
LogMessages.IDX20810,
result.ErrorMessage)));
else
UpdateConfiguration(configuration);
UpdateConfiguration(configuration, TimeProvider.GetUtcNow().UtcDateTime);
}
}
#pragma warning disable CA1031 // Do not catch general exception types
Expand All @@ -325,6 +386,7 @@ private void UpdateCurrentConfiguration()
var elapsedTime = TimeProvider.GetElapsedTime(startTimestamp);
TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
elapsedTime,
ex);

Expand All @@ -345,11 +407,32 @@ private void UpdateCurrentConfiguration()
_onBackgroundTaskFinish?.Invoke();
}

private void UpdateConfiguration(T configuration)
private void UpdateConfiguration(T configuration, DateTimeOffset retrievalTime)
{
_currentConfiguration = configuration;
_syncAfter = DateTimeUtil.Add(TimeProvider.GetUtcNow().UtcDateTime, AutomaticRefreshInterval +
_syncAfter = DateTimeUtil.Add(retrievalTime.UtcDateTime, AutomaticRefreshInterval +
TimeSpan.FromSeconds(new Random().Next((int)AutomaticRefreshInterval.TotalSeconds / 20)));

if (ConfigurationEventHandler != null)
{
_ = Task.Run(async () =>
{
try
{
await ConfigurationEventHandler.AfterUpdateAsync(MetadataAddress, configuration).ConfigureAwait(false);
}
catch (Exception ex)
{
LogHelper.LogExceptionMessage(
new InvalidOperationException(
LogHelper.FormatInvariant(
LogMessages.IDX20812,
LogHelper.MarkAsNonPII(MetadataAddress ?? "null"),
ex),
ex));
}
});
}
}

/// <summary>
Expand Down Expand Up @@ -391,7 +474,8 @@ private void RequestRefreshBackgroundThread()
{
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.Manual);
TelemetryConstants.Protocols.Manual,
TelemetryConstants.Protocols.ConfigurationSourceUnknown);

_isFirstRefreshRequest = false;
if (Interlocked.CompareExchange(ref _configurationRetrieverState, ConfigurationRetrieverRunning, ConfigurationRetrieverIdle) == ConfigurationRetrieverIdle)
Expand All @@ -402,6 +486,63 @@ private void RequestRefreshBackgroundThread()
}
}

private async Task<ConfigurationEventHandlerResult<T>> HandleBeforeRetrieveAsync(CancellationToken cancel = default)
{
long beforeHandlerTimestamp = TimeProvider.GetTimestamp();

try
{
var handlerResult = await ConfigurationEventHandler.BeforeRetrieveAsync(MetadataAddress, cancel).ConfigureAwait(false);
if (handlerResult != null && handlerResult.Configuration != null)
{
var handlerElapsedTime = TimeProvider.GetElapsedTime(beforeHandlerTimestamp);
TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceHandler,
handlerElapsedTime);

// Validate configuration from handler
if (_configValidator != null)
{
ConfigurationValidationResult result = _configValidator.Validate(handlerResult.Configuration);
if (!result.Succeeded)
{
// Just log the error and proceed to fetch from endpoint
LogHelper.LogExceptionMessage(
new InvalidConfigurationException(
LogHelper.FormatInvariant(
LogMessages.IDX20812,
result.ErrorMessage)));

return ConfigurationEventHandlerResult<T>.NoResult;
}
}

// No validator configured, return configuration
return handlerResult;
}
}
catch (Exception ex)
{
var handlerErrorElapsedTime = TimeProvider.GetElapsedTime(beforeHandlerTimestamp);
TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceHandler,
handlerErrorElapsedTime,
ex);

LogHelper.LogExceptionMessage(
new InvalidOperationException(
LogHelper.FormatInvariant(
LogMessages.IDX20811,
LogHelper.MarkAsNonPII(MetadataAddress ?? "null"),
ex),
ex));
}

return ConfigurationEventHandlerResult<T>.NoResult;
}

/// <summary>
/// 12 hours is the default time interval that afterwards, <see cref="GetBaseConfigurationAsync(CancellationToken)"/> will obtain new configuration.
/// </summary>
Expand Down
33 changes: 28 additions & 5 deletions src/Microsoft.IdentityModel.Protocols/Configuration/ConfigurationManager_Blocking.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

namespace Microsoft.IdentityModel.Protocols
{
partial class ConfigurationManager<T> where T : class
public partial class ConfigurationManager<T> where T : class
{
private readonly SemaphoreSlim _refreshLock = new(1, 1);
private TimeSpan _bootstrapRefreshInterval = TimeSpan.FromSeconds(1);
Expand All @@ -34,13 +34,33 @@ private async Task<T> GetConfigurationWithBlockingAsync(CancellationToken cancel
{
try
{
// Check if event handler can provide configuration
if (ConfigurationEventHandler != null)
{
var configurationRetrieved = await HandleBeforeRetrieveAsync(cancel).ConfigureAwait(false);

// replicate the behavior of successful retrieval from endpoint
if (configurationRetrieved != null && configurationRetrieved.Configuration != null)
{
TelemetryForUpdateBlocking(TelemetryConstants.Protocols.ConfigurationSourceHandler);

if (_refreshRequested)
_refreshRequested = false;

UpdateConfiguration(configurationRetrieved.Configuration, configurationRetrieved.RetrievalTime);

return _currentConfiguration;
}
}

// Don't use the individual CT here, this is a shared operation that shouldn't be affected by an individual's cancellation.
// The transport should have it's own timeouts, etc..
var configuration = await _configRetriever.GetConfigurationAsync(MetadataAddress, _docRetriever, CancellationToken.None).ConfigureAwait(false);

var elapsedTime = TimeProvider.GetElapsedTime(startTimestamp);
TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
elapsedTime);

if (_configValidator != null)
Expand All @@ -52,12 +72,12 @@ private async Task<T> GetConfigurationWithBlockingAsync(CancellationToken cancel

_lastRequestRefresh = TimeProvider.GetUtcNow().UtcDateTime;

TelemetryForUpdateBlocking();
TelemetryForUpdateBlocking(TelemetryConstants.Protocols.ConfigurationSourceRetriever);

if (_refreshRequested)
_refreshRequested = false;

UpdateConfiguration(configuration);
UpdateConfiguration(configuration, TimeProvider.GetUtcNow().UtcDateTime);
}
catch (Exception ex)
{
Expand All @@ -82,6 +102,7 @@ private async Task<T> GetConfigurationWithBlockingAsync(CancellationToken cancel
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
TelemetryConstants.Protocols.FirstRefresh,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
ex);

throw LogHelper.LogExceptionMessage(
Expand All @@ -98,6 +119,7 @@ private async Task<T> GetConfigurationWithBlockingAsync(CancellationToken cancel

TelemetryClient.LogConfigurationRetrievalDuration(
MetadataAddress,
TelemetryConstants.Protocols.ConfigurationSourceRetriever,
elapsedTime,
ex);

Expand Down Expand Up @@ -139,7 +161,7 @@ private void RequestRefreshBlocking()
}
}

private void TelemetryForUpdateBlocking()
private void TelemetryForUpdateBlocking(string configurationSource)
{
string updateMode;

Expand All @@ -152,7 +174,8 @@ private void TelemetryForUpdateBlocking()
{
TelemetryClient.IncrementConfigurationRefreshRequestCounter(
MetadataAddress,
updateMode);
updateMode,
configurationSource);
}
#pragma warning disable CA1031 // Do not catch general exception types
catch
Expand Down
Loading
Loading