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).
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
- Cloud supports SAML 2.0
Port 8443 is required for clients to POST the SAML assertions to the Cloud SP (a Cloud datapod)
The Cloud does not sign or 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)
- 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
Client -> pod (CONNECT to the SP) GET saml.threatpulse.net:8443
Pod -> client HTTP 302 to: http://idp-url/bcca/saml/idp/?SAMLRequest=
- 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)
Client -> IDP GET http://idp-url/bcca/saml/idp/?SAMLRequest= (with <AuthnRequest>)
- The SP told the client to redirect to the IDP (with the <AuthnRequest> that the SP provided)
IDP -> client HTTP 401 Authentication required!
- 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)
client -> IDP GET http://idp-url/bcca/saml/idp/?SAMLRequest=
IDP -> client HTTP 200 OK: HTML Form that is with "SAMLResponse"
- 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
<form action="https://saml.threatpulse.net:8443/saml/saml_realm/bcsamlpost" method="POST">
<input type="hidden" name="SAMLResponse" value="PD94......(large-value-here)......=" />
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=...
- 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:
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/
- 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)
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 WSSA:
- Once the WSSA is in the connecting phase, a request is sent to http://pod.threatpulse.com/api/v1/check_auth. The endpoint will return an HTTP 204 No Content response.
- The above request is opened on the browser which gets redirected (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 browser 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.
- 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.
- 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.
- 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.