To render a page protected by forms authentication, authenticate through the application’s normal login flow first, then give wkhtmltopdf the valid cookie state. wkhtmltopdf renders URLs; its --username and --password options are for HTTP Authentication, not for submitting an HTML login form. The right cookie names, redirects, and required session state depend on the application, so validate the complete flow with the exact wkhtmltopdf binary you deploy.
How forms authentication works with wkhtmltopdf
In a typical ASP.NET forms-authentication flow, a request for a protected resource is redirected to a login page. The user submits credentials through an HTML form; the application responds with an authentication cookie, often alongside redirects. A later request carrying the valid cookie can reach the protected resource. Microsoft’s legacy ASP.NET Web API documentation, last updated November 4, 2022, describes this pattern and notes that forms authentication uses an HTML form to send credentials to the server.
wkhtmltopdf is not a browser-driven login agent. It does not independently navigate an arbitrary site’s interactive login workflow, discover hidden form fields, or complete JavaScript-dependent sign-in. Instead, establish the session through the application’s normal authentication process, then provide the resulting cookie or cookie state when wkhtmltopdf requests the protected URL.
This guidance is about cookie-based forms authentication. HTTP Basic or Digest authentication is a different mechanism: the server challenges an HTTP request, and wkhtmltopdf’s --username and --password options are documented for HTTP Authentication. They do not turn an HTML login form into an authenticated session.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Choose how to provide the authenticated cookies
The wkhtmltopdf command-line interface documents two cookie mechanisms. Neither is universally preferable: use the one that fits how your application creates and updates session state, and test the behavior of your installed binary.
| Method | What it does | Good fit | Operational trade-off |
|---|---|---|---|
--cookie name value |
Adds a cookie to the request; the option can be repeated for multiple cookies. | A small, known set of valid cookies that you can obtain securely before conversion. | Inputs are explicit in the invocation, which makes them easy to inspect but can expose secrets through logs or process inspection. URL-encode cookie values supplied this way. |
--cookie-jar path |
Reads and writes cookies using the supplied jar path. | A flow in which a preceding request or the conversion process needs to preserve cookie state across requests. | The jar becomes a credential-bearing file: control its permissions, lifetime, location, and cleanup. Confirm the exact load/write behavior and access permissions for your installed binary. |
The CLI documents the cookie options, and wkhtmltopdf’s generated library settings also expose a cookie-jar path as a load setting. Documentation establishes that the options exist, not that every build handles every redirect or secondary resource identically.
Pass cookies directly on the command line
After authenticating outside the conversion step, pass the minimum cookie set that the target application requires. This illustrative ASP.NET example uses names often seen in such deployments; neither name is guaranteed for every site.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
wkhtmltopdf
--cookie ASP.NET_SessionId '<session-value>'
--cookie .ASPXFORMSAUTH '<auth-value>'
'https://example.invalid/protected/report' output.pdfReplace the example URL and values with those from your own authenticated application. Cookie values supplied to --cookie should be URL encoded. Do not paste live cookies into shared documentation, tickets, shell history, or logs. Be especially cautious with shell commands on multi-user systems, where command arguments may be visible to other processes or administrators.
The exact cookie set is application-specific. A site may require a session cookie, an authentication cookie, or additional state. Cookies are scoped by properties such as domain and path and have expiry rules; a cookie that is valid for one host or path may not authorize the URL being rendered. Historical community advice for ASP.NET deployments mentions forwarding the current user’s authentication cookies and sometimes both .ASPXFORMSAUTH and ASP.NET_SessionId, but that is not a universal recipe. Start with the smallest set that works.
Use a cookie jar when state needs to persist
A cookie jar is useful when cookie state is created or updated during a preceding request and later requests need that state. The CLI documents --cookie-jar <path> as a read/write jar. The precise behavior can vary with the installed binary and the application’s flow, so verify that the jar contains the expected cookies and that the conversion process can read and write it.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
wkhtmltopdf
--cookie-jar /secure/path/session-cookies.txt
'https://example.invalid/protected/report' output.pdfThis command shows the option’s shape; it does not log a user in or guarantee that the jar is populated. Arrange for the authenticated cookie state to reach the jar through a process suitable for your application, protect the file as a credential, and remove it when it is no longer needed. Use restrictive file permissions and a private temporary directory rather than a shared or web-accessible location.
Why the login page may appear in the PDF
If the output is a login screen instead of the protected document, wkhtmltopdf may have received a redirect because the application did not accept the supplied session. Treat the following as a diagnostic sequence rather than a universal fault tree:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →- Confirm the cookie values. Obtain fresh values from the application’s normal login flow. Check for truncation, accidental quoting, or failure to URL-encode values passed through
--cookie. - Check scope and expiry. Verify the cookie’s domain and path cover the target URL and that it has not expired or been invalidated by logout, rotation, or a new login.
- Check whether more than one cookie is required. The authentication cookie may not be sufficient without a session cookie or other application-specific state. Add only cookies the real application requires.
- Follow the redirect behavior. The login flow may redirect through several endpoints, and the final protected resource may require a cookie set during one of those responses. Confirm that the state you pass corresponds to the final host and request.
- Inspect dependent resources. A page can render its main document while images, stylesheets, or other resources fail because their requests also require authentication or use different scope. Verify the resulting PDF includes the resources your use case needs.
- Check the exact deployed executable. Run the test with the same wkhtmltopdf binary, runtime environment, permissions, and URL used in production; success on a developer workstation does not establish success for a server deployment.
Headers and footers may be fetched from separate URLs. A historical GitHub issue reported duplicated cookies for headers or footers in version 0.12.1.0 and listed milestone 0.12.5 as fixed. This is version-specific historical evidence, not proof of a current universal defect or guarantee. If only a header or footer is unauthenticated, test those URLs and the installed version separately.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Why username and password flags do not log in to a form
--username and --password are described for HTTP Authentication. They do not submit arbitrary login forms, maintain an application’s forms-authentication session, or satisfy every login page’s workflow. For forms authentication, obtain a valid cookie through the application’s ordinary login process and supply that cookie state.
wkhtmltopdf also has --post <name> <value> and --post-file. Their existence does not mean a login form can be replayed reliably with a simple POST. A real login may require an anti-CSRF token, hidden fields, redirects, JavaScript, or other application-specific steps. Use the application’s normal authentication mechanism rather than assuming a form submission can be reduced to a fixed set of command-line values.
Security: treat cookies as passwords
An authentication cookie can grant access to protected data, so handle it as a credential. Keep it out of source control, shared logs, tickets, and shared temporary files. Restrict access to cookie jars, use short lifetimes where practical, and remove stored state when the conversion job is finished. Avoid placing secrets in command arguments when your environment exposes process listings; use a protected cookie-jar workflow if it better fits your operational controls.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Microsoft’s forms-authentication guidance states that forms authentication does not encrypt user credentials and is not secure unless used with SSL. Use HTTPS for the login and authenticated resource flow. The same guidance identifies cross-site request forgery (CSRF) exposure and the need for anti-CSRF measures; cookie forwarding for a server-side conversion should not be mistaken for a replacement for the application’s own security controls.
wkhtmltopdf’s project downloads page warns against using the tool with untrusted HTML, advising sanitization of user-supplied HTML and JavaScript because malicious input can compromise the server running the renderer. Treat any user-controlled page or HTML input as a security boundary, especially when the process has access to privileged network resources or credentials.
Validate the exact environment before relying on it
- Record the wkhtmltopdf version and binary path used by the job. The project downloads page lists stable series 0.12.6, released June 11, 2020; that release listing is version context, not evidence by itself of current active maintenance.
- Authenticate against the actual application and obtain fresh cookie state using its normal login flow.
- Run the conversion under the same user account, host, network path, and runtime environment as the production job.
- Check the final PDF for protected text and any required images, styling, headers, and footers.
- Test behavior after cookie expiry or session invalidation so the job can detect an unexpected login page rather than silently treating it as a successful report.
- Confirm cookie-jar storage permissions, retention, cleanup, and log redaction.
- Repeat the check when the application’s authentication flow, domain, or deployed wkhtmltopdf binary changes.
Or skip the browser setup
If your goal is to capture a page rather than specifically generate a PDF with wkhtmltopdf, ScreenshotNeo is a screenshot API and MCP server for developers. It can accept cookies, headers, or Authorization settings, but the call below is a simple URL capture and does not itself log in to a protected application. For authenticated pages, provide appropriate authentication through the service’s supported request options and test against your application; do not send credentials you are not authorized to use.
One-call cURL example (replace the target URL as needed; find setup and options in the ScreenshotNeo documentation):
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minutecurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can wkhtmltopdf reuse a cookie from my browser?
Yes, if you securely obtain the valid cookie state and provide it in a supported form. Make sure it is fresh and scoped to the protected URL.
Will passing the authentication cookie always make the PDF work?
No. Applications can require additional session state, redirects, or authentication for dependent resources. Verify the PDF with the actual application and deployed binary.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
