Gate: OAuth 2.0 access token verification

This plugin validates OAuth 2.0 access tokens. It supports both JWT access tokens, which are validated using a public JWKS, and opaque tokens, which are validated using an introspection endpoint.

Requests are only allowed if the JWT is valid or the opaque token is active according to the response from the introspection endpoint. In addition, the plugin can be configured with required scopes - requests are only allowed if the JWT has the required scope in its scope claim, or the opaque token has the required scope according to the response from the introspection endpoint.

note

Requests with the OPTIONS method are not validated.

Configuring Gate

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=validate-oauth2-token

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_FORMAT=<Format of the access token>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_HEADER_WITH_TOKEN=<Header with token>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_REQUIRED_SCOPES=<Required scopes>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_METHOD_REQUIRED_SCOPES=<Required scopes per HTTP method>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_METHOD_REQUIRED_SCOPES_0_HTTP_METHOD=<HTTP method>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_METHOD_REQUIRED_SCOPES_0_SCOPES=<Required scopes per HTTP method>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_METHOD_REQUIRED_SCOPES_1_HTTP_METHOD=<HTTP method>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_METHOD_REQUIRED_SCOPES_1_SCOPES=<Required scopes per HTTP method>

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_TOKEN_INTROSPECTION_URL=<Token introspection URL>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_INTROSPECTION_CLIENT_ID=<Client ID for authorizing token introspection>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_INTROSPECTION_CLIENT_SECRET=<Client secret for authorizing token introspection>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_TOKEN_INTROSPECTION_BEARER_TOKEN=<Bearer token for authorizing token introspection>

GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_INCLUDE_REQUIRED_SCOPES_IN_INTROSPECTION_REQUEST=<Include required scopes in introspection request>

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

HCL

gate = {
    plugins = [
        // ...
        {
            type       = "validate-oauth2-token"
            parameters = {
                token_format                                     = "<Format of the access token>"
                header_with_token                                = "<Header with token>"
                required_scopes                                  = "<Required scopes>"
                method_required_scopes                           = "<Required scopes per HTTP method>"
                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>"
                token_introspection_url                          = "<Token introspection URL>"
                token_introspection_client_id                    = "<Client ID for authorizing token introspection>"
                token_introspection_client_secret                = "<Client secret for authorizing token introspection>"
                token_introspection_bearer_token                 = "<Bearer token for authorizing token introspection>"
                include_required_scopes_in_introspection_request = "<Include required scopes in introspection request>"
            }
        }
        // ...
    ]
}

JSON

{
    "gate": {
        "plugins": [
            // ...
            {
                "type": "validate-oauth2-token",
                "parameters": {
                    "token_format": "<Format of the access token>",
                    "header_with_token": "<Header with token>",
                    "required_scopes": "<Required scopes>",
                    "method_required_scopes": "<Required scopes per HTTP method>",
                    "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>",
                    "token_introspection_url": "<Token introspection URL>",
                    "token_introspection_client_id": "<Client ID for authorizing token introspection>",
                    "token_introspection_client_secret": "<Client secret for authorizing token introspection>",
                    "token_introspection_bearer_token": "<Bearer token for authorizing token introspection>",
                    "include_required_scopes_in_introspection_request": "<Include required scopes in introspection request>"
                }
            // ...
            }
        ]
    }
}

TOML

[[gate.plugins]]
type = "validate-oauth2-token"
parameters.token_format = "<Format of the access token>",
parameters.header_with_token = "<Header with token>",
parameters.required_scopes = "<Required scopes>",
parameters.method_required_scopes = "<Required scopes per HTTP method>",
parameters.jwks_url = "<Custom JSON Web Key Sets URL>",
parameters.jwks_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.token_introspection_url = "<Token introspection URL>",
parameters.token_introspection_client_id = "<Client ID for authorizing token introspection>",
parameters.token_introspection_client_secret = "<Client secret for authorizing token introspection>",
parameters.token_introspection_bearer_token = "<Bearer token for authorizing token introspection>",
parameters.include_required_scopes_in_introspection_request = "<Include required scopes in introspection request>"

YAML

gate:
    plugins:
    // ...
    - type: validate-oauth2-token
      parameters:
        token_format: <Format of the access token>
        header_with_token: <Header with token>
        required_scopes: <Required scopes>
        method_required_scopes: <Required scopes per HTTP method>
        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>
        token_introspection_url: <Token introspection URL>
        token_introspection_client_id: <Client ID for authorizing token introspection>
        token_introspection_client_secret: <Client secret for authorizing token introspection>
        token_introspection_bearer_token: <Bearer token for authorizing token introspection>
        include_required_scopes_in_introspection_request: <Include required scopes in introspection request>
    // ...

Where:

• <Format of the access token> the format of the access token, either jwt or opaque
• <Header with token> is the request header containing the token. If not provided, the plugin will attempt to retrieve the token from the Authorization header and strip the Bearer token.
• <Required scopes> a list of scopes required for access to the protected endpoint. Only tokens that have these scopes requested will be accepted. In environment variables, multiple scopes should be separated by a comma. For example: foo,bar. In HCL, JSON, TOML and YAML, multiple scopes should be provided as a list. For example: ["foo", "bar"].
• <Required scopes per HTTP method> a list of scopes required for access to the protected endpoint with a particular HTTP method. Only tokens that have these scopes requested will be accepted for requests with the specific method. This value should be a list of objects containing the HTTP method and a list of scopes. In HCL, JSON, TOML and YAML, this should be provided as a list of objects. For example: [{"http_method": "GET", scopes: ["foo", "bar"]}].

    - `<HTTP method>` the HTTP method to protect
    - `<Required scopes per HTTP method>` the scopes required for the specified HTTP method
• <Custom JSON Web Key Sets URL> URL of key sets used for offline token validation. Required if <Format of the access token> is set to jwt.
• <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. Required if <Format of the access token> is set to jwt.
• <JWT expected issuer> expected issuer of the JWT token. Required if <Format of the access token> is set to jwt.
• <JWT expected audience> expected audience of the JWT token. Required if <Format of the access token> is set to jwt.
• <Token introspection URL> the URL for introspecting the access token. Required if <Format of the access token> is set to opaque.
• <Client ID for authorizing token introspection> the OAuth2 client ID used to request the access token, which will be used to authorize the token introspection request. This is mutually exclusive with <Bearer token for authorizing token introspection>. At least one is required if <Format of the access token> is set to opaque.
• <Client secret for authorizing token introspection> the OAuth2 client secret used to request the access token, which will be used to authorize the token introspection request. This is required with <Client ID for authorizing token introspection>.
• <Bearer token for authorizing token introspection> the bearer token from the OAuth2 authorization server, which will be used to authorize the token introspection request. This is mutually exclusive with <Client ID for authorizing token introspection>. At least one is required if <Format of the access token> is set to opaque.
• <Include required scopes in introspection request> whether to include the specified required scopes in the token introspection request. Some authorization servers will check scopes server-side and return a response body with active: false if the token does not have the requested scopes. This is only accepted if <Format of the access token> is set to opaque.

For a given request processed by this plugin, the required scopes will be the union of <Required scopes> and the required scopes for the relevant method, if any. If no required scopes are specified, all requests with a valid token will be allowed.

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.