Add doc for configuring IdPs with ext-jwt-signers

docusaurus/docs/guides/external-auth/formatting-demo.md

@@ -0,0 +1,62 @@
+# Code Block Formatting Demo
+
+This here is a "plain" code block
+```
+results: total 12
+drwxr-xr-x  5 user staff 160 Jan 28 12:34 .
+drwxr-xr-x 20 user staff 640 Jan 28 12:34 ..
+-rw-r--r--  1 user staff   0 Jan 28 12:34 file.txt
+```
+
+This here is a "example" block. an example with just results and no
+matching "language" ends up rendering like a plain code block
+```example
+results: total 12
+drwxr-xr-x  5 user staff 160 Jan 28 12:34 .
+drwxr-xr-x 20 user staff 640 Jan 28 12:34 ..
+-rw-r--r--  1 user staff   0 Jan 28 12:34 file.txt
+```
+
+This here is a "example" block that has bash attached to it but does
+not have a command/code section
+```example-bash
+results: total 12
+drwxr-xr-x  5 user staff 160 Jan 28 12:34 .
+drwxr-xr-x 20 user staff 640 Jan 28 12:34 ..
+-rw-r--r--  1 user staff   0 Jan 28 12:34 file.txt
+```
+
+This is the paragraph leading up to the example. the example
+is down below this text. here is more text just to emulate
+what a long bit of text before the example might look like.
+
+```example-python
+description:
+this is a longer description. it's long. it's trying to be really,
+really long just to put some words between you and the upcoming
+example. more than the code below it. I'm just typing a bunch of stuff
+here so that it is a lot
+
+command:
+ls -l
+
+code:
+print("Hello, World!")  # Python
+print("Hello, World!")  # Python
+print("Hello, World!")  # Python
+results: the results go here
+and this is fundd
+```
+
+```javascript
+console.log("Hello, World!"); // JavaScript
+```
+
+```c
+#include <stdio.h>
+int main() { printf("Hello, World!\n"); return 0; } // C
+```
+
+```sh
+echo "Hello, World!" # Bash
+```

docusaurus/docs/guides/external-auth/index.md

@@ -0,0 +1,84 @@
+# External Authentication
+
+OpenZiti external jwt signers are intended to be used with various external providers. Arguably, the most common type of
+provider are external authorization servers, often referred to as IdPs. This guide will focus on this kind of external
+provider and will focus on one authorization flow in particular:  Authorization Code Flow with PKCE.
+
+OpenZiti can be configured to delegate authentication to external providers using
+[external jwt signers](../../learn/core-concepts/security/authentication/50-external-jwt-signers.md). Configuring
+OpenZiti to use external providers can be simple, however if you're new to the concepts (specifically the
+[Proof Key for Code Exchange flow](https://www.rfc-editor.org/rfc/rfc7636)) it may be tricky to setup. There are
+numerous excellent resources on the internet to learn more about OIDC, OAuth, and the PKCE flow if you need or want to
+learn more.
+
+The guides provided here are meant to get you up and running quickly and guide you through configuring the OpenZiti
+Controller to allow clients such as OpenZiti tunnelers to delegate authentication to a centralized provider.
+
+## Authentication Policies
+
+The OpenZiti Controller will come with a default authorization policy that allows for all primary authentication
+methods: username/password, certificate-based, exteral-jwt-signer. If you are familiar with OpenZiti concepts,
+additional auth-policies can be created and the default policy modified. If you are new to OpenZiti, it's recommended
+you leave the default [authentication policy](../..
+/learn/core-concepts/security/authentication/30-authentication-policies.md) intact.
+
+> [!TIP]
+> It's often useful to use certificate-based authentication (the "normal", one-time-token enrollment) along with
+> an external provider providing a strong two-factor authentication scheme. This would ensure the device in use is
+> trusted and would ensure a trusted human is using the device: human + device.
+
+## Configuring the Controller With an External JWT Signer for OIDC
+
+Correctly configuring an external JWT signer for use with OIDC requires a few key fields to be supplied. Most of
+these fields are discoverable using the openid discovery endpoint. Generally, this will be a URl accessible by
+adding `./.well-known/openid-discovery` to your identity provider issuer URL. For example, if you were using
+Keycloak as your authorization provider of choice, you might have a Keycloak realm at
+https://my.keycloak.openzitiio/realms/example. If that were the case, the openid discovery endpoint would be located at
+https://my.keycloak.openzitiio/realms/example/.well-known/openid-configuration.
+
+Using the `.well-known/openid-configuration` will get much of the information required to successfully configure the
+controller with an ext-jwt-signer for OIDC authentication. From this url, gather the following pieces of information:
+* issuer
+*
+
+```yaml-table
+- CVE: cve-1-here
+  Advisory: 30
+  Notice: New York
+- CVE: Bob
+  Advisory: 25  
+  Notice: San Francisco
+```
+
+```yaml
+- CVE: cve-1-here
+  Advisory: 30
+  Notice: New York
+- CVE: Bob
+  Advisory: 25  
+  Notice: San Francisco
+```
+
+```code
+description: desc
+---
+command: ls -l
+---
+results:
+here are the results
+they could be super long
+
+```
+
+
+```code
+description: This command lists all files in the current directory.
+command: ls -la
+results: total 12
+drwxr-xr-x  5 user staff 160 Jan 28 12:34 .
+drwxr-xr-x 20 user staff 640 Jan 28 12:34 ..
+-rw-r--r--  1 user staff   0 Jan 28 12:34 file.txt
+```
+
+
+a

docusaurus/docusaurus.config.js

@@ -2,9 +2,8 @@
 // Note: type annotations allow type checking and IDEs autocompletion
 
 // This docusaurus.config.js is used by GitHub Pages to build the site with baseUrl: '/docusaurus/'
+import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
 
-//const lightCodeTheme = require('prism-react-renderer/themes/github');
-//const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 const { themes: prismThemes } = require('prism-react-renderer');
 
 /** @type {import('@docusaurus/types').Config} */
@@ -37,7 +36,7 @@ const config = {
     mermaid: true,
   },
   themes: ['@docusaurus/theme-mermaid'],
-
+  
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -244,9 +243,12 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/openziti/ziti-doc/tree/main/docusaurus',
-
+          editUrl: 'https://github.com/openziti/ziti-doc/tree/main/docusaurus',
+          beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives, ],
+          remarkPlugins: [
+            require('./src/plugins/remark/remark-yaml-table'),
+            require('./src/plugins/remark/remark-code-block'),
+          ],
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
@@ -314,7 +316,7 @@ const config = {
         sidebar: {
           hideable: true,
           autoCollapseCategories: true,
-        }
+        },
       },
       navbar: {
         title: '',
@@ -416,8 +418,11 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} NetFoundry Inc.`,
       },
       prism: {
-		  theme: prismThemes.github,
-		  darkTheme: prismThemes.dracula,
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
+        // scala necessary to avoid Cannot set properties of undefined (setting 'triple-quoted-string')
+        // see https://github.com/Redocly/redoc/issues/2511
+        additionalLanguages: ['python', 'java', 'csharp', 'go', 'bash', 'scala'],
       },
     },
 };

docusaurus/package.json

@@ -28,14 +28,17 @@
     "echarts": "^5.6.0",
     "echarts-for-react": "^3.0.2",
     "jquery": "^3.7.1",
+    "js-yaml": "^4.1.0",
     "prism-react-renderer": "2.4.1",
     "react": "^19.0.0",
     "react-device-detect": "^2.2.3",
     "react-dom": "^19.0.0",
     "react-github-btn": "^1.4.0",
     "react-helmet": "^6.1.0",
     "react-player": "^2.16.0",
-    "redocusaurus": "^2.2.1"
+    "redocusaurus": "^2.2.1",
+    "remark-github-admonitions-to-directives": "^2.1.0",
+    "unist-util-visit": "^5.0.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.7.0",