StoreFront Web API

SAML Authentication

July 22, 2025

Contributed by:

Use SAML authentication to authenticate a user using a configured external identity provider (IdP). Authentication of a user will be handled by the IdP and a SAML assertion returned to StoreFront asserting the identity of the authenticated user. Typically the SAML assertion will contain one or more statements including, but not limited to: the user’s identity, how the user was authenticated: by what method, and when.

To initiate the authentication process using SAML the client should make a request to the Generic Forms URL as returned by Authentication/GetAuthMethods, to get the first form in a series of forms.

The forms are always returned as XML, which must be parsed by the client, transformed into corresponding HTML, and displayed to the user. Once the user completes and submits a form, the client posts the form data back to a post-back URL provided in the original form XML. This may in general result in further forms being sent to the client to solicit additional information from the user. The client continues the process of rendering and submitting forms until either an authentication success or failure response is received. The initial form typically contains a WebView element, with parameter StartUrl that gives the URL of a webpage to display. For more information, see Citrix Common forms authentication API and Webview credential type.

Upon successful authentication the IdP will generate a SAMLResponse, which should be directed back to StoreFront where it will be processed. Upon successful validation of the assertion by StoreFront the user will be authenticated and granted access to protected resources.

StoreFront SAML authentication flow sequence diagram

URL (indicative only)	Description
ExplicitAuth/Login?formsProtocol=Forms-Saml	Requests the form that details how the request should be constructed to transfer the user to the Identity Provider for authentication. The URL is returned by /Authentication/GetAuthMethods.
/ExplicitAuth/Bounce	Initiates the processing of the SAML assertion received from the Identity Provider. When authentication has been performed at the IDP this request will be made automatically by StoreFront. If the SAML assertion has been obtained manually the client will have to make this request. This URL is returned by /Home/Configuration.
/ExplicitAuth/ResumeForms	Instructs StoreFront to process the SAML assertion received from the Identity Provider and continues the authentication flow. When authentication has been performed at the IDP this request will be made automatically by StoreFront. If the SAML assertion has been obtained manually the client will have to make this request. This URL is returned by /Home/Configuration.

Request

POST https://webserver/Citrix/StoreWeb/ExplicitAuth/Login?formsProtocol=Forms-Saml HTTP/1.1
Host: kontiki
Connection: keep-alive
Content-Length: 0
X-Citrix-AM-LabelTypes: none, plain, heading, information, warning, error, confirmation, image
X-Citrix-IsUsingHTTPS: Yes
Accept: application/vnd.citrix.authenticateresponse -1+xml, text/html, */*; q=0.01
Csrf-Token: CC2F95295A10D432BA6282D28D9DF0E0
X-Citrix-AM-CredentialTypes: none, username, domain, password, newpassword, passcode, savecredentials, textcredential, webview
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Cookie: CsrfToken=CC2F95295A10D432BA6282D28D9DF0E0; ASP.NET_SessionId=4jyvhnaj4go34iillvalniax
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/vnd.citrix.authenticateresponse-1+xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-Citrix-ExplicitAuthProtocol: Forms-Saml
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Wed, 06 Feb 2019 11:03:09 GMT
Content-Length: 762

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse xmlns="http://citrix.com/authentication/response/1">
    <Status>success</Status>
    <Result>more-info</Result>
    <StateContext />
    <AuthenticationRequirements>
        <PostBack>ExplicitAuth/SendForm</PostBack>
        <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
        <CancelButtonText>Cancel</CancelButtonText>
        <Requirements>
            <Requirement>
                <Credential>
                    <ID>samlResponseId</ID>
                    <Type>webview</Type>
                    <wv:WebView xmlns:wv="http://citrix.com/authentication/response/webview/1">
                        <wv:StartUrl>https://webserver/Citrix/StoreAuth/SamlForms/WebView</wv:StartUrl>
                    </wv:WebView>
                </Credential>
                <Label>
                    <Type>none</Type>
                </Label>
                <Input />
            </Requirement>
        </Requirements>
    </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

Example: SAML Authentication – Submit SAML Response

Request

POST https://webserver/Citrix/StoreWeb/ExplicitAuth/Bounce HTTP/1.1
Host: kontiki
Connection: keep-alive
Content-Length: 9833
User-Agent: Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: application/vnd.citrix.authenticateresponse -1+xml, text/html, 
*/*; q=0.01
Csrf-Token: CC2F95295A10D432BA6282D28D9DF0E0
X-Requested-With: XMLHttpRequest
X-Citrix-IsUsingHTTPS: Yes
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Cookie: CtxsDeviceId=WR_vTBnOoDoXoLz; CsrfToken=CC2F95295A10D432BA6282D28D9DF0E0; CtxsAuthId=C366B589DC9A033B6A0B8313F83EC2F3; ASP.NET_SessionId=4jyvhnaj4go34iillvalniax

_cx=&samlResponseId=SAMLResponse<SAML_RESPONSE>&_cs=CC2F95295A10D432BA6282D28D9DF0E0
<!--NeedCopy-->

Response

HTTP/1.1 302 Found
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: text/html; charset=utf-8
Expires: -1
Location: /Citrix/stf-mima-cam1-aWeb/#resumeForms:_cx=&samlResponseId=
Server: Microsoft-IIS/8.5
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Wed, 06 Feb 2019 11:03:09 GMT
Content-Length: 193

<html><head><title>Object moved</title></head><body>
<h2>Object moved to <a href="%2fCitrix%2fstf-mima-cam1-aWeb%2f%23resumeForms%3a_cx%3d%26samlResponseId%3d">here</a>.</h2>
</body></html>
<!--NeedCopy-->

Example: SAML Authentication – Valid SAML assertion

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/ResumeForms HTTP/1.1
Host: kontiki
Connection: keep-alive
Content-Length: 29
Origin: https://stf-mima-cam1-a.washington.net
X-Citrix-AM-LabelTypes: none, plain, heading, information, warning, error, confirmation, image
X-Citrix-IsUsingHTTPS: Yes
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: application/xml, text/xml, */*; q=0.01
X-Citrix-AM-CredentialTypes: none, username, domain, password, newpassword, passcode, savecredentials, textcredential, webview, webview
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
Csrf-Token: 4C036B847B68C84300F61AB2A678565E
Referer: https://stf-mima-cam1-a.washington.net/Citrix/stf-mima-cam1-aWeb/ApiExampleUsingSaml.html
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Cookie: CsrfToken=4C036B847B68C84300F61AB2A678565E; ASP.NET_SessionId=4jyvhnaj4go34iillvalniax

StateContext=&samlResponseId=
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
Set-Cookie: CtxsAuthId=B09AA2A87F66EC5E0F0B1CD120BB263E; path=/Citrix/stf-mima-cam1-aWeb/; secure; HttpOnly
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Content-Length: 225

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticationStatus xmlns="http://citrix.com/delivery-services/webAPI/2-6/authStatus"  >
  <Result>success</Result>
  <AuthType>ExplicitForms</AuthType>
</AuthenticationStatus>
<!--NeedCopy-->

Example: SAML Authentication – Invalid SAML assertion

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/ResumeForms HTTP/1.1
Host: kontiki
Connection: keep-alive
Content-Length: 29
Origin: https://stf-mima-cam1-a.washington.net
X-Citrix-AM-LabelTypes: none, plain, heading, information, warning, error, confirmation, image
X-Citrix-IsUsingHTTPS: Yes
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: application/vnd.citrix.authenticateresponse -1+xml, text/html, */*; q=0.01
X-Citrix-AM-CredentialTypes: none, username, domain, password, newpassword, passcode, savecredentials, textcredential, webview, webview
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
Csrf-Token: 4C036B847B68C84300F61AB2A678565E
Referer: https://stf-mima-cam1-a.washington.net/Citrix/stf-mima-cam1-aWeb/ApiExampleUsingSaml.html
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Cookie: CsrfToken=4C036B847B68C84300F61AB2A678565E; ASP.NET_SessionId=4jyvhnaj4go34iillvalniax

StateContext=&samlResponseId=
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/vnd.citrix.authenticateresponse-1+xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-Citrix-ExplicitAuthProtocol: Forms-Saml
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Content-Length: 729

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse xmlns="http://citrix.com/authentication/response/1">
  <Status>success</Status>
  <Result>more-info</Result>
  <StateContext/>
  <AuthenticationRequirements>
    <PostBack>ExplicitAuth/Login?formsProtocol=Forms-Saml</PostBack>
    <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
    <Requirements>
    <Requirement>
        <Credential>
        <Type>none</Type>
        </Credential>
        <Label>
        <Text>There was a failure with the mapped account.</Text>
        <Type>error</Type>
        </Label>
        <Input />
    </Requirement>
    <Requirement>
        <Credential>
        <ID>confirmBtn</ID>
        <Type>none</Type>
        </Credential>
        <Label>
        <Type>none</Type>
        </Label>
        <Input>
        <Button>OK</Button>
        </Input>
    </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

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

Resources

StoreFront Web API OpenAPI Specification

Copy Download

SAML Authentication

July 22, 2025

Contributed by:

July 22, 2025

Contributed by:

SAML Authentication

Example: SAML Authentication – Initiate login process

Request

Response

Example: SAML Authentication – Submit SAML Response

Request

Response

Example: SAML Authentication – Valid SAML assertion

Request

Response

Example: SAML Authentication – Invalid SAML assertion

Request

Response

Resources

StoreFront Web API OpenAPI Specification

In this article

Resources

StoreFront Web API OpenAPI Specification