Skip to main content

Configure Kong OSS with Nevis ID

This guide shows how to configure Kong Gateway OSS as a resource server for JWT access tokens issued by Nevis ID. Kong validates the token signature locally with the RSA public key published by the Nevis ID JWKS endpoint.

This guide uses Kong OSS's JWT and ACL plugins. It does not require Kong Enterprise.

warning

Kong OSS does not automatically perform OpenID Connect discovery, refresh JWKS, or introspect OAuth access tokens. The key retrieval and configuration update process described in this guide is an external deployment responsibility.

The configuration in this guide is a basic local JWT validation example. The Kong OSS JWT plugin configuration shown here verifies the signature and token expiration, but does not enforce the complete Nevis ID API-gateway profile, including audience, scope, and role requirements. Do not treat this example as a production authorization profile without adding and testing those controls.

The examples target Kong Gateway OSS 3.9 in DB-less declarative mode. Adapt and test the configuration if you use another Kong version or deployment mode.

Before you start​

You need:

  • a Nevis ID instance and environment;
  • OpenID Connect enabled in the OAuth 2.0 Authorization Server / OpenID Connect Provider pattern, so access tokens contain the iss claim;
  • a configured OAuth client in Nevis ID;
  • Nevis ID configured to issue signed JWS access tokens with the RS256 algorithm and publish the corresponding JWKS;
  • an API protected by Kong;
  • Kong Gateway OSS with the JWT and ACL plugins enabled;
  • a deployment process that can store and update the RSA public key securely.

Do not put client secrets, private keys, access tokens, or user data in the Kong configuration or in source control.

Kong's JWT plugin validates signed JWS tokens. It cannot locally validate encrypted JWE or opaque access tokens, so configure the Nevis ID authorization server to issue an RS256-signed access token and publish its signing key through JWKS.

Identify the Nevis ID issuer​

The standard LIVE login host follows the pattern https://login.<instance>.getnevis.net; the standard TEST host uses https://login-test.<instance>.getnevis.net. An environment can also use a custom login domain. Use the issuer published by the selected Nevis ID environment; do not infer it from the instance name or from an incoming token.

The selected environment publishes /.well-known/openid-configuration. Its issuer field is the authoritative value to configure in Kong.

The issuer is the exact value of the iss claim in the access token. Do not add a trailing slash unless the discovery document and token use one.

The paths in this guide are the standard Nevis ID pattern defaults. A deployment can configure different paths. Always use the URLs published by the deployed discovery document and verify them against the deployed configuration.

Fetch the discovery document:

INSTANCE=your-instance
ISSUER="https://login.${INSTANCE}.getnevis.net"
curl --fail --silent --show-error \
  "$ISSUER/.well-known/openid-configuration" | jq .

Read the jwks_uri value from the discovery document and fetch the signing keys:

JWKS_URI=$(curl --fail --silent --show-error \
  "$ISSUER/.well-known/openid-configuration" | jq -er '.jwks_uri')
curl --fail --silent --show-error "$JWKS_URI" | jq .

Verify that the issuer value in the discovery document is exactly the trusted ISSUER value configured for Kong. Do not derive the trusted issuer from an incoming token.

Select the RSA signing key that matches the kid header of the access token. Verify that the key uses RS256 and is intended for signatures. Convert the selected JWK to the PEM format required by the Kong JWT plugin. See the official Kong JWT plugin documentation for the supported credential fields and key formats.

Configure a Kong consumer​

Create one Kong consumer for each Nevis ID issuer in this configuration. Use the issuer as the JWT credential key so that Kong can select the correct public key from the token iss claim. Do not create multiple consumers for different scopes or roles that use the same issuer: with key_claim_name: iss, they resolve to the same issuer value.

The following example is a fragment of a declarative Kong configuration. Replace the placeholder PEM value with the public key obtained from the Nevis ID JWKS endpoint.

_format_version: "3.0"

consumers:
  - username: nevis-id-live
    acls:
      - group: nevis-id-live
    jwt_secrets:
      - key: https://login.your-instance.getnevis.net
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          <public-key-material>
          -----END PUBLIC KEY-----

For direct DB-less configuration, secret is not needed for an RS256 credential: Kong uses rsa_public_key for verification. If you use a Kong integration whose declarative schema requires secret, add an arbitrary per-credential placeholder; it is not an application secret and is not used for RS256 verification. See the official Kong JWT plugin documentation for the complete credential schema.

The value in jwt_secrets[].key must match the trusted issuer in the token. The JWT plugin uses the iss claim by default. If you use a different claim as the key, set key_claim_name to that claim and configure separate issuer validation.

Protect an API route​

Attach the JWT plugin to the protected route. Use the ACL plugin when different consumers need different route permissions.

services:
  - name: customer-api
    url: http://customer-api:8080
    routes:
      - name: customer-api
        paths:
          - /api/customer
        strip_path: false
        plugins:
          - name: jwt
            config:
              key_claim_name: iss
              claims_to_verify:
                - exp
                - nbf
              uri_param_names: []
              cookie_names: []
          - name: acl
            config:
              allow:
                - nevis-id-live

Send the access token in the HTTP Authorization header:

curl --fail \
  -H "Authorization: Bearer <access-token>" \
  https://gateway.example.com/api/customer

Kong rejects requests with a missing, expired, incorrectly signed, or unknown-issuer token before forwarding them to the upstream API.

The ACL example authorizes a Kong consumer, not an OAuth scope or role. Configure the expected audience and authorization claims for the protected API and add a gateway control that enforces them before using this integration for sensitive APIs. This guide does not claim that the Kong OSS JWT plugin enforces aud.

Verify the limited example with negative tests:

  • no token, an expired token, or an invalid signature is rejected;
  • a token with an unknown issuer is rejected;
  • a consumer that is not allowed by the ACL is rejected;
  • a correctly signed, unexpired ID token or a correctly signed, unexpired token with the wrong audience may pass this example, because it does not enforce those distinctions;
  • after adding audience and token-type authorization controls, both cases are rejected.

Connect an application to Nevis ID​

For a browser application, use the authorization-code flow with PKCE:

  1. Generate an unpredictable state value, a code verifier, and an S256 code challenge. Store the state and verifier in the browser session.
  2. Redirect the user to the Nevis ID authorization endpoint from the discovery document.
  3. Include the registered redirect URI, client ID, response_type=code, scope, state, code_challenge, and code_challenge_method=S256. If the configured Nevis ID audience strategy uses resources, also include the protected API as resource, or request scopes belonging to exactly one resource server.
  4. On the callback, verify the returned state before exchanging the authorization code at the token endpoint with the code verifier.
  5. Send the access token to the Kong-protected route.

Register the application redirect URI in Nevis ID. The redirect URI must match exactly, including the scheme, host, path, and port.

The API gateway does not replace the Nevis ID authorization flow. It validates the access token after Nevis ID has issued it.

Handle signing-key rotation​

The Kong OSS JWT plugin uses the key configured in Kong. It does not refresh the Nevis ID JWKS automatically.

With key_claim_name: iss, Kong selects one JWT credential for the issuer. A second credential with the same issuer key does not provide an old-key/new-key overlap. Replacing the configured public key therefore makes tokens signed with the previous key fail.

Build coordinated key replacement into the deployment process:

  1. Fetch the discovery document and JWKS over TLS.
  2. Detect the kid used by current tokens.
  3. Prepare and validate the new Kong configuration before the issuer starts signing with the new key.
  4. Coordinate the Kong reload with the Nevis ID signing-key change.
  5. Test the new key and monitor requests after the change.

This simple iss-based configuration cannot safely validate tokens signed by both old and new keys during a rollover. Supporting overlapping keys requires a different validation design, such as a validator that selects keys by kid while separately enforcing the trusted issuer. That design is outside this guide.

Once the updated configuration is active on a Kong instance, that instance rejects tokens signed with the previous key. Plan for that interruption and do not silently continue with stale key material if discovery or JWKS retrieval fails.

Kong OSS limitations​

Kong OSS does not provide the following as a built-in Nevis ID integration:

  • automatic OpenID Connect discovery;
  • periodic or on-demand JWKS refresh;
  • OAuth 2.0 token introspection;
  • audience, scope, or role authorization based on Nevis ID claims.

If you need fresher signing keys, implement an external JWKS refresh and Kong reload process. That only distributes key material; it does not add token introspection or audience, scope, and role enforcement. Those capabilities require a dedicated authorization service, custom Kong plugin, or Kong Enterprise plugin.

Local JWT validation is fast and does not make every API request depend on Nevis ID availability. Key replacement invalidates tokens signed with the replaced key, but it is not selective token or session revocation. Immediate individual revocation requires an additional mechanism that communicates revocation state to the resource server. Reject ID tokens at the API boundary and require an access-token audience and authorization policy when those controls are part of the integration profile.

Kong:

Nevis ID: