Skip to main content
Home Documentation

Step-by-Step Guide: Troubleshooting Generic Login Issues (Agent Workflow)

Ariela Goldberg

0 comments

This article provides a structured, repeatable process support agents can use to diagnose and resolve common login problems across most platforms (web, mobile, SSO, and apps). Use it as a baseline and adapt steps to your product’s tools and policies.

1) Confirm the Issue and Gather Key Details

Goal: Quickly understand what “can’t log in” means and collect the minimum details needed to investigate.

Ask the user:

  • What exactly happens when you try to log in? (error message, blank page, looping, “wrong password,” etc.)
  • Where are you logging in? (Web, mobile app, desktop app)
  • What is the login method?
    • Email + password
    • “Continue with Google/Apple/Microsoft”
    • SSO (company login)
  • When did it start? Has it ever worked before?
  • Are you using a VPN, corporate network, or password manager?
  • What device/browser/app version are you using?

Collect and document:

  • User identifier (email/username/account ID)
  • Screenshots of the error (if possible)
  • Time of attempt + timezone
  • Any recent changes (new device, password reset, new employer/SSO, account email change)

2) Check for Service Incidents or Known Outages

Goal: Rule out platform-wide issues before doing account-level troubleshooting.

Agent actions:

  • Check internal status dashboards, incident channels, and monitoring tools.
  • Check public status page (if applicable).

If an outage is confirmed:

  • Inform the user clearly.
  • Provide ETA if available.
  • Log the affected account and attach incident reference.
  • Avoid unnecessary troubleshooting steps.

3) Identify the Primary Login Failure Type

Classify the issue based on symptoms—this determines the fastest path to resolution.

Common categories:

  1. Credentials rejected (incorrect password/username)
  2. MFA/2FA issues (code not received, authenticator out of sync)
  3. SSO problems (redirect loops, “not authorized,” IdP errors)
  4. Account status issues (locked, suspended, unverified)
  5. Session/browser/app problems (cookies, cache, app state, time skew)
  6. Email delivery issues (password reset or verification emails not arriving)

4) Validate Account Existence and Status (Internal Tools)

Goal: Ensure the account is in good standing and the user is using the correct identifier.

Agent checks (as applicable):

  • Does the account exist for the email/username provided?
  • Is the account active, suspended, disabled, deleted, or pending verification?
  • Is the account locked due to failed attempts?
  • Is there a region/age/compliance restriction that blocks login?
  • Are there recent security events (suspicious login blocks, risk flags)?

If you find a status problem:

  • Follow policy: unlock/restore if permitted, or escalate to the proper team.
  • Communicate clearly what must happen next (verification, waiting period, compliance review).

5) Resolve “Incorrect Password / Credentials” Issues

Goal: Get the user into the account without weakening security.

Agent steps:

  1. Confirm the user is using the correct email/username (common typo check).
  2. Ask if they have multiple accounts or aliases (e.g., work vs personal email).
  3. Have them attempt a password reset via the standard “Forgot password” flow.
  4. If reset succeeds but login still fails:
    • Ensure they are not accidentally logging in via SSO/social login when the account is password-based (or vice versa).
    • Confirm the new password meets requirements.
    • Ask them to try in a private/incognito window or another browser/device.

If policy allows agent-assisted resets:

  • Use approved tools and identity verification steps before making changes.

6) Troubleshoot MFA / 2FA Problems

Goal: Restore MFA access while maintaining account security.

Common symptoms: Codes not arriving, invalid code, “too many attempts,” authenticator mismatch.

Agent steps:

  1. Identify MFA type: SMS, email code, authenticator app, push notification, security key.
  2. For SMS/email codes:
    • Confirm contact info on file (last digits/partial match if required by policy).
    • Ask user to check spam/junk, blocked numbers, message filtering, and inbox rules.
    • Ask user to try resending after waiting 1–2 minutes (avoid spamming resend).
  3. For authenticator apps:
    • Confirm device time is set to automatic (time skew commonly breaks codes).
    • Have them generate a fresh code and try again.
  4. If the user no longer has the MFA device:
    • Follow your account recovery process (identity verification, recovery codes, or escalation).
  5. If the account is temporarily locked due to failed MFA:
    • Confirm lockout duration and advise user when to retry (or unlock if permitted).

7) Handle SSO (Single Sign-On) Login Issues

Goal: Determine whether the issue is in your platform or the user’s identity provider (IdP).

Agent steps:

  1. Confirm they are using the correct SSO entry point (SSO button vs password form).
  2. Capture the exact error message and the domain/tenant (company identifier).
  3. Check internal SSO configuration:
    • Is the SSO connection active?
    • Has metadata/cert expired?
    • Are email domains correctly mapped?
  4. Ask the user to try:
    • Logging into their IdP directly (e.g., Microsoft/Google workspace portal) to confirm credentials work there.
    • Another browser or incognito to eliminate cached sessions.
  5. If the IdP is failing:
    • Advise the user to contact their IT/IdP admin with the error details.
  6. If configuration appears broken on your side:
    • Escalate to the SSO/admin team with logs and reproduction steps.

8) Fix Browser / App Session Issues (Common “Loops” and Blank Screens)

Goal: Eliminate client-side causes like corrupted cookies, cached sessions, or outdated builds.

Agent steps:

  1. Ask the user to try incognito/private mode.
  2. Clear cookies and cache for your site/app.
  3. Disable browser extensions that can interfere (ad blockers, script blockers, privacy tools).
  4. Try another browser/device/network.
  5. For mobile apps:
    • Update the app to the latest version.
    • Force close and reopen.
    • Log out (if possible) and log back in.
    • Reinstall the app if needed.

If issue is tied to a specific environment:

  • Document browser version, OS version, device model, and extension list for escalation.

9) Resolve “Email Not Received” (Verification / Password Reset)

Goal: Ensure deliverability and correct routing.

Agent steps:

  1. Confirm the email address (carefully check spelling and domain).
  2. Have the user check:
    • Spam/junk/promotions
    • Email filters/rules
    • Quarantine (corporate email systems)
  3. Ask them to search inbox for your sender domain and subject keywords.
  4. Confirm whether your system shows the email was sent (if you have logs).
  5. If emails are bouncing or suppressed:
    • Remove suppression (if your tools allow and policy permits)
    • Recommend allowlisting your sender domain
  6. Offer an alternate verification method if available (MFA, backup email, support-assisted verification).

10) Review Security Events and Apply Risk Controls

Goal: Prevent account compromise while still helping legitimate users.

Agent checks (where available):

  • Recent login attempts: IP/location anomalies, device changes, impossible travel flags
  • Rate limiting or brute-force protections triggered

Agent actions:

  • If suspicious activity is detected:
    • Follow security protocol (forced reset, lock account, escalate to security team).
    • Do not disclose sensitive security details to the user (e.g., exact IPs) beyond policy.

11) Confirm Resolution and Document Thoroughly

Goal: Ensure the user can log in and leave a clean trail for future support.

Before closing:

  • Ask the user to log in successfully while you wait (if possible).
  • Confirm they can access the correct account/workspace/profile.

Document in the ticket:

  • Symptom and error text
  • Root cause category (credentials/MFA/SSO/status/client/email)
  • Steps taken and outcomes
  • Any account actions performed (unlock/reset) and verification method used
  • Escalation details if unresolved

12) Escalation Criteria (When to Hand Off)

Escalate when:

  • Account is disabled/suspended and agent cannot restore
  • Repeated failures with no client-side cause identified
  • SSO configuration/cert issues suspected
  • Email delivery issues show bounces/suppression you cannot clear
  • Possible account takeover or security flags appear
  • You cannot reproduce but multiple users report the same issue (potential incident)

Include in escalation:

  • User identifier + affected environment
  • Timestamps and error messages
  • Screenshots/har files/logs if available
  • Steps already tried (to prevent duplication)


 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

0 comments

Please sign in to leave a comment.

Powered by Zendesk