Skip to main content

Create a JWT signer

A JWT signer is a configuration used to facilitate secure, token-based authentication from an external Identity Provider (IdP). The JWT signer defines the set of parameters used during authentication to determine if the token presented is authenticated. This is necessary for integration with popular IdPs such as Azure AD, Okta, Auth0, and open-source solutions like Keycloak.

For more info on JWT signers, see Authentication overview.

Steps​

  1. From the console, select your network from the dropdown in the left-hand menu.

  2. Click Authentication from the same menu.

  3. Click the JWT Signers tab.

  4. Click the plus icon (+) to open the Create JWT Signer form.

  5. Fill in the required fields:

    • Name: Enter a unique name for the JWT Signer (e.g., Okta-Auth-Signer).

    • Issuer: Enter the URL or string that identifies the token issuer (the IdP). This must exactly match the iss claim in the incoming JWT.

      important

      This field is case-sensitive and must be an exact string match. Be meticulous about trailing slashes (/). For example, if the claim is https://auth.example.com/, entering https://auth.example.com will cause authentication to fail.

    • Audience: Enter the identifier that specifies the intended recipient of the token. This must exactly match the aud claim in the incoming JWT.

    • Claims Property: Enter the name of the custom claim field in the JWT that contains identity information (e.g., email). This value is used to map an identity's id or external_id field to the configured claim. The default is sub.

      • EXTERNAL ID: Toggle this to YES if you want the value from the Claims Property field to be saved as the identity's External ID.

        If toggled to YES, the platform will match the value in the Claims Property to an identity's externalId field. If toggled to NO, it will match the value to the identity's system id field. We generally recommend enabling this option, as matching to the externalId is typically the intended behavior when integrating with an external IdP.

  6. Configure the remaining identity settings:

    These settings are required when using a JWT signer to facilitate external IdP authentication, such as the common OIDC Authorization Code with PKCE flow (single sign-on).

    • Client ID: Enter the Client ID issued by your external IdP. This value identifies the client application requesting authentication.
    • External Auth URL: Enter the URL where the external authentication process takes place (often the IdP's login page).
    • Scopes: Enter the permissions or access levels requested from the external IdP (e.g., openid, profile, or email).

  7. Configure the verification method (Required):

    This step defines how the controller cryptographically verifies that the incoming JWT is genuine and trustworthy.

    • JWKS Endpoint: If the external provider uses a JWKS (JSON Web Key Set) endpoint to publish its public keys for verification, enter the URL here. This is the recommended and preferred approach as it allows the controller to automatically retrieve and trust updated keys.

      note

      The JWKS endpoint itself must be trusted by the controller authenticating the request. IdPs presenting certificates that can't be verified (e.g., self-signed, expired, or issued by an untrusted CA) will prevent authentication.

    • Cert PEM: Alternatively, you can paste the public certificate (in PEM format) directly into the provided text box.

  8. (Optional) Toggle Show more options to ON to reveal more configuration options:

    • Target Token Type: Select the type of token being issued by the IdP (Access or ID).

      The default and generally recommended selection is Access token. However, some IdPs, such as Auth0 and Google Workspace, may issue opaque access tokens. These opaque tokens aren't directly usable for authentication as they contain no claim information. In such cases, you must change the selection to ID Token, which contains the user's identity claims.

    • Verify OIDC Authentication: If you're configuring an OIDC connection, click Authenticate to test the connection against the external IdP using the Callback URL. This button is specifically designed to help you troubleshoot your OIDC Authorization Code + PKCE flow setup. Successfully authenticating here provides confidence that the core configuration is correct and that client tunnelers will be able to connect.

    • Custom tags: Use the Name and Value fields to attach non-functional metadata to the signer for tracking or inventory purposes.

  9. Click Save.