updates to doc for zdew/ext-jwt-signer

docusaurus/docs-policies/new-project-template/NF_EULA.md

@@ -1,6 +1,6 @@
 # NetFoundry End User License Agreement
 
-This End User License Agreement (" **Agreement**") is between NetFoundry, Inc. (" **NetFoundry**"),
+This End User License Agreement (" **Agreement**") is between NetFoundry Inc. (" **NetFoundry**"),
 and the individual, organization, or entity using the NetFoundry software (the " **Software**") pursuant to
 this Agreement (" **Customer**").
 

docusaurus/docs/downloads.mdx

@@ -33,7 +33,7 @@ This app provides the Ziti tunneler background service (`ziti-edge-tunnel`) and
 
 [Download Ziti Desktop Edge for Windows from GitHub](https://github.com/openziti/desktop-edge-win/releases/latest)
 
-[Read about tunneling in Windows](/reference/tunnelers/02-windows.md)
+[Read about tunneling in Windows](/reference/tunnelers/02-windows/index.md)
 
 <br/><br/>
 

docusaurus/docs/reference/tunnelers/02-windows/_category_.yml

@@ -0,0 +1,5 @@
+label: Windows
+position: 02
+link:
+  type: doc
+  id: reference/tunnelers/windows/index

docusaurus/docs/reference/tunnelers/02-windows/add-ids/10-ott.md

@@ -0,0 +1,20 @@
+# One Time Tokens
+
+Enrolling an identity with a "one time token" is possibly the most common form of adding an identity to
+a tunneler. This token is the original form supported by OpenZiti. It entails an operator provisioning an identity
+for a user. This process results in a single use (one-time) token that can be used to generated an OpenZiti identity,
+allowing the process to be trusted by the OpenZiti overlay network.
+
+## Prerequisites
+* An identity has been created and the one-time use JWT captured. If needed, follow this [guide](/docs/learn/core-concepts/identities/creating) to
+create an identity and one-time token. Once created, transfer the JWT file to the Windows machine you want to enroll.
+
+## Adding the Identity
+
+Go to the **Ziti Desktop Edge for Windows** and click **ADD IDENTITY** in the top right of the UI.
+![windows-with-jwt](/img/ext-jwt-signer/windows-with-jwt.png)
+
+After the context menu pops up, choose "With JWT". Select the JWT file and your identity will be enrolled.
+You can now selectively enable/disable the service and see how many individual services your identity has access to.
+
+![windows-after-enroll](/img/clients/windows-after-enroll.png)

docusaurus/docs/reference/tunnelers/02-windows/add-ids/20-third-party-ca.md

@@ -0,0 +1,55 @@
+import Details from '@theme/MDXComponents/Details';
+
+# Third-Party CA
+
+OpenZiti supports adding identities where the key and certificate are provided by a third-party CA.
+
+## Prerequisites
+* ZDEW 2.5.2+
+* a third-party-ca (`ca`) has been configured and verified in the OpenZiti Network
+* an identity exists with an `external-id` properly mapped to a claim, 
+  see [External Id & x509 Claims](/docs/learn/core-concepts/security/authentication/10-third-party-cas.md#external-id--x509-claims)
+* The CA's JWT has been transferred to the computer running the ZDEW
+
+<Details>
+<summary><b>Obtaining the Third-Party CA JWT</b></summary>
+
+Adding an identity to a Windows machine that uses a third party CA requires the user or an operator to obtain a JWT
+ahead of time. This can be done in two different ways.
+<hr/>
+
+### Obtain the Third-Party CA JWT - ZAC
+
+Obtain a third party CA's JWT using the Ziti Admin Console. From the Authentication->Certificate Authorities page, 
+click on the icon in the JWT column for the appropriate CA and send the JWT to the user trying to add an
+identity.
+
+![ext-jwt-signer-basic](/img/zac-3rd-party-ca-jwt.png)
+
+<hr/>
+
+### Obtain the Third-Party CA JWT - Shell
+
+Alternatively, a request can be made to the OpenZiti controller's API to return the JWT. Make an HTTP GET to the controller's
+`/edge/management/v1/cas/${ca_id}/jwt` endpoint and save the JWT into a file. Using bash with `curl` this  might look
+something like:
+```text
+curl -X GET -sk \
+    -H "Content-Type: application/json" \
+    -H "zt-session: ${zt_session}" \
+    -o ${pki_root}/auto.jwt \
+    "https://my.openziti.controller.local:443/cas/${ca_id}/jwt"
+```
+</Details>
+
+## Adding the Identity
+
+With the JWT for the CA on the machine running the ZDEW, click on the "ADD IDENTITY" button in the top right of the
+screen. After the context menu pops up choose "With JWT". In the file dialog, select the third-party CA JWT file.
+
+![windows-with-jwt](/img/ext-jwt-signer/windows-with-jwt.png)
+
+After selecting the file, a dialog will appear asking for the key and certificate to use when adding the identity. 
+Select the appropriate key and certificate and click "Join Network"
+
+![third party ca](/img/ext-jwt-signer/windows-3rd-party-ca.png)

docusaurus/docs/reference/tunnelers/02-windows/add-ids/_category_.yml

@@ -0,0 +1,5 @@
+label: Adding Identities
+position: 02
+link:
+  type: doc
+  id: reference/tunnelers/windows/add-ids/index

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/30-ext-jwt.mdx

@@ -0,0 +1,52 @@
+import Details from '@theme/MDXComponents/Details';
+import AboutExtAuth from './_about-ext-jwt.md'
+
+# By JWT
+
+<AboutExtAuth />
+
+## Prerequisites
+* OpenZiti Controller 1.2+
+* ZDEW 2.5.2+
+* an `external-jwt-provider` is properly configured
+* an identity exists with an `external-id` field set to a value provided from the external provider
+* the OpenZiti network operator has sent the Windows machine the network jwt file
+
+<Details>
+<summary><b>Obtaining the Network JWT</b></summary>
+
+Adding an identity to a Windows machine that uses an external provider as the primary authentication mechanism with a JWT
+requires the user or an operator to obtain a JWT ahead of time. This can be done in two different ways.
+<hr/>
+
+### Obtain the Network JWT - ZAC
+
+Obtain a controller's network JWT using the Ziti Admin Console. From the Authentication->JWT Signers page, click on 
+"Download Network JWT" located on the top right, near the "plus" icon and send the JWT to the user trying to add an
+identity.
+
+![ext-jwt-signer-basic](/img/ext-jwt-signer/zac-ext-jwt-signer-basic.png)
+<hr/>
+
+### Obtain the Network JWT - Shell
+
+Alternatively, a request can be made to the OpenZiti controller's API to return the JWT. Make an HTTP GET to the controller's
+`/network-jwts` endpoint and extract the `token` field and save this content to a JWT. Using bash, `curl` and `jq` this
+might look something like:
+```text
+curl -s https://my.openziti.controller.local:443/network-jwts | jq -r .data[].token > my-network-jwt
+```
+</Details>
+
+## Adding the Identity
+
+With the JWT on the Windows machine to be added, click on the "ADD IDENTITY" button in the top right of the screen. 
+After the context menu pops up choose "With JWT". In the file dialog, select the network JWT file and the identity will
+be added to the system.
+
+![windows-with-jwt](/img/ext-jwt-signer/windows-with-jwt.png)
+
+## Authenticating
+
+Once an identity is added for a network leveraging an external provider. [See Authenticating](./authenticating)
+for more details about how to authenticate to the network.

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/40-ext-jwt-url.mdx

@@ -0,0 +1,36 @@
+import Details from '@theme/MDXComponents/Details';
+import AboutExtAuth from './_about-ext-jwt.md'
+import ExtJwtFlow from './_ext-jwt-flow.md'
+import ExtJwtFlowMulti from './_ext-jwt-flow-multi.md'
+
+# By URL
+
+<AboutExtAuth />
+
+Adding an identity by URL is very straight-forward. Deliver the root URL of the OpenZiti controller to the user, and
+send them the following instructions.
+
+## Prerequisites
+* OpenZiti Controller 1.2+
+* ZDEW 2.5.2+
+* an `external-jwt-provider` is properly configured
+* an identity exists with an `external-id` field set to a value provided from the external provider
+* the OpenZiti Controller is configured to serve a pre-configured trusted certificate. The certificate must be verifiable
+  by the OS without additional information such as using a widely trusted CA or the Windows administrator has
+  added the certificate chain to the OS trust store
+
+## Adding the Identity
+
+To add an identity to Windows by URL, first start by clicking on the "ADD IDENTITY" button in the top right of the screen.
+After the context menu pops up, select the "With URL" option. 
+
+![With URL](/img/ext-jwt-signer/windows-with-url.png)
+
+A dialog will appear. Enter a valid https url to a controller and click
+
+![With URL](/img/ext-jwt-signer/windows-with-url-dialog.png)
+
+## Authenticating
+
+Once an identity is added for a network leveraging an external provider. [See Authenticating](./authenticating)
+for more details about how to authenticate to the network.

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/50-authenticating.mdx

@@ -0,0 +1,11 @@
+import ExtJwtFlow from './_ext-jwt-flow.md'
+import ExtJwtFlowMulti from './_ext-jwt-flow-multi.md'
+
+# Authenticating
+
+## Single External Provider
+<ExtJwtFlow/>
+
+
+## More Than One External Provider
+<ExtJwtFlowMulti/>

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/_about-ext-jwt.md

@@ -0,0 +1,3 @@
+New with ZDEW 2.5.2+ and an OpenZiti Controller version 1.2+ is adding an identity to a Windows installation using
+externally provided authentication. This process involves mapping an identity provided by an identity provider to
+an OpenZiti Identity using the `external-id` field as well as configuring an `ext-jwt-signer`.

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/_ext-jwt-flow-multi.md

@@ -0,0 +1,30 @@
+If your network is configured with more than one external provider, a popup will be shown when clicking on
+the "authorize IdP" icon. The popup will contain a list of the providers to select from. Choosing a provider from the
+list will begin the authorization flow for the selected provider.
+
+![more than one provider](/img/ext-jwt-signer/windows-more-than-one-provider.png)
+
+### Saving a Preferred Provider
+
+When using external providers, it's likely users will want to assign a preferred provider as a default. Before
+authenticating, click on the detail entry for the given identity a default should be assigned to. A new screen will
+appear looking like the image shown below.
+
+![more than one provider](/img/ext-jwt-signer/windows-provider-prefs.png)
+
+To assign a default provider, click the desired provider and click the "Default provider?" checkbox. The UI will remember
+the setting when it is clicked. There is no need to 'save' this setting. When a default provider is selected on a network
+with multiple providers, no popup will be shown when clicking the "authorize IdP" icon.
+
+
+### Resetting a Preferred Provider
+
+To reset the default provider simply uncheck the "Default provider" checkbox. When first opening the identity details
+page, the default provider will be automatically selected. If another provider is highlighted, choose the default provider
+and uncheck the "Default provider" box. There is no need to 'save' this setting, the values is stored immediately.
+
+### Non-Default Provider
+
+If a default provider has been selected, users may still elect to authenticate with a different provider. To use a
+different provider than the default, open the identity details page and select the provider to authenticate with. Once
+selected, click "Authenticate With Provider" and the selected provider will be used to authenticate.

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/_ext-jwt-flow.md

@@ -0,0 +1,18 @@
+Once the JWT is accepted, a new identity will be added to the ZDEW. Initially, the identity will not be authorized and a
+new icon will show up indicating the user needs to authorize via the external provider. If a single external provider is
+configured for this OpenZiti overlay network, clicking the icon will being the Auth Flow with PKCE process. During this
+time, the ZDEW will be listening on port 20314.
+
+![Authenticating 1](/img/ext-jwt-signer/windows-auth-1.png)
+
+After successfully completing the authentication with the external provider, the browser will redirect to the listening
+port and complete the authentication flow. The user will be shown a screen that looks similar to this. The first time
+this screen is shown in a browser session, it will not automatically close. Subsequent authentication events should
+result in the tab automatically closing.
+
+![pkce-success](/img/ext-jwt-signer/zac-pkce-success.png)
+
+Assuming everything succeeds, the user will see the normal information shown by an authenticated identity.
+
+![after-pkce-success.png](/img/ext-jwt-signer/windows-after-pkce-success.png)
+

docusaurus/docs/reference/tunnelers/02-windows/add-ids/ext-providers/index.md

@@ -0,0 +1,36 @@
+import MDXComponents from '@theme-original/MDXComponents';
+import Details from '@theme/MDXComponents/Details';
+import Code from '@theme/MDXComponents/Code';
+import Highlight from "/src/components/OpenZitiHighlight";
+
+import ExternalAuthConfigAbout from '../../../_ext-auth-config_about.md'
+import ExternalAuthConfigExample from '../../../_ext-auth-config_example.md'
+
+# External Providers
+
+The Ziti Desktop Edge for Windows (ZDEW) 2.5.2+ supports integrating with external identity providers such as Google, Auth0,
+Yahoo, Facebook, etc. The OpenZiti Controller has an authentication system utilizing JWTs as authentication tokens.
+The [External JWT Signers](/docs/learn/core-concepts/security/authentication/50-external-jwt-signers.md) functionality
+allows an OpenZiti operator to configure the OpenZiti overlay to use external providers as sources of authentication.
+
+External providers can now be used for primary authentication with the Ziti Desktop Edge for Windows. The default authorization
+policy for an OpenZiti controller will allow external authentication by default. If preferred, a new auth-policy can be
+declared and assigned to identities, restricting those identities from using other authentication mechanisms and
+exclusively rely on external authentication providers.
+
+<ExternalAuthConfigAbout />
+
+<Details>
+<summary>Example Configuring OpenZiti for External Auth</summary>
+
+<ExternalAuthConfigExample />
+
+</Details>
+
+## Add an Externally Authenticated Identity
+
+After configuring the OpenZiti Controller with an external JWT signer, the ZDEW can be used to add an identity using the
+external provider.
+
+* [External JWT Provider - JWT](./ext-jwt) - Add an identity using the configured provider and network JWT
+* [External JWT Provider - URL](./ext-jwt-url) - Add an identity using the configured provider and URL

docusaurus/docs/reference/tunnelers/02-windows/add-ids/index.md

@@ -0,0 +1,15 @@
+# Adding Identities
+
+Adding an identity is often referred to as enrolling an identity. This is the act of bootstrapping trust between
+the computer adding an identity and the OpenZiti Controller.
+
+There are numerous mechanisms to bootstrap this trust and enroll an identity to a tunneler. The most common
+is probably via a JWT using a one-time token. There are however, other enrollment types. Currently, each type of
+enrollment comes in the form of a JWT with one notable exception - the URL.
+
+## Types of Enrollment Supported
+
+* [One-Time Token](./ott) - Add an identity with a single use token. The most common option
+* [Third-Party CA](./third-party-ca) - Add an identity using a third-party CA
+* [External JWT Provider - JWT](./ext-providers/ext-jwt) - Add an identity using the configured provider and network JWT
+* [External JWT Provider - URL](./ext-providers/ext-jwt-url) - Add an identity using the configured provider and URL