Domain Pass-Through Citrix Workspace app for Linux

Credential Insertion SDK

September 4, 2025

Contributed by:

S C

The Credential Insertion SDK allows you to insert a set of credentials into AuthManager’s internal cache to be used for SSO when launching an app/desktop. The SDK is a C/C++ library consumed by external code and exposes functions to add/remove domain, smart card, or cookie credentials.

API functions

LogonSSOUser
LogonSSOUserWithPin
LogonSsoCookies (Available from version 2508)
LogoffSSOUser
ErrorDescription

The function is available under the namespace CitrixSSOnSDK.

LogonSSOUser

LOGONSSOUSER_ERROR_CODE LogonSsoUser    (const wchar_t *username,
                                         const wchar_t *domain,
                                         const wchar_t *password);
<!--NeedCopy-->

This function is used to provide user credentials to SSO.

Parameter	Description
`username`	The username
`domain`	The domain
`password`	The password

Return value	Description
`LOGONSSOUSER_OK`	Operation completed
`LOGONSSOUSER_INVALID_PARAMETER`	Invalid parameter passed to the function
`LOGONSSOUSER_INITIALIZATION_FAILED`	An error occurred initializing the SSO client
`LOGONSSOUSER_UNABLE_TO_CONNECT_TO_SSO`	Unable to connect to the SSO service (AM)
`LOGONSSOUSER_UNABLE_TO_SEND_REQUEST`	Unable to send the request to the SSO service
`LOGONSSOUSER_UNABLE_TO_RECEIVE_RESPONSE`	Unable to receive the response from the SSO service
`LOGONSSOUSER_INVALID_REQUEST_TYPE`	Invalid SSO request type
`LOGONSSOUSER_CONTAINER_FULL`	The SSO container is full and cannot store more credentials
`LOGONSSOUSER_SERVER_INTERNAL_ERROR`	An error has occurred in AM while processing the request
`LOGONSSOUSER_SERVER_IPC_ERROR`	An error has occurred during the IPC communication with the server (AM)

LogonSsoUserWithPin

LOGONSSOUSER_ERROR_CODE LogonSsoUserWithPin(const wchar_t *pin)
<!--NeedCopy-->

This function is used to provide smart card user credentials to SSO.

Parameter	Description
`pin`	The smart card PIN

Return value	Description
`LOGONSSOUSER_OK`	Operation completed.
`LOGONSSOUSER_INVALID_PARAMETER`	Invalid parameter passed to the function
`LOGONSSOUSER_INITIALIZATION_FAILED`	An error occurred initializing the SSO client
`LOGONSSOUSER_UNABLE_TO_CONNECT_TO_SSO`	Unable to connect to the SSO service (AM)
`LOGONSSOUSER_UNABLE_TO_SEND_REQUEST`	Unable to send the request to the SSO service
`LOGONSSOUSER_UNABLE_TO_RECEIVE_RESPONSE`	Unable to receive the response from the SSO service
`LOGONSSOUSER_INVALID_REQUEST_TYPE`	Invalid SSO request type
`LOGONSSOUSER_CONTAINER_FULL`	The SSO container is full and cannot store more credentials
`LOGONSSOUSER_SERVER_INTERNAL_ERROR`	An error has occurred in AM while processing the request
`LOGONSSOUSER_SERVER_IPC_ERROR`	An error has occurred during the IPC communication with the server (AM)

LogonSsoCookies

LOGONSSOUSER_ERROR_CODE LogonSsoCookies(const char *cookiesJson)
<!--NeedCopy-->

Inserts cookie credentials into the SSO cache.

On success, cookie credentials are pushed to the top of the SSO credential stack and will be used for SSO until cleared.

Parameter	Description
`cookiesJson`	A UTF‑8 JSON string describing one or more cookies.

cookiesJson

Top-level must be a JSON array of cookie objects
Each cookie must include mandatory fields:
- name: string
- value: string
- domain: string
- path: string
Maximum total input size: under 256 KB (otherwise rejected)

[
  {
    "name": "NSC_AAAC",
    "value": "abcdef123456",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true,
    "sameSite": "Lax",
    "expirationDate": 1735689600
  },
  {
    "name": "CitrixAuth",
    "value": "abcxyz123",
    "domain": "store.example.com",
    "path": "/citrix/store",
    "secure": true,
    "httpOnly": false,
    "sameSite": "Strict",
    "expirationDate": 1735689600
  }
]
<!--NeedCopy-->

Return value	Description
`LOGONSSOUSER_OK`	Operation completed
`LOGONSSOUSER_INVALID_PARAMETER`	Invalid parameter passed to the function
`LOGONSSOUSER_INITIALIZATION_FAILED`	An error occurred initializing the SSO client
`LOGONSSOUSER_UNABLE_TO_CONNECT_TO_SSO`	Unable to connect to the SSO service (AM)
`LOGONSSOUSER_UNABLE_TO_SEND_REQUEST`	Unable to send the request to the SSO service
`LOGONSSOUSER_UNABLE_TO_RECEIVE_RESPONSE`	Unable to receive the response from the SSO service
`LOGONSSOUSER_INVALID_REQUEST_TYPE`	Invalid SSO request type
`LOGONSSOUSER_CONTAINER_FULL`	The SSO container is full and cannot store more credentials
`LOGONSSOUSER_SERVER_INTERNAL_ERROR`	An error has occurred in AM while processing the request
`LOGONSSOUSER_SERVER_IPC_ERROR`	An error has occurred during the IPC communication with the server (AM)
`LOGONSSOUSER_COOKIE_INVALID_JSON`	Cookie JSON is invalid
`LOGONSSOUSER_COOKIE_MISSING_MANDATORY_FIELD`	Cookie is missing a mandatory field
`LOGONSSOUSER_COOKIE_FIELD_VALUE_TOO_LARGE`	Cookie field value is too large

Note:

Use ErrorDescription(LOGONSSOUSER_ERROR_CODE) to obtain a description for any error, including the new cookie-related codes.

LogoffSsoUser

int LogoffSsoUser()
<!--NeedCopy-->

Removes the credentials at the top of the SSO stack and restores previous credentials if available.

Behavior note (cookies): If cookie credentials are present at the top of the stack, LogoffSsoUser() clears cookies. If no cookies are on top, it pops the current (domain/smart card) credentials on top (if any).

Returns: 0 if successful, otherwise an error code.

Return value	Description
`LOGONSSOUSER_OK`	Operation completed
`LOGONSSOUSER_INVALID_PARAMETER`	Invalid SSO parameter
`LOGONSSOUSER_INITIALIZATION_FAILED`	SSO client initialization failed
`LOGONSSOUSER_UNABLE_TO_CONNECT_TO_SSO`	Unable to connect to the SSO service
`LOGONSSOUSER_UNABLE_TO_SEND_REQUEST`	Unable to send the request to the SSO service
`LOGONSSOUSER_UNABLE_TO_RECEIVE_RESPONSE`	Unable to receive the response from the SSO service
`LOGONSSOUSER_INVALID_REQUEST_TYPE`	Invalid SSO request type (allowed types are )
`LOGONSSOUSER_UNAUTHORIZED`	Trying to remove a set of credentials that was stored in SSO by AM itself
`LOGONSSOUSER_SERVER_INTERNAL_ERROR`	An error has occurred in AM while processing the request
`LOGONSSOUSER_SERVER_IPC_ERROR`	An error has occurred while establishing the IPC with AM

ErrorDescription

const wchar_t *ErrorDescription(LOGONSSOUSER_ERROR_CODE errorCode)
<!--NeedCopy-->

Parameter	Description
`errorCode`	The error code to get the description of

Return value	Description
The error description	The error description string, or an “Unknown error” message if the error code is unknown

Compatibility matrix

	Citrix Workspace app for Linux < 2508	Citrix Workspace app for Linux >= 2508
Credential Insertion SDK < 2508	✅	✅
Credential Insertion SDK >= 2508	❌	✅

Note:

New Credential Insertion SDK (>= 2508) is not fully compatible with older versions of Citrix Workspace app for Linux (< 2508), even for legacy operations like inserting credentials. Do not use newer versions of Credential Insertion SDK with older versions of Citrix Workspace app for Linux.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Credential Insertion SDK

September 4, 2025

Contributed by:

S C

September 4, 2025

Contributed by:

S C

Credential Insertion SDK

API functions

LogonSSOUser

LogonSsoUserWithPin

LogonSsoCookies

cookiesJson

Cookie JSON example

LogoffSsoUser

ErrorDescription

Compatibility matrix

In this article