ROADtools Token eXchange (roadtx)

ROADtools Token eXchange, or roadtx in short, is a tool to automate and implement authentication and registration flows against Azure AD. It is focused around tokens, such as (primary) refresh tokens and access tokens.

It can do the following:

• Register and join devices to Azure AD.
• Request Primary Refresh Tokens from user credentials or other valid tokens.
• Use Primary Refresh Tokens in a similar way as the Web Account Manager (WAM) in Windows does.
• Perform all kind of Oauth2 token redemption flows.
• Perform interactive logins based on Browser SSO by injecting the Primary Refresh Token into the authentication flow.
• Add SSO capabilities to Chrome via the Windows 10 accounts plugin and a custom browsercore implementation.
• Automate sign-ins, MFA and token requesting to various resources in Azure AD by using Selenium.
• Possibility to load credentials and MFA TOTP seeds from a KeePass database to use in automated flows.

Authentication

Authentication in the OAuth2 token flows that Azure AD uses always work with two important parts. A client, which is the app we are using or impersonating, and a resource that we are requesting access to. In many cases, the client will be the Azure AD PowerShell module, the Azure CLI, or a client such as Teams when dealing with Microsoft 365 services. The resource is where the data is stored that we want to access. For internal Azure AD operations, this will be the Azure AD Graph or the Microsoft Graph. Clients are identified by a GUID, and resources by a GUID or a URL, but in roadtx you can also use one of the built-in aliases that will automatically translate to the right GUID/URL. You can list them with roadtx listaliases. These aliases work in any command requiring a client or resource parameter.

The gettokens or auth module can be used to request access tokens and/or refresh tokens for various services. It uses the authentication options offered by roadlib, so while it is flexible it is not designed to work seamlessly with .prt files from disk or device credentials.

You will likely use this as initial authentication method before calling the other roadtx functions, and it is a useful tool to work with refresh tokens. See the ROADrecon documentation for examples of what you can use in this module.

Examples:

Request tokens for AAD Graph with a username and password

roadtx gettokens -u [email protected] -p mypassword -r aadgraph

Use a refresh token to request a token for the Microsoft Graph

roadtx gettokens --refresh-token <token> -r msgraph

Authentication with refresh tokens

When using a refresh token to authenticate, you should ensure that the client ID used to refresh the token is identical to the client the token was issued to, or the request will fail. An exception to this is when you are using a FOCI client, which support refreshing tokens with different client IDs to obtain different access scopes. A list of client IDs and their scopes can be found here. Example of authentication using one client and refreshing using a different client:

roadtx gettokens -u [email protected] -p mypassword -c azcli
roadtx gettokens --refresh-token file -c msteams

Devices

roadtx can register a device in Azure AD, either as a registered or joined device. Devices are represented by their device certificate and a private key. By default, these will be stored in devicename.pem and devicename.key respectively, though you can also store them in pfx format to use them with other tools.

Registering a device can be done with an access token to the device registration service. You can obtain such a token via one of the methods implemented in roadtx, via the gettokens command, using the devicereg resource alias with -r devicereg. See authentication for details. Registering a device is done with the roadtx device command. This reads the access token from the .roadtools_auth file and submits the request with a randomized name. For customization options, see roadtx device -h.