EntraTokenAid

EntraTokenAid is a PowerShell module to simplify OAuth workflows with Microsoft Entra ID, to get the access and refresh tokens for different APIs using different clients.

Accessing cleartext access and refresh tokens for various MS APIs (e.g., MS Graph) is often a requirement during engagements and research, especially using pre-consented clients (e.g., AzureCLI) to avoid additional consent prompts. Tokens are needed not only for manual enumeration via APIs but also for tools like AzureHound or GraphRunner, which require a valid refresh token.

With more customers starting to block the Device Code Flow, alternative authentication methods for obtaining cleartext refresh tokens are becoming increasingly important. While using AzureCLI modules is a common solution, its installation may not always be feasible—especially on customer systems. Other alternatives like roadtx require Python, which might not be ideal in customer environments.

This tool bridges this gap with a lightweight, standalone PowerShell solution that works even on customers' Windows systems.

---

Features

• No dependencies: A pure PowerShell single-file module that works on Windows systems (tested in PS 5&7) and partially on Linux.
• Interactive Authentication: Supports both OAuth Auth Code Flow and Device Code Flow.
• Flexible Refresh: Obtain access tokens for any API and client using refresh tokens.
• CAE Support: By default, requests CAE (Continuous Access Evaluation) capable access tokens, valid for 24 hours.
• JWT Parsing: Automatically decodes access tokens to display details (e.g., scope, tenant, IP, authentication methods).
• Avoiding Consent: By default, the tool uses the Azure CLI client ID, enabling many MS Graph API actions without additional consent due to pre-consented permissions.
• Parameters: A wide range of parameters allow you to customize the tool's behavior, such as enabling features like PKCE, CAE, and more, providing greater control during usage.
• Automation-Friendly: Enables automated OAuth Auth Code Flow tests by disabling user selection, with the gathered tokens and claims exported to a CSV file.
• Experimental: Catching OAuth Codes on any URL: Utilizes a legacy method to launch and control a browser, allowing automatic retrieval of the authorization code and seamless token exchange (Windows only).

---

Images

Performing an authentication and showing the gathered tokens and other useful information:

Using the obtained refresh token to get new tokens on another API and using another client (Azure PowerShell):

---

Installation

1. Clone the repository:

   git clone https://github.com/zh54321/EntraTokenAid.git
   

2. Import the module before usage:

   Import-Module ./EntraTokenAid/EntraTokenAid.psm1
   

---

Getting Started

The module includes the following commands:

| Command | Description |Default behavior| |---------------------------|-----------------------------------------------------------------------|----| | Invoke-Auth | Perform authentication (auth code flow) and retrieve tokens. |API: MS Graph / Client: Azure CLI / CAE: Yes| | Invoke-DeviceCodeFlow | Authenticate via the device code flow. |API: MS Graph / Client: Azure CLI| | Invoke-ClientCredential | Authenticate using the client credential flow. |API: MS Graph| | Invoke-Refresh | Get a new access token using the refresh token. |API: MS Graph / Client: Azure CLI| | Invoke-ParseJwt | Decode a JWT and display its body properties. |-| | Show-EntraTokenAidHelp | Show Help. |-|

Quick Start

# Authenticate with default settings (MS Graph API, Azure CLI client)
$tokens = Invoke-Auth

# Get a token for Azure Resource Manager
$tokens = Invoke-Auth -Api "management.azure.com"

# Get a token with Device Code Flow (MS Graph API, Azure CLI client)
$tokens = Invoke-DeviceCodeFlow

# Refresh the token
$tokens = Invoke-Refresh -RefreshToken $tokens.refresh_token

---

Module Functions

Invoke-Auth

Performs OAuth authentication using the authorization code flow. By default, tokens from the MS Graph API are requested using Azure CLI as the client.

Parameters

All parameters are optional.

| Parameter | Description | Default Value | |----------------------|-----------------------------------------------------------------------------|---------------------------------------------------| | ClientID | Specifies the client ID for authentication. | 04b07795-8ddb-461a-bbee-02f9e1bf7b46 (Azure CLI)| | Scope | Scopes (space separated) to be requested. | .default offline_access | | Api | API for which the access token is needed (FQDN or GUID). | graph.microsoft.com | | Tenant | Specific tenant id. | organizations | | Port | Local port to listen on for the OAuth callback. | 13824 | | TokenOut | If provided, outputs the raw token to console. | false | | RedirectURL | URL for the OAuth redirect. | http://localhost:%PORT% | | DisableJwtParsing| Skips the parsing of the JWT. | false | | DisablePrompt | Suppresses interactive user selection. Uses the already logged-in user directly. | false | | HttpTimeout | Time in seconds the HTTP server waits for the OAuth callback. | 180 | | DisablePKCE | Disables the PKCE usage. | false | | DisableCAE | Disables Continuous Access Evaluation (CAE) support. | false | | Origin | Origin Header (required to Auth on a SPA). | - | | Reporting | If provided, enables detailed token logging to csv. | false | | ManualCode | Get auth URL for external login; use final URL with the code to auth | false | | SkipGen | Skip auth URL generation (use with -ManualCode) | false | | LoginHint | Pre-fill the username on the login page. | - | | UserAgent | User agent used (token endpoint) (impacts only non-interactive sign-ins) | python-requests/2.32.3 |

Authentication Examples

Perform authentication and retrieve tokens with default options (MS Graph API / Azure CLI as the client):

$Tokens = Invoke-Auth

Authenticate on Azure ARM API:

$Tokens = Invoke-Auth -API "management.azure.com"

Authenticate with a custom client ID and scope:

$Tokens = Invoke-Auth -ClientID "your-client-id" -Scope "offline_access Mail.Read"

Bypass the Conditional Access Policy which require a compliant device:

$Tokens = Invoke-Auth -ClientID '9ba1a5c7-f17a-4de9-a1f1-6178c8d51223' -RedirectUrl 'urn:ietf:wg:oauth:2.0:oob'

Get tokens for main.iam.ad.ext.azure.com:

$Tokens = Invoke-Auth -Api '74658136-14ec-4630-ad9b-26e160ff0fc6'

Perform automated testing by disabling user selection (the already logged-in user in the browser will be used), activating reporting, setting the HTTP timeout, and looping through a list of client IDs:

# Define the array of GUIDs
$guids = @(
    "1950a258-227b-4e31-a9cf-717495945fc2",
    "7ae974c5-1af7-4923-af3a-fb1fd14dcb7e",
    "5572c4c0-d078-44ce-b81c-6cbf8d3ed39e"
)

# Loop through each GUID in the array
foreach ($guid in $guids) {
    Invoke-Auth -ClientID $guid -DisablePrompt -Reporting -HttpTimeout 5
}

Usage with 3rd-Party Tooling

Connect to Microsoft Graph API using the official PowerShell modules:

$Tokens = Invoke-Auth
Connect-MgGraph -AccessToken ($Tokens.access_token | ConvertTo-SecureString -AsPlainText -Force)

Authenticate and use with AzureHound:

$Tokens = Invoke-Auth
.\azurehound.exe --refresh-token $Tokens.refresh_token list --tenant $Tokens.tenant -o output-all.json

Authenticate and use with GraphRunner:

$tokens = Invoke-Auth
Invoke-GraphRecon -Tokens $tokens -PermissionEnum

---

Invoke-DeviceCodeFlow

Authenticate using the device code flow. The browser opens automatically, and the required code is copied to the clipboard.

Parameters

All parameters are optional. | Parameter | Description | Default Value