When logging in with SURFconext multiple systems are involved: the authentication system of the institution (the IdP), SURFconext, and the service onto which the user is logging in (the SP). Between these three communication occurs through the SAML communication protocol. In a SAML-trace all these SAML messages between parties are recorded. With this information we can pinpoint what went wrong at which party during the logging in.
Tools for recording SAML messages in an insightful manner are available in two browsers: Mozilla Firefox en Google Chrome. Below you'll find a manual for both, although at the moment only the tracer of Firefox produces files which we can use for problem analysis.
Firefox - SAML tracer
SAML-tracer is a Firefox extension which, upon activation, records all HTTP traffic between the browser and the internet. SAML is also send with HTTP and can be made visible in the SAML-tracer by clicking the SAML tab at HTTP GET and HTTP POST messages that contain SAML.
With SAML-tracer you can save all recorded HTTP messages, the trace, to a file. This file can later be loaded into SAML-tracer for later viewing of the HTTP and SAML messages. When the standard method does not succeed in finding the solution to a log in problem with SURFconext, our support can request for such a SAML trace to be send to them for detailed investigation.
Installation
Follow these steps for installing the SAML-tracer:
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open Firefox. | |
| 2 | Navigate to the following site |
|
| 3 | Press "+ Add to Firefox" (+ Toevoegen aan Firefox). |
|
| 4 | Press "Add" to add the plugin to your browser. |
|
| 5 | Check the box to allow the Plugin to work in a Private-Window. Then press "Okay, Got it" to confirm. |
|
Making a trace
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open the SAML-tracer. The icon can be found in the top right corner next to the "hamburger menu" (☰) to the right of the URL bar. |
|
| 2 | A new window opens and the trace starts automatically. You can press the "X Clear" button to reset the trace before going to the next step. |
|
| 3 | Navigate to the service you want to login to. | |
| 4 | Attempt to login. | |
| 5 | Follow the steps under section "Export to file" to export the trace safely after the login has been completed. |
While the SAML-trace window is open, all HTTP-messages are recorded. To get a complete trace it is therefore important to open SAML-tracer before starting the login, and keep it open until the logging in procedure has completed.
Export to file
Once you have made a trace you can save it to a file.
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Click on the 'Export'-button in the taskbar of the 'Saml tracer'-window. |
|
| 2 | Select 'Mask Values', to hide sensitive information from the trace. See for more information:: "Privacy and hiding values". |
|
| 3 | Click on Export. | |
| 4 | Give the file a name and location to save. | |
| 5 | Mail the file to support@surfconext.nl. |
Chrome - SAML Chrome Panel
SAML Chrome Panel is an extension similar to Firefox's SAML-tracer. It records all HTTP traffic between the browser and the internet. SAML is also send with HTTP and can be made visible in the SAML-tracer by clicking the SAML tab at HTTP GET and HTTP POST messages that contain SAML.
With SAML-tracer you can save all recorded HTTP messages, the trace, to a file. This file can later be loaded into SAML-tracer for later viewing of the HTTP and SAML messages. When the standard method does not succeed in finding the solution to a log in problem with SURFconext, our support can request for such a SAML trace to be send to them for detailed investigation.
Installation
To install the SAML Chrome Panel extension:
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open Chrome. | |
| 2 | Navigate to the following page. | |
| 3 | Press "Add to Chrome" (Toev. aan Chrome). |
|
| 4 | Press Add Extension (Extensie toevoegen) to add the plugin to the browser. |
|
Recording a SAML trace
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open the SAML-tracer. You can find the icon in the top right of the browser, next to the URL bar |
|
| 2 | A new window opens and the trace starts automatically. You can press the "X Clear" button to reset the trace before going to the next step. |
|
| 3 | Navigate to the service you want to login to. | |
| 4 | Attempt to login. | |
| 5 | Follow the steps under section "Export to file" to export the trace safely after the login has been completed. |
Export trace
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Click on the 'Export'-button in the taskbar of the 'Saml tracer'-window. |
|
| 2 | Select 'Mask Values', to hide sensitive information from the trace. See for more information:: "Privacy and hiding values". |
|
| 3 | Click on Export. | |
| 4 | Give the file a name and location to save. | |
| 5 | Mail the file to support@surfconext.nl. |
Edge - SAML-tracer
Edge SAML-tracer is an extension similar to Firefox's SAML-tracer. It records all HTTP traffic between the browser and the internet. SAML is also send with HTTP and can be made visible in the SAML-tracer by clicking the SAML tab at HTTP GET and HTTP POST messages that contain SAML.
With SAML-tracer you can save all recorded HTTP messages, the trace, to a file. This file can later be loaded into SAML-tracer for later viewing of the HTTP and SAML messages. When the standard method does not succeed in finding the solution to a log in problem with SURFconext, our support can request for such a SAML trace to be send to them for detailed investigation.
Installation
To install the SAML-tracer extension:
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open Microsoft Edge. | |
| 2 | Navigate to the following page. | |
| 3 | Press "Get" (Toev. aan Edge). |
|
| 4 | Press Add Extension (Extensie toevoegen) to add the plugin to the browser. |
|
Recording a SAML trace
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Open the SAML-tracer. You can find the icon in the top right of the browser, next to the URL bar |
|
| 2 | A new window opens and the trace starts automatically. You can press the "X Clear" button to reset the trace before going to the next step. |
|
| 3 | Navigate to the service you want to login to. | |
| 4 | Attempt to login. | |
| 5 | Follow the steps under section "Export to file" to export the trace safely after the login has been completed. |
Export trace
| Stap | Actie | Afbeelding |
|---|---|---|
| 1 | Click on the 'Export'-button in the taskbar of the 'Saml tracer'-window. |
|
| 2 | Select 'Mask Values', to hide sensitive information from the trace. See for more information:: "Privacy and hiding values". |
|
| 3 | Click on Export. | |
| 4 | Give the file a name and location to save. | |
| 5 | Mail the file to support@surfconext.nl. |
Privacy and security
A SAML-trace contains valuable information: for the user or the help desk to investigate what happens during authentication, but also for hackers. Session cookies and information submitted into the browser by the user, including username and passwords, are collected by the SAML-tracer. Aside from this a trace can also include privacy sensitive information in the form of attributes, such as institution name and email address, when this information is exchanged between parties. Therefore the contents of a SAML-trace should be treated as sensitive information.
The Firefox plugin has options for masking or removing these sensitive values. The Chrome plugin does not yet have this feature and hence is only suitable for private use.
Privacy and hiding values
To prevent unintended leaking of sensitive information the SAML-tracer offers users multiple degrees of hiding or removing this information when storing the trace to a file. There are three options:
- None - the trace is stored unchanged, values are not masked.
- Mask values - Masks cookies and POST arguments with their SHA-1 hash value. This makes the information more difficult to read. It is the default option.
- Remove values - removes cookies and POST arguments. The contents of the SAML messages is stored. A SAML message can still contain sensitive cookie information when it is generated from a “IdP initiated” login. However this data has a usefulness time window of 5 minutes making sure attackers have only a very limited time to apply stolen data.