Skip to content

Credentials Provider Alpha#

The Credentials Provider is an HTTPS service, run by your organization, that gives Jump Desktop the host's sign-in credentials when a user opens a Fluid launch link. Users connect and sign in without seeing or typing the host's account password, and each link is good for one launch. Use it when a portal or connection broker that you operate decides which host and host account a user gets, for example to hand out pooled lab or kiosk workstations, or to launch sessions from an internal self-service portal.

Alpha

The Credentials Provider is in alpha and is available only in Jump Desktop 10.16 or later. Test it in your environment before relying on it. Earlier versions of Jump Desktop ignore the credentials provider parameters in a launch link.

Applies to#

  • Team administrators and developers who build the portal and the credentials provider. End users only open the link.
  • Jump Desktop 10.16 or later on Windows, macOS, iPhone, or iPad.
  • Fluid connections only. Jump Desktop refuses RDP and VNC links that contain credentials provider parameters.
  • Hosts running Jump Desktop Connect on Windows, macOS, or Linux Alpha. The host needs no additional configuration: Jump Desktop signs in with the returned credentials as it does with any username and password.
  • Not supported: Jump Desktop for Android and the web browser client do not open credentials provider links, and Jump CLI rejects them with an error.

Connection flow#

Credentials Provider connection flow The user signs in to the portal. The portal gets a single-use token from the credentials provider and opens or shows a jump:// link with credhost and credtoken. Jump Desktop sends POST https://<credhost>/jump/credentials with the bearer token, receives the username and password, then connects to the host and signs in. Reconnects in the same session reuse the in-memory credentials without contacting the provider. User Portal Credentials Provider Jump Desktop (user's device) Host (Jump Desktop Connect) 1. Sign in to the portal 2. Request a token for this user, host, and account Single-use token 3. Open or show jump:// link with credhost and credtoken 4. POST https://<credhost>/jump/credentials Authorization: Bearer <token> 5. 200 OK {"username", "password"} Connect and sign in Reconnects in the same session reuse the in-memory credentials. The provider is not contacted again.
Connection flow with a credentials provider
  1. Your portal authenticates the user and decides which host and which host account the user gets.
  2. Your credentials provider issues a short-lived, single-use token bound to that user, host, and account.
  3. Your portal delivers a Fluid launch link to the user's device: it either opens the link automatically, or shows it, for example on a portal page, for the user to click. The link carries the provider's hostname in credhost and the token in credtoken. A clicked link and a link the portal opens behave the same way: either one opens Jump Desktop and starts the flow. On Windows, Jump Desktop must have been started once to register the link handler. A browser may ask the user to confirm before it opens Jump Desktop.
  4. Jump Desktop sends the token to https://<credhost>/jump/credentials, before it connects to the host.
  5. The provider returns the username and password. Jump Desktop connects to the host and signs in with them.

Jump Desktop contacts the credentials provider once per launch, on the first connection. It keeps the returned username and password in memory only, for that launch; nothing is written to disk. Later connections in the same session (automatic reconnects, reconnects after a network change, and manual reconnects) reuse those credentials and never contact the provider again. To connect again after the session window closes, the user needs a new link with a new token.

Jump Desktop does not send the user's identity or the target host to the credentials provider; the token is the only value that identifies the request. Your provider must therefore bind each token to the intended user, host, and credentials when it issues the token.

Start from a Fluid launch link for the host, then append the two credentials provider parameters:

The resulting link has this form:

jump://?protocol=fluid&NeuronId=<computer-id>&DisplayName=<name>&OSTypeCode=<code>&credhost=<provider-hostname>&credtoken=<token>
Parameter Rules
credhost The provider's DNS hostname only, such as provider.example.com. No scheme, port, path, or IP address. It must contain at least one dot and be at most 253 characters. Each label is 1–63 letters, digits, or hyphens, and does not start or end with a hyphen. The last label starts with a letter. A trailing dot is not allowed. Write internationalized names in their ASCII (punycode) form.
credtoken 1–1,024 characters from A–Z, a–z, 0–9, -, ., _, ~, +, and /, optionally followed by = padding characters at the end. The token cannot start with =. Base64url without padding works well.

Jump Desktop rejects the whole link, and shows Incorrect URL on Windows and macOS, when any of the following is true:

  • The link contains credhost or credtoken more than once, or only one of them. Parameter names are matched case-insensitively for this check.
  • The link also contains a username, password, or domain parameter (even an empty one), or a username or password before the host name.
  • The link is not a Fluid link.
  • credhost or credtoken breaks the rules in the table.

Percent-encode every value with a URL library rather than by joining strings, so that +, /, and = in the token survive. For example, in Python:

from urllib.parse import urlencode

def provider_link(connect_url: str, provider_host: str, token: str) -> str:
    return connect_url + "&" + urlencode({"credhost": provider_host, "credtoken": token})

Do not start from the askScreenShare URL: credentials provider sessions always sign in with the returned credentials and never ask the person at the host for approval.

Treat the link as a secret

Anyone who opens the link before it is used can redeem the token. Deliver the link only to the authenticated user, give the token a short lifetime, and do not log links. Never put the host's password in the link.

Implement the provider endpoint#

The credentials provider can run on any platform and be written in any language. It needs one HTTPS endpoint at a fixed location: port 443, path /jump/credentials. The port and path cannot be changed.

Request#

Jump Desktop sends a POST request with an empty body:

POST /jump/credentials HTTP/1.1
Host: provider.example.com
Authorization: Bearer <token>
Accept: application/json
Content-Length: 0

The request has no query string, no JSON body, no cookies, and no client certificate, and Jump Desktop does not answer HTTP authentication challenges. The bearer token is the only authentication. Do not require anything else.

Success response#

Return HTTP 200 with Content-Type: application/json (a charset parameter is allowed) and a JSON object:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store

{"username": "EXAMPLE\\jdoe", "password": "<password>"}
Field Value
username Required. A non-empty string with the host account's user name: jdoe, DOMAIN\jdoe (written DOMAIN\\jdoe in JSON), or jdoe@example.com. No control characters.
password Required. A non-empty string with the host account's password, as is. Do not URL-encode or Base64-encode it.

Each field is at most 1,024 bytes in UTF-8 and cannot contain a NUL character. Jump Desktop ignores other fields. The response headers and the response body are each limited to 16,384 bytes. Do not compress the response. Jump Desktop treats any other 2xx status, another content type, invalid JSON, or a missing or empty field as a failure. Cache-Control: no-store is recommended on every response.

Error responses#

To refuse a request, return any 4xx status with Content-Type: application/json and one of these error codes. Jump Desktop reads the code, not the status; the statuses shown are suggestions.

Suggested status Body Use when User sees
410 Gone {"error": "expired"} The token's lifetime has ended. This connection link has expired or was already used. Request a new link and try again.
409 Conflict {"error": "already_used"} The token was already redeemed. This connection link has expired or was already used. Request a new link and try again.
404 Not Found {"error": "not_found"} The token is unknown. This connection link has expired or was already used. Request a new link and try again.
403 Forbidden {"error": "denied"} Your policy denies the request. The credential provider did not allow access to this computer.

Error codes are case-sensitive. Any other failure, including an unknown error code, a 4xx response without a JSON body, a 5xx status, a redirect, a TLS error, or a timeout, shows Unable to retrieve credentials from the credential provider. Each message appears in a dialog titled Unable to connect, and Jump Desktop does not connect to the host. Jump Desktop never displays text from the provider's response.

Tokens#

  • Make tokens unpredictable, short-lived, and single-use. Jump Desktop does not impose a lifetime; leave enough time for the app to start if it is not already running.
  • Check that the token exists, has not expired, and is authorized, then mark it used atomically, in durable storage, before returning credentials, so neither concurrent requests nor a provider restart can redeem it twice.
  • Jump Desktop does not retry a request. If a response is lost after the token is used, the user needs a new link.
  • Jump Desktop has no endpoint for issuing or refreshing tokens: issuing them is part of your own portal.

Security#

  • HTTPS only. Jump Desktop connects to the credentials provider over TLS 1.2 or later and has no plaintext fallback. The provider's certificate must be valid for credhost and chain to a certificate authority trusted by the operating system of the user's device. There is no option to accept an untrusted certificate.
  • No redirects. Jump Desktop does not follow redirects, including redirects to another HTTPS address.
  • Time limit. The whole request, including proxy detection, must finish within 10 seconds, and the connection to the provider must be established within 5 seconds.
  • Proxies. On Windows and macOS, the request uses the proxy configured in Jump Desktop (see Use a proxy server). On iPhone and iPad, it uses the device's system proxy settings. Proxy credentials are never sent to the credentials provider.
  • Credentials stay in memory. Jump Desktop keeps the returned username and password in memory for the launch and does not save them. Import > From URL... does not save credentials provider links; on Windows it shows "This link signs in through a credential provider and can't be saved. Open the link to connect."
  • No password typing. The Password menu item, which types the saved password on the host, is unavailable in sessions started from a credentials provider link.
  • Logging. Do not log tokens, Authorization headers, or response bodies on the credentials provider or the portal.

Verify the setup#

  1. Issue a token and open the link on a device with Jump Desktop 10.16 or later.
  2. Confirm that the session signs in to the host without asking for a password, and that your credentials provider recorded exactly one redemption.
  3. Disconnect the network briefly, or restart Connect on the host, and confirm that the session reconnects without a second redemption.
  4. Close the session and open the same link again. Jump Desktop shows "This connection link has expired or was already used. Request a new link and try again."

Troubleshooting#

Symptom Likely cause Fix
Incorrect URL when the link opens The link breaks a rule in Build the launch link, for example a duplicate parameter, a username parameter, an IP address in credhost, or a raw + in the token. Rebuild the link with a URL library and check each rule.
The link connects without contacting the credentials provider and asks for the host's credentials The device runs a Jump Desktop version earlier than 10.16, which ignores the credentials provider parameters. Update Jump Desktop to 10.16 or later.
"This connection link has expired or was already used." The provider returned expired, already_used, or not_found, for example because the link was opened twice or opened after the token's lifetime. Issue a new link. If links expire before users open them, lengthen the token lifetime.
"The credential provider did not allow access to this computer." The provider returned denied. Check your provider's policy for that user and host.
"Unable to retrieve credentials from the credential provider." The provider could not be reached within the time limit, its certificate is not trusted or does not match credhost, it redirected, or its response did not match the contract. A retry in the same launch after a failed request also shows this message without sending a request, because Jump Desktop discards the token when it starts the first request, even if that request never reached the provider. Check the provider's certificate and DNS name from the user's device, its response status, content type, and JSON, and any proxy in the path. Then issue a new link.
The host rejects the sign-in The provider returned a username or password the host does not accept. Correct the credentials in the provider and issue a new link. Jump Desktop does not contact the provider again for the same launch.

Limitations#

  • Each link works for one launch. A credentials provider link cannot be saved as a computer or reused after its session window closes.
  • On iPhone and iPad, a session started from a credentials provider link is not restored when the system restores the app's windows.
  • Only Jump Desktop on Windows, macOS, iPhone, and iPad supports credentials provider links.