pyrit.auth.CopilotAuthenticator

class CopilotAuthenticator(*, headless: bool = False, maximized: bool = True, timeout_for_elements_seconds: int = 10, token_capture_timeout_seconds: int = 60, network_retries: int = 3, fallback_to_plaintext: bool = False)

Bases: Authenticator

Playwright-based authenticator for Microsoft Copilot. Used by WebSocketCopilotTarget.

This authenticator automates browser login to obtain and refresh access tokens that are necessary for accessing Microsoft Copilot via WebSocket connections. It uses Playwright to simulate user interactions for authentication, and msal-extensions for encrypted token persistence.

An access token acquired by this authenticator is usually valid for about 60 minutes.

Note

To be able to use this authenticator, you must set the following environment variables:

• COPILOT_USERNAME: your Microsoft account username (email)

• COPILOT_PASSWORD: your Microsoft account password

Additionally, you need to have playwright installed and set up: pip install playwright && playwright install chromium.

__init__(*, headless: bool = False, maximized: bool = True, timeout_for_elements_seconds: int = 10, token_capture_timeout_seconds: int = 60, network_retries: int = 3, fallback_to_plaintext: bool = False)

Initialize the CopilotAuthenticator.

Parameters:

• headless (bool) – Whether to run the browser in headless mode. Default is False.

• maximized (bool) – Whether to start the browser maximized. Default is True.

• timeout_for_elements_seconds (int) – Timeout used when waiting for page elements, in seconds.

• token_capture_timeout_seconds (int) – Maximum time to wait for token capture via network monitoring.

• network_retries (int) – Number of retry attempts for network operations. Default is 3.

• fallback_to_plaintext (bool) – Whether to fallback to plaintext storage if encryption is unavailable. If set to False (default), an exception will be raised if encryption cannot be used. WARNING: Setting to True stores tokens in plaintext.

Raises:

ValueError – If the required environment variables are not set.

Methods

__init__(*[, headless, maximized, ...])	Initialize the CopilotAuthenticator.
get_claims()	Get the JWT claims from the current authentication token.
get_token()	Get the current authentication token synchronously.
get_token_async()	Get the current authentication token.
refresh_token()	Refresh the authentication token synchronously.
refresh_token_async()	Refresh the authentication token asynchronously.

Attributes

CACHE_FILE_NAME	Name of the cache file to store tokens
DEFAULT_ELEMENT_TIMEOUT_SECONDS	Default timeout for waiting on page elements (in seconds)
DEFAULT_NETWORK_RETRIES	Number of retries for network operations
DEFAULT_TOKEN_CAPTURE_TIMEOUT	Default timeout for capturing token via network monitoring (in seconds)
EXPIRY_BUFFER_SECONDS	Buffer before token expiry to avoid using tokens about to expire (in seconds)
token

CACHE_FILE_NAME: str = 'copilot_token_cache.bin'

Name of the cache file to store tokens

DEFAULT_ELEMENT_TIMEOUT_SECONDS: int = 10

Default timeout for waiting on page elements (in seconds)

DEFAULT_NETWORK_RETRIES: int = 3

Number of retries for network operations

DEFAULT_TOKEN_CAPTURE_TIMEOUT: int = 60

Default timeout for capturing token via network monitoring (in seconds)

EXPIRY_BUFFER_SECONDS: int = 300

Buffer before token expiry to avoid using tokens about to expire (in seconds)

async get_claims() → dict[str, Any]

Get the JWT claims from the current authentication token.

Returns:

The JWT claims decoded from the access token.

Return type:

dict[str, Any]

async get_token_async() → str

Get the current authentication token.

This checks the cache first and only launches the browser if no valid token is found. If multiple calls are made concurrently, they will be serialized via an asyncio lock to prevent launching multiple browser instances.

Returns:

A valid Bearer token for Microsoft Copilot.

Return type:

str

async refresh_token_async() → str

Refresh the authentication token asynchronously.

This will clear the existing token cache and fetch a new token with automated browser login.

Returns:

The refreshed authentication token.

Return type:

str

Raises:

RuntimeError – If token refresh fails.