Gate: JWT verification

This plugin validates JSON Web Tokens (JWTs) using a publicly available JWKS verification key.

The JWT validation plugin can be used in two ways.

If you are expecting to receive SlashID-issued JWTs, you can configure the plugin with your SlashID organization ID, API key, and base URL. The plugin will automatically be configured to verify the JWT correctly. You can also enforce that the user must belong to a specified set of groups for the request to be allowed.

If you are expecting to receive JWTs issued by a third party, you must configure the fields required to correctly validate received JWTs.

Examples of each are shown in the configuration documentation below.

note

Requests with the OPTIONS method are not validated.

Example usage

Please see API authentication at the edge.

Configuring Gate

To validate JWTs issued by SlashID:

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=validate-jwt
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_ORG_ID=<SlashID Org ID>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_API_KEY=<SlashID API key>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_BASE_URL=<SlashID base URL>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_REQUIRED_GROUPS=<Required SlashID groups list>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_MAX_GROUPS_INFO_AGE=<Max SlashID groups info age>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_HEADER_WITH_TOKEN=<Header with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_COOKIE_WITH_TOKEN=<Cookie with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_SCHEMA=<Token schema>

In the Environment variables configuration, <PLUGIN NUMBER> defines plugin execution order.

HCL

gate = {
    plugins = [
        // ...
        {
            type       = "validate-jwt"
            parameters = {
                slashid_org_id              = "<SlashID Org ID>"
                slashid_api_key             = "<SlashID API key>"
                slashid_base_url            = "<SlashID base URL>"
                slashid_required_groups     = "<Required SlashID groups list>"
                slashid_max_groups_info_age = "<Max SlashID groups info age>"
                header_with_token           = "<Header with token>"
                cookie_with_token           = "<Cookie with token>"
                token_schema                = "<Token schema>"
            }
        }
        // ...
    ]
}

JSON

{
  "gate": {
    "plugins": [
      // ...
      {
        "type": "validate-jwt",
        "parameters": {
          "slashid_org_id": "<SlashID Org ID>",
          "slashid_api_key": "<SlashID API key>",
          "slashid_base_url": "<SlashID base URL>",
          "slashid_required_groups": "<Required SlashID groups list>",
          "slashid_max_groups_info_age": "<Max SlashID groups info age>",
          "header_with_token": "<Header with token>",
          "cookie_with_token": "<Cookie with token>",
          "token_schema": "<Token schema>"
        }
      }
      // ...
    ]
  }
}

TOML

[[gate.plugins]]
type = "validate-jwt"
parameters.slashid_org_id = "<SlashID Org ID>"
parameters.slashid_api_key = "<SlashID API key>"
parameters.slashid_base_url = "<SlashID base URL>"
parameters.slashid_required_groups = "<Required SlashID groups list>"
parameters.slashid_max_groups_info_age = "<Max SlashID groups info age>"
parameters.header_with_token = "<Header with token>",
parameters.cookie_with_token = "<Cookie with token>",
parameters.token_schema = "<Token schema>"

YAML

gate:
  plugins:
    // ...
    - type: validate-jwt
      parameters:
        slashid_org_id: <SlashID Org ID>
        slashid_api_key: <SlashID API key>
        slashid_base_url: <SlashID base URL>
        slashid_required_groups: <Required SlashID groups list>
        slashid_max_groups_info_age: <Max SlashID groups info age>
        header_with_token: <Header with token>
        cookie_with_token: <Cookie with token>
        token_schema: <Token schema>
    // ...

To validate JWTs issued by a third party:

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=validate-jwt
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_JWKS_URL=<Custom JSON Web Key Sets URL>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_JWKS_REFRESH_INTERVAL=<JSON Web Key Sets refresh interval>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_JWT_ALLOWED_ALGORITHMS=<Allowed JWT signing algorithms>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_JWT_EXPECTED_ISSUER=<JWT expected issuer>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_JWT_EXPECTED_AUDIENCE=<JWT expected audience>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_HEADER_WITH_TOKEN=<Header with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_COOKIE_WITH_TOKEN=<Cookie with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_SCHEMA=<Token schema>

In the Environment variables configuration, <PLUGIN NUMBER> defines plugin execution order.

HCL

gate = {
    plugins = [
        // ...
        {
            type          = "validate-jwt"
            parameters = {
                jwks_url               = "<Custom JSON Web Key Sets URL>"
                jwks_refresh_interval  = "<JSON Web Key Sets refresh interval>"
                jwt_allowed_algorithms = "<Allowed JWT signing algorithms>"
                jwt_expected_issuer    = "<JWT expected issuer>"
                jwt_expected_audience  = "<JWT expected audience>"
                header_with_token      = "<Header with token>"
                cookie_with_token      = "<Cookie with token>"
                token_schema           = "<Token schema>"
            }
        }
        // ...
    ]
}

JSON

{
    "gate": {
        "plugins": [
            // ...
            {
                "type": "validate-jwt",
                "parameters": {
                    "jwks_url": "<Custom JSON Web Key Sets URL>",
                    "jwk_refresh_interval": "<JSON Web Key Sets refresh interval>",
                    "jwt_allowed_algorithms": "<Allowed JWT signing algorithms>",
                    "jwt_expected_issuer": "<JWT expected issuer>",
                    "jwt_expected_audience": "<JWT expected audience>",
                    "header_with_token": "<Header with token>",
                    "cookie_with_token": "<Cookie with token>",
                    "token_schema": "<Token schema>"
                }
            // ...
            }
        ]
    }
}

TOML

[[gate.plugins]]
type = "validate-jwt"
parameters.jwks_url = "<Custom JSON Web Key Sets URL>"
parameters.jwk_refresh_interval = "<JSON Web Key Sets refresh interval>"
parameters.jwt_allowed_algorithms = "<Allowed JWT signing algorithms>"
parameters.jwt_expected_issuer = "<JWT expected issuer>"
parameters.jwt_expected_audience = "<JWT expected audience>"
parameters.header_with_token = "<Header with token>",
parameters.cookie_with_token = "<Cookie with token>",
parameters.token_schema = "<Token schema>"

YAML

gate:
    plugins:
    // ...
    - type: validate-jwt
      parameters:
        jwks_url: <Custom JSON Web Key Sets>
        jwk_refresh_interval: <JSON Web Key Sets refresh interval>
        jwt_allowed_algorithms: <Allowed JWT signing algorithms>
        jwt_expected_issuer: <JWT expected issuer>
        jwt_expected_audience: <JWT expected audience>
        header_with_token: <Header with token>
        cookie_with_token: <Cookie with token>
        token_schema: <Token schema>
    // ...

Where:

• <SlashID Org ID> your SlashID organization ID. If provided, this will be used as the JWT audience.
• <SlashID API key> your SlashID API key.
• <SlashID base URL> base URL of the SlashID API. If provided, this will be used as the JWT issuer and JWKS URL.
• <Required SlashID groups list> list of groups required to access the endpoint. By default, empty (no groups required). If multiple groups are provided, all of them are required. In environment variables multiple groups should be separated by a comma. For example: user,admin. In HCL, JSON, TOML and YAML, multiple groups should be provided as a list. For example: ["user", "admin"].
• <Max SlashID groups info age> maximum age of SlashID groups information. If groups are present in the JWT, but their information is older than this value, Gate will fetch the latest information from SlashID servers. Age should have format 1h, 1m, 1s or 1ms. You can combine multiple units, for example: 1h30m. If not provided, groups information will be fetched from SlashID servers on every request.
• <Custom JSON Web Key Sets URL> URL of key sets used for offline token validation.
• <JSON Web Key Sets refresh interval> interval for refreshing key sets used for offline token validation. By default, 15m.
• <Allowed JWT signing algorithms> list of allowed signing algorithms for JWTs. At least one algorithm must be provided. Only JWTs with one of these algorithms in the alg field will be accepted; requests with JWTs using another algorithm will be rejected. In environment variables, multiple algorithms should be separated by a comma. For example: ES256,ES512. In HCL, JSON, TOML and YAML, multiple algorithms should be provided as a list. For example: ["ES256", "ES512"]. This plugin supports the following algorithms: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512.
• <JWT expected issuer> expected issuer of the JWT token.
• <JWT expected audience> expected audience of the JWT token.
• <Header with token> is the request header containing the token. This option and cookie_with_token are mutually exclusive.
• <Cookie with token> is the request cookie containing the token. This option and header_with_token are mutually exclusive.
• <Token schema> a JSON or YAML schema for the JWT payload

To learn more about configuring Gate, please visit configuration page and plugins section.

info

The order of plugins in configuration determines their execution order.

Disabling plugin for specific URLs

You can enable or disable this plugin for specific URLs by using the enabled option in the URLs configuration.

Environment variables

GATE_URLS_0_PATTERN=svc-example.com/*
GATE_URLS_0_TARGET=http://example:8080

GATE_URLS_1_PATTERN=svc-another-example.com/
GATE_URLS_1_TARGET=https://another-example:8080

HCL

gate = {
  urls = [
    {
      pattern = "svc-example.com/*"
      target  = "http://example:8080"
    },
    {
      pattern = "svc-another-example.com/"
      target  = "https://another-example:8080"
    }
  ]

  // ...
}

JSON

{
  "gate": {
    "urls": [
      {
        "pattern": "svc-example.com/*",
        "target": "http://example:8080",
      },
      {
        "pattern": "svc-another-example.com/",
        "target": "https://another-example:8080"
      }
    ],
    // ...

URL are matched in the order they are defined in the configuration file.

TOML

[[gate.urls]]
pattern = "svc-example.com/*"
target = "http://example:8080"

[[gate.urls]]
pattern = "svc-another-example.com/"
target = "https://another-example:8080"

URL are matched in the order they are defined in the configuration file.

YAML

gate:
  urls:
    - pattern: svc-example.com/*
      target: http://example:8080
    - pattern: svc-another-example.com/
      target: https://another-example:8080

URL are matched in the order they are defined in the configuration file.