OAuth Device Code Phishing Defense

Production-ready scripts to detect and block OAuth 2.0 Device Authorization Grant (RFC 8628) phishing across Microsoft Entra ID, Keycloak, and Auth0 — plus SIEM detection queries and an incident-response playbook for accounts that were already compromised.

Full tutorial: OAuth Device Code Flow Security: How to Detect and Prevent Device Code Phishing

Device code phishing (SquarePhish, Graphish, and similar toolkits) is one of the most effective MFA-bypass techniques of 2024–2026: the victim completes real MFA against the real login page, but ends up authorizing an attacker's polling script instead of their own device. These scripts turn that guide's mitigation steps into idempotent, safe-to-rerun automation instead of copy-pasted curl commands.

What's Inside

oauth-device-code-phishing-defense/
├── entra-id/
│   ├── Deploy-DeviceCodeBlockPolicy.ps1   # Conditional Access block policy + exemption group (idempotent, -WhatIf support)
│   └── Find-DeviceCodeAnomalies.ps1       # Retroactive scan of sign-in logs for suspicious device-code usage
├── keycloak/
│   ├── disable-device-code-grant.sh       # Disable at realm or per-client level via Admin REST API, with verification
│   └── audit-device-code-clients.sh       # List every client with the grant enabled before you flip the realm switch
├── auth0/
│   └── remove-device-code-grant.sh        # Audit + remove the device_code grant type via the Management API
├── detection/
│   ├── sentinel-device-code-anomalies.kql # 3 queries: sweep, service-account filter, high-confidence multi-IP alert
│   └── splunk-device-code-anomalies.spl   # Same detection logic for Splunk (Azure AD Add-on sourcetype)
└── incident-response/
    └── Invoke-DeviceCodeIncidentResponse.ps1  # Revoke sessions, force password reset, audit consents/inbox rules/MFA methods

Quick Start

1. Audit before you block (Keycloak / Auth0)

export KEYCLOAK_URL="https://keycloak.example.com"
export KEYCLOAK_ADMIN_CLIENT_ID="admin-cli-confidential"
export KEYCLOAK_ADMIN_CLIENT_SECRET="..."

./keycloak/audit-device-code-clients.sh --realm your-realm

export AUTH0_MGMT_CLIENT_ID="..."
export AUTH0_MGMT_CLIENT_SECRET="..."

./auth0/remove-device-code-grant.sh --domain your-tenant.auth0.com --audit

2. Block the grant

# Keycloak — realm-wide
./keycloak/disable-device-code-grant.sh --realm your-realm

# Auth0 — per application
./auth0/remove-device-code-grant.sh --domain your-tenant.auth0.com --client-id abc123 --apply

# Entra ID — Conditional Access with an exemption group for legitimate TV/CLI clients
Connect-MgGraph -Scopes "Policy.ReadWrite.ConditionalAccess","Group.ReadWrite.All"
./entra-id/Deploy-DeviceCodeBlockPolicy.ps1 -ExemptGroupName "Device Code Exempt Accounts"

3. Retroactively check for prior abuse

Connect-MgGraph -Scopes "AuditLog.Read.All","Directory.Read.All"
./entra-id/Find-DeviceCodeAnomalies.ps1 -DaysBack 90 -OutputPath ./report.json

4. Wire up SIEM detection

Import detection/sentinel-device-code-anomalies.kql into a Sentinel analytics rule, or detection/splunk-device-code-anomalies.spl as a saved search. Tune the KnownServiceAccountPattern / automation IP allowlists for your environment before alerting — headless CI runners using az login --use-device-code will otherwise show up as false positives.

5. If an account was already compromised

Connect-MgGraph -Scopes "User.RevokeSessions.All","User.ReadWrite.All","DelegatedPermissionGrant.ReadWrite.All","UserAuthenticationMethod.Read.All"
./incident-response/Invoke-DeviceCodeIncidentResponse.ps1 -UserId user@corp.example.com

This revokes all sessions (invalidating the attacker's stolen refresh token), forces a password reset, and lists OAuth consent grants, inbox rules, and MFA methods for review — the same five steps from the tutorial's response playbook, wrapped in one auditable script with -WhatIf support.

Why This Matters

The device authorization grant was built for TVs, CLIs, and IoT devices that can't open a browser — but any identity provider implementing RFC 8628 (Entra ID, Okta, Google Workspace, Ping Identity, Keycloak, Auth0) is exposed to the same phishing pattern: the attacker requests a code, phishes the victim into entering it on the real login page, and the victim's own completed MFA hands the attacker a fully authorized refresh token. Blocking the grant for everyone except a small, explicit exemption group closes the hole without breaking legitimate headless clients.

Related Reading

• OAuth Device Code Flow Security: How to Detect and Prevent Device Code Phishing — the full tutorial this repo accompanies
• MFA Bypass Attacks: Understanding Threats and Implementing Phishing-Resistant Authentication — where device code phishing fits into the broader MFA-bypass landscape
• NHI Secrets Sprawl: Fixing the Non-Human Identity Credential Crisis — long-lived refresh tokens and service-account credential sprawl
• Device Code Phishing Campaign Targets 340+ Microsoft 365 Organizations — real-world campaign writeup
• IAM Tools Comparison: Complete Guide to Identity Platforms — comparing Entra ID, Keycloak, Auth0, and other platforms covered here

License

MIT — see LICENSE.