A complete guide to securely handling secrets, credentials, and sensitive configuration in Java applications.

Table of Contents

1. The Problem with Secrets
2. Secret Management Principles
3. Implementation Approaches
4. Cloud Secret Managers
5. Encryption Strategies
6. Secure Coding Practices
7. Monitoring & Audit

The Problem with Secrets

Common Anti-Patterns

• Hardcoded secrets in source code
• Plaintext configuration files
• Environment variables for sensitive data
• Version control containing secrets
• Logging sensitive data

Types of Secrets

public enum SecretType {
DATABASE_CREDENTIALS,
API_KEYS,
SSL_CERTIFICATES,
ENCRYPTION_KEYS,
OAUTH_TOKENS,
SSH_KEYS,
JWT_SECRETS,
SERVICE_ACCOUNT_KEYS
}

Secret Management Principles

Core Principles

1. Never store secrets in code
2. Use minimal privilege - only access what's needed
3. Encrypt secrets at rest and in transit
4. Rotate secrets regularly
5. Audit secret access
6. Use secure storage backends

Implementation Approaches

1. Environment-Based Configuration

@Component
public class EnvironmentSecretProvider {
private static final Logger logger = LoggerFactory.getLogger(EnvironmentSecretProvider.class);
public String getSecret(String key) {
return getSecret(key, null);
}
public String getSecret(String key, String defaultValue) {
String value = System.getenv(key);
if (value == null) {
value = System.getProperty(key);
}
if (value == null && defaultValue == null) {
throw new SecretNotFoundException("Secret not found for key: " + key);
}
return value != null ? value : defaultValue;
}
public char[] getSecretAsChars(String key) {
String value = getSecret(key);
return value != null ? value.toCharArray() : null;
}
// Secure cleanup
public void clearSecret(char[] secret) {
if (secret != null) {
Arrays.fill(secret, '\0');
}
}
}

2. Configuration Service with Encryption

@Service
public class SecureConfigService {
private final EncryptionService encryptionService;
private final Map<String, String> secretCache = new ConcurrentHashMap<>();
@Value("${app.secrets.master-key-env-var:APP_MASTER_KEY}")
private String masterKeyEnvVar;
public SecureConfigService(EncryptionService encryptionService) {
this.encryptionService = encryptionService;
}
public String getSecureProperty(String encryptedValue) {
if (encryptedValue == null) return null;
return secretCache.computeIfAbsent(encryptedValue, 
enc -> encryptionService.decrypt(enc, getMasterKey()));
}
public void setSecureProperty(String key, String plaintextValue) {
String encrypted = encryptionService.encrypt(plaintextValue, getMasterKey());
// Store encrypted value in your configuration
System.setProperty(key, encrypted);
}
private char[] getMasterKey() {
String masterKey = System.getenv(masterKeyEnvVar);
if (masterKey == null) {
throw new IllegalStateException("Master key not found in environment variable: " + masterKeyEnvVar);
}
return masterKey.toCharArray();
}
@PreDestroy
public void cleanup() {
secretCache.clear();
}
}

3. Secrets Manager Interface

public interface SecretsManager {
String getSecret(String secretId);
String getSecret(String secretId, String version);
void putSecret(String secretId, String secretValue);
void rotateSecret(String secretId);
List<String> listSecrets();
Map<String, String> getSecretMetadata(String secretId);
}
public class SecretResponse {
private final String value;
private final Instant created;
private final Instant expires;
private final Map<String, String> metadata;
// Constructor, getters, builder...
}

Cloud Secret Managers Integration

1. AWS Secrets Manager

@Service
@Profile("aws")
public class AwsSecretsManager implements SecretsManager {
private final AWSSecretsManager client;
private final ObjectMapper objectMapper;
private final Cache<String, SecretResponse> cache;
public AwsSecretsManager(@Value("${aws.region:us-east-1}") String region) {
this.client = AWSSecretsManagerClient.builder()
.withRegion(region)
.build();
this.objectMapper = new ObjectMapper();
this.cache = Caffeine.newBuilder()
.expireAfterWrite(5, TimeUnit.MINUTES)
.maximumSize(1000)
.build();
}
@Override
public String getSecret(String secretId) {
return cache.get(secretId, this::fetchSecret).getValue();
}
@Override
public String getSecret(String secretId, String version) {
String cacheKey = secretId + "#" + version;
return cache.get(cacheKey, 
k -> fetchSecretVersion(secretId, version)).getValue();
}
private SecretResponse fetchSecret(String secretId) {
try {
GetSecretValueRequest request = GetSecretValueRequest.builder()
.secretId(secretId)
.build();
GetSecretValueResponse response = client.getSecretValue(request);
return SecretResponse.builder()
.value(parseSecretString(response.secretString()))
.created(Instant.now())
.metadata(Map.of(
"arn", response.arn(),
"createdDate", response.createdDate().toString()
))
.build();
} catch (ResourceNotFoundException e) {
throw new SecretNotFoundException("Secret not found: " + secretId, e);
} catch (Exception e) {
throw new SecretAccessException("Failed to access secret: " + secretId, e);
}
}
private String parseSecretString(String secretString) {
try {
// Handle JSON secrets
JsonNode jsonNode = objectMapper.readTree(secretString);
if (jsonNode.has("password")) {
return jsonNode.get("password").asText();
} else if (jsonNode.has("value")) {
return jsonNode.get("value").asText();
}
// Return first field if no standard keys found
Iterator<String> fieldNames = jsonNode.fieldNames();
if (fieldNames.hasNext()) {
return jsonNode.get(fieldNames.next()).asText();
}
} catch (Exception e) {
// Not JSON, return as-is
}
return secretString;
}
@Override
public void putSecret(String secretId, String secretValue) {
try {
String secretString = objectMapper.writeValueAsString(
Map.of("value", secretValue, "updated", Instant.now().toString()));
PutSecretValueRequest request = PutSecretValueRequest.builder()
.secretId(secretId)
.secretString(secretString)
.build();
client.putSecretValue(request);
// Invalidate cache
cache.invalidate(secretId);
} catch (Exception e) {
throw new SecretUpdateException("Failed to update secret: " + secretId, e);
}
}
@PreDestroy
public void shutdown() {
if (client != null) {
client.close();
}
}
}

2. Azure Key Vault

@Service
@Profile("azure")
public class AzureKeyVaultService implements SecretsManager {
private final SecretClient secretClient;
private final Cache<String, SecretResponse> cache;
public AzureKeyVaultService(
@Value("${azure.keyvault.uri}") String keyVaultUri,
TokenCredential tokenCredential) {
this.secretClient = new SecretClientBuilder()
.vaultUrl(keyVaultUri)
.credential(tokenCredential)
.buildClient();
this.cache = Caffeine.newBuilder()
.expireAfterWrite(10, TimeUnit.MINUTES)
.maximumSize(1000)
.build();
}
@Override
public String getSecret(String secretName) {
return cache.get(secretName, this::fetchSecret).getValue();
}
private SecretResponse fetchSecret(String secretName) {
try {
KeyVaultSecret secret = secretClient.getSecret(secretName);
return SecretResponse.builder()
.value(secret.getValue())
.created(secret.getProperties().getCreatedOn().toInstant())
.expires(secret.getProperties().getExpiresOn() != null ? 
secret.getProperties().getExpiresOn().toInstant() : null)
.metadata(Map.of(
"version", secret.getProperties().getVersion(),
"enabled", String.valueOf(secret.getProperties().isEnabled())
))
.build();
} catch (ResourceNotFoundException e) {
throw new SecretNotFoundException("Secret not found: " + secretName, e);
}
}
}

3. Google Cloud Secret Manager

@Service
@Profile("gcp")
public class GcpSecretManager implements SecretsManager {
private final SecretManagerServiceClient client;
private final String projectId;
private final Cache<String, SecretResponse> cache;
public GcpSecretManager(
SecretManagerServiceClient client,
@Value("${spring.cloud.gcp.project-id}") String projectId) {
this.client = client;
this.projectId = projectId;
this.cache = Caffeine.newBuilder()
.expireAfterWrite(15, TimeUnit.MINUTES)
.maximumSize(1000)
.build();
}
@Override
public String getSecret(String secretId) {
return getSecret(secretId, "latest");
}
@Override
public String getSecret(String secretId, String version) {
String cacheKey = secretId + "#" + version;
return cache.get(cacheKey, k -> fetchSecret(secretId, version)).getValue();
}
private SecretResponse fetchSecret(String secretId, String version) {
try {
SecretVersionName secretVersionName = SecretVersionName.of(projectId, secretId, version);
AccessSecretVersionResponse response = client.accessSecretVersion(secretVersionName);
String secretValue = response.getPayload().getData().toStringUtf8();
return SecretResponse.builder()
.value(secretValue)
.created(Instant.now()) // Would parse from secret metadata
.build();
} catch (StatusRuntimeException e) {
if (e.getStatus().getCode() == Status.Code.NOT_FOUND) {
throw new SecretNotFoundException("Secret not found: " + secretId, e);
}
throw new SecretAccessException("Failed to access secret: " + secretId, e);
}
}
}

Encryption Strategies

1. Master Key Encryption Service

@Service
public class AesGcmEncryptionService {
private static final String ALGORITHM = "AES/GCM/NoPadding";
private static final int TAG_LENGTH_BIT = 128;
private static final int IV_LENGTH_BYTE = 12;
private static final int SALT_LENGTH_BYTE = 16;
private static final int KEY_LENGTH_BIT = 256;
private final SecureRandom secureRandom = new SecureRandom();
public String encrypt(String plaintext, char[] password) {
try {
// Generate salt and IV
byte[] salt = new byte[SALT_LENGTH_BYTE];
byte[] iv = new byte[IV_LENGTH_BYTE];
secureRandom.nextBytes(salt);
secureRandom.nextBytes(iv);
// Derive key from password
SecretKey key = deriveKey(password, salt);
// Encrypt
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec parameterSpec = new GCMParameterSpec(TAG_LENGTH_BIT, iv);
cipher.init(Cipher.ENCRYPT_MODE, key, parameterSpec);
byte[] cipherText = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
// Combine salt + iv + ciphertext
byte[] encrypted = new byte[salt.length + iv.length + cipherText.length];
System.arraycopy(salt, 0, encrypted, 0, salt.length);
System.arraycopy(iv, 0, encrypted, salt.length, iv.length);
System.arraycopy(cipherText, 0, encrypted, salt.length + iv.length, cipherText.length);
return Base64.getEncoder().encodeToString(encrypted);
} catch (Exception e) {
throw new EncryptionException("Encryption failed", e);
}
}
public String decrypt(String encryptedData, char[] password) {
try {
byte[] decoded = Base64.getDecoder().decode(encryptedData);
// Extract components
byte[] salt = Arrays.copyOfRange(decoded, 0, SALT_LENGTH_BYTE);
byte[] iv = Arrays.copyOfRange(decoded, SALT_LENGTH_BYTE, SALT_LENGTH_BYTE + IV_LENGTH_BYTE);
byte[] cipherText = Arrays.copyOfRange(decoded, SALT_LENGTH_BYTE + IV_LENGTH_BYTE, decoded.length);
// Derive key
SecretKey key = deriveKey(password, salt);
// Decrypt
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec parameterSpec = new GCMParameterSpec(TAG_LENGTH_BIT, iv);
cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec);
byte[] plaintext = cipher.doFinal(cipherText);
return new String(plaintext, StandardCharsets.UTF_8);
} catch (Exception e) {
throw new EncryptionException("Decryption failed", e);
}
}
private SecretKey deriveKey(char[] password, byte[] salt) {
try {
PBEKeySpec spec = new PBEKeySpec(password, salt, 65536, KEY_LENGTH_BIT);
SecretKeyFactory factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
byte[] keyBytes = factory.generateSecret(spec).getEncoded();
return new SecretKeySpec(keyBytes, "AES");
} catch (Exception e) {
throw new EncryptionException("Key derivation failed", e);
}
}
}

2. Key Rotation Service

@Service
public class KeyRotationService {
private final SecretsManager secretsManager;
private final AesGcmEncryptionService encryptionService;
private final Map<String, String> keyVersions = new ConcurrentHashMap<>();
@Value("${app.encryption.current-key-version:v1}")
private String currentKeyVersion;
public KeyRotationService(SecretsManager secretsManager, 
AesGcmEncryptionService encryptionService) {
this.secretsManager = secretsManager;
this.encryptionService = encryptionService;
loadKeyVersions();
}
public void rotateMasterKey() {
try {
// Generate new key
String newKeyVersion = "v" + (keyVersions.size() + 1);
String newMasterKey = generateRandomKey();
// Store new key in secrets manager
secretsManager.putSecret("app/master-key/" + newKeyVersion, newMasterKey);
// Update current version
this.currentKeyVersion = newKeyVersion;
keyVersions.put(newKeyVersion, newMasterKey);
// Re-encrypt sensitive data (asynchronous)
reencryptDataWithNewKey(newKeyVersion, newMasterKey);
} catch (Exception e) {
throw new KeyRotationException("Key rotation failed", e);
}
}
public String getCurrentMasterKey() {
return keyVersions.get(currentKeyVersion);
}
public char[] getCurrentMasterKeyAsChars() {
String key = getCurrentMasterKey();
return key != null ? key.toCharArray() : null;
}
private void loadKeyVersions() {
// Load all key versions from secrets manager
List<String> secretKeys = secretsManager.listSecrets().stream()
.filter(key -> key.startsWith("app/master-key/"))
.collect(Collectors.toList());
for (String secretKey : secretKeys) {
String version = secretKey.substring("app/master-key/".length());
String keyValue = secretsManager.getSecret(secretKey);
keyVersions.put(version, keyValue);
}
}
private String generateRandomKey() {
byte[] keyBytes = new byte[32]; // 256 bits
new SecureRandom().nextBytes(keyBytes);
return Base64.getEncoder().encodeToString(keyBytes);
}
@Async
public void reencryptDataWithNewKey(String newKeyVersion, String newMasterKey) {
// Implementation for re-encrypting all data with new key
// This should process data in batches
logger.info("Starting data re-encryption with key version: {}", newKeyVersion);
// Example: Re-encrypt database credentials, API keys, etc.
// This is application-specific
}
}

Secure Coding Practices

1. Secure Configuration Class

@Configuration
@ConfigurationProperties(prefix = "app.security")
@Validated
public class SecurityConfig {
@NotNull
private SecretsManagerType secretsManager;
@NotBlank
private String masterKeyEnvVar;
private boolean enableKeyRotation = true;
private int keyRotationDays = 90;
private boolean auditSecretAccess = true;
// Getters and setters
public SecretsManagerType getSecretsManager() { return secretsManager; }
public void setSecretsManager(SecretsManagerType secretsManager) { 
this.secretsManager = secretsManager; 
}
public String getMasterKeyEnvVar() { return masterKeyEnvVar; }
public void setMasterKeyEnvVar(String masterKeyEnvVar) { 
this.masterKeyEnvVar = masterKeyEnvVar; 
}
public boolean isEnableKeyRotation() { return enableKeyRotation; }
public void setEnableKeyRotation(boolean enableKeyRotation) { 
this.enableKeyRotation = enableKeyRotation; 
}
public int getKeyRotationDays() { return keyRotationDays; }
public void setKeyRotationDays(int keyRotationDays) { 
this.keyRotationDays = keyRotationDays; 
}
public boolean isAuditSecretAccess() { return auditSecretAccess; }
public void setAuditSecretAccess(boolean auditSecretAccess) { 
this.auditSecretAccess = auditSecretAccess; 
}
public enum SecretsManagerType {
AWS, AZURE, GCP, HASHICORP_VAULT, CUSTOM
}
}

2. Secret Protection Aspect

@Aspect
@Component
public class SecretProtectionAspect {
private static final Logger logger = LoggerFactory.getLogger(SecretProtectionAspect.class);
private static final Set<String> SENSITIVE_PARAMS = Set.of(
"password", "secret", "key", "token", "credential"
);
@Around("execution(* *(.., @SecretParameter (*), ..))")
public Object protectSecretParameters(ProceedingJoinPoint joinPoint) throws Throwable {
Object[] args = joinPoint.getArgs();
Object[] protectedArgs = new Object[args.length];
for (int i = 0; i < args.length; i++) {
if (args[i] instanceof String || args[i] instanceof char[]) {
protectedArgs[i] = args[i];
} else {
protectedArgs[i] = args[i];
}
}
try {
return joinPoint.proceed(protectedArgs);
} finally {
// Cleanup sensitive data
for (int i = 0; i < protectedArgs.length; i++) {
if (protectedArgs[i] instanceof char[]) {
Arrays.fill((char[]) protectedArgs[i], '\0');
}
}
}
}
@AfterThrowing(pointcut = "execution(* com.yourcompany..*.*(..))", throwing = "ex")
public void logSecretAccessError(JoinPoint joinPoint, Exception ex) {
if (ex.getMessage() != null && 
(ex.getMessage().contains("secret") || ex.getMessage().contains("password"))) {
logger.warn("Potential secret access error in {}: {}", 
joinPoint.getSignature(), ex.getMessage());
}
}
}

3. Secure Password Handling

@Component
public class SecurePasswordManager {
private final SCryptPasswordEncoder sCryptEncoder;
private final BCryptPasswordEncoder bCryptEncoder;
public SecurePasswordManager() {
this.sCryptEncoder = new SCryptPasswordEncoder(16384, 8, 1, 32, 64);
this.bCryptEncoder = new BCryptPasswordEncoder(12);
}
public String hashPassword(char[] password) {
try {
return sCryptEncoder.encode(CharBuffer.wrap(password));
} finally {
Arrays.fill(password, '\0');
}
}
public boolean verifyPassword(char[] rawPassword, String encodedPassword) {
try {
return sCryptEncoder.matches(CharBuffer.wrap(rawPassword), encodedPassword);
} finally {
Arrays.fill(rawPassword, '\0');
}
}
public String generateSecureRandomPassword(int length) {
String upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
String lower = "abcdefghijklmnopqrstuvwxyz";
String digits = "0123456789";
String special = "!@#$%^&*()-_=+[]{}|;:,.<>?";
String all = upper + lower + digits + special;
SecureRandom random = new SecureRandom();
StringBuilder password = new StringBuilder(length);
// Ensure at least one of each type
password.append(upper.charAt(random.nextInt(upper.length())));
password.append(lower.charAt(random.nextInt(lower.length())));
password.append(digits.charAt(random.nextInt(digits.length())));
password.append(special.charAt(random.nextInt(special.length())));
// Fill remaining
for (int i = 4; i < length; i++) {
password.append(all.charAt(random.nextInt(all.length())));
}
// Shuffle
return shuffleString(password.toString());
}
private String shuffleString(String input) {
List<Character> characters = input.chars()
.mapToObj(c -> (char) c)
.collect(Collectors.toList());
Collections.shuffle(characters);
return characters.stream()
.collect(StringBuilder::new, StringBuilder::append, StringBuilder::append)
.toString();
}
}

Monitoring & Audit

1. Secret Access Auditor

@Component
public class SecretAccessAuditor {
private static final Logger auditLogger = LoggerFactory.getLogger("SECURITY_AUDIT");
public void auditSecretAccess(String secretId, String operation, String user) {
auditLogger.info("Secret access - ID: {}, Operation: {}, User: {}, Timestamp: {}, IP: {}", 
secretId, operation, user, Instant.now(), getClientIp());
}
public void auditSecretCreation(String secretId, String user) {
auditLogger.info("Secret created - ID: {}, User: {}, Timestamp: {}", 
secretId, user, Instant.now());
}
public void auditSecretDeletion(String secretId, String user) {
auditLogger.warn("Secret deleted - ID: {}, User: {}, Timestamp: {}", 
secretId, user, Instant.now());
}
private String getClientIp() {
// Implementation to get client IP
return "unknown";
}
}

2. Health Check for Secret Services

@Component
public class SecretsManagerHealthIndicator implements HealthIndicator {
private final SecretsManager secretsManager;
public SecretsManagerHealthIndicator(SecretsManager secretsManager) {
this.secretsManager = secretsManager;
}
@Override
public Health health() {
try {
// Test access with a dummy operation
secretsManager.listSecrets();
return Health.up()
.withDetail("service", "secrets-manager")
.withDetail("timestamp", Instant.now())
.build();
} catch (Exception e) {
return Health.down(e)
.withDetail("service", "secrets-manager")
.withDetail("error", e.getMessage())
.build();
}
}
}

Complete Spring Boot Configuration

application.yml

app:
security:
secrets-manager: AWS
master-key-env-var: APP_MASTER_KEY
enable-key-rotation: true
key-rotation-days: 90
audit-secret-access: true
encryption:
algorithm: AES/GCM/NoPadding
key-length: 256
iv-length: 12
spring:
profiles:
active: ${SPRING_PROFILES_ACTIVE:default}
cloud:
vault:
enabled: false
management:
endpoints:
web:
exposure:
include: health,info,metrics
endpoint:
health:
show-details: when_authorized
logging:
level:
com.yourcompany.security: DEBUG
SECURITY_AUDIT: INFO

Main Application Class

@SpringBootApplication
@EnableConfigurationProperties(SecurityConfig.class)
@EnableAsync
@EnableScheduling
@EnableAspectJAutoProxy
public class SecureApplication {
public static void main(String[] args) {
SpringApplication.run(SecureApplication.class, args);
}
@Bean
@Profile("!test")
public SecretsManager secretsManager(SecurityConfig securityConfig) {
return switch (securityConfig.getSecretsManager()) {
case AWS -> new AwsSecretsManager();
case AZURE -> new AzureKeyVaultService();
case GCP -> new GcpSecretManager();
case HASHICORP_VAULT -> new HashiCorpVaultService();
default -> new EnvironmentSecretProvider();
};
}
@Bean
public EncryptionService encryptionService() {
return new AesGcmEncryptionService();
}
}

Best Practices Summary

1. Never log secrets - Use masking in logs
2. Use secure memory handling - Clear char arrays after use
3. Implement proper key rotation - Automated and regular
4. Audit all secret access - Who accessed what and when
5. Use minimal privilege - Principle of least privilege
6. Secure transmission - TLS for all API calls
7. Regular security scanning - For dependencies and code
8. Secure disposal - Properly wipe sensitive data from memory

This comprehensive approach ensures your Java applications handle secrets securely while maintaining operational efficiency and compliance with security standards.