> For the complete documentation index, see [llms.txt](https://docs.pd4ml.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pd4ml.com/features/http-authentication-and-session-propagation.md).

# HTTP Authentication and Session Propagation

When the HTML PD4ML is converting references resources that require authentication or live session state -- a protected image, a session-scoped fragment rendered only for a logged-in user -- PD4ML needs to be told how to reach them the same way the original browser request would have. This page covers the three distinct mechanisms PD4ML provides for that: reusing the current web application's own request/response, explicit HTTP basic authentication, and session-ID propagation, in both its URL-rewriting and cookie-based forms.

{% hint style="info" %}
This page was checked directly against the current `com.pd4ml.PD4ML` source rather than transcribed from older documentation as-is. Two corrections came out of that: `setSessionID(...)` -- covered below -- turns out to be a dedicated, purpose-built method that has existed since v3.0.0.b1, but was never mentioned on the original version of this page at all; and basic HTTP authentication has a current, direct API (`setHttpOptions(...)`) that supersedes the dynamic-parameter technique shown previously.
{% endhint %}

## Reusing the current web application's request/response

When PD4ML is converting a page that's part of the same running web application -- rather than an arbitrary external URL -- handing it the live servlet request and response lets it resolve dynamic, session-dependent resources exactly as that request would, without needing to reconstruct or propagate any authentication state explicitly:

```java
public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
    PD4ML pd4ml = new PD4ML();
    pd4ml.useHttpRequest(request, response);
    // ... configure the conversion as needed ...
    pd4ml.readHTML(new URL(sourceUrl));
    pd4ml.writePDF(response.getOutputStream());
}
```

`useHttpRequest(...)` takes its two arguments as plain `Object`, accepting either a classic `javax.servlet.http.HttpServletRequest`/`HttpServletResponse` pair or a Jakarta EE 9+ `jakarta.servlet.http.*` pair -- the same javax/jakarta duality already covered for the JSP taglib itself in the Programmer's Manual's [§13](/pd4ml-manual.md), so the same conversion code works unmodified against either servlet API generation.

## Basic HTTP authentication

For a source that sits behind HTTP basic authentication rather than being part of the same application, `setHttpOptions(proxy, basicAuthentication)` supplies the credentials as a plain `"login:password"` string -- and, in the same call, an optional proxy in `"host:port"` form, passing `null` for whichever of the two isn't needed:

{% tabs %}
{% tab title="v4" %}

```java
pd4ml.setHttpOptions(null, "mylogin:mypassword");
```

{% endtab %}

{% tab title="v3" %}

```java
Map m = new HashMap();
m.put(PD4Constants.PD4ML_BASIC_AUTHENTICATION, "mylogin:mypassword");
pd4ml.setDynamicParams(m);
```

{% endtab %}
{% endtabs %}

Because `setHttpOptions(...)` covers proxy configuration too, it's a more direct alternative to the dynamic-parameter approach shown on the [Configuring an HTTP Proxy](/features/configuring-an-http-proxy.md) page for that use case as well -- worth revisiting if a codebase is still using `PD4ML_HTTP_PROXY` via `setParam(...)`/`setDynamicParams(...)`.

## Session ID propagation

PD4ML supports two different ways of carrying a session identifier through to the resources it fetches, and which one applies depends on how the target application tracks sessions in the first place.

### URL-rewriting style: `setSessionID(...)`

For an application that propagates its session via URL rewriting rather than cookies, `setSessionID(...)` tells PD4ML the current session ID once, and PD4ML appends it as a matrix parameter to every resource reference (image, stylesheet, ...) it requests from that point on -- in the form `resource.jpg;jsessionid=<sessionID>?other_args`. It must be called before `readHTML(...)`; calling it afterward throws `InvokeException`.

```java
pd4ml.setSessionID(sessionID);
```

The reserved variable name `jsessionid` can be overridden -- for a session-tracking scheme that expects a different parameter name -- via the `PD4ML_SESSIONID_VARNAME` dynamic parameter:

```java
pd4ml.setParam(Constants.PD4ML_SESSIONID_VARNAME, "customsessionidname");
pd4ml.setSessionID(sessionID);
```

### Cookie-based session propagation (any platform)

When the target application instead tracks its session via an ordinary cookie -- as most non-Java stacks do, and as Java web applications configured for cookie-based sessions also do -- `setCookie(name, value)` attaches that cookie to every outbound resource request PD4ML makes. The method's `value` parameter is the cookie's value alone; there's no need to append a `path=` attribute or otherwise construct a raw `Set-Cookie`-style string, as older examples of this technique sometimes showed:

```java
pd4ml.setCookie("JSESSIONID", sessionID);
```

The same call, with the platform's own session cookie name, is exactly how the same technique carries over outside Java -- PHP's default session cookie, for instance:

```java
pd4ml.setCookie("PHPSESSID", sessionID);
```

## See also

* [Configuring an HTTP Proxy](/features/configuring-an-http-proxy.md) -- worth a look alongside `setHttpOptions(...)`'s proxy argument above.
* [PD4ML Programmer's Manual](/pd4ml-manual.md) -- §13 covers the same javax/jakarta servlet-API duality for the JSP taglib that `useHttpRequest(...)` supports directly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pd4ml.com/features/http-authentication-and-session-propagation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.