StoreFront Web API

Explicit forms authentication examples

July 11, 2023

Contributed by:

With Explicit Forms authentication, the client is required to submit the user’s credentials using one or more forms, which are part of a conversation.

The client initiates a forms conversation by making a request to the Explicit Forms Endpoint (returned by Authentication/GetAuthMethods) to get the first form in a possible 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 client must not assume that the initial form returned represents a login form. This may typically be the case, but some other form may be returned in certain circumstances, for example a change password form is returned if password expiry is configured and the user’s password has expired. Third parties may also use the StoreFront Authentication SDK to inject custom forms into the authentication process.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/Login HTTP/1.1
Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Csrf-Token: 23E18D9002817048C931EA636E0D5C81
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=23E18D9002817048C931EA636E0D5C81; ASP.NET_SessionId=hdqnxu21dz3p2nb2zcfo2sfs
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 0
<!--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: ExplicitForms
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Fri, 17 Jan 2014 16:25:09 GMT
Content-Length: 1555
<?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/LoginAttempt</PostBack>
    <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
    <CancelButtonText>Cancel</CancelButtonText>
    <Requirements>
      <Requirement>
        <Credential>
        <ID>username</ID>
        <SaveID>ExplicitForms-Username</SaveID>
        <Type>username</Type>
        </Credential>
        <Label>
        <Text>User name:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <AssistiveText>domain\user or user@domain.com</AssistiveText>
        <Text>
            <Secret>false</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>password</ID>
        <SaveID>ExplicitForms-Password</SaveID>
        <Type>password</Type>
        </Credential>
        <Label>
        <Text>Password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>saveCredentials</ID>
        <Type>savecredentials</Type>
        </Credential>
        <Label>
        <Text>Remember my password</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <CheckBox>
            <InitialValue>false</InitialValue>
        </CheckBox>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>loginBtn</ID>
        <Type>none</Type>
        </Credential>  <Label>
        <Type>none</Type>
        </Label>
        <Input>
        <Button>Log On</Button>
        </Input>
      </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

The client transforms the XML form description into an HTML representation, which is then dynamically added to the web page DOM. The proceeding XML results in an HTML form consisting of a User name label and text input field, a Password label and password input field, and a Log On button. The user types sign in credentials in the input fields and submits the form by clicking the “Log On” button. The client intercepts the form submission and follows the Common Forms Authentication rules to build the form data to submit to the PostBack URL, in this case Authentication/LoginAttempt.

Incorrect credentials submitted

If the user mistypes their password this results in the Authentication service returning another login form XML document, this time highlighting the error with an additional Requirements node.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/LoginAttempt HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: E2FF5D342BA9193DF707062EA7A31C54
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 72
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=E2FF5D342BA9193DF707062EA7A31C54; ASP.NET_SessionId=1zfyotwrcjr3uzry3jbqcpvg
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

username=acmecorp%5Cuser1&password=rubbish&loginBtn=Log+On&StateContext=
<!--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: ExplicitForms
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 09:52:42 GMT
Content-Length: 1725

<?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/LoginAttempt</PostBack>
    <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
    <CancelButtonText>Cancel</CancelButtonText>
    <Requirements>
      <Requirement>
        <Credential>
        <ID>username</ID>
        <SaveID>ExplicitForms-Username</SaveID>
        <Type>username</Type>
        </Credential>
        <Label>
        <Text>User name:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <AssistiveText>domain\user or user@domain.com</AssistiveText>
        <Text>
            <Secret>false</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>acmecorp\user1</InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>password</ID>
        <SaveID>ExplicitForms-Password</SaveID>
        <Type>password</Type>
        </Credential>
        <Label>
        <Text>Password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <Type>none</Type>
        </Credential>
        <Label>
          <Text>Incorrect user name or password</Text>
          <Type>error</Type>
        </Label>
        <Input />
      </Requirement>
      <Requirement>
        <Credential>
        <ID>saveCredentials</ID>
        <Type>savecredentials</Type>
        </Credential>
        <Label>
        <Text>Remember my password</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <CheckBox>
            <InitialValue>false</InitialValue>
        </CheckBox>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>loginBtn</ID>
        <Type>none</Type>
        </Credential>
        <Label>
        <Type>none</Type>
        </Label>
        <Input>
        <Button>Log On</Button>
        </Input>
      </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

Again, the client parses the XML form, transforms it to HTML and displays it to the user, including the additional text to inform the user that the previously entered password was incorrect.

Correct credentials submitted

The user then enters the correct password and resubmits the form, resulting in an AuthenticationStatus response indicating success.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/LoginAttempt HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: E2FF5D342BA9193DF707062EA7A31C54
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 72
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=E2FF5D342BA9193DF707062EA7A31C54; ASP.NET_SessionId=1zfyotwrcjr3uzry3jbqcpvg
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

username=acmecorp%5Cuser1&password=mypassword&loginBtn=Log+On&StateContex t=
<!--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=22BE25569A283D63B1C5668580119320; path=/Citrix/StoreWeb/; HttpOnly
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Fri, 17 Jan 2014 16:42:49 GMT
Content-Length: 157
<?xml version="1.0" encoding="UTF-8"?>
<AuthenticationStatus xmlns="http://citrix.com/deliveryservices/webAPI/2-6/authStatus">
  <Result>success</Result>
  <AuthType>ExplicitForms</AuthType>
</AuthenticationStatus>
<!--NeedCopy-->

Password expired

If StoreFront is configured to allow users to change an expired password and a user attempts to log on when their password has expired, a change password XML form is returned when the user submits their credentials. This form includes a label to inform the user that their password must be changed, and text input fields (plus corresponding labels) for the user to enter the old password and to enter and confirm a new password. Note that the post-back URL is also updated to point back to the URL ExplicitAuth/SendForm.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/LoginAttempt HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: A75AC234CA8C565EEEBE96FF81E495BA
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 70
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=A75AC234CA8C565EEEBE96FF81E495BA; ASP.NET_SessionId=ulemrewlolkvhallkgcbwm3l
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

username=acmecorp%5Cuser1&password=mypassword&loginBtn=Log+On&StateContex t=
<!--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: ExplicitForms
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 10:53:59 GMT
Content-Length: 2111

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse xmlns="http://citrix.com/authentication/response/1">
  <Status>success</Status>
  <Result>update-credentials</Result>
  <StateContext />
  <AuthenticationRequirements>
    <PostBack>ExplicitAuth/SendForm</PostBack>
    <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
    <CancelButtonText>Cancel</CancelButtonText>
    <Requirements>
      <Requirement>
        <Credential>
          <Type>none</Type>
        </Credential>
        <Label>
        <Text>Change Password</Text>
        <Type>heading</Type>
        </Label>
        <Input />
      </Requirement>
      <Requirement>
        <Credential>
        <Type>none</Type>
        </Credential>
        <Label>
        <Text>Your password has expired and must be changed.</Text>
        <Type>information</Type>
        </Label>
        <Input />
      </Requirement>
      <Requirement>
        <Credential>
        <Type>username</Type>
        </Credential>
        <Label>
        <Text>User name:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>false</Secret>
            <ReadOnly>true</ReadOnly>
            <InitialValue>acmecorp\user1</InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>oldPassword</ID>
        <Type>password</Type>
        </Credential>
        <Label>
        <Text>Old password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>newPassword</ID>
        <SaveID>ExplicitForms-Password</SaveID>
        <Type>newpassword</Type>
        </Credential>
        <Label>
        <Text>New password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>confirmPassword</ID>
        <Type>newpassword</Type>
        </Credential>
        <Label>
        <Text>Confirm password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>changePasswordBtn</ID>
        <Type>none</Type>
        </Credential>
        <Label>
        <Type>none</Type>
        </Label>
        <Input>
        <Button>OK</Button>
        </Input>
      </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

When the user enters the requested information and submits the form, a further form is returned by the Authentication service for the user to confirm that their password has been successfully changed. Note that the request specifies the button ID changePasswordBtn specified in the form above; failing to specify the correct button id would result in the form being rejected. This confirmation form comprises simply a text label and OK button.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/SendForm HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101 Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: 94FEF17799905C51ADD4599AC0056209
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 95
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=94FEF17799905C51ADD4599AC0056209; ASP.NET_SessionId=01omrcuoenllin1eugyr142j
Connection: keep-alive Pragma: no-cache
Cache-Control: no-cache

oldPassword=mypassword&newPassword=newpassword&confirmPassword=newpasswor d&changePasswordBtn=OK&StateContext=
<!--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: ExplicitForms
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 11:13:18 GMT
Content-Length: 720

<?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>
    </CancelPostBack>
    <Requirements>
      <Requirement>
 <Credential>
   <Type>none</Type>
 </Credential>
 <Label>
   <Text>Your password has been changed successfully.</Text>
   <Type>confirmation</Type>
 </Label>
 <Input />
      </Requirement>
      <Requirement>
 <Credential>
   <ID>changePasswordConfirmBtn</ID>
   <Type>none</Type>
 </Credential>
 <Label>
   <Type>none</Type>
 </Label>
 <Input>
   <Button>OK</Button>
 </Input>
      </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

After the user clicks OK, the confirmation form is submitted and a successful authentication response is obtained.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/SendForm HTTP/1.1
Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101 Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: 94FEF17799905C51ADD4599AC0056209
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 41
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=94FEF17799905C51ADD4599AC0056209; ASP.NET_SessionId=01omrcuoenllin1eugyr142j
Connection: keep-alive Pragma: no-cache
Cache-Control: no-cache

changePasswordConfirmBtn=OK&StateContext=
<!--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=7BFB98069F1D33A0FB4268F702B0C983; path=/Citrix/StoreWeb/; HttpOnly
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 11:13:24 GMT
Content-Length: 157

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

Elective change password

If StoreFront is configured to allow users to change password at any time and a user attempts to log on when their password is due to expire within the configured expiry period, a successful authentication response is returned with additional elements indicating that expiry notification is enabled and the number of days remaining until the password expires.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/LoginAttempt HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: 94FD74E2F4DF05D6B0642D25021F632A
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 70
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=94FD74E2F4DF05D6B0642D25021F632A; ASP.NET_SessionId=mgucndg5j24cgvymxgrjblr4
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

username=acmecorp%5Cuser1&password=mypassword&loginBtn=Log+On&StateContex t=
<!--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=F431D32D995E3CF6A59F5728A0F54085; path=/Citrix/StoreWeb/; HttpOnly
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 11:25:46 GMT
Content-Length: 320

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticationStatus xmlns="http://citrix.com/deliveryservices/webAPI/2-6/authStatus">
  <Result>success</Result>
  <AuthType>ExplicitForms</AuthType>
  <IsChangePasswordEnabled>true</IsChangePasswordEnabled>
  <IsExpiryNotificationEnabled>true</IsExpiryNotificationEnabled>
  <TimeRemaining>89</TimeRemaining>
</AuthenticationStatus>
<!--NeedCopy-->

The client may then provide an interface for the user to initiate an elective change password request at any time using the Change Credentials URL obtained from the Receiver for Web configuration at XPath /clientSettings/authManager. Requesting this URL initiates a Common Forms protocol conversation in a similar way to /ExplicitAuth/Login. If the user submits the form after entering invalid data (or omitting required data), further forms may be generated. The client needs to be prepared to receive multiple forms in succession and process these until either a success or failure response is received. If the password change is successful, a password confirmation form is returned; when the confirmation form is submitted a successful AuthenticationStatus response is returned. In other words, the change password conversation proceeds exactly as described in the earlier example for the case where the user’s password has expired at logon time.

Request

POST
http://webserver/Citrix/StoreWeb/Authentication/GetChangeCredentialForm HTTP/1.1
Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Csrf-Token: A4BF7CB3334846575421F41AD44EBA67
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=A4BF7CB3334846575421F41AD44EBA67; CtxsAuthId=910C6BFC2C98184CA57F77556041E0D3; ASP.NET_SessionId=cxd25yc3xwq10qevwpxywyxu
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache Content-Length: 0
<!--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: ExplicitForms
X-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 11:48:00 GMT
Content-Length: 2097
<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse xmlns="http://citrix.com/authentication/response/1"> 
<Status>success</Status>
  <Result>update-credentials</Result>
  <StateContext />
  <AuthenticationRequirements>
    <PostBack>ExplicitAuth/SendForm</PostBack>
    <CancelPostBack>ExplicitAuth/CancelForm</CancelPostBack>
    <CancelButtonText>Cancel</CancelButtonText>
    <Requirements>
      <Requirement>
        <Credential>
        <Type>none</Type>
        </Credential>
        <Label>
        <Text>Change Password</Text>
        <Type>heading</Type>
        </Label>
        <Input />
      </Requirement>
      <Requirement>
        <Credential>
        <Type>none</Type>
        </Credential>
        <Label>
        <Text>Enter your old and new passwords</Text>
        <Type>information</Type>
        </Label>
        <Input />
      </Requirement>
      <Requirement>
        <Credential>
        <Type>username</Type>
        </Credential>
        <Label>
        <Text>User name:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>false</Secret>
            <ReadOnly>true</ReadOnly>
            <InitialValue>acmecorp\user1</InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>oldPassword</ID>
        <Type>password</Type>
        </Credential>
        <Label>
        <Text>Old password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>newPassword</ID>
        <SaveID>ExplicitForms-Password</SaveID>
        <Type>newpassword</Type>
        </Credential>
        <Label>
        <Text>New password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>confirmPassword</ID>
        <Type>newpassword</Type>
        </Credential>
        <Label>
        <Text>Confirm password:</Text>
        <Type>plain</Type>
        </Label>
        <Input>
        <Text>
            <Secret>true</Secret>
            <ReadOnly>false</ReadOnly>
            <InitialValue>
            </InitialValue>
            <Constraint>.+</Constraint>
        </Text>
        </Input>
      </Requirement>
      <Requirement>
        <Credential>
        <ID>changePasswordBtn</ID>
        <Type>none</Type>
        </Credential>
        <Label>
        <Type>none</Type>
        </Label>
        <Input>
        <Button>OK</Button>
        </Input>
      </Requirement>
    </Requirements>
  </AuthenticationRequirements>
</AuthenticateResponse>
<!--NeedCopy-->

With elective change password the user has already authenticated. Since the change password request is not essential to access the site, the client UI should provide a Cancel button on the form. If the user chooses to cancel, the cancel post-back URL in the above form should be used to relay to the Authentication service that the request has been cancelled.

Request

POST http://webserver/Citrix/StoreWeb/ExplicitAuth/CancelForm HTTP/1.1 Host: kontiki
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:26.0) Gecko/20100101
Firefox/26.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-us,en;q=0.7,fr;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Csrf-Token: 3E5784A870D03FF16BF7A37415F9E0AB
X-Citrix-IsUsingHTTPS: No
X-Requested-With: XMLHttpRequest
Referer: http://webserver/Citrix/StoreWeb/
Content-Length: 73
Cookie: CtxsAuthMethod=ExplicitForms; CsrfToken=3E5784A870D03FF16BF7A37415F9E0AB; CtxsAuthId=C389FA6A3BD8E1E3811C184C01918411; ASP.NET_SessionId=chgeeknlk5aiewkyyqfwp43p
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
oldPassword=&newPassword=&confirmPassword=&cancelBtn=Cancel&StateContext=
<!--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-Powered-By: ASP.NET
X-Citrix-Application: Receiver for Web
Date: Mon, 20 Jan 2014 12:02:33 GMT
Content-Length: 201

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse xmlns="http://citrix.com/authentication/response/1">
  <Status>success</Status>
  <Result>cancelled</Result>
  <StateContext />
</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

Explicit forms authentication examples

July 11, 2023

Contributed by:

July 11, 2023

Contributed by:

Explicit forms authentication examples

Sign in form returned

Request

Response

Incorrect credentials submitted

Request

Response

Correct credentials submitted

Request

Response

Password expired

Request

Response

Request

Response

Request

Response

Elective change password

Request

Response

Request

Response

Request

Response

Resources

StoreFront Web API OpenAPI Specification

In this article

Resources

StoreFront Web API OpenAPI Specification