JWT Auth

Certain Nova types allow a Custom Ruleset which is a system where advanced users can specify complex access control options by URL, or many more HTTP/S features.

Usage

You can find the Custom Ruleset under Authentication on supported ADC types (e.g. API Gateway). This is a text block where you can enter any supported Nova Rules to make allow/deny/capture decisions for your ADC.

To disable custom ruleset usage, simply leave the field empty, or remove all lines.

In order to use a custom ruleset, you must always have at least this text string within it, which is where the Nova JWT authentication happens:

{% nova_verify_jwt %}

What that string will do is three things:

  1. Deny any requests without an Authorization header.
  2. Include the Nova JWT verification system.
  3. Deny the request unless Nova authorizes it via JWT verification.

The reason you specify where to include it is to allow you to decide to pass certain traffic before the deny rule. There are examples of this below.

Examples

We have several examples available for common use cases, specifically with APIs.

Allow all GET requests, authenticate the rest

# Accept GET requests and skip further checks
allow if { method GET }

# Include the nova JWT authorization
{% nova_verify_jwt %}

Allow all GET or HEAD requests, authenticate the rest

# Accept GET OR HEAD requests and skip further checks
allow if { method GET } || { method HEAD }

# Include the nova JWT authorization
{% nova_verify_jwt %}

Allow access to a specific URL without auth

# Allow if requesting /auth/
allow if { path_beg /auth/ }

# Include the nova JWT authorization
{% nova_verify_jwt %}

Deny certain URLs depending on JWT Scopes

# Include the nova JWT authorization
{% nova_verify_jwt %}

# Deny the request if it's a POST/DELETE to a path beginning with /api/coins, but the token doesn't include the "write:coins" scope
capture var(txn.oauth_scopes) len 20
deny if { path_beg /api/coins } { method POST DELETE } ! { var(txn.oauth_scopes) -m sub write:coins }

Rate limit depending on package

# Include the nova JWT authorization
{% nova_verify_jwt %}

# Rate limit basic users to 10 and enterprise users to 1000
capture var(txn.oauth_scopes) len 20
deny deny_status 429 if { var(txn.oauth_scopes) -m sub basic } { src,table_http_req_cnt gt 10 }
deny deny_status 429 if { var(txn.oauth_scopes) -m sub enterprise } { src,table_http_req_cnt gt 1000 }

Complex example using all the above

# Accept GET requests and skip further checks
allow if { method GET }

# Allow if requesting /auth/
allow if { path_beg /auth/ }

# Include the nova JWT authorization
{% nova_verify_jwt %}

# Deny the request if it's a POST/DELETE to a path beginning with /api/coins, but the token doesn't include the "write:coins" scope
capture var(txn.oauth_scopes) len 20
deny if { path_beg /api/coins } { method POST DELETE } ! { var(txn.oauth_scopes) -m sub write:coins }

# Rate limit basic users to 10 and enterprise users to 1000
deny deny_status 429 if { var(txn.oauth_scopes) -m sub basic } { src,table_http_req_cnt gt 10 }
deny deny_status 429 if { var(txn.oauth_scopes) -m sub enterprise } { src,table_http_req_cnt gt 1000 }

Variables

Nova automatically gives your rulesets access to variables for each of the claims in the token. For example:

var(txn.oauth.aud)
var(txn.oauth.clientId)
var(txn.oauth.scope)
var(txn.oauth.iss)