Automated Qualtrics Login

Overview

The **Automated Qualtrics Login** module is designed to securely and reliably automate the login process to the Qualtrics survey platform using institutional credentials. This includes handling multi-step authentication procedures such as two-factor authentication (2FA) and browser trust prompts. The automation mimics human-like interactions to minimize detection and ensure smooth login flow. This module is critical because Qualtrics restricts API access to authenticated users, so establishing a valid session programmatically is a prerequisite for all subsequent collaboration management actions.

Core Concepts and Purpose

Secure Access Automation: Automate the entire login sequence to Qualtrics with NYU institutional credentials without manual input beyond initial username and password entry.
Human Interaction Simulation: Introduce realistic delays and typing patterns when interacting with login form fields to simulate genuine user behavior.
Two-Factor Authentication Handling: Account for 2FA prompts and browser trust dialogs that typically interrupt automated login attempts.
Session Transfer: Extract authenticated cookies from the automated browser session and transfer them into a backend HTTP session for API communication.

This module solves the problem of programmatically authenticating to a web platform that uses complex web-based authentication flows, including multi-factor authentication and browser trust confirmations, which cannot be handled by simple HTTP requests alone.

How the Module Works

1. Selenium Browser Automation

The module uses Selenium WebDriver to programmatically control a Chrome browser instance:

Browser Setup: The browser is launched in headless mode with a custom user-agent string to resemble a real user environment.
Navigation: The browser navigates to the Qualtrics login page (https://nyu.qualtrics.com/ControlPanel/).
Credential Entry: The username and password fields are located and filled in by simulating human typing (_human_type method).
Login Submission: The login button is programmatically clicked to submit credentials.

2. Human Interaction Simulation

To avoid bot detection and ensure smoother automation, the module simulates human behavior through:

Typing Delays: The _human_type method sends each character one-by-one to input fields, with variable pauses between keystrokes. Pauses are longer for punctuation and spaces to mimic natural typing rhythm.

def _human_type(element: WebElement, string: str) -> None:
    for char in string:
        if char in ["!", ".", "?", ","]:
            time.sleep(random.uniform(.6, 1))
        elif char == " ":
            time.sleep(random.uniform(.14, .20))
        else:
            time.sleep(random.uniform(.1, .13))
        element.send_keys(char)

Randomized Sleep: Between key steps, the module calls human_sleep(), which uses a truncated normal distribution to generate realistic random wait times (around 2 to 6 seconds), simulating human pauses.

3. Handling Two-Factor Authentication and Trust Prompts

After submitting credentials, the login flow may require:

Two-Factor Authentication (2FA): The user manually completes 2FA on the browser. The automation detects that the login is not complete by checking if the user has reached the Qualtrics landing page.
Browser Trust Prompt: The module detects if a "trust this browser" prompt appears and clicks the corresponding button to proceed.

This is achieved by polling the browser state in a loop, using helper methods:

_at_qualtrics(driver): Detects if the browser has reached Qualtrics by finding a known footer element.
_check_for_trust_browser_page(driver): Detects presence of the trust prompt and clicks the trust button.

while not self._at_qualtrics(driver):
    if self._check_for_trust_browser_page(driver):
        trust_browser_button = driver.find_element(By.ID, 'trust-browser-button')
        trust_browser_button.click()
        self.human_sleep()

4. Session Cookie Extraction and Transfer

Once authenticated and navigated to the main Qualtrics projects page, the module extracts all session cookies from the Selenium-controlled browser and inserts them into a persistent `requests.Session` object. This session is then used for all subsequent API calls to manage survey collaborations.

cookies = driver.get_cookies()
for cookie in cookies:
    self.session.cookies.set(cookie["name"], cookie["value"])

This cookie synchronization enables authenticated HTTP requests without requiring further browser automation.

Interactions with Other Modules

Survey Collaboration Management: The authenticated session established here is leveraged by collaboration management methods such as add_collaborator() and enter_collaboration_code() to perform API calls with proper authorization.
Session and API Request Management: The cookies and headers set during login are essential for constructing valid API request headers (_generate_qualtrics_headers()), ensuring secure communication with Qualtrics services.
User Input: The login method depends on receiving user credentials securely via standard input and password prompt.

Important Concepts and Design Patterns

Human Behavior Emulation: By integrating typed delays and randomized sleeps, the module adopts a pattern of behavior emulation to reduce the chance of automated login detection or failure.
Polling with Conditional Handling: The login waits for the authenticated state by polling the browser page condition, responding dynamically to 2FA or trust prompts.
Session Bridging Pattern: The module bridges between a Selenium-driven browser session and a requests HTTP session by transferring cookies, enabling API calls without the overhead of browser automation.
Encapsulation within a Client Class: All login logic is encapsulated within the CollaborationClient class, providing a clean interface (login()) for users to authenticate before performing other operations.

Key Code Snippets

Login Sequence Initiation

def login(self) -> None:
    nyu_username: str = input('NYU username:').strip()
    nyu_password: str = getpass('NYU password:').strip()
    self._selenium_login(nyu_username, nyu_password)

Selenium Automated Login Flow

def _selenium_login(self, nyu_username: str, nyu_password: str) -> None:
    options = Options()
    options.add_argument("--headless")
    options.add_argument(f"user-agent={self.user_agent}")
    driver = webdriver.Chrome(options=options)
    driver.get(f"https://{self.subdomain}.qualtrics.com/ControlPanel/")

    username_input = WebDriverWait(driver, 20).until(EC.presence_of_element_located((By.ID, 'username')))
    self._human_type(username_input, nyu_username)

    password_input = WebDriverWait(driver, 20).until(EC.presence_of_element_located((By.ID, 'password')))
    self._human_type(password_input, nyu_password)

    login_button = WebDriverWait(driver, 20).until(EC.presence_of_element_located(
        (By.XPATH, '//button[contains(text(), "Login") and @type = "submit"]')))
    login_button.click()

    while not self._at_qualtrics(driver):
        if self._check_for_trust_browser_page(driver):
            trust_browser_button = driver.find_element(By.ID, 'trust-browser-button')
            trust_browser_button.click()
            self.human_sleep()

    driver.get(f'https://{self.subdomain}.qualtrics.com/Q/MyProjectsSection')

    cookies = driver.get_cookies()
    for cookie in cookies:
        self.session.cookies.set(cookie["name"], cookie["value"])

    driver.quit()

Mermaid Sequence Diagram: Automated Qualtrics Login Flow

sequenceDiagram
    participant User
    participant CollaborationClient
    participant SeleniumBrowser
    participant QualtricsLoginPage
    participant TwoFactorAuth
    participant QualtricsMainPage

    User->>CollaborationClient: Provide username & password
    CollaborationClient->>SeleniumBrowser: Launch headless Chrome
    SeleniumBrowser->>QualtricsLoginPage: Open login page
    CollaborationClient->>SeleniumBrowser: Type username (simulate human)
    CollaborationClient->>SeleniumBrowser: Type password (simulate human)
    CollaborationClient->>SeleniumBrowser: Click login button
    SeleniumBrowser->>TwoFactorAuth: Wait for 2FA completion
    alt Trust Browser Prompt Appears
        SeleniumBrowser->>TwoFactorAuth: Click "Trust Browser" button
    end
    SeleniumBrowser->>QualtricsMainPage: Load main projects page
    SeleniumBrowser->>CollaborationClient: Extract session cookies
    CollaborationClient->>User: Login complete, session ready

This diagram illustrates the step-by-step interaction from receiving user credentials to establishing an authenticated session ready for API use.

This documentation explains the **Automated Qualtrics Login** module's purpose, workflow, key functionalities, and integration points, supported by code references and a visual login sequence diagram.