PE-ROA
roadtx
ROADtools Token eXchange — acquires, refreshes, and exchanges Entra ID OAuth tokens across clients and flows for red-team token testing.
OVERVIEW
roadtx (ROADtools Token eXchange, part of dirkjanm/ROADtools alongside the roadrecon exploration tool) automates the OAuth2 flows Entra ID uses to issue access, refresh, and Primary Refresh Tokens (PRTs). Its `gettokens`, `refreshtokento`, `devicecode`, and `appauth` commands cover interactive, device-code, and application-based authentication, letting a tester obtain a token for one client/resource pair and then exchange it for another.
Its most relevant capability for red-team testing is FOCI (Family of Client IDs) token exchange: many first-party Microsoft client IDs share refresh tokens, so a refresh token issued to one client (e.g. Azure CLI) can often be redeemed for an access token scoped to a completely different first-party app (e.g. Microsoft Teams or SharePoint) without re-authenticating. roadtx is used to demonstrate that this token portability, combined with weak or absent conditional access scoping, lets a single compromised token reach far more of a tenant than its original consent scope suggests.
USE CASES
Practical use cases
- 01
Exchanging a refresh token obtained from one FOCI client ID for access tokens to other first-party Microsoft apps and resources.
- 02
Testing whether Entra ID conditional access policies are actually enforced across different client/resource combinations, not just the one a user first authenticated to.
- 03
Simulating device-code and application-based authentication flows to assess Entra ID sign-in and consent hardening.
- 04
Requesting and using Primary Refresh Tokens to evaluate Windows Hello for Business / WAM-style authentication exposure.
QUICK START
Once post-exploitation testing of Entra ID conditional access and token scope boundaries is authorized, to acquire, refresh, and exchange OAuth tokens across client IDs and flows.
- Install roadtx once token-exchange testing is in scope: `pip install roadtx`.
- Obtain an initial token with client-provided or compromised credentials, e.g. `roadtx gettokens -u user@tenant.onmicrosoft.com -p '<password>' -r msgraph`.
- List available client/resource aliases with `roadtx listaliases` to understand which FOCI exchanges are possible.
- Use `roadtx refreshtokento` to exchange the cached refresh token for a different client or resource and document what conditional access allowed or blocked.
roadtx gettokens -u user@tenant.onmicrosoft.com -p '<password>' -r msgraphBEFORE YOU RUN IT
What to check before running it
Every token request and exchange is a real Entra ID sign-in event and appears in the sign-in logs under the identity used — agree with the client on expected volume and timing so it doesn't get flagged as a live incident.
FOCI token exchange can grant access to resources well beyond the scope the user or tester expected; confirm in writing which resources are in scope before exchanging tokens toward them.
Password-based authentication flows (`gettokens -p`) count against account lockout thresholds like any other sign-in attempt — prefer device-code or existing token/refresh-token flows where possible.