expand password reset documentation

content/docs/faq.md

@@ -8,7 +8,7 @@ draft: false
 
 ([issue](https://github.com/hrfee/jellyfin-accounts/issues/12))
 
-* The best way to get around this (if you're using a reverse proxy) is to selectively not send the users real IP to jellyfin on the paths that are used for password resets. Read more and see an example [here]({{<relref "/docs/password-resets" >}}).
+* The best way to get around this (if you're using a reverse proxy) is to selectively not send the users real IP to jellyfin on the paths that are used for password resets. Read more and see an example [here]({{<relref "/docs/pwr/remote-network" >}}).
 
 * Another method is to tell Jellyfin to treat all traffic as local. I don't recommend this as it stops you from using other features like remote bandwidth limiting. In Jellyfin, go to Dashboard > Networking (under Advanced), and set the 'LAN networks' setting to `0.0.0.0/0`.
 
@@ -54,7 +54,7 @@ Make sure to check the ports you are using, as generally they correspond to the
 
 ## Does this need to be installed on the same host as Jellyfin?
 
-Not necessarily. For invite functionality, an http connection is only necessary. However, password resets require jfa-go to be able to access Jellyfin's installation directory, so you'll need to use SMB or similar to mount it.
+Not necessarily. For invite functionality, an http connection is only necessary. Password resets through the "User Page" Feature will also function, see [this note](/docs/pwr/#method-4-my-account-reset). However, password resets through the Jellyfin UI require jfa-go to be able to access its config directory, so you'll need to use SMB or similar to mount it. See [this page](/docs/pwr/#prerequisite-for-methods-1-3) for help finding the correct directory.
 
 ## Can i `go get` this repository?
 No, because the supporting files (CSS, email templates, etc.) need to be compiled and placed next to the executable before it will run, and `go get` will only compile the app itself.

content/docs/pwr/_index.md

@@ -0,0 +1,50 @@
+---
+title: "Password Resets"
+date: 2023-09-09T13:32:35+01:00
+draft: false
+---
+
+## Password Reset Methods
+There are 4 main methods for facilitating password resets. They are ordered from (in my opinion, at least) worst to best, although your choice will depend on your situation.. They are described below:
+1) **Through Jellyfin (PIN Reset)**: The user clicks "Forgot Password" on the Jellyfin login screen, and enters their username. Jellyfin generates a file with a PIN code. Jfa-go reads this file, and sends the PIN to any contact methods associated with the user (Email, Discord, Matrix or Telegram). The user then types this PIN when Jellyfin asks for it.
+2) **Partially through Jellyfin (Link Reset)**: Similarly to above, the user clicks "Forgot Password" and enters their username. Jfa-go reads the file with the PIN, but instead sends the user a link that will automatically set their password to the PIN, as Jellyfin would if they typed it in.
+3) **Partially through Jellyfin (Internal Reset)**: Same as above, but the link sent to the user takes them to a special jfa-go password reset page.
+4) **Through Jfa-go (User Page/"My Account" Reset)**: The user visits the "My Account" page (`your-jfa-go.site/my/account`), and presses the "Forgot Password" button. They enter their Jellyfin username, or address/ID of a contact method (email address or discord/telegram/matrix username). A message with a link is sent, which links to the same password reset page described in method 2.
+
+## Pros/Cons
+
+{{< include-html "content/docs/pwr/pwr-pros-cons.html" >}}
+
+## Setting them up
+
+### Prerequisite for Methods 1-3
+jfa-go will need access to your Jellyfin config directory, as this is where it places the files containing PINs.
+  * General Advice: When initiating a password reset in Jellyfin, a message will pop up telling you the location the PIN file was created in. This is the easisest way to find the directory. However, this feature was [broken in older versions](https://github.com/jellyfin/jellyfin/issues/6093) and still is for some.
+
+![PWR Directory Screenshot](/pwr-directory.png)
+
+
+  * Docker: The directory you mounted to `/config` in the container, e.g. for `docker create ... -v /opt/jellyfin:/config`, the config directory would be `/opt/jellyfin`.
+    * If you're also running jfa-go in docker, make sure to mount it to `/jf` within the container; jfa-go should default to that path.
+  * Windows: The directory should be `C:\ProgramData\Jellyfin\Server` or similar.
+  * Ubuntu/Debian: Should be `/var/lib/jellyfin`, or one of it's sub-directories. initiate a Password Reset and look for a file beginning with `passwordreset` to confirm.
+
+### Method 1 (PIN Reset)
+
+* Enable Password Resets in settings, that's all.
+
+### Method 2 (Link Reset)
+
+* Enable Password Resets, and in the same section, enable *"Use reset link instead of PIN"*.
+
+### Method 3 (Internal Reset)
+
+* Enable both the settings for the above 2 methods, and also enable *"Set password through link"*.
+
+### Method 4 ("My Account" Reset)
+
+* Enable all of the settings listed above.
+* Enable the *User Page* feature.
+* Ensure *Use Jellyfin for Authentication* in *General* is enabled.
+
+* **Note**: Despite enabling the above features, jfa-go **does not need access** to the Jellyfin config directory if you only want this method to be used. You can point the directory to wherever, it doesn't matter.

content/docs/pwr/pwr-pros-cons.html

@@ -0,0 +1,95 @@
+<table>
+    <tbody>
+        <tr>
+            <th>Methods</th>
+            <th>Pros</th>
+            <th>Cons</th>
+        </tr>
+        <tr>
+            <td>PIN Reset</td>
+            <td>
+                <ul>
+                    <li>Initiated through Jellyfin</li>
+                </ul>
+            </td>
+            <td>
+                <ul>
+                    <li>
+                        Can confuse user
+                        <ul>
+                            <li>Jellyfin doesn't tell you to check email/discord/telegram/matrix for a message with a PIN.</li>
+                        </ul>
+                    </li>
+                    <li>
+                        No way to enforce password requirements
+                        <ul>
+                            <li>User's password is set to the PIN, user must set their new password through Jellyfin.</li>
+                        </ul>
+                    </li>
+                    <li>Ombi Password will not change (if enabled)</li>
+                </ul>
+            </td>
+        </tr>
+        <tr>
+            <td>Link Reset</td>
+            <td>
+                <ul>
+                    <li>User doesn't have to keep Jellyfin's Password Reset page open</li>
+                    <li>User doesn't have to type anything</li>
+                    <li>Reminds user to change their password after it resets to the PIN code</li>
+                    <li>Automatically changes password to PIN on Ombi</li>
+                </ul>
+            </td>
+            <td>
+                <ul>
+                    <li>Same as above</li>
+                    <li>User will also have to manually change their Ombi password from the PIN</li>
+                </ul>
+            </td>
+        </tr>
+        <tr>
+            <td>Internal Reset</td>
+            <td>
+                <ul>
+                    <li>
+                        Enforces password requirements
+                        <ul>
+                            <li>Users are shown a page similar to the "Create Account" form</li>
+                        </ul>
+                    </li>
+                    <li>New password is also applied to Ombi</li>
+                </ul>
+            </td>
+            <td>
+                <ul>
+                    <li>Can confuse user in the same way as the above</li>
+                </ul>
+            </td>
+        </tr>
+        <tr>
+            <td>"My Account" Reset</td>
+            <td>
+                <ul>
+                    <li>Performed in the same place as other account management tasks</li>
+                    <li>
+                        Explains itself better than other methods
+                        <ul>
+                            <li>The page tells the user to check their inbox for a link</lu>
+                        </ul>
+                    </li>
+                </ul>
+            </td>
+            <td>
+                <ul>
+                    <li>
+                        "My Account" page may not be familiar to user
+                        <ul>
+                            <li>For this feature to be used, users must know the "My Account" page exists</li>
+                            <li>The page is already referenced on the signup form, but mentioning it on your Jellyfin instance or app portal might be a good idea.</li>
+                        </ul>
+                    </li>
+                </ul>
+            </td>
+        </tr>
+    </tbody>
+</table>

content/docs/password-resets.md → content/docs/pwr/remote-network.md

@@ -14,7 +14,7 @@ If you're using a reverse proxy, Jellyfin knows the real IP of a user through th
 
 ***Example NGINX config***
 ```nginx
-    # add to your \`server {\` section
+    # add to your `server { ... }` block
 
     # rest of jellyfin config
 

content/menu/index.md

@@ -17,7 +17,8 @@ headless = true
   - [Docker]({{< relref "/docs/build/docker" >}})
 - [Development]({{< relref "/docs/dev" >}})
   - [Web API Docs](https://api.jfa-go.com)
-- [Password Resets outside local network]({{< relref "/docs/password-resets" >}})
+- [Password Resets]({{< relref "/docs/pwr/" >}})
+  - [Password Resets outside local network]({{< relref "/docs/pwr/remote-network" >}})
 - [Reverse Proxying]({{< relref "/docs/reverse-proxy" >}})
 - [TLS Setup]({{< relref "/docs/tls" >}})
 - [Translation]({{< relref "/docs/translation" >}})

layouts/shortcodes/include-html.html

@@ -0,0 +1,2 @@
+{{ $file := .Get 0 }}
+{{ $file | readFile | safeHTML }}