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_PLUGINS_<plugin number>_TYPE=<plugin type>
GATE_PLUGINS_<plugin number>_ID=<plugin ID>
GATE_PLUGINS_<plugin number>_ENABLED=false
GATE_PLUGINS_<plugin number>_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_URLS_0_PATTERN=svc-another-example.com/
GATE_URLS_0_TARGET=https://another-example:8080
GATE_URLS_0_PLUGINS__<PLUGIN ID>__ENABLED=true
GATE_URLS_0_PLUGINS__<PLUGIN ID>__PARAMETERS_<plugin_parameter>=<plugin parameter value>

Plugin ID is case-insensitive. Because of that, <PLUGIN ID> can be the uppercase version of the plugin ID.

Please note that in URL configuration, the plugin ID is separated by two underscores (__).

HCL

gate = {
  plugins = [
    {
      type       = "<plugin type>"
      id         = "<plugin ID>"
      enabled    = false
      parameters = {
        <plugin parameter> = <plugin parameter value>
      }
    }
  ]

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

      plugins = {
        "<plugin ID>" = {
          enabled     = true
          parameters = {
            <plugin parameter> = "<plugin parameter value>"
          }
        }
      }
    }
  ]

  // ...
}

JSON

{
  "gate": {
    "plugins": [
      {
        "type": "<plugin type>",
        "id": "<plugin ID>",
        "enabled": false,
        "parameters": {
          "<plugin parameter>": "<plugin parameter value>"
        }
      },
      "urls": [
        {
          "pattern": "svc-another-example.com/",
          "target": "https://another-example:8080",
          "plugins": {
            "<plugin ID>": {
              "enabled": true,
              "parameters": {
                "<plugin parameter>": "<plugin parameter value>"
              }
            }
          }
        }
      ],
    // ...

TOML

[[gate.plugins]]
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters.<plugin parameter> = <plugin parameter value>

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

plugins.<plugin ID>.enabled = true
plugins.<plugin ID>.parameters.<plugin parameter> = "<plugin parameter value>"

YAML

gate:
  plugins:
    - type: <plugin type>
      id: <plugin ID>
      enabled: false
      parameters:
        <plugin parameter>: <plugin parameter value>
  urls:
    - pattern: svc-another-example.com/
      target: https://another-example:8080
      plugins:
        <plugin ID>:
          enabled: true
          parameters:
            <plugin parameter>: <plugin parameter value>