Login Forensics

Login Forensics

This skill activates when a practitioner needs to investigate individual or bulk user login activity in a Salesforce org — reconstructing timelines, identifying failed or anomalous logins, analyzing source IPs, reviewing identity verification outcomes, and tracing session origins. It covers the LoginHistory sObject (free, 6-month retention), the Login Forensics feature in the Event Monitoring add-on (extended session metadata), IdentityVerificationHistory, and Login Flows. It does not cover MFA configuration (use org-setup-and-configuration), EventLogFile bulk log download (use event-monitoring), or real-time threat detection (use event-monitoring).

Before Starting

Gather this context before working on anything in this domain:

• LoginHistory retention: The LoginHistory standard object retains records for up to 6 months. Records older than 6 months are automatically purged. If the investigation window exceeds 6 months, no recovery path exists unless the org exports to a SIEM.
• Login Forensics vs. LoginHistory: "Login Forensics" (capital F) refers specifically to a feature in the Event Monitoring add-on that provides enriched per-session data beyond what LoginHistory contains — including session duration, pages accessed, and correlated API calls. Free orgs only have LoginHistory. Confirm which the requester has.
• Permission required: SOQL on LoginHistory requires the "View Login Forensics" permission (Salesforce Shield / Event Monitoring add-on) OR System Administrator profile. Standard users cannot query other users' LoginHistory records.
• LoginHistory is read-only: You cannot insert, update, or delete LoginHistory records. Attempts will throw a System.DmlException.
• Limits: SOQL against LoginHistory supports a maximum of 30,000 rows per query. For high-volume orgs, always filter by LoginTime and UserId to avoid governor limit failures.

Core Concepts

Mode 1 — LoginHistory SOQL (Free, All Orgs)

The LoginHistory sObject is available in every Salesforce org at no extra cost and stores up to 6 months of login records. Key fields:

Query pattern for failed logins over a period:

SELECT UserId, LoginTime, LoginType, SourceIp, Status, Browser, Platform
FROM LoginHistory
WHERE LoginTime >= 2025-01-01T00:00:00Z
  AND LoginTime <= 2025-03-31T23:59:59Z
  AND Status != 'Success'
ORDER BY LoginTime DESC
LIMIT 1000

Query pattern for a specific user's full login timeline:

SELECT LoginTime, LoginType, SourceIp, Status, Browser, Platform
FROM LoginHistory
WHERE UserId = '005XXXXXXXXXXXXXXX'
ORDER BY LoginTime DESC
LIMIT 500

IP-based breadth query — find all users who logged in from a suspicious IP block:

SELECT UserId, LoginTime, SourceIp, Status
FROM LoginHistory
WHERE SourceIp LIKE '203.0.113.%'
  AND LoginTime >= LAST_N_DAYS:30
ORDER BY LoginTime DESC

Mode 2 — Login Forensics Feature (Event Monitoring Add-On)

The Login Forensics feature (available with Salesforce Shield or the Event Monitoring add-on) extends session-level data beyond LoginHistory. It surfaces:

• Session duration and activity patterns per login session
• Correlated API usage within a session
• More granular event details accessible via the LoginEvent object in Real-Time Event Monitoring

The LoginEvent object is part of Real-Time Event Monitoring (RTEM) and is distinct from LoginHistory. It fires as a streaming event, not a stored record. To analyze historical login events at this level, use the EventLogFile with EventType = 'Login' (covered by the event-monitoring skill).

For Login Forensics specifically, the workflow is:

1. Navigate to Setup > Login Forensics to access the UI-based drill-down for per-session investigation.
2. Filter by user, date range, or session ID.
3. Export session data for SIEM ingestion if needed.

Mode 3 — IdentityVerificationHistory and Login Flows

IdentityVerificationHistory tracks when Salesforce prompted a user for identity verification (e.g., email verification code, SMS, TOTP authenticator) and whether they passed or bypassed:

SELECT UserId, VerificationTime, Activity, Status, Comments
FROM IdentityVerificationHistory
WHERE UserId = '005XXXXXXXXXXXXXXX'
ORDER BY VerificationTime DESC
LIMIT 200

Status values include Success, Failure, Skipped, and Trusted. A Skipped or Trusted status means the user was not prompted — investigate whether their device/network was trusted unexpectedly.

Login Flows are Screen Flows attached to a profile or connected app via Setup > Login Flows. They intercept the login process after credential validation and before session creation, allowing conditional step-up authentication:

• Use case: require an additional TOTP code for users in a privileged profile
• Use case: block logins from non-approved countries by calling a Flow-invocable Apex class that checks $Flow.CurrentDate and source IP
• Login Flows do not themselves log events; the underlying LoginHistory record is still created

Common Patterns

Pattern: Incident Response Login Timeline Reconstruction

When to use: A user account is suspected compromised. You need to reconstruct the full timeline of login events, including source IPs, browser fingerprints, and failure patterns, to determine the blast radius.

How it works:

1. Query LoginHistory for the user over the suspected window:

   SELECT LoginTime, LoginType, SourceIp, Status, Browser, Platform, LoginUrl
   FROM LoginHistory
   WHERE UserId = '005XXXXXXXXXXXXXXX'
     AND LoginTime >= LAST_N_DAYS:30
   ORDER BY LoginTime DESC
   

2. Pivot on SourceIp — group IPs that appear across multiple users to detect credential stuffing:

   SELECT SourceIp, COUNT(Id) loginCount, COUNT_DISTINCT(UserId) affectedUsers
   FROM LoginHistory
   WHERE LoginTime >= LAST_N_DAYS:7
     AND Status != 'Success'
   GROUP BY SourceIp
   ORDER BY loginCount DESC
   

3. Cross-reference with IdentityVerificationHistory to see whether MFA was completed or skipped:

   SELECT UserId, VerificationTime, Activity, Status
   FROM IdentityVerificationHistory
   WHERE UserId = '005XXXXXXXXXXXXXXX'
   ORDER BY VerificationTime DESC
   LIMIT 50
   

4. Freeze the user account in Setup > Users while the investigation continues.
5. Revoke active sessions: Setup > Session Management, or via Apex: Auth.SessionManagement.revokeSessionsForUser(userId).

Why not to rely on the UI alone: Setup > Login History in the UI only shows the most recent 20,000 records and does not support complex filtering or cross-user pivots. SOQL is mandatory for incident response at any scale.

Pattern: Geo-Anomaly Detection Without Shield

When to use: The org does not have Shield or Event Monitoring, but the security team wants to identify logins from unexpected geographies using free tools.

How it works:

1. Export LoginHistory via SOQL using the REST API or Data Loader.
2. Run the exported SourceIp values through a free IP geolocation API (e.g., ip-api.com) in a local Python script.
3. Flag logins from country codes outside the org's known user base.
4. Note: Salesforce does not include country or region in LoginHistory natively — IP-to-geo mapping must be done externally.

Why not built-in geo-blocking: Transaction Security Policies (event-monitoring skill) can block logins by country in real time, but that requires the Shield or Event Monitoring add-on. For free orgs, Login Hours + Login IP Ranges on profiles are the only native controls.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

• Confirmed whether the org has the Event Monitoring add-on (determines Login Forensics feature availability)
• SOQL queries are filtered by LoginTime range to avoid querying full table and hitting 30,000-row limit
• Cross-user IP pivot query run to identify credential stuffing scope
• IdentityVerificationHistory checked for Skipped or unexpected Trusted statuses
• Compromised account frozen in Setup > Users and active sessions revoked
• Investigation window confirmed against 6-month LoginHistory retention limit
• If Login Flow is being configured: tested against all affected profiles in a sandbox first

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. LoginHistory only retains 6 months — there is no admin override — Records are automatically purged at the 6-month mark. There is no configuration option to extend retention, no recycle bin for these records, and no way to recover purged data. If an investigation spans longer than 6 months, the data simply does not exist in Salesforce unless the org was exporting it to a SIEM continuously.

2. SourceIp can be a Salesforce internal IP for API logins — When an integration or connected app authenticates using the OAuth client credentials flow or IP relaxation, the SourceIp field may reflect a Salesforce internal datacenter IP rather than the true client IP. This causes IP allowlisting checks to produce false negatives and makes geo-analysis unreliable for API-based logins.

3. Status field values are not normalized across LoginType — The Status field contains inconsistent values depending on whether the login was a UI login, SAML SSO, or API login. For example, a SAML login failure may appear as Failed while a direct login failure appears as Invalid Password. Grouping all failures as Status != 'Success' is the only reliable cross-type failure query pattern.

4. Login Forensics (the feature) requires a separate permission — "View Login Forensics" — Having Event Monitoring access does not automatically grant access to the Login Forensics Setup page. The View Login Forensics permission must be explicitly granted on the profile or permission set. Forgetting this is a common cause of 403 errors when trying to access Setup > Login Forensics.

5. IdentityVerificationHistory 'Trusted' does not mean MFA was performed — A Trusted status means the user's device or network was registered as trusted, so Salesforce skipped the MFA prompt entirely. This is expected behavior if the org allows trusted devices, but it can appear in an audit as an MFA bypass when it is actually by design. Investigate the Activity field value (High Assurance Login, Identity Verification) to understand what was being verified.

Output Artifacts

Related Skills

• event-monitoring — Use when you need to download EventLogFile Login logs in bulk, configure real-time event monitoring, or set up Transaction Security Policies to block logins by country or IP
• org-setup-and-configuration — Use for MFA enablement, session settings (timeout, IP locking), and Login Hours/IP Ranges on profiles
• transaction-security-policies — Use when you need real-time enforcement policies that react to login events automatically