Proto: jwt_policy.proto

Package: security.policy.gloo.solo.io

Types:

JWTPolicyReport

FieldDescription
workspaces(repeated JWTPolicyReport.WorkspacesEntry)

The status of the resource in each workspace that it exists in.
selectedRoutes(repeated common.gloo.solo.io.RouteReference)

A list of references to all routes selected by the policy.

JWTPolicyReport.WorkspacesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.Report)

JWTPolicySpec

JWTPolicy used to enable JWT Authentication for routes.

Example: Sample JWT Payload:

  {
  "org": "solo-io",
  "iss": "https://localhost",
  "exp": 4804324736,
  "iat": 1648651136
}

Configuration below will enable JWT Authentication for selected routes as well as inject a header into the request containing the value found within the parsed claim if it exists. Empty sources default to extracting JWTs from Authorization Header with prefix “Bearer ”" or Query Param “access_token=”

  apiVersion: security.policy.gloo.solo.io/v2
kind: JWTPolicy
metadata:
  name: <name>
  namespace: <namespace>
spec:
  config:
    providers:
      <provider_name>:
        issuer: "https://localhost"
        local:
          inline: |
            <pem formatted public key>
        claimsToHeaders:
        - claim: org
          header: x-org
      stage: PRE_AUTHZ

This example enables JWT Authentication for selected routes and request will be checked using token found at either X-Auth header with prefix “Bearer ” or query param “auth_token=”. Note if a request has both sources available all tokens will need to be valid for the request to be accepted.

  apiVersion: security.policy.gloo.solo.io/v2
kind: JWTPolicy
metadata:
  name: <name>
  namespace: <namespace>
spec:
  config:
    providers:
      <provider_name>:
        issuer: "https://localhost"
        local:
          inline: |
            <pem formatted public key>
        tokenSource:
          header:
          - name: "X-Auth"
            prefix: "Bearer"
          queryParams:
          - "auth_token"
      stage: PRE_AUTHZ
FieldDescription
applyToRoutes(repeated common.gloo.solo.io.RouteSelector)

Select the routes where the policy will be applied. If left empty, no policy will be applied to any routes in the workspace.
config(JWTPolicySpec.Config)

The details of the JWT policy to apply to the selected routes.

JWTPolicySpec.Config

FieldDescription
providers(repeated JWTPolicySpec.Config.ProvidersEntry)

Map provider name to jwt provider configuration.
Successfully verified JWT payloads will be written to Envoy Dynamic Metadata in the format {{ policy generated prefix }}.{{ provider }}. For more info, see the payload_in_metadata field here.
Note: You can name the providers to help you map the provider when viewing logs to debug. However, the provider name does not affect the policy’s behavior and cannot be used by other resources to select the policy.
phase(common.gloo.solo.io.PrioritizedPhase)

Optional: Specify the phase to indicate where in the request chain this JWT Filter should be applied. If no phase is specified, the default will be preAuthz.
allowMissingOrFailed(bool)

Allow requests to succeed even if JWT authentication is missing or fails. For example, you might apply multiple policies to your routes to require JWT auth OR another method such as external auth. Set this value to “true” to allow a failed JWT auth request to pass through to the other authentication method. By default, this value is “false” so that requests that fail JWT authentication then fail authorization immediately.
clearRouteCache(JWTPolicySpec.Config.ClearRouteCache)

Optional: Decide whether to clear the route cache after the JWT filter. By clearing the route cache, the gateway recomputes route matching. This way, you can configure traffic rules after JWT auth, such as claim-based routing on cleared routes or direct response on cached routes. Defaults to the ‘AUTO’ option.
claims(repeated JWTPolicySpec.Config.ClaimMatcher)

Optional: A key-value list of claims to require for JWT authorization. The JWT must meet all of the claims to be allowed (logically AND’d together). For each claim, you can specify values that must or must not be present.
requiredScopes(repeated string)

Optional: An unordered list of required JWT scopes. The JWT “scope” claim must have all of the listed scopes to be allowed (logically AND’d together). Scopes typically come from an identity provider and are formatted similar to "<product>:<permission>" or "is:<role>". For more information, see the IETF docs.
For example, you might use this field to set email and is:developer as required scopes. Then the scope claim in the JWT must have all of those required scopes, but could also have others. JWTs with scopes such as "scope":"email is:developer" or "scope":"email is:developer phone address" would be allowed. JWTs with only one of the required scopes, such as "scope":"email address" would not be allowed.
If you want to set scopes that if present in the claim are not allowed (notValues), or to allow a request to succeed with just one of many listed scopes (email OR is:developer), use the claims field instead. To skip scope validation, omit this value or leave the list empty. Note that nested scopes (a scope with multiple sub scopes) are not supported at this time.

JWTPolicySpec.Config.ClaimMatcher

Optionally configure a list of key-value claims for JWT authorization rules. The JWT must meet all of the claims to be allowed (logically AND’d together). For each claim, you can specify values that must or must not be present. If a claim has multiple supported values, any of these values is allowed (logically OR’d together). You can also use wildcards, such as "*" to allow any value, or for example "*@solo.io" to allow any @solo.io email. Nested claims are not supported at this time.

FieldDescription
key(string)

The name of the JWT claim’s key. RFC 7519 spec reserves seven claims, and the IANA JSON Web Token Claims outline many more registered claims to encourage interoperability across providers. Further, your OIDC provider might have custom claims, such as described in the Auth0 docs.
values(repeated string)

Optional. A list of allowed values for the JWT claim. If a claim has multiple supported values, any of these values is allowed (logically OR’d together). You can also use wildcards, such as "*" to allow any value or for example "*@solo.io" to allow any @solo.io email. Nested claims are not supported at this time. Note: You must set at least one of “values” or “not_values”.
notValues(repeated string)

Optional. A list of values that are not allowed for the JWT claim. If a claim contains one of these values, the request is denied. You can also use wildcards, such as "*" to deny any value, or for example "*@solo.io" to deny any @solo.io email. Note: You must set at least one of “values” or “not_values”.

JWTPolicySpec.Config.Provider

Specifies how a JWT should be verified.

FieldDescription
issuer(string)

Optional: The principal that issued the JWT, usually a URL or an email address. If specified, the iss field in JWT token in the incoming request has to match this field else the request is denied. If left empty the iss field in the JWT token is not checked.
audiences(repeated string)

Optional: A list of intended audiences for this JWT token. A JWT containing any of these audiences will be accepted. If not specified, the audiences in JWT will not be checked.
tokenSource(JWTPolicySpec.Config.Provider.TokenSource)

Optional: If no explicit location is specified, the following default locations are tried in order:
1. The Authorization header using the Bearer
Authorization: Bearer .
2. access_token query parameter
https:///path?access_token=
Multiple JWTs can be verified for a request. Each JWT has to be extracted from the locations its provider specified or from the default locations. Note if a single request contains multiple sources e.g header and query param set, then all tokens found in the request will need to be valid for the request to be accepted. Configured fields are case sensitive will be matched verbatim
local(JWTPolicySpec.Config.Provider.LocalJWKS)

Local can be either inline raw string of public jwks or kubernetes secret reference.
remote(JWTPolicySpec.Config.Provider.RemoteJWKS)

JWKS from remote url source.
claimsToHeaders(repeated JWTPolicySpec.Config.Provider.ClaimsToHeader)

Optional: What claims should be copied to upstream headers.
keepToken(bool)

Optional: KeepToken is used to keep the JWT in the request post verification.
clockSkewSeconds(google.protobuf.UInt32Value)

Optional: ClockSkewSeconds is used to verify time constraints, such as exp and npf. Default is 60s For information about the value format, see the Google protocol buffer documentation.

JWTPolicySpec.Config.Provider.ClaimsToHeader

Allows copying verified claims to headers sent upstream

FieldDescription
claim(string)

Claim name. for example, “sub”
header(string)

The header the claim will be copied to. for example, “x-sub”.
append(bool)

If the header exists, append to it (true), or overwrite it (false).

JWTPolicySpec.Config.Provider.LocalJWKS

FieldDescription
secretRef(JWTPolicySpec.Config.Provider.LocalJWKS.SecretRef)

Reference to a secret containing the PEM formatted public key.
inline(string)

Inline PEM formatted public key.

JWTPolicySpec.Config.Provider.LocalJWKS.SecretRef

FieldDescription
objectRef(common.gloo.solo.io.ObjectReference)

Secret can be referenced explicitly by the namespace and cluster containing them.
key(string)

Key of data within specified secret.

JWTPolicySpec.Config.Provider.RemoteJWKS

FieldDescription
url(string)

The url used when accessing the remote destination for Json Web Key Set. This is used to set the host and path in the request
destinationRef(common.gloo.solo.io.DestinationReference)

The remote destination representing the Json Web Key Set server
cacheDuration(google.protobuf.Duration)

Duration after which the cached JWKS should be expired.
If not specified, default cache duration is 5 minutes. For information about the value format, see the Google protocol buffer documentation.
timeout(google.protobuf.Duration)

Sets the maximum duration in seconds that a response can take to arrive upon request.
If left empty, defaults to 5s For information about the value format, see the Google protocol buffer documentation.
enableAsyncFetch(bool)

Fetch Jwks asynchronously in the main thread before the listener is activated. Fetched Jwks can be used by all worker threads.
If this feature is not enabled:
* The Jwks is fetched on-demand when the requests come. During the fetching, first few requests are paused until the Jwks is fetched. * Each worker thread fetches its own Jwks since Jwks cache is per worker thread.
If this feature is enabled:
* Fetched Jwks is done in the main thread before the listener is activated. Its fetched Jwks can be used by all worker threads. Each worker thread doesn’t need to fetch its own. * Jwks is ready when the requests come, not need to wait for the Jwks fetching.

JWTPolicySpec.Config.Provider.TokenSource

Optional: Where to extract JWT Token in HTTP Request

If left empty, defaults to Header “Authorization: Bearer ” or Query Param “access_token=”

FieldDescription
headers(repeated JWTPolicySpec.Config.Provider.TokenSource.fromHeader)

Try to retrieve token from these headers
queryParams(repeated string)

Try to retrieve token from these query params

JWTPolicySpec.Config.Provider.TokenSource.fromHeader

Describes how to retrieve a JWT from a header

FieldDescription
name(string)

The name of header. E.g: “Authorization”
prefix(string)

Prefix before the token. for example, “Bearer " with space

JWTPolicySpec.Config.ProvidersEntry

FieldDescription
key(string)

value(JWTPolicySpec.Config.Provider)

JWTPolicyStatus

reflects the status of the JWTPolicyStatus

FieldDescription
common(common.gloo.solo.io.Status)

numSelectedRoutes(uint32)

The number of routes selected by the policy.

JWTPolicySpec.Config.ClearRouteCache

NameNumberDescription
AUTO0The default behavior, which clears the route cache when the auth response is successful or if the JWT policy adds a claim in the ‘claimsToHeader’ field. This way, the gateway recomputes route matching, such as to route traffic based on the claims you add in the JWT policy.
FALSE1Set to false so that the route cache is not cleared after the JWT filter. This way, you can configure traffic rules based on routing details from both before and after the JWT filter. For example, you might want to reject with a direct response any requests that send a header that is also set in the JWT policy’s ‘claimsToHeader’ field.
TRUE2Set to true so that the route cache is always cleared after the JWT filter. This way, the gateway recomputes route matching, such as to route traffic based on the claims you add in the JWT policy.