Anatomy of a SAML Transaction (WSS)
search cancel

Anatomy of a SAML Transaction (WSS)

book

Article ID: 165524

calendar_today

Updated On:

Products

Cloud Secure Web Gateway - Cloud SWG

Issue/Introduction

You need to understand how Security Assertion Markup Language authentication (SAML) works or you have one of the following questions:

  • How does a SAML (user authentication) transaction work?
  • How does the client-to-SP (Service Provider) and client-to-IDP (Identity Provider) process work?
  • What does a SAML trace look like?

Environment

WSS implementing SAML Authentication. 

Resolution

This document details the SAML authentication process with the WSS service.

For these examples, we use the Auth Connector Software as the SAML IDP (the BCCA-as-IDP feature).

Overview

For Web Security Service, SAML user authentication is currently available for the Explicit Proxy and IPsec/VPN access methods.

SAML allows for "promptless" user authentication.

With SAML integrated, the WSS cannot authenticate explicit HTTPS requests without SSL Intercept enabled.

Please understand that SAML is a complex protocol, that requires at least seven (7) request/response transactions for every URL (including for every image and object on a page).

More information about configuring SAML 

SP = Service Provider
IDP = Identity Provider


Cloud SAML Considerations

  • WSS supports SAML 2.0
  • The user-agents (clients) must support: redirects, cookies, and HTML POST forms by JavaScript
  • Port 8443 is required for clients to POST or REDIRECT the SAML assertions to the WSS SAML Service Provider (a Cloud datapod)
  • The WSS SAML Service Provider may sign but does not encrypt Authentication requests (those do NOT contain sensitive information)
  • Authentication Response's, however, MUST be signed by the IDP, and must contain the IDP signing certificate
  • Cloud does not currently support encrypted AuthnResponse's

Visual of the SAML client-to-SP and client-to-IDP interaction:

 

Tools to inspect SAML Transactions: 

Since all interaction with the SP and IDP is handled by the browser/client (the SP and IDP never talk directly), then using browser-side tools are needed to inspect SAML transactions.  
 
Good tools are: 
  • HttpWatch (or similar tool such as Fiddler)
  • The Firefox add-on: "SAML tracer"
  • SAML Online Decoder

SAML Transaction Details: 

  • In this example, the browser accesses the website: http://checkip.dyndns.com
  • SP is the Cloud service, specifically: https://saml.threatpulse.net:8443
  • IDP is the BCCA
  • The URL "http://idp-url/..." referenced below reflects your IDP "Endpoint URL" defined in Portal. The SP sends the endpoint URL to your client)
Client -> pod GET http://checkip.dyndns.com
Pod -> client HTTP 302 to: https://saml.threatpulse.net:8443/ (the SP)
 
Notes: 
  •  Client's initial request for a website (protected by Cloud)
  •  When client first requests content, the Cloud redirects the client to the SAML SP, to begin the SAML authentication
______
1 
 
Client -> pod (CONNECT to the SP) GET saml.threatpulse.net:8443
Pod -> client HTTP 302 to: http://idp-url/bcca/saml/idp/?SAMLRequest=
 
Notes: 
  •   saml.threatpulse.net:8443 is the SP
  •   The "SAMLRequest" is in the QueryString, and contains the <AuthnRequest>...</AuthnRequest>
  •   You can DECODE (as REDIRECT) the value of the "SAMLRequest" parameter to see the <AuthnRequest> content
  •   The SP tells the client to communicate directly to the IDP (next step)
______ 
2
 
Client -> IDP GET http://idp-url/bcca/saml/idp/?SAMLRequest= (with <AuthnRequest>)
 
Notes: 
  • The SP told the client to redirect to the IDP (with the <AuthnRequest> that the SP provided)
 
______ 
3 & 4 
 
IDP -> client HTTP 401 Authentication required!
 
Notes: 
  •  Represents the credential challenge between the client and the IDP
  •  Represents where the browser authenticates to the IDP (against Active Directory, using either BCCA-as-IDP or ADFS)
 
______ 
5 
 
client -> IDP GET http://idp-url/bcca/saml/idp/?SAMLRequest=
IDP -> client HTTP 200 OK: HTML Form that is with "SAMLResponse"
 
Notes: 
  • After authentication, the client does a GET to the IDP with the original SAMLRequest, and the IDP now replies with the "SAMLResponse"
  • The value of the "SAMLResponse" is large, around 4,000 characters, and is in the HTML form (Base64 encoded)
  • The HTML form that is returned by the IDP sends the client back to the SP
  • The IDP returns an HTML form that MUST be submitted by the client by a JavaScript POST, such as: 
 
<html>
<body onLoad="document.forms[0].submit()">
<form action="https://saml.threatpulse.net:8443/saml/saml_realm/bcsamlpost" method="POST">
 
<input type="hidden" name="SAMLResponse" value="PD94......(large-value-here)......=" />
...
</form>
</body>
</html>
 
______
6 
 
client -> pod (CONNECT to the SP) POST https://saml.threatpulse.net:8443/saml/saml_realm/bcsamlpost
pod -> client HTTP 302 to: http://checkip.dyndns.com/?bcsi-ac-61d2bca16bb82eb2=...
 
Notes: 
  • Represents the POST from the client to the SP
  • The SAMLResponse (received from the IDP in the previous step) is POST'd to the SP
  • You can DECODE (as POST) the value of the "SAMLResponse" to see the: <samlp:Response>...</samlp:Response>
  • Inside the <samlp:Response> you can see the identity of the user, such as: 
<NameID>sjohns</NameID>
 
______ 
6.5 not shown on image
 
client -> pod GET http://checkip.dyndns.com/?bcsi-ac-61d2bca16bb82eb2=...
pod -> client HTTP 302 to: http://checkip.dyndns.com/
 
Notes: 
  • Client is now authenticated (note the "bcsi-ac-..." QueryString parameter) and requests the resource
  • The client is told to request the original content (now without the "bcsi-ac-..." param)
 
______
7 
 
client -> pod GET http://checkip.dyndns.com/
pod -> client HTTP 200 OK
 
SUCCESS: content that is requested is now returned to client.
 
______ 
 

SAML Transaction Details for the WSS Agent access method:

  1. Once the WSSA is in the connecting phase, a request is sent to http://pod.threatpulse.com/api/v1/check_auth to start the SAML authentication process and allow WSS identify the user and user groups. The request is generated by the Webview (Windows) or Webkit (MacOS) component that WSSA integrates with for SAML based authentication.
  2. The above request should trigger a redirected HTTP response (HTTP 302 or 307) to an endpoint on https://saml.threatpulse.net – which then gets redirected to the IdP. During this time, the PID of the Webview/Webkit process is bypassed by WSSA so that all requests generated during the authentication process will go to the OCS, with the exception of the internal IP addresses.
  3. The WSSA service watches for responses coming through the tunnel from http://pod.threatpulse.com. When a “successful” (HTTP 2xx) response is received over port 80 from pod.threatpulse.com, WSSA completes the internal authentication logic.
  4. A timer is set for 5 minutes, +/- 60 seconds. Once the timer has triggered, WSS Agent will once again trigger the "check_auth" endpoint to ensure that the tunnel is still authenticated.  During the time that WSSA is actively awaiting the user to log in, this timeout is shortened to 10 seconds.
  5. After full authentication has been completed, a status message of “Authenticated” is sent to the notifier which triggers the notifier to close the browser component. The status of the connection is set to “Connected” in the WSSA notifier.
  6. The session is valid for 12 hours on the WSS SAML SP. As long as the users network does not change, the host restarted or a manual RECONNECT initiated, no additional authentication exchange will be performed. When any of these conditions occur however, then the authentication process starts from scratch. If users are being prompted to re-authenticate more often that this, check out the following KB article for potential reasons why, and solutions to the problem.


    NOTE: When using SAML with WSS Agent you need to make sure that, if PAC files are being used on the host, traffic destined for pod.threatpulse.com and *.threatpulse.net must be "DIRECT".
Powered by Wolken Software