External JWT Authentication

Authenticate users using externally created JSON Web Tokens (JWT). In this setup, your 3rd-party provider creates JWTs

Prerequisites for JWT Authentication

  • You have an external JWT identity provider that is issuing JWTs to your users.

  • You have configured a user directory to PrivX from which PrivX can resolve users by JWT subject.

  • JWTs from your identity provider must include the following claims:

    Headers

    • alg: Algorithm used for generating the JWT.
    • typ: JWT

    Payload

    • sub: subject name in either plain or DN format (for example alice or CN=alice,DC=example,DC=com).
    • iss: Issuer name

    Additionally if PrivX is configured to fetch JWT signature verification certificates or keys from network, then the JWT header must include the x5u claim.

    If the JWT token payload includes the optional iat, nbf or exp claims then PrivX verifies those timestamps against local server time.

PrivX can validate JWTs against locally stored public key(s) or against public keys/certificates located at a X.509 URL. Typically you only need one or the other, not both.

Example of a JWT with minimal claims:

{
    "headers": {
    "alg": "RS256",
    "typ": "JWT",
    "x5u": "https://idp.example.com/v1/k/12345"
    }
    "payload": {
    "iss": "issuer12345",
    "sub": "alice"
    }
}

External JWT-Validation Setup

To add your JWT issuer as a trusted provider to PrivX:

  1. On Administration→Deployment→External Token Authentication, click Add New Provider.

  2. Provide the information about your JWT identity provider, which is used for validating users' JWTs. You will at least need to provide the General, Public key, and Token validation settings.

    Select a user directory from which PrivX resolves users by JWT subject.

    Set Subject type according to the format of your JWT tokens' sub claim. For example, set to Plain if the sub claim only contains the user name:

    "sub": "alice"

    As another example, if the sub claim is in DN notation with the user name in the cn attribute:

    "sub": "cn=alice,dc=example,dc=com"

    You should set Subject type to DN, and DN attribute to cn.

    In both of the previous examples PrivX will search user alice from the configured user directory.

  3. Set Public key method to one of the following:

    • Use Token Provider Public Key

      Specify one or more signer's public keys and corresponding kids. The incoming JWT Token will be verified against these public keys. The JWT token's optional kid claim will be used as a hint for selecting the public key. If JWT token does not contain a kid claim then signature verification is attempted with all configured public keys.

    • Fetch Token Provider Certificate From X5U Header

      This method is used when JWT token's x5u header claim refers to a resource for an X.509 public key certificate or certificate chain. PrivX fetches the certificate from the x5u URL, validates the certificate and verifies the JWT signature using the public key extracted from the leaf certificate.

      Specify one or more X.509 certificates in X5U Trust Anchor. These trust anchor certificates are used for validating the X.509 certificate fetched from the x5u URL.

      You can optionally specify an X5U Prefix for enforcing that the JWT token's x5u claim must have a specific https URL prefix.

      Optionally specify X5U TLS Trust Anchors within this method. You can provide one or more X.509 certificates to be used for validating the server TLS certificate when making HTTPS request to x5u URL, otherwise, a system trusted trust anchor configuration is used instead.

    • Fetch Token Provider Public Key From X5U Header

      This method is used when a JWT X5U Header Parameter refers to a resource for a PKIX PEM format public key. PrivX verifies that the x5u URL starts with an allowed URL prefix, fetches the public key from the URL and uses it to verify the JWT signature.

      Specify an X5U Prefix for enforcing that the JWT token's x5u claim must have a specific https URL prefix.

      Optionally X5U TLS Trust Anchors can also be specified within this method. You can provide one or more X.509 certificates to be used for validating the server TLS certificate when making HTTPS request to x5u URL, otherwise, a system trusted trust anchor configuration is used instead.

  4. Set Issuer to correspond with the iss claim in your JWT tokens.

    Optionally you can specify audience which must be present in the JWT token's aud claim.

  5. (Optional) Under Custom parameter validation, you may specify additional claims that need to be satisfied for authentication. Possible value types include:

  • String pattern: The expected value compares a claim value to a glob pattern.

  • Numeric range: The claim value will be checked if it is within an expected numeric range.

  • IP range: The claim value will be checked if it is within an expected IP range. Can be either IPv4 for IPV6. CIDR notation is unsupported.

  • Client IP: The claim value will be checked if it matches the IP address from which the token login REST API request is made.

For the JWT token to pass each custom parameter validation the claim must either have a single matching value or it must have an array of values of which at least one value matches.

  1. Save your settings.

    You may verify back on the Administration→Deployment→External Token Authentication page that the new identity provider has been added.

JWTs provided by the identity provider can now be used for authentication to PrivX. You can exchange the JWT token to a PrivX access token using the API endpoint /auth/api/v1/token/login.

Was this page helpful?