Skip to content

ROADtools Token eXchange (roadtx)

Jump to bottom
Dirk-jan edited this page Nov 8, 2022 · 26 revisions

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 <token> -c msteams

In the above example you can also use the word file as argument to --refresh-token, which will make it read the refresh token from the .roadtools_auth file where the first command saved it.

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 change the file names with the command line parameters.

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.

roadtx device -n blogdevice
Saving private key to blogdevice.key
Registering device
Device ID: 5f138d8b-6416-448d-89ef-9b279c419943
Saved device certificate to blogdevice.pem

Primary Refresh Tokens (PRTs)

Requesting PRTs

With a device identity and user credentials it is possible to request a Primary Refresh Token. There are currently 2 ways of requesting a PRT:

  • Via username + password
  • Via a refresh token specifically requested for this purpose (see Enriching a PRT below)
roadtx prt -u [email protected] -p password --key-pem blogdevice.key --cert-pem blogdevice.pem

Primary Refresh tokens and their session key are saved in a .prt file by default (named roadtx.prt). You can choose a different name with the --prt-file or the shorter -f parameter. Most commands that accept a PRT also accept one that is specified via the command line with the --prt and --prt-sessionkey parameters.

Renewing

You can renew a PRT with the -a renew action. This will extend the validity of the PRT with 90 days from the renew date.

roadtx prt -a renew
Renewing PRT
Saved PRT to roadtx.prt

Using Primary Refresh Tokens

You can use PRTs in multiple ways with roadtx:

  • Use them directly similar to how Windows deals with PRTs with roadtx prtauth
  • Use them interactively with a Selenium based browser window with roadtx browserprtauth
  • Use them via in Chrome on Windows via a BrowserCore replacement
  • Use them in an emulated SSO flow with roadtx gettokens

If you are just looking to use default Microsoft client IDs to get tokens for various resources, the roadtx prtauth method is the easiest. This emulates the Web Account Manager (WAM). It will automatically load the PRT from disk from roadtx.prt, from the PRT file you specify with -f or it will use a manual PRT and session key specified with --prt and --prt-sessionkey. Similar to the gettokens command, this command accepts custom clients, resources and redirect URLS.

usage: roadtx prtauth [-h] [-c CLIENT] [-r RESOURCE] [-ru URL] [-f FILE] [--prt PRT] [--prt-sessionkey PRT_SESSIONKEY] [--tokenfile TOKENFILE] [--tokens-stdout]

optional arguments:
  -h, --help            show this help message and exit
  -c CLIENT, --client CLIENT
                        Client ID to use when authenticating.
  -r RESOURCE, --resource RESOURCE
                        Resource to authenticate to. Either a full URL or alias (list with roadtx listaliases)
  -ru URL, --redirect-url URL
                        Custom redirect URL used when authenticating (default: ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientid>)
  -f FILE, --prt-file FILE
                        PRT storage file (default: roadtx.prt)
  --prt PRT             Primary Refresh Token
  --prt-sessionkey PRT_SESSIONKEY
                        Primary Refresh Token session key (as hex key)
  --tokenfile TOKENFILE
                        File to store the credentials (default: .roadtools_auth)
  --tokens-stdout       Do not store tokens on disk, pipe to stdout instead

Examples:

Request access/refresh tokens to Azure AD graph with Azure AD PowerShell client ID (default client and resource)

roadtx prtauth

Use the Azure CLI client ID and request access to Azure Resource manager (the resulting refresh token can be used with AzureHound).

roadtx prtauth -c azcli -r azrm

Use the Microsoft Teams client ID, request tokens for Microsoft Graph

raodtx prtauth -c msteams -r msgraph
Clone this wiki locally