input username + password -> check database -> login

identifier resolution
credential verification
account lifecycle
risk decision
session establishment
abuse control
audit trail
recovery path
incident response

Password tidak membuktikan “user ini aman”.
Password hanya membuktikan “claimant mengetahui secret yang sebelumnya diregistrasikan”.

Identifier bukan credential.
Credential bukan account.
Account bukan session.
Password reset bukan login.
Login success bukan berarti aksi sensitif boleh langsung dilakukan.

Internal reason boleh detail.
External response harus generic.
Audit harus detail tetapi aman.
Metric harus agregat dan tidak bocor ke attacker.

Registration adalah enrollment account + identifier + initial credential + verification obligation.

{
  "message": "If the account can be created or verified, instructions will be sent."
}

RI-001: Login identifier harus dinormalisasi sebelum uniqueness check.
RI-002: Plain password tidak boleh pernah disimpan, dilog, dikirim ke queue, atau dimasukkan ke event.
RI-003: Password policy divalidasi sebelum hashing mahal dilakukan.
RI-004: Credential dibuat dengan algorithm id dan parameter version.
RI-005: Account baru sebaiknya punya status eksplisit: PENDING_VERIFICATION, ACTIVE, DISABLED, CLOSED.
RI-006: Verification token harus single-use, expiring, dan hashed at rest.
RI-007: Registration event tidak boleh berisi password atau token mentah.

public final class LoginIdentifierNormalizer {
    public NormalizedIdentifier normalizeEmail(String raw) {
        if (raw == null || raw.isBlank()) {
            throw new InvalidIdentifierException();
        }

        String trimmed = raw.trim();
        int at = trimmed.lastIndexOf('@');
        if (at <= 0 || at == trimmed.length() - 1) {
            throw new InvalidIdentifierException();
        }

        String local = trimmed.substring(0, at);
        String domain = trimmed.substring(at + 1).toLowerCase(Locale.ROOT);

        // Jangan otomatis menghapus dot/plus pada local-part secara global.
        // Itu provider-specific dan bisa menyebabkan account takeover edge case.
        String canonical = local + "@" + IDN.toASCII(domain);

        return new NormalizedIdentifier("email", canonical);
    }
}

Normalize enough for consistency.
Do not normalize so aggressively that two distinct real-world mailboxes collapse into one identity.

minimum 8, harus uppercase, lowercase, number, symbol, rotate tiap 90 hari

- minimum length cukup panjang;
- allow spaces dan passphrase;
- maximum length tinggi tetapi tetap punya batas DoS;
- block common/breached/known weak password;
- jangan paksa composition rule aneh;
- jangan periodic reset tanpa indikasi compromise;
- dukung password manager paste/autofill;
- tampilkan strength guidance tanpa menyimpan password.

public final class PasswordPolicy {
    private final BreachedPasswordChecker breachedPasswordChecker;

    public PasswordValidationResult validate(char[] password, AccountContext ctx) {
        if (password == null) return PasswordValidationResult.invalid("PASSWORD_REQUIRED");

        int codePoints = new String(password).codePointCount(0, password.length);
        if (codePoints < 12) return PasswordValidationResult.invalid("PASSWORD_TOO_SHORT");
        if (codePoints > 1024) return PasswordValidationResult.invalid("PASSWORD_TOO_LONG");

        if (looksLikeIdentifier(password, ctx.loginIdentifier())) {
            return PasswordValidationResult.invalid("PASSWORD_RESEMBLES_IDENTIFIER");
        }

        if (breachedPasswordChecker.isKnownCompromised(password)) {
            return PasswordValidationResult.invalid("PASSWORD_COMPROMISED");
        }

        return PasswordValidationResult.valid();
    }
}

public sealed interface AuthenticationResult permits
        AuthenticationResult.Success,
        AuthenticationResult.ChallengeRequired,
        AuthenticationResult.Failure {

    record Success(
            AccountId accountId,
            SessionId sessionId,
            AuthenticationAssuranceLevel assuranceLevel,
            Instant authenticatedAt
    ) implements AuthenticationResult {}

    record ChallengeRequired(
            ChallengeId challengeId,
            ChallengeType challengeType,
            Duration expiresIn
    ) implements AuthenticationResult {}

    record Failure(
            FailureCode internalCode,
            PublicFailure publicFailure,
            boolean retryable
    ) implements AuthenticationResult {}
}

enum FailureCode {
    UNKNOWN_IDENTIFIER,
    PASSWORD_INVALID,
    ACCOUNT_DISABLED,
    ACCOUNT_LOCKED,
    PASSWORD_EXPIRED,
    RATE_LIMITED,
    RISK_DENIED,
    CREDENTIAL_REVOKED
}

enum PublicFailure {
    INVALID_CREDENTIALS,
    TRY_AGAIN_LATER
}

public final class PasswordAuthenticationService {
    private final AccountRepository accountRepository;
    private final PasswordCredentialRepository credentialRepository;
    private final PasswordVerifier passwordVerifier;
    private final RateLimiter rateLimiter;
    private final RiskEngine riskEngine;
    private final SessionService sessionService;
    private final AuthenticationAudit audit;
    private final SyntheticPasswordVerifier syntheticPasswordVerifier;

    public AuthenticationResult authenticate(LoginCommand command) {
        Instant now = Instant.now();
        AttemptContext attempt = AttemptContext.from(command, now);

        RateDecision rateDecision = rateLimiter.check(attempt.rateLimitKeys());
        if (!rateDecision.allowed()) {
            audit.failure(attempt, FailureCode.RATE_LIMITED);
            return failure(FailureCode.RATE_LIMITED, PublicFailure.TRY_AGAIN_LATER);
        }

        NormalizedIdentifier identifier = normalize(command.identifier());
        Optional<Account> maybeAccount = accountRepository.findByIdentifier(identifier);

        VerificationResult verification = maybeAccount
                .map(account -> verifyKnownAccount(account, command.password()))
                .orElseGet(() -> syntheticPasswordVerifier.verify(command.password()));

        if (maybeAccount.isEmpty() || !verification.valid()) {
            rateLimiter.recordFailure(attempt.rateLimitKeys());
            audit.failure(attempt.withIdentifier(identifier), maybeAccount.isEmpty()
                    ? FailureCode.UNKNOWN_IDENTIFIER
                    : FailureCode.PASSWORD_INVALID);
            return failure(FailureCode.PASSWORD_INVALID, PublicFailure.INVALID_CREDENTIALS);
        }

        Account account = maybeAccount.get();
        if (!account.canAuthenticate()) {
            audit.failure(attempt.forAccount(account.id()), account.toFailureCode());
            return failure(account.toFailureCode(), PublicFailure.INVALID_CREDENTIALS);
        }

        RiskDecision risk = riskEngine.evaluate(account, attempt, verification);
        if (risk.denied()) {
            audit.failure(attempt.forAccount(account.id()), FailureCode.RISK_DENIED);
            return failure(FailureCode.RISK_DENIED, PublicFailure.INVALID_CREDENTIALS);
        }

        if (risk.requiresChallenge()) {
            Challenge challenge = riskEngine.issueChallenge(account, risk);
            audit.challengeIssued(attempt.forAccount(account.id()), challenge);
            return new AuthenticationResult.ChallengeRequired(
                    challenge.id(), challenge.type(), challenge.expiresIn());
        }

        Session session = sessionService.createAuthenticatedSession(account, attempt, verification.assuranceLevel());
        rateLimiter.recordSuccess(attempt.rateLimitKeys());
        audit.success(attempt.forAccount(account.id()), session.id());

        return new AuthenticationResult.Success(
                account.id(), session.id(), verification.assuranceLevel(), now);
    }

    private VerificationResult verifyKnownAccount(Account account, char[] password) {
        PasswordCredential credential = credentialRepository.activePasswordFor(account.id())
                .orElseThrow(() -> new AuthenticationInvariantViolation("No active password credential"));
        return passwordVerifier.verify(password, credential);
    }

    private AuthenticationResult.Failure failure(FailureCode internal, PublicFailure external) {
        return new AuthenticationResult.Failure(internal, external, true);
    }
}

Unknown account path tetap melakukan synthetic password verification.

if (account == null) {
    return invalid(); // terlalu cepat
}

public final class SyntheticPasswordVerifier {
    private final PasswordEncoder passwordEncoder;
    private final String syntheticHash;

    public VerificationResult verify(char[] rawPassword) {
        boolean ignored = passwordEncoder.matches(CharBuffer.wrap(rawPassword), syntheticHash);
        return VerificationResult.invalid();
    }
}

public enum AccountStatus {
    PENDING_VERIFICATION,
    ACTIVE,
    LOCKED,
    DISABLED,
    CLOSED,
    COMPROMISED
}

Jangan biarkan password valid pada account disabled menghasilkan response yang membedakan account disabled dari password salah.

Gunakan graduated response, bukan binary lockout.

public record RateDecision(
        boolean allowed,
        boolean delayed,
        Duration delay,
        boolean challengeRecommended,
        String policyId
) {}

public final class LoginRateLimiter {
    private final RedisScript<Long> consumeTokenScript;
    private final StringRedisTemplate redis;

    public RateDecision check(List<RateLimitKey> keys) {
        for (RateLimitKey key : keys) {
            long remaining = redis.execute(
                    consumeTokenScript,
                    List.of(key.redisKey()),
                    String.valueOf(key.capacity()),
                    String.valueOf(key.refillPerMinute()),
                    String.valueOf(Instant.now().getEpochSecond())
            );

            if (remaining < 0) {
                return new RateDecision(false, false, Duration.ZERO, false, key.policyId());
            }
        }
        return new RateDecision(true, false, Duration.ZERO, false, "login-default");
    }
}

{ "error": "Email not found" }

{ "error": "Password wrong for active account" }

{
  "error": "INVALID_CREDENTIALS",
  "message": "The identifier or password is invalid."
}

{
  "error": "TRY_AGAIN_LATER",
  "message": "Unable to process the login attempt right now. Please try again later."
}

Password change = user sudah authenticated dan membuktikan password lama atau step-up.
Password reset = user tidak bisa menggunakan password lama dan memakai recovery proof.

CP-001: User harus recently authenticated atau memberikan old password.
CP-002: New password harus melewati policy yang sama atau lebih kuat dari registration.
CP-003: New password tidak boleh sama dengan current password.
CP-004: Old password hash tidak di-update in-place tanpa version history/revocation event.
CP-005: Credential version harus naik.
CP-006: Session/token yang dibuat sebelum credential change harus punya policy: revoke all, revoke others, atau step-up required.
CP-007: Audit harus mencatat actor, subject, method, assurance, device, IP, dan correlation id.

public record AuthenticatedSession(
        SessionId id,
        AccountId accountId,
        long credentialVersionAtLogin,
        Instant authenticatedAt
) {}

if (session.credentialVersionAtLogin() < account.currentCredentialVersion()) {
    throw new ReauthenticationRequiredException();
}

Attacker tidak perlu tahu password lama.
Attacker cukup menguasai email/phone/recovery channel.

RT-001: Token harus high entropy.
RT-002: Token mentah hanya dikirim ke user, tidak disimpan plaintext.
RT-003: Simpan hash token di database.
RT-004: Token single-use.
RT-005: Token punya expiry pendek.
RT-006: Token terikat ke purpose: PASSWORD_RESET.
RT-007: Token terikat ke account dan credential version.
RT-008: Reset completion harus revoke session sesuai policy.
RT-009: Reset request response harus generic.
RT-010: Reset event harus audit-grade.

public final class RecoveryToken {
    private RecoveryTokenId id;
    private AccountId accountId;
    private RecoveryPurpose purpose;
    private String tokenHash;
    private Instant expiresAt;
    private Instant consumedAt;
    private long credentialVersionAtIssue;

    public boolean canBeConsumed(Instant now, long currentCredentialVersion) {
        return consumedAt == null
                && now.isBefore(expiresAt)
                && credentialVersionAtIssue == currentCredentialVersion;
    }
}

Jika user berhasil mengganti password setelah token dibuat, token reset lama tidak boleh tetap valid.

create table auth_account (
    id uuid primary key,
    status varchar(40) not null,
    current_credential_version bigint not null default 1,
    created_at timestamptz not null,
    updated_at timestamptz not null
);

create table auth_login_identifier (
    id uuid primary key,
    account_id uuid not null references auth_account(id),
    identifier_type varchar(40) not null,
    normalized_value varchar(512) not null,
    verified_at timestamptz,
    created_at timestamptz not null,
    unique(identifier_type, normalized_value)
);

create table auth_password_credential (
    id uuid primary key,
    account_id uuid not null references auth_account(id),
    credential_version bigint not null,
    password_hash text not null,
    algorithm varchar(80) not null,
    parameters_json jsonb not null,
    created_at timestamptz not null,
    revoked_at timestamptz,
    revoke_reason varchar(80),
    unique(account_id, credential_version)
);

create table auth_recovery_token (
    id uuid primary key,
    account_id uuid not null references auth_account(id),
    purpose varchar(80) not null,
    token_hash text not null,
    credential_version_at_issue bigint not null,
    expires_at timestamptz not null,
    consumed_at timestamptz,
    created_at timestamptz not null
);

create index idx_auth_recovery_token_hash
    on auth_recovery_token(token_hash);

public final class DomainPasswordAuthenticationProvider implements AuthenticationProvider {
    private final PasswordAuthenticationService passwordAuthenticationService;

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        String identifier = authentication.getName();
        char[] password = authentication.getCredentials().toString().toCharArray();

        AuthenticationResult result = passwordAuthenticationService.authenticate(
                new LoginCommand(identifier, password, RequestMetadata.current())
        );

        if (result instanceof AuthenticationResult.Success success) {
            AccountPrincipal principal = new AccountPrincipal(success.accountId(), success.assuranceLevel());
            return UsernamePasswordAuthenticationToken.authenticated(
                    principal,
                    null,
                    List.of()
            );
        }

        if (result instanceof AuthenticationResult.ChallengeRequired challenge) {
            throw new MfaRequiredAuthenticationException(challenge.challengeId());
        }

        throw new BadCredentialsException("Invalid credentials");
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return UsernamePasswordAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

Spring exception boleh generic.
Domain audit harus tetap detail.

@ApplicationScoped
public class PasswordHttpAuthenticationMechanism implements HttpAuthenticationMechanism {
    @Inject
    PasswordAuthenticationService authenticationService;

    @Override
    public AuthenticationStatus validateRequest(
            HttpServletRequest request,
            HttpServletResponse response,
            HttpMessageContext context) throws AuthenticationException {

        if (!isLoginRequest(request)) {
            return context.doNothing();
        }

        LoginCommand command = parseLoginCommand(request);
        AuthenticationResult result = authenticationService.authenticate(command);

        if (result instanceof AuthenticationResult.Success success) {
            CredentialValidationResult validation = new CredentialValidationResult(
                    success.accountId().toString(),
                    Set.of()
            );
            return context.notifyContainerAboutLogin(validation);
        }

        writeGenericFailure(response);
        return AuthenticationStatus.SEND_FAILURE;
    }
}

Framework mechanism bukan tempat semua domain rule tinggal.

public record AuthenticationAuditEvent(
        UUID eventId,
        String eventType,
        Instant occurredAt,
        AccountId accountId,
        String normalizedIdentifierHash,
        String tenantId,
        String outcome,
        String internalReason,
        String publicReason,
        String ipAddressHash,
        String userAgentHash,
        String deviceId,
        String correlationId,
        AuthenticationAssuranceLevel assuranceLevel
) {}

Log enough to investigate.
Do not log enough to help the attacker.

Unknown email response lebih cepat atau pesan berbeda.

Banyak login failure dengan password valid di breach lain.

Attacker sengaja membuat banyak failed attempts agar account korban locked.

Password reset berhasil melalui email/phone yang sudah dikompromi.

Session pre-login tetap dipakai setelah login.

Attacker submit password sangat panjang atau banyak login paralel sehingga CPU/memory habis.

Semakin besar dampak account takeover, semakin password harus menjadi salah satu sinyal, bukan satu-satunya proof.

{
  "identifier": "alice@example.com",
  "password": "correct horse battery staple",
  "tenantHint": "acme",
  "deviceId": "optional-device-id"
}

{
  "status": "AUTHENTICATED",
  "session": {
    "expiresAt": "2026-07-03T12:00:00Z"
  },
  "assuranceLevel": "AAL1"
}

{
  "status": "CHALLENGE_REQUIRED",
  "challengeId": "ch_01J...",
  "challengeType": "TOTP",
  "expiresInSeconds": 300
}

{
  "status": "FAILED",
  "error": "INVALID_CREDENTIALS",
  "message": "The identifier or password is invalid."
}

users(id, email, password_hash, role)

10.000 failed login attempts per menit
rotating IP
100 target account
1 tenant enterprise

{ "error": "ACCOUNT_DISABLED" }

identifier -> account -> credential -> verification -> risk -> challenge -> session -> audit -> recovery -> revocation

Password valid hanya berarti claimant tahu secret.
Ia belum berarti user aman, device aman, session aman, tenant benar, atau aksi sensitif boleh dilakukan.