Skip to main content
Star us on GitHub Star

External Provider - JWT

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.

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
Obtaining the Network JWT

Obtain the Network JWT - ZAC​

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.

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.

ext-jwt-signer-basic

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:

curl -s https://my.openziti.controller.local:443/network-jwts | jq -r .data[].token > my-network-jwt

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

Authenticating with the External Provider​

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

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

Assuming everything succeeds, the user will see the normal information shown by an authenticated identity.

after-pkce-success.png

More Than One External Provider​

If your network is configured with more than one external provider, a popup will be shown when the mouse hovers over 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

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

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.