From aad43d4acc65f1033774cff0a9dd7b36094e9f61 Mon Sep 17 00:00:00 2001
From: James Elliott <james-d-elliott@users.noreply.github.com>
Date: Fri, 26 Aug 2022 13:50:51 +1000
Subject: [PATCH] docs: har reference guide (#3900)

---
 .../reference/guides/domain-sanitizaiton.md   | 30 ++++++++
 .../en/reference/guides/http-archive-file.md  | 70 +++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 docs/content/en/reference/guides/domain-sanitizaiton.md
 create mode 100644 docs/content/en/reference/guides/http-archive-file.md

diff --git a/docs/content/en/reference/guides/domain-sanitizaiton.md b/docs/content/en/reference/guides/domain-sanitizaiton.md
new file mode 100644
index 000000000..643fc9a14
--- /dev/null
+++ b/docs/content/en/reference/guides/domain-sanitizaiton.md
@@ -0,0 +1,30 @@
+---
+title: "Domain Sanitization"
+description: "This guide describes and helps users sanitize provided files to hide their domain"
+lead: "This guide describes and helps users sanitize provided files to hide their domain."
+date: 2022-06-20T10:05:55+10:00
+draft: false
+images: []
+menu:
+  reference:
+    parent: "guides"
+weight: 220
+toc: true
+---
+
+Some users may wish to hide their domain in files provided during troubleshooting. While this is discouraged, if a user
+decides to perform this action it's critical for these purposes that you hide your domain in a very specific
+way. Most editors allow replacing all instances of a value, utilizing this is essential to making troubleshooting
+possible.
+
+## General Rule
+
+Only replace the purchased portion of domains. For example if you have `auth.abc123.com` and `app.abc123.com` they
+should become `auth.example.com` and `app.example.com`, i.e. replace all instances of `abc123.com` with `example.com`.
+
+## Multiple Domains
+
+*__Replacement Value:__* `example#.com` (where `#` is a unique number per domain)
+
+In instances where there are multiple domains it's recommended these domains are replaced with `example1.com`,
+`example2.com`, etc.
diff --git a/docs/content/en/reference/guides/http-archive-file.md b/docs/content/en/reference/guides/http-archive-file.md
new file mode 100644
index 000000000..138c66d57
--- /dev/null
+++ b/docs/content/en/reference/guides/http-archive-file.md
@@ -0,0 +1,70 @@
+---
+title: "HTTP Archive Files"
+description: "This guide describes and helps users create HTTP Archive (HAR) files"
+lead: "This guide describes and helps users create HTTP Archive (HAR) files."
+date: 2022-06-20T10:05:55+10:00
+draft: false
+images: []
+menu:
+  reference:
+    parent: "guides"
+weight: 220
+toc: true
+aliases:
+  - /r/har
+---
+
+## Introduction
+
+The HTTP Archive File Format (HAR) is a common developer import/export format which shows web requests that browsers
+make including all headers which includes cookies, forms submitted, etc.
+
+This format allows users to open the developer tools, perform several actions, and then export a file with all of the
+requests that still exist in the network tab of the developer tools. This file is stored in JSON which makes it easy to
+view what information exists before sharing it. Subsequently users may import this file on another browser and see all
+of these requests which makes it easier to debug certain situations without having to replicate an environment or be
+present in an environment.
+
+## Sanitization
+
+The following section outlines some helpful information if you wish to sanitize your HAR file to share it with others.
+
+### Domain
+
+See the dedicated [Domain Sanitization](domain-sanitizaiton.md) reference guide.
+
+### Security Sensitive Information
+
+*__Important:__ this file may contain sensitive information which should be sanitized manually before sharing it
+anywhere with anyone. Sensitive information can vary wildly but some of the key areas that may be sensitive when
+exporting this for troubleshooting with Authelia are:*
+- `Cookie` request header
+- `Set-Cookie` response header
+- Data sent to the following endpoints:
+  - `/api/firstfactor`: username / password
+  - `/api/*/identity/start`: the token query parameter
+  - `/api/secondfactor/*`: the post data
+
+## Instructions
+
+The following are instructions on how to perform valuable HAR exports. The instructions for Chrome / Chromium should be
+applicable in all Chromium based browsers, and likewise for Firefox based browsers.
+
+1. Open your browser.
+2. Open a blank tab.
+3. Press Ctrl + Shift + I to open the browser Developer Tools.
+4. Open the `Network` tab.
+5. Ensure the browser persists logs:
+   1. Firefox:
+      1. Select the `Network Settings` cog symbol at the top right of the `Network` tab.
+      2. Ensure `Persist Logs` is checked.
+   2. Chrome / Chromium:
+      1. Ensure `Preserve logs` in the top left of the `Network` tab is checked.
+6. Perform your intended requests, or the requests that have been requested.
+7. Export the HAR File:
+   1. Firefox:
+      1. Select the `Network Settings` cog symbol at the top right of the `Network` tab.
+      2. Select `Save All AS HAR`.
+   2. Chrome / Chromium:
+      1. Right click any request in the `Network` tab.
+      2. Select `Save all as HAR with content` at the bottom of the dialogue.