for openziti/ziti#2324 adds external JWT enrollment doc (#1238)

* for openziti/ziti#2324 adds external JWT enrollment doc

- adds documentation for ext-jwt-signer enrollment

Author: andrewpmartinez

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

@@ -13,7 +13,7 @@ _click here to see a list of guides to help you configure your selected [Identit
 OpenZiti utilizes and implements the [Authorization Code Flow with PKCE or PKCE flow](https://oauth.net/2/pkce/) 
 for authentication. This flow is well-known and numerous excellent resources on the internet explain what PKCE is 
 and what it entails. The guides here focuses on correctly configuring an OpenZiti 
-[external JWT signer](../../learn/core-concepts/security/authentication/50-external-jwt-signers.md) for use with an OIDC 
+[external JWT signer](../../learn/core-concepts/security/authentication/50-external-jwt-signers.mdx) for use with an OIDC 
 provider. 
 
 Correctly configuring an external jwt signer requires the careful attention. The fields below all correspond to fields 

docusaurus/docs/learn/core-concepts/security/_ext_jwt_enroll_details.md

@@ -0,0 +1,19 @@
+- `enrollToCertEnabled` - Allows clients with valid JWTs to request a certificate from the controller by providing a
+  [Certificate Signing Request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request). The resulting certificate will be used for authentication. The target `enrollAuthPolicyId` must be set
+  to a policy that allows certificate authentication. If `enrollAuthPolicyId` is not set, the default policy
+  will be used and must allow certificate authentication.
+- `enrollToTokenEnabled`- Allows clients with valid JWTs to continue to use JWTs for authentication. The target
+  policy must be set to a policy that allows External JWT Signer authentication. If `enrollAuthPolicyId` is not
+  set, the default policy will be used and must allow External JWT Signer authentication.
+
+
+Additionally, there are optional values that can be used to control which claims within the JWT are significant:
+
+- `enrollAttributeClaimsSelector` - a root level property name (e.g. `claims`) or a JSON pointer (e.g. `/claims`) that
+  points to a string or array of strings that will be used to populate the `attributes` field of the enrolling
+  identity. Defaults to no value set and identities will enroll without attributes.
+- `enrollAuthPolicyId` - the id of the authentication policy to use for the enrolling identity. Defaults to no value set
+  and the identity will enroll with the default authentication policy.
+- `enrollNameClaimsSelector` - the root level property name (e.g. `claims`) or a JSON pointer (e.g. `/claims`) that
+  points to a string that will be used to populate the `name` field of the enrolling identity.
+  Defaults to the subject property of the JWT (e.g. `/sub`)

docusaurus/docs/learn/core-concepts/security/authentication/10-third-party-cas.md

@@ -14,8 +14,8 @@ index zero and any required intermediate certificates afterwards.
 ## Usage 
 
 3rd Party CAs can be used in the following manners:
-- allows clients to enroll and authenticate automatically for at-scale network boarding - [Auto CA Enrollment](../enrollment.md#auto-ca-enrollment)
-- allows clients to enroll pre-created identities - [OTT CA Enrollment](../enrollment.md#ott-ca-enrollment)
+- allows clients to enroll and authenticate automatically for at-scale network boarding - [Auto CA Enrollment](../enrollment.mdx#auto-ca-enrollment)
+- allows clients to enroll pre-created identities - [OTT CA Enrollment](../enrollment.mdx#ott-ca-enrollment)
 - allows clients to map to pre-created identities using `externalId` and [X509 Claims](#external-id--x509-claims)
 
 ## Create
@@ -28,11 +28,11 @@ certificates will be validated. The following fields configure client authentica
 - `isAuthEnabled` - allows client certificates of the CA to attempt to enroll
 - `externalIdClaim` - configuration used to pull values out of the x509 client certificate used to match identity `externalId`, see [External Id & x509 Claims](#external-id--x509-claims)
 
-For [Auto CA Enrollment](../enrollment.md#auto-ca-enrollment) an identity is created on first authentication. 
+For [Auto CA Enrollment](../enrollment.mdx#auto-ca-enrollment) an identity is created on first authentication. 
 The following fields allow configuration of newly created identities:
 
 - `identityRoles` - the identity roles to give to automatically enrolling identities
-- `identityNameFormat` - the identity name format used to name [automatically enrolling identities](../enrollment.md#auto-ca-enrollment)
+- `identityNameFormat` - the identity name format used to name [automatically enrolling identities](../enrollment.mdx#auto-ca-enrollment)
 
 On initial creation of a 3rd Party CA it will be in an unverified stated and must undergo [verification](#verification).
 The following fields relate to [verification](#verification):

docusaurus/docs/learn/core-concepts/security/authentication/30-authentication-policies.md

@@ -76,9 +76,9 @@ process to maintain client certificate validity if `allowExpiredCerts` is false.
 Fields:
 
 - `allowed` - whether external JWTs may be used for authentication
-- `allowedSigners` - the ids of valid [External JWT Signers](./50-external-jwt-signers.md)
+- `allowedSigners` - the ids of valid [External JWT Signers](50-external-jwt-signers.mdx)
 
-If `allowed` is true the [External JWT Signers](./50-external-jwt-signers.md) specified in the `allowedSigners` field
+If `allowed` is true the [External JWT Signers](50-external-jwt-signers.mdx) specified in the `allowedSigners` field
 may be used for authentication.
 
 #### Username Password (updb)
@@ -92,4 +92,4 @@ may be used for authentication.
 The secondary section contain only two top-level configuration values:
 
 - `requireTotp` - if true authenticating clients must have [MFA TOTP](./70-totp.md) enabled
-- `requireExtJwt` - if set to an id of an [External JWT Signer](./50-external-jwt-signers.md) every request must have a valid JWT in the HTTP `Authentication` header
+- `requireExtJwt` - if set to an id of an [External JWT Signer](50-external-jwt-signers.mdx) every request must have a valid JWT in the HTTP `Authentication` header

docusaurus/docs/learn/core-concepts/security/authentication/40-certificate-management.md

@@ -12,7 +12,7 @@ PKIs via [3rd Party CAs](./10-third-party-cas.md). Ziti can trust certificates f
 Routers will attempt to extend their current client and server certificates one week prior to expiration. No
 intervention is necessary on behalf of the network administrator. The request must be sent to the controller via a 
 pre-authenticated connection. If a router has been disconnected from the Ziti network and their client certificates
-have expired, the router must be [re-enrolled](../enrollment.md#router-enrollment-extension).
+have expired, the router must be [re-enrolled](../enrollment.mdx#router-enrollment-extension).
 
 ## Client Certificate Extension
 

docusaurus/docs/learn/core-concepts/security/authentication/50-external-jwt-signers.md renamed to docusaurus/docs/learn/core-concepts/security/authentication/50-external-jwt-signers.mdx

@@ -1,3 +1,5 @@
+import ExtJwtDocEnrollDetails from '../_ext_jwt_enroll_details.md'
+
 # External JWT Signers
 
 External JWT Signers allow external identity providers to facilitate authentication with a Ziti network. External
@@ -21,6 +23,14 @@ _Note: `externalId` values on identities are enforced to be unique._
 `claimsProperty` can contain JWT standard claims or private claims. An example usage would be an `email` JWT private
 claim and Ziti identities with `externalId` set to email addresses.
 
+### Enrollment
+
+External JWT Signers can be used to enroll identities that are not pre-created by administrators. Enrollment is 
+controlled by the `enrollToCertEnabled` and `enrollToTokenEnabled` fields on `enabled` External JWT Signers. See the 
+[Enrollment - Auto External JWT Signer Enrollment](../enrollment.mdx#auto-external-jwt-signer-enrollment) 
+documentation for more information.
+
+<ExtJwtDocEnrollDetails />
 
 ### x509 Certificate
 

docusaurus/docs/learn/core-concepts/security/authentication/60-identities.md

@@ -6,7 +6,7 @@ itself, a single account on a multi-user device, an application, or a set of app
 Identity is only limited by the intent of its use, its security configuration, and where/how it stores its credentials.
 
 If an Identity represents a human that is using an SSO provider that ties into Ziti Edge's
-[External JWT Signers](./50-external-jwt-signers.md) the human operator can move from device to device using whichever Ziti
+[External JWT Signers](50-external-jwt-signers.mdx) the human operator can move from device to device using whichever Ziti
 enabled applications that allow them to authenticate. If the Identity can only authenticate via a x509 Client
 Certificate where the private key is stored in a hardware back keystore on a device, such that the key can not be moved,
 the identity is tied to that hardware. Further if the Identity's credentials are stored in an OS-backed user specific
@@ -36,7 +36,7 @@ erDiagram
 ## Creating
 
 Creating an identity alone may not be enough to make it usable. An identity will also need a valid primary
-authentication mechanism. Depending on that mechanism it may also need to complete [enrollment](../enrollment.md#clients).
+authentication mechanism. Depending on that mechanism it may also need to complete [enrollment](../enrollment.mdx#clients).
 
 Please note that all authentication mechanisms also require a properly configured [authentication policy](./auth.md)
 
@@ -46,7 +46,7 @@ The following [primary authentication](./auth.md#primary-authentication) mechani
 - 3rd Party x509 Client Certificate
 - Username Password (UPDB)
 
-The following do not require enrollment, but must have a properly configured [External JWT Signer](./50-external-jwt-signers.md)
+The following do not require enrollment, but must have a properly configured [External JWT Signer](50-external-jwt-signers.mdx)
 
 - JWT
 
@@ -137,7 +137,7 @@ Note: This identity will be using the default [authentication policy](./auth.md)
 ```
 
 ### Creating w/ JWT Authenticator
-Note: A valid [External JWT Signer](./50-external-jwt-signers.md) must be created and an [authentication policy](./auth.md)
+Note: A valid [External JWT Signer](50-external-jwt-signers.mdx) must be created and an [authentication policy](./auth.md)
 must be defined that allows the identity to authenticate with that signer.
 
 #### Ziti CLI:
@@ -165,7 +165,7 @@ Deleting an Identity removes all directly associated data. This includes:
   - [Session Certificates](./20-api-session-certificates.md)
 - Identity Role Attributes
 - [Authenticators](./auth.md#authenticators)
-- [Enrollments](../enrollment.md)
+- [Enrollments](../enrollment.mdx)
 - [MFA TOTP Configuration](./70-totp.md)
 
 It does not remove entities are that re-usable between Identities:

docusaurus/docs/learn/core-concepts/security/authentication/auth.md

@@ -91,21 +91,21 @@ intermediate CA, and root CA functionality supports RSA and EC keys.
 Please note that intermediate CA certificates may be provided during authentication if necessary. The client certificate
 should be in index zero and intermediate CA certificates in subsequent indexes in any order.
 
-To associate a client certificate with an Identity and Authenticator see the [Enrollment](../enrollment.md) 
+To associate a client certificate with an Identity and Authenticator see the [Enrollment](../enrollment.mdx) 
 section.
 
 Expired client certificates may be allowed via [Authentication Policies](30-authentication-policies.md) if desired.
 
 ### JWT Primary Authentication
 
-JWT authentication requires that an [External JWT Signer](50-external-jwt-signers.md) be added via the Ziti edge management 
-API. The definition of [External JWT Signer](50-external-jwt-signers.md) allows configuration of which JWT claim should be
+JWT authentication requires that an [External JWT Signer](50-external-jwt-signers.mdx) be added via the Ziti edge management 
+API. The definition of [External JWT Signer](50-external-jwt-signers.mdx) allows configuration of which JWT claim should be
 used as a value to map against the unique `externalId` or `id` property on Identities. This mapping of JWT claim to 
 `externalId`/`id` is used to determine which Identity is authenticating.
 
 The JWT must be provided in the HTTP request in the `Authorization` header with a value in the format of 
 `Bearer <jwt>`. The JWT provided must pass signature, expiration, issuer, and audience validation as configured
-on the [External JWT Signer](50-external-jwt-signers.md).
+on the [External JWT Signer](50-external-jwt-signers.mdx).
 
 ### Username/password
 

docusaurus/docs/learn/core-concepts/security/enrollment.md renamed to docusaurus/docs/learn/core-concepts/security/enrollment.mdx

@@ -1,3 +1,5 @@
+import ExtJwtDocEnrollDetails from './_ext_jwt_enroll_details.md'
+
 # Enrollment
 
 Enrollment is the process of some Edge client or edge router associating itself with a Ziti network. Client enrollment
@@ -46,7 +48,7 @@ Routers will automatically maintain their enrollment by refreshing their certifi
 
 ## Clients
 
-Client enroll in one of two major categories:
+Clients enroll in one of two major categories:
 
 - pre-provisioned - identities are created before the client attempts to run and are provided with one-time-tokens to enroll
   - OTT, OTT CA
@@ -147,7 +149,7 @@ Ziti network without first creating an identity or distributing a JWT enrollment
 [3rd Party CA](./authentication/10-third-party-cas.md) and ensure that `isAutoCaEnrollmentEnabled` is set to `true`.
 
 The name of enrolling clients is controlled by the `identityNameFormat` of the [3rd Party CA](./authentication/10-third-party-cas.md).
-The format support a number of replacement strings:
+The /format supports a number of replacement strings:
 
 - `[caName]` - the Ziti `name` of the [3rd Party CA](./authentication/10-third-party-cas.md) that validates the enrolling certificate
 - `[caId]` - the Ziti `id` of the [3rd Party CA](./authentication/10-third-party-cas.md) that validates the enrolling certificate
@@ -157,7 +159,123 @@ The format support a number of replacement strings:
 
 The default format is `[caName] - [commonName]`.
 
-Identity names are unique and if a collision occurs, incrementing numbers are appended.
+Identity names are unique, and if a collision occurs, incrementing numbers are appended.
+
+### Auto External JWT Signer Enrollment
+
+[External JWT Signers](./authentication/50-external-jwt-signers.mdx) represent an external IdP that can sign JWTs
+as proof of identity (including OAuth/OIDC servers). Auto Ext-JWT-Signer enrollment allows a client with a JWT from a
+configured [External JWT Signers](./authentication/50-external-jwt-signers.mdx) to enroll without an administrator
+preconfiguring an identity for them.
+
+For this to function, the following must be true:
+- the External JWT Signer is configured to validate incoming JWTs
+- the External JWT Signer is enabled
+- the External JWT Signer has a `claimsProperty` set that maps to an id value to use as `externalId` of enrolling 
+    identities.
+- either the `enrollToCertEnable` or `enrollToTokenEnabled` are set to `true`
+
+
+The [External JWT Signers](./authentication/50-external-jwt-signers.mdx) options `enrollToCertEnable` and
+`enrollToTokenEnabled` are defined as follows:
+
+<ExtJwtDocEnrollDetails />
+
+These values are included on the OpenZiti CLI command `ziti edge create ext-jwt-signer`.
+
+#### Identity Uniqueness
+
+The `claimsProperty` that selects the external id of the enrolling identity must be unique. Attempting to enroll
+with further duplicate external ids will result in an error. If desired, remove the previously enrolled identity
+to allow re-enrollment.
+
+#### Enrollment Process
+
+In order for Auto External JWT Signer Enrollment to happen, a client must be used that implements the enrollment flow.
+This process is similar to External JWT Signer authentication (e.g. OIDC or OAuth).
+
+1. The client queries the public External JWT Signers list on the Client API
+    ```text
+    GET /edge/client/v1/external-jwt-signers
+    ```
+    
+    ```text
+    200 OK
+    Content-Type: application/json
+    
+    {
+        meta: {...},
+        data: [
+            {
+                id: "20jgir0ji02",
+                  "name": "Example 1",
+                  "externalAuthUrl": "https://auth.example.com/login",
+                  "clientId": "native",
+                  "scopes": "openid profile email",
+                  "openIdConfigurationUrl": "https://auth.example.com/.well-known/openid-configuration",
+                  "audience": "myAudience",
+                  "targetToken": "ACCESS",
+                  "enrollToCertEnabled": true,
+                  "enrollToTokenEnabled": false,
+            },
+            ...
+        ]
+    }
+    ```
+2. The client presents a list to be selected from or selects a specific one.
+3. The client follows the authentication flow, enabling user input where necessary.
+4. The client receives a JWT from the external IdP.
+5. The client uses the JWT for enrollment. (see below)
+
+#### Enrollment Token Submission
+
+The client can submit the JWT to the controller for enrollment that results in either certificate-based authentication
+(`enrollToCert` is true) or token-based authentication (`enrollToToken` is true).
+
+
+##### Certificate Enrollment
+
+Certificate enrollment requires the creation of a [Certificate Signing Request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request). The CSR can contain any values desired. However, they will
+be ignored by the controller. The only requirement is that a properly configured key set was used to create and sign
+the CSR.
+
+```text
+POST /edge/client/v1/enroll/token
+Authorization: Bearer <jwt from IdP>
+
+<CSR>
+```
+
+```text
+200 OK
+Content-Type: application/json
+
+{
+    "meta":{},
+    "data":{}
+}
+```
+
+```text
+200 OK
+Content-Type: application/json
+
+{
+    "meta": {...},
+    "data": {
+        "cert": "<PEM encoded certificate chain>",
+        "ca": "<PEM encoded CA certificate bundle>"
+    }
+}
+```
+
+##### Token Enrollment
+
+Token enrollment is a simple request to the controller with the JWT.
+```text
+POST /edge/client/v1/enroll/token
+Authorization: Bearer <jwt from IdP>
+```
 
 ### Client Re-Enrollment
 

docusaurus/docs/learn/core-concepts/security/overview.md

@@ -7,10 +7,10 @@ are related to identity authentication and service access:
 
 - [Identities](#identity) - describe a human, device, or service within the edge
 - [Authenticators](./authentication/auth.md#authenticators) - describes the credentials of an authentication method associated with an Identity
-- [Enrollments](./enrollment.md) - describes a set of criteria necessary to create a new Identity and associated Authenticator
+- [Enrollments](enrollment.mdx) - describes a set of criteria necessary to create a new Identity and associated Authenticator
 - [Authentication Policy](./authentication/30-authentication-policies.md) - describes the methods available for Identity authentication
 - [3rd Party CAs](./authentication/10-third-party-cas.md) - allows external x509 PKIs to be used for authentication
-- [External JWT Signers](./authentication/50-external-jwt-signers.md) - allows external JWT signers to be used for authentication
+- [External JWT Signers](authentication/50-external-jwt-signers.mdx) - allows external JWT signers to be used for authentication
 - [API Session](./sessions.md) - a security context represented by a security token (JWT, secret, etc) that represents
   Identity authentication
 - [Session](./sessions.md) - a security context represented by a security token (JWT, secret, etc) that represents access
@@ -78,14 +78,14 @@ dial (connect) to services over a network. Read more in the [Identity](/learn/co
 
 Enrollment is a client initiated process where the result is the creation of an Identity that has some manner
 of authenticating. Enrollments may be automated through [3rd Party Cas](./authentication/10-third-party-cas.md) and 
-[External JWT Signers](./authentication/50-external-jwt-signers.md)  or may be completed through pre-provisioning. Read more in the 
-[Enrollment](./enrollment.md) section.
+[External JWT Signers](authentication/50-external-jwt-signers.mdx) or may be completed through pre-provisioning. Read more in the 
+[Enrollment](enrollment.mdx) section.
 
 ### Authentication
 
 [Authentication](./authentication/auth.md) is the process of a client proving their identity through the submission of one primary credential
 and zero or more secondary credentials that are prompted by Authentication Queries. Authentication methods can be
-configured through [3rd Party Cas](./authentication/10-third-party-cas.md), [External JWT Signers](./authentication/50-external-jwt-signers.md),
+configured through [3rd Party Cas](./authentication/10-third-party-cas.md), [External JWT Signers](authentication/50-external-jwt-signers.mdx),
 and [Authentication Policies](./authentication/30-authentication-policies.md). Read more in the
  [Authentication](./authentication/auth.md) section.