Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Cloud-agnostic secrets management for .NET applications. Covers the full lifecycle: user secrets for local development,
environment variables for production, IConfiguration binding patterns, secret rotation, and managed identity as a
production best practice. Includes anti-patterns to avoid (secrets in source, appsettings.json, hardcoded connection
strings).
Scope
User secrets for local development
Environment variables for production
IConfiguration binding patterns for secrets
Secret rotation strategies
Managed identity as a production best practice
Anti-patterns to avoid (secrets in source, appsettings.json)
Authentication/authorization implementation (OAuth, Identity) -- see [skill:dotnet-api-security] and
[skill:dotnet-blazor-auth]
Cryptographic algorithm selection -- see [skill:dotnet-cryptography]
General Options pattern and configuration sources -- see [skill:dotnet-csharp-configuration]
Cross-references: [skill:dotnet-security-owasp] for OWASP A02 (Cryptographic Failures) and deprecated pattern warnings,
[skill:dotnet-csharp-configuration] for Options pattern and configuration source precedence.
OS-level env vars, managed identity, or vault provider
Principle: Secrets must never exist in the source repository or in any file committed to version control. Each
environment tier uses the appropriate mechanism for its trust boundary.
User Secrets (Local Development)
User secrets store sensitive configuration outside the project directory in the user profile, preventing accidental
commits.
Setup
# Do NOT commit real secrets; use dotnet user-secrets or env vars# Initialize user secrets for a project (creates UserSecretsId in csproj)
dotnet user-secrets init
dotnet user-secrets
dotnet user-secrets
dotnet user-secrets
dotnet user-secrets list
dotnet user-secrets remove
dotnet user-secrets clear
# Set individual secrets (placeholders shown)
# (placeholders shown; do NOT use real secrets in shell history)
User secrets are loaded automatically by WebApplication.CreateBuilder and Host.CreateDefaultBuilder when
DOTNET_ENVIRONMENT or ASPNETCORE_ENVIRONMENT is Development:
var builder = WebApplication.CreateBuilder(args);
// User secrets are already loaded. Access them via IConfiguration:var connectionString = builder.Configuration.GetConnectionString("DefaultDb");
For non-web hosts (console apps, worker services):
var builder = Host.CreateApplicationBuilder(args);
// User secrets are loaded automatically in Development environment.// For explicit control:if (builder.Environment.IsDevelopment())
{
builder.Configuration.AddUserSecrets<Program>();
}
Gotcha: User secrets are not encrypted -- they are just stored outside the repo. They are appropriate for
development only, never for production.
Environment Variables (Production)
Environment variables are the standard mechanism for injecting secrets into production applications without touching the
filesystem.
Configuration Precedence
In the default ASP.NET Core configuration stack, environment variables override file-based sources (last wins):
appsettings.json
appsettings.{Environment}.json
User secrets (Development only)
Environment variables (overrides all above)
Command-line arguments
Mapping Convention
.NET maps environment variables to configuration keys using __ (double underscore) as the section separator:
# These environment variables map to configuration sections:export ConnectionStrings__DefaultDb="Server=prod-db;Database=myapp;..."export Smtp__ApiKey="<SENDGRID_API_KEY_PLACEHOLDER>"export Jwt__SigningKey="<JWT_SIGNING_KEY_PLACEHOLDER>"# With a prefix (recommended to avoid collisions):export MYAPP_ConnectionStrings__DefaultDb="Server=prod-db;..."
// Load prefixed environment variables
builder.Configuration.AddEnvironmentVariables(prefix: "MYAPP_");
// Access the same way as any configuration source:var smtpKey = builder.Configuration["Smtp:ApiKey"];
Container Environments
# docker-compose.yml -- inject secrets via environmentservices:api:image:myapp:latestenvironment:-ConnectionStrings__DefaultDb=Server=db;Database=myapp;User=sa;Password=<DB_PASSWORD_PLACEHOLDER>-Smtp__ApiKey=${SMTP_API_KEY}env_file:-.env# NOT committed to source control
# Dockerfile -- do NOT bake secrets into images
# Use environment variables at runtime instead
ENV ASPNETCORE_URLS=http://+:8080
# NEVER: ENV ConnectionStrings__DefaultDb="Server=..."
Gotcha: Environment variables are visible to all processes under the same user. In multi-tenant container
environments, use container-level isolation (Kubernetes secrets, Docker secrets) rather than host-level env vars.
IConfiguration Binding Patterns
Bind secrets to strongly typed options classes for compile-time safety and validation.
publicsealedclassJwtOptions
{
publicconststring SectionName = "Jwt";
[Required, MinLength(32)]
publicstring SigningKey { get; set; } = "";
///<summary>/// Previous signing key retained during rotation window./// Set this when rotating keys so tokens signed with the old key/// remain valid until they expire. Remove after rotation completes.///</summary>publicstring? PreviousSigningKey { get; set; }
[Required]
publicstring Issuer { get; set; } = "";
[Required]
publicstring Audience { get; set; } = "";
[Range(1, 1440)]
publicint ExpirationMinutes { get; set; } = 60;
}
// Registration with validation
builder.Services
.AddOptions<JwtOptions>()
.BindConfiguration(JwtOptions.SectionName)
.ValidateDataAnnotations()
.ValidateOnStart(); // Fail fast if secrets are missing// Inject and usepublicsealedclassTokenService(IOptions<JwtOptions> jwtOptions)
{
privatereadonly JwtOptions _jwt = jwtOptions.Value;
publicstringGenerateToken(string userId)
{
var key = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(_jwt.SigningKey));
var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
var token = new JwtSecurityToken(
issuer: _jwt.Issuer,
audience: _jwt.Audience,
claims: [new Claim(ClaimTypes.NameIdentifier, userId)],
expires: DateTime.UtcNow.AddMinutes(_jwt.ExpirationMinutes),
signingCredentials: credentials);
returnnew JwtSecurityTokenHandler().WriteToken(token);
}
}
Options classes must use { get; set; } (not { get; init; }) because the configuration binder and PostConfigure
need to mutate properties after construction. Use data annotation attributes ([Required], [MinLength]) for
validation.
Gotcha:ValidateOnStart() catches missing secrets at application startup rather than at first use. Always use it
for secrets-bearing options to fail fast with a clear error message.
Secret Rotation
Design applications to handle secret rotation without downtime.
Rotation-Friendly Patterns
// Use IOptionsMonitor<T> for secrets that may change at runtimepublicsealedclassEmailService(IOptionsMonitor<SmtpOptions> smtpOptions, ILogger<EmailService> logger)
{
publicasync Task SendAsync(string to, string subject, string body)
{
// CurrentValue reads the latest configuration on every callvar options = smtpOptions.CurrentValue;
logger.LogDebug("Using SMTP host {Host}", options.Host);
// ... send email using current options ...
}
}
// Audit-log configuration changes via a hosted service.// IHostedService is always activated by the host, so the subscription is guaranteed.publicsealedclassSmtpOptionsChangeLogger(
IOptionsMonitor<SmtpOptions> monitor,
ILogger<SmtpOptionsChangeLogger> logger) : IHostedService, IDisposable
{
private IDisposable? _subscription;
public Task StartAsync(CancellationToken cancellationToken)
{
_subscription = monitor.OnChange(options =>
{
logger.LogInformation("SMTP configuration reloaded at {Time}", DateTime.UtcNow);
});
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
publicvoidDispose() => _subscription?.Dispose();
}
// Registration:
builder.Services.AddHostedService<SmtpOptionsChangeLogger>();
// Dual-key validation for zero-downtime rotation// Accept both old and new signing keys during rotation windowpublicsealedclassDualKeyTokenValidator(IOptionsMonitor<JwtOptions> optionsMonitor)
{
public TokenValidationParameters GetParameters()
{
// Read CurrentValue on every call so rotated keys are picked up// without restarting the applicationvar options = optionsMonitor.CurrentValue;
var keys = new List<SecurityKey>
{
new SymmetricSecurityKey(Encoding.UTF8.GetBytes(options.SigningKey))
};
if (!string.IsNullOrEmpty(options.PreviousSigningKey))
{
keys.Add(new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(options.PreviousSigningKey)));
}
returnnew TokenValidationParameters
{
ValidateIssuer = true,
ValidIssuer = options.Issuer,
ValidateAudience = true,
ValidAudience = options.Audience,
ValidateLifetime = true,
IssuerSigningKeys = keys
};
}
}
Rotation Checklist
Deploy the new secret alongside the old one (dual-key window)
Update the application to accept both old and new secrets
Roll the deployment so all instances use the new secret for signing/encrypting
After all clients have rotated, remove the old secret
Audit-log every rotation event
Managed Identity (Production Best Practice)
Managed identity eliminates secrets entirely for cloud-hosted applications by using the platform's identity system to
authenticate to services.
Concept: Instead of storing a connection string with a password, the application authenticates to the
database/service using its platform-assigned identity. No secret to manage, rotate, or leak.
// Example: passwordless connection to SQL Server using DefaultAzureCredential// This pattern works across Azure, and similar patterns exist for AWS and GCPvar connectionString = "Server=myserver.database.windows.net;Database=mydb;Authentication=Active Directory Default";
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(connectionString));
// No password in the connection string -- identity is resolved from the environment
When to use managed identity:
Production and staging environments hosted on cloud platforms
Any service-to-service communication where the platform supports identity federation
Local development (use user secrets as a fallback)
Anti-Patterns
Secrets in Source Control
// NEVER: hardcoded secrets in source code// Replaced real keys with placeholders. Do NOT store real keys in source.privateconststring ApiKey = "<API_KEY_PLACEHOLDER>"; // WRONG: hardcoded secretprivateconststring ConnectionString = "Server=prod-db;Database=myapp;User=sa;Password=<DB_PASSWORD_PLACEHOLDER>"; // WRONG: hardcoded secret
Fix: Use user secrets (dev) or environment variables (production). See sections above.
// NEVER: connection strings directly in code// Use IConfiguration or environment variables instead of hardcoded credentials.var connection = new SqlConnection("Server=prod-db;Database=myapp;User=sa;Password=<DB_PASSWORD_PLACEHOLDER>"); // WRONG
Fix: Always resolve connection strings from IConfiguration:
// Correct: resolve from configurationpublicsealedclassOrderRepository(IConfiguration configuration)
{
privatereadonlystring _connectionString =
configuration.GetConnectionString("DefaultDb")
?? thrownew InvalidOperationException("ConnectionStrings:DefaultDb is not configured");
}
// Better: use Options pattern with validationpublicsealedclassOrderRepository(IOptions<DatabaseOptions> options)
{
privatereadonlystring _connectionString = options.Value.ConnectionString;
}
logger.LogInformation("API key configured: {IsConfigured}", !string.IsNullOrEmpty(apiKey));
logger.LogInformation("Database connection configured for {Server}", new SqlConnectionStringBuilder(connectionString).DataSource);
Agent Gotchas
Do not generate code with hardcoded secrets -- always use IConfiguration or IOptions<T> to resolve secrets.
Even in examples, use placeholder values.
Do not put real secrets in appsettings.json -- it is committed to source control. Use user secrets for
development, environment variables for production.
Do not use { get; init; } on Options classes -- the configuration binder requires mutable setters. Use
{ get; set; } with data annotation validation instead.
Do not skip ValidateOnStart() -- without it, missing secrets cause runtime failures at first use rather than a
clear startup error.
Do not log secret values -- log whether a secret is configured (IsConfigured: true/false) or metadata (server
name from connection string), never the value.
Do not use IOptions<T> for secrets that rotate -- use IOptionsMonitor<T> for runtime-reloadable secrets so
rotation does not require a restart.
Do not bake secrets into Docker images -- use environment variables or mounted secrets at container runtime.
Prerequisites
.NET 8.0+ (LTS baseline)
Microsoft.Extensions.Configuration.UserSecrets (included in ASP.NET Core SDK; add manually for console apps)
Microsoft.Extensions.Options.DataAnnotations for ValidateDataAnnotations()
