4 Protocol Examples

  • Article

This scenario shows the message exchanges that occur when a protocol client requests an access-protected document at the URI https://www.contoso.com/dir/document.docx from a protocol server that is gated by forms based authentication.

Prior to requesting this document, the client attempt to determine the capabilities of the server:

 C: OPTIONS /dir/
 C: User-Agent: MSOffice 12

The server issues a response indicating that it is capable of forms based authentication:

 S: HTTP/1.1 403 Forbidden
 S: X-FORMS_BASED_AUTH_REQUIRED: https://www.contoso.com/fbalogin.aspx?wreply=https://www.contoso.com/OnSuccess.aspx
 S: X-FORMS_BASED_AUTH_RETURN_URL: https://www.contoso.com/OnSuccess.aspx
 S: X-FORMS_BASED_AUTH_DIALOG_SIZE: 800x600.

The client then issues an HTTP request to the header specified in the X-FORMS_BASED_AUTH_REQUIRED URI, requesting HTML that the user can employ to establish his or her identity:

 C: GET /fbalogin.aspx?wreply=https://www.contoso.com/OnSuccess.aspx
 C: User-Agent: Mozilla/4.0

The server then replies with an HTML form that contains enough logic to establish the user’s identity with the server. In this example, the server returns a simple form:

 S: HTTP/1.1 200 OK
 S: <body>
 S: <form name="CredentialForm" method="post" 
 S: action="fbalogin.aspx?wreply=https://www.contoso.com/OnSuccess.aspx" 
 S: id="Creds">
 S: <table>
 S:         <tr><td>Login: </td></tr>
 S:         <tr><td>Username: <input name="UsernameTextBox" type="text" 
 S:         id="UsernameTextBox" </td></tr>
 S:         <tr><td>Password: <input name="PasswordTextBox" 
 S:         type="password"
 S:         id="PasswordTextBox" /></td></tr>
 S:         <tr><td><input type="submit" name="UsernamePasswordButton" 
 S:         value="Submit" id="UsernamePasswordButton" /></td></tr>
 S: </table>
 S: </form>
 S: </body>

On receipt of the preceding HTML, the client instantiates a dialog box of the size that is specified in the initial response to the OPTIONS request. (In this example, that size is 800x600). After the HTML is rendered, the rich client follows the instructions dictated by the HTML form. This example assumes that the user entered the credentials "user:pass" for the user name and password, and then clicked the submit button.

 C: POST /fbalogin.aspx?wreply=https://www.contoso.com/OnSuccess.aspx
 C: User-Agent: Mozilla/4.0
 C: UsernameTextBox=user&PasswordTextBox=pass

If the user’s interactions with the HTML form allowed the server to establish the user’s identity, the remote protocol server sets the identity as a cookie on the request and redirects the user back to the return_url specified in the response to the Protocol Discovery request.

 S: HTTP/1.1 302 Object Moved
 Location: https://www.contoso.com/OnSuccess.aspx
 Set-Cookie: Authentication=<server-determined hash of the user’s identity>

On seeing the redirect, the client determines that this URI matches that returned in response to the Protocol Discovery request. Because the URIs match, the client assumes success, follows the redirect, and closes the form that it was using to render the HTML

 C: GET /OnSuccess.aspx
 C: User-Agent: Mozilla/4.0
 C: Cookie: Authentication=<server-determined hash of the user’s identity>

The server can then respond with any finalization logic that is required:

 S: HTTP/1.1 200 OK
 S: Set-Cookie: FooCookie=bar

After this call completes, the client runs the series of HTTP transactions that is required to successfully open https://www.contoso.com/dir/document.docx.  For more information about this series of transactions, see [MS-OCPROTO] section 2.1.2.1.2.