Migrating from the Legacy Web Client API

The legacy Web Client API — passing launch data and credentials through a JavaScript payload URL (?appinfo=https://.../appinfo.js) consumed by _RASWebClientLoadApp / _RASHTML5LoadApp is deprecated. It has been replaced by the Authentication Handoff API, which is more secure: credentials and launch data are submitted in a POST body directly to the RAS Secure Gateway instead of being exposed through a URL and a publicly fetchable JavaScript payload.

Attention: The legacy API is disabled by default starting with Parallels RAS 21.2. When you upgrade to 21.2 or later, integrations that still use the appinfo mechanism will stop working until they are migrated.

Re-enabling the legacy API is possible but strongly discouraged and should only ever be used as a temporary measure while you complete the migration. For instructions on re-enabling the deprecated API and updating your code, see this KB article.

What changes for your integration

• GET becomes POST. Stop passing launch data through a JS payload URL. Submit the payload to POST https://<user-portal-domain>/userportal/auth-handoff instead.

• No hosted payload file. You no longer host or dynamically generate an appinfo.js file. The payload is the POST body.

• No JavaScript function call. _RASWebClientLoadApp and _RASHTML5LoadApp are not used.

• Redirect-based result. The Gateway responds with a 3xx redirect (typically 302) which the browser follows to the User Portal.

• No token handling. Token creation, validation, and session handling are managed by the User Portal Gateway. Your integration never inspects JWT contents.

Parameter mapping

Legacy	New	Notes
?appinfo=https://.../appinfo.js	POST /auth-handoff	Stop passing launch data through a JS URL.
u	username	Username field renamed for clarity.
q	password	Password.
a	appid	Published resource ID. Optional.
logonURL	login	URL to redirect to the IDP login page on User Portal refresh. Optional.
logoutURL	logout	URL to redirect to the IDP logout page upon User Portal logout. Optional.
theme (URL parameter)	theme	Now part of the POST payload.
p	p	Additional launch parameters string. Unchanged.
extra	extra	Per-session redirection settings. Unchanged.

Migration steps

1. Replace the code that generates the appinfo.js payload and opens the Web Client URL with a single POST of the JSON payload to /auth-handoff (see Authentication Handoff API and Example).

2. Rename the payload fields according to the mapping table above.

3. If your frontend does not hold the user's credentials, initiate the POST from your backend and relay the redirect to the browser (see Backend-Initiated Handoff).

4. Remove the hosted payload endpoint from your web server once the migration is verified.

5. Test against a Parallels RAS environment running 21.2 or later with the legacy API in its default (disabled) state.

Timeline

Parallels RAS version	Legacy Web Client API status
Up to 21.1	Available (deprecated). Migrate now.
21.2 or later	Disabled by default. Can be temporarily re-enabled (not recommended). See this KB article.