IronPdfEngine Security Settings

Curtis Chau
Curtis Chau
Updated: November 5, 2026

IronPDF 2026.11.1 adds optional security settings to IronPdfEngine: an access token, a working listen-address setting, and a switch that limits which file paths a request can ask the engine to open. All are off or unchanged by default, but once one is turned on, a client or start-up command that does not match it is rejected. Send the token from the client, pass settings in the supported format, and send HTML content instead of file paths.

Each setting introduces its own failure mode. Understanding what controls each one tells you which fix to apply:

  • IRONPDF_ENGINE_AUTH_TOKEN (default: not set): once set, every call must send the header authorization: Bearer <token>, and health checks stay open. The token is accepted only as an environment variable, so it does not appear on the command line or in the engine's logs.
  • allow_local_file_access / IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS (default true): when false, a request that asks the engine to render an HTML file by path or a file: URL is refused, and local custom CSS URLs and font file paths are ignored. The setting applies to file paths and URLs that a request passes to the engine as parameters. It does not filter the content of the HTML you send: resources that the HTML references are loaded by the browser engine as usual.
  • host / IRONPDF_ENGINE_HOST (default 0.0.0.0): before 2026.11.1 this setting was ignored, and it is now applied. Inside a container, localhost or 127.0.0.1 makes the engine unreachable from outside the container.
Warning: Render only HTML from sources you trust, and keep the engine reachable only by your application, behind a private network and an access token.

Solution

RPC error Unauthenticated

IronPdfEngine requires an authentication token. The same message appears whether the token is missing or wrong. In .NET it is thrown from Installation.ConnectToIronPdfHost, before any render.

Recommended: Send the same token the engine was started with.

var config = IronPdfConnectionConfiguration.Docker;
config.Metadata.Add("Authorization", "Bearer a-long-random-secret");
Installation.ConnectToIronPdfHost(config);
C#

For other clients, add the gRPC metadata header authorization with the value Bearer <token>.

Check that the token values match exactly. Leading and trailing spaces are ignored on both sides; anything else must be identical.

Engine stops at start-up with exit code 2

If the log shows the line below, remove auth_token= from the command and set the environment variable instead:

ERROR: auth_token cannot be given on the command line. Set the IRONPDF_ENGINE_AUTH_TOKEN environment variable instead.
Text
docker run -d -p 127.0.0.1:33350:33350 \
   -e IRONPDF_ENGINE_AUTH_TOKEN=a-long-random-secret \
   ironsoftwareofficial/ironpdfengine:<version>
SHELL

A different pair of errors points at the local file access value:

ERROR: IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS='<value>' is not a valid value. Use true or false.
ERROR: allow_local_file_access='<value>' is not a valid value. Use true or false.
Text

The first line comes from the environment variable, the second from the command line. Accepted values are true/false, 1/0, yes/no and on/off, in any letter case.

Warning that the host could not be resolved

When the log shows the lines below, set host to localhost, an IP address of the machine, or a resolvable host name. Until you fix it, the engine listens on every interface.

WARNING: host '<value>' could not be resolved (Name or service not known).
WARNING: host '<value>' is not 0.0.0.0, localhost, an IP address or a resolvable host name; listening on every interface. In Docker, keep 0.0.0.0 inside the container and limit access when you publish the port (-p 127.0.0.1:33350:33350).
Text

Render error mentioning allow_local_file_access=false

Rendering an HTML file by path is disabled on this IronPdfEngine (allow_local_file_access=false).
Send the HTML content instead, or use RenderZipFileAsPdf.
Rendering a file: URI or local path is disabled on this IronPdfEngine (allow_local_file_access=false).
Render an http or https URL, or send the HTML content instead.
Text

Send the HTML as a string, render a ZIP with RenderZipFileAsPdf, or render an http(s) URL. The .NET client already sends the HTML content for RenderHtmlFileAsPdf, so that call keeps working. IronPDF for Java's renderHtmlFileAsPdf sends a path, so read the file and render the HTML string instead.

If your clients need to render files by path or file: URL on the engine host, set the variable back to true:

-e IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS=true
SHELL

CSS or fonts missing, or the default font used, with local file access off

This is by design: local custom CSS URLs and font paths are ignored, and the default font is used instead. Serve the assets over http(s), or embed them in the HTML as inline CSS, data URIs, or a ZIP.

Keep the engine private

Publish the port on one address (-p 127.0.0.1:33350:33350) or keep it on a private Docker network, and never expose it to the internet. Turn on the token wherever more than one app or person can reach the engine. Connections are plain gRPC, so put a private network or a TLS-terminating proxy in front of it.

References

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

Read More

Ready to Get Started?

NuGet Downloads 22,198,312Version:2026.11just released