Skip to main content
Star us on GitHub Star

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 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.

Configuring External Auth in OpenZiti​

To configure an External Provider for use with an OpenZiti tunneler, create an ext-jwt-signer.

This can be accomplished using the ziti CLI or through the Ziti Admin Console (ZAC). Properly configuring the external jwt signer will require careful attention, as even one stray character can prevent authentication from working. It is very easy to add an extra slash or remove an important slash. Remember, the fields all must match exactly or authentication will fail.

The following fields are used creating an external JWT signer:

  • issuer - the issuer (iss) to expect
  • audience - the audience (aud) the JWT is expected to be for, for example: openziti
  • client-id - a string assigned by the provider, used when performing the Auth Flow with PKCE process
  • jwks-endpoint - a URL used by the OpenZiti Controller to verify the provided JWT
  • claims-property to match (often email). The JWT must contain a claim with the provided value
  • scopes - additional scopes to request from the provider. Often email or profile
  • external-auth-url - the URL users are directed to for authentication with the external provider
Example Configuring OpenZiti for External Auth

A Practical Example​

Locate the provider's OpenID discovery endpoint. For example, for Keycloak, the OpenID discovery endpoint is generally located at:

https://${keycloak.domain.name}:${keycloak.port}/realms/${realm-name}/.well-known/openid-configuration

The OpenID discovery endpoint returns three important fields necessary for the ext-jwt-signer. The discovery endpoint contains the issuer, external-auth-url (within the json, this will be the authorization_endpoint value), and the jwks-endpoint (jwks_uri from the discovery endpoint). Copy and paste these values exactly as they are shown into either the ziti CLI command, or into the Ziti Admin Console.

After capturing the necessary fields from the discovery endpoint, determine:

  • the audience the JWT will present. This can be whatever the IdP is configured for, but it would make sense to have the audience set to something like openziti
  • the client id assigned by the IdP
  • the claims property that should be mapped from the JWT to an OpenZiti identity
  • any scopes that the OpenZiti client should request
Example Configuring OpenZiti for External Auth

Using the ziti CLI:​

With the values collected, create an ext-jwt-signer with the CLI. Replace the placeholder variables with the appropriate content and execute:

ziti edge create ext-jwt-signer example-ext-jwt-signer $issuer \
    --external-auth-url $ext_jwt_auth_url \
    --jwks-endpoint $jwks_uri \
    --audience $ext_jwt_audience \
    --client-id $ext_jwt_client_id \
    --claims-property $ext_jwt_claims_prop \
    --scopes $ext_jwt_scopes

The ziti CLI will indicate success/failure of the opeation.

Using the Ziti Admin Console​

Add External JWT Signer​

Navigate to the Authentication page, choose JWT Signers and click the plus in the upper right

Add External JWT Signer

Initial Fields​

Fill out the Name, Issuer, Audience, Claims Property and toggle "Use External Id" to on. Then, add the JWKS endpoint on the right side of the screen.

Initial Fields

More Option Fields​

Toggle the "Show More Options" and fill out the Client ID, External Auth URL and add scopes. When done click "Save" in the top right corner.

More Option Fields

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.