1 Talking to Engineers, Developers & Specialist Teams
When communicating with engineers, be precise. Avoid "Login doesn't work." Instead describe exactly what happened:
POST /oauth/token returns HTTP 401.
Response: invalid_grant
User authentication succeeds through the web portal.
The issue only occurs using the API.
Reproduced with three users.
Started after application deployment 4.8.2.Developers will often ask "Can you reproduce it?" — provide numbered reproduction steps plus expected vs. actual behaviour, and never paraphrase an error where you could paste it exactly (javax.net.ssl.SSLHandshakeException: PKIX path building failed is far more useful than "it showed some certificate error"). Always include exact timestamps, with timezone.
Other specialist teams need their own kind of specific evidence:
- Network engineers: source IP, destination IP, protocol, destination port, timestamp, expected vs. observed behaviour — e.g. "Source 10.20.30.14, destination 10.50.12.8, TCP 443, 14:22:16 UTC: SYN sent, no SYN-ACK received."
- Database teams: database name, application server, query, timestamp, error, connection behaviour, performance impact — e.g. "APP02 experienced database connection timeouts between 13:15 and 13:32 UTC. Application logs show connection acquisition exceeding 30 seconds."
- Security teams: source IP, destination IP, user, timestamp, event type, affected system, indicator, logs, business context. Avoid incomplete alerts like "Suspicious traffic seen" — context is what makes an alert actionable.
2 Global Handover & Internal Notes
Large organisations often provide 24/7 support using regional teams — APAC → EMEA → Americas — sometimes called a "follow-the-sun" support model. When one team finishes its working day, responsibility transfers to another region, and a good handover is essential so the next region doesn't have to rediscover everything:
Case: INC-78432
Customer: Example Bank
Issue: Intermittent MFA failure in production.
Impact: Approximately 20% of users affected.
Current status:
Issue remains under investigation.
Findings:
Authentication requests reach the IAM server successfully.
No outbound push request appears for failed transactions.
Actions completed:
- restarted one node
- checked DB connectivity
- validated push provider
- collected DEBUG logs
Next actions:
Engineering to review notification processing thread.
Customer update:
Last update sent at 16:30 UTC.
Next customer update:
18:00 UTC.
Important:
Do not restart both authentication nodes simultaneously.Internal case notes can be shorter, but should still create a clear history of the investigation:
14:12 UTC Customer reproduced issue.
14:14 UTC Received auth logs.
14:25 UTC Identified HTTP 403 from upstream API.
14:34 UTC Customer confirmed recent firewall change.
14:45 UTC Escalated to network team.
Next: Waiting for firewall review.3 Writing Knowledge Base Articles
A Knowledge Base (KB) article documents a known solution so someone else can resolve the same issue without asking the original engineer. A strong structure is: title, symptoms, environment, cause, resolution, verification, additional notes.
Title: Users receive HTTP 401 when requesting OAuth token
Symptoms:
API authentication fails with HTTP 401.
Response: invalid_grant
Environment:
OAuth 2.0 authentication server
Cause:
Client application sends credentials using JSON instead of
application/x-www-form-urlencoded.
Resolution:
Send the request using:
Content-Type: application/x-www-form-urlencoded
Example parameters:
grant_type=password
username=user@example.com
password=example
Verification:
Successful response returns HTTP 200 and an access token.A KB article should be searchable — use words someone experiencing the problem might actually search for. "Login problem" is a bad title; "HTTP 401 invalid_grant when requesting OAuth access token" is a good one, because it puts the exact error someone would paste into a search box right in the title. For legacy environments, document exactly which versions the article applies to (e.g. "Applies to: Windows Server 2016/2019/2022. Not applicable to: Windows Server 2008 R2") — never assume every customer runs the newest technology.
4 Explaining Technical Concepts Simply
A strong engineer can explain complicated technology in simple language without removing accuracy — it means choosing the right abstraction for the audience:
- DNS — Technical: "A distributed hierarchical naming system that resolves domain names into IP addresses." Simple: "The internet's phonebook — it converts names like example.com into the IP address a computer needs to connect to."
- Authentication — Technical: "The identity provider issues an OAuth access token after successful authentication and authorisation." Simple: "The user proves who they are to the identity system, which then gives the application a temporary token that allows access."
- Firewalls — Technical: "Evaluates packets against policy rules using source, destination, protocol and port." Simple: "A security checkpoint that decides which network connections are allowed to pass."
- MFA — Technical: "Requires credentials from more than one authentication factor category." Simple: "More than one type of proof you're the real user — like a password plus a mobile approval."
Analogies help beginners — DNS as a phonebook, a firewall as a security guard, an access token as a temporary pass, a certificate as a digital ID card, a load balancer as a traffic controller, an API as a waiter between two systems. But when speaking to technical engineers, pair the analogy with the real terminology, not instead of it.
5 Avoiding Jargon & Presenting Evidence
Consider: "The IdP generated an assertion containing the NameID which was consumed by the SP following an SP-initiated SAML AuthnRequest." This may be completely correct, but if your audience is a business manager, say instead: "The authentication provider successfully verified the user, but the application failed while processing the login response." Same problem, different audience.
Strong engineers also communicate evidence in a logical chain rather than jumping straight to a conclusion:
Evidence 1: DNS resolves correctly.
Evidence 2: TCP connection to port 443 succeeds.
Evidence 3: TLS handshake succeeds.
Evidence 4: Application returns HTTP 403.
Conclusion: Network connectivity is functioning. Investigation should
now focus on authorisation.Compare "OAuth is broken" (a conclusion without evidence) to "The OAuth token endpoint responds successfully, but returns HTTP 401 for this client" (a statement that narrows the investigation for whoever reads it next).