{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://www.krakend.io/schema/v2.9/auth/validator.json",
  "title": "JWT validator",
  "description": "Protect endpoints from public usage by validating JWT tokens generated by any industry-standard OpenID Connect (OIDC) integration.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
  "type": "object",
  "oneOf": [
    {
      "required": [ "alg", "jwk_local_path" ]
    },
    {
      "required": [ "alg", "jwk_url" ]
    }
  ],
  "properties": {
    "alg": {
      "$id": "#auth/validator/alg",
      "title": "Algorithm",
      "description": "The hashing algorithm used by the token issuer.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": "RS256",
      "enum": [
        "EdDSA",
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ]
    },
    "audience": {
      "$id": "#auth/validator/audience",
      "title": "Audience",
      "description": "Reject tokens that do not contain ALL audiences declared in the list.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [
        [ "audience1" ]
      ],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "auth_header_name": {
      "$id": "#auth/validator/auth_header_name",
      "title": "Authorization header",
      "description": "Allows to parse the token from a custom header.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "X-Custom-Auth" ],
      "default": "Authorization",
      "type": "string"
    },
    "cache": {
      "$id": "#auth/validator/cache",
      "title": "Cache",
      "description": "Set this value to `true` (recommended) to stop downloading keys on every request and store them in memory for the next `cache_duration` period and avoid hammering the key server, as recommended for performance. Do not use this flag when using `jwk_local_ca`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": false,
      "type": "boolean"
    },
    "cache_duration": {
      "$id": "#auth/validator/cache_duration",
      "title": "Cache duration",
      "description": "The cache duration in seconds when the `cache` is enabled. 15 minutes when unset.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": 900,
      "type": "integer"
    },
    "cipher_suites": {
      "$id": "#auth/validator/cipher_suites",
      "title": "Cipher suites",
      "description": "Override the default cipher suites. Use it if you want to enforce an even higher security standard.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": [ 49199, 49195, 49200, 49196, 52392, 52393 ],
      "type": "array",
      "items": {
        "title": "Object in array",
        "description": "\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
        "enum": [
          5,
          10,
          47,
          53,
          60,
          156,
          157,
          49159,
          49161,
          49162,
          49169,
          49170,
          49171,
          49172,
          49187,
          49191,
          49199,
          49195,
          49200,
          49196,
          52392,
          52393
        ]
      }
    },
    "cookie_key": {
      "$id": "#auth/validator/cookie_key",
      "title": "Cookie key",
      "description": "Add the key name of the cookie containing the token when it is not passed in the headers\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "cookie_jwt" ],
      "type": "string"
    },
    "cypher_key": {
      "$id": "#auth/validator/cypher_key",
      "title": "Cypher key",
      "description": "The cyphering key.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "string"
    },
    "disable_jwk_security": {
      "$id": "#auth/validator/disable_jwk_security",
      "title": "Disable_jwk_security",
      "description": "When true, disables security of the JWK client and allows insecure connections (plain HTTP) to download the keys. Useful for development environments.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": false,
      "type": "boolean"
    },
    "failed_jwk_key_cooldown": {
      "title": "Failed JWK Key cooldown",
      "description": "When a request comes with a token declaring an unknown `kid` (or the key strategy you choose), and the JWK is in a remote destination, KrakenD downloads the JWK from the Identity Provider for its recognition. Suppose there is a network failure, or the key is not in the list (e.g., you rotated the keys without anticipation). In that case, you can tell the gateway not to contact the Identity Provider again during the time specified here. We recommend setting this value, even with a low time (e.g., `10s`), to prevent misconfigurations from hammering your Identity Providers. Any values under one second are ignored.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "1m", "10s", "1h" ],
      "$ref": "../timeunits.json#/$defs/timeunit",
      "type": "string"
    },
    "issuer": {
      "$id": "#auth/validator/issuer",
      "title": "Issuer",
      "description": "When set, tokens not matching the issuer are rejected.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "issuer" ],
      "type": "string"
    },
    "jwk_fingerprints": {
      "$id": "#auth/validator/jwk_fingerprints",
      "title": "Roles",
      "description": "A list of fingerprints (the certificate's unique identifier) for certificate pinning and avoid man-in-the-middle attacks. Add fingerprints in base64 format.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "jwk_local_ca": {
      "$id": "#auth/validator/jwk_local_ca",
      "title": "Local CA",
      "description": "Path to the CA's certificate verifying a secure connection when downloading the JWK. Use when not recognized by the system (e.g., self-signed certificates).\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "string"
    },
    "jwk_local_path": {
      "$id": "#auth/validator/jwk_local_path",
      "title": "JWK local path",
      "description": "Local path to the JWK public keys, has preference over `jwk_url`. Instead of pointing to an external URL (with `jwk_url`), public keys are kept locally, in a plain JWK file (security alert!), or encrypted. When encrypted, also add `secret_url` and `cypher_key`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "./jwk.txt" ],
      "type": "string"
    },
    "jwk_url": {
      "$id": "#auth/validator/jwk_url",
      "title": "JWK URL",
      "description": "The URL to the JWK endpoint with the public keys used to verify the token's authenticity and integrity. Use with `cache` to avoid re-downloading the key on every request. Consider enabling [shared caching](https://www.krakend.io/docs/authorization/jwk-caching/) too. The identity server will receive an HTTP(s) request from KrakenD with a KrakenD user agent, and the identity server must reply with a JSON object and a content-type `application/jwk-set+json` or `application/json`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [
        "https://some-domain.auth0.com/.well-known/jwks.json",
        "http://KEYCLOAK:8080/auth/realms/master/protocol/openid-connect/certs",
        "https://yourOktaBaseUrl/v1/keys"
      ],
      "type": "string"
    },
    "key_identify_strategy": {
      "$id": "#auth/validator/key_identify_strategy",
      "title": "Key identify strategy",
      "description": "Allows strategies other than `kid` to load keys.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "enum": [ "kid", "x5t", "kid_x5t" ]
    },
    "leeway": {
      "title": "Leeway",
      "description": "A margin of time where you will accept an already expired token. You should not accept expired tokens other than enabling two environments that are not perfectly synchronized and have minor clock drifts to accept each other differences. Any value specified here will be rounded to seconds, with a minimum of one second.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "1m", "1s" ],
      "default": "1s",
      "$ref": "../timeunits.json#/$defs/timeunit",
      "type": "string"
    },
    "operation_debug": {
      "$id": "#auth/validator/operation_debug",
      "title": "Debug",
      "description": "When `true`, any JWT **validation operation** gets printed in the log with a level `ERROR`. You will see if a client does not have sufficient roles, the allowed claims, scopes, and other useful information.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": false,
      "type": "boolean"
    },
    "propagate_claims": {
      "$id": "#auth/validator/propagate_claims",
      "title": "Claims to propagate",
      "description": "Enables passing claims in the backend's request header. You can pass nested claims using the dot `.` operator. E.g.: `realm_access.roles`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "array",
      "items": {
        "type": "array",
        "maxItems": 2,
        "minItems": 2,
        "items": {
          "type": "string"
        }
      }
    },
    "roles": {
      "$id": "#auth/validator/roles",
      "title": "Roles",
      "description": " When set, the JWT token not having at least one of the listed roles is rejected.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "roles_key": {
      "$id": "#auth/validator/roles_key",
      "title": "Roles key",
      "description": "When validating users through roles, provide the key name inside the JWT payload that lists their roles. If this key is nested inside another object, add `roles_key_is_nested` and use the dot notation `.` to traverse each level. E.g.: `resource_access.myclient.roles` represents the payload `{resource_access: { myclient: { roles: [\"myrole\"] } }`. Notice that the roles object you choose is a list, not a map.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [ "resource_access.myclient.roles" ],
      "type": "string"
    },
    "roles_key_is_nested": {
      "$id": "#auth/validator/roles_key_is_nested",
      "title": "Roles key is nested",
      "description": "If the roles key uses a nested object using the `.` dot notation, you must set it to `true` to traverse the object.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "boolean"
    },
    "scopes": {
      "$id": "#auth/validator/scopes",
      "title": "Scopes",
      "description": "A list of scopes to validate. The token, after decoding it, can have the scopes declared as a space-separated list, e.g.: `\"my_scopes\": \"resource1:action1 resource3:action7\"` or inside a list, e.g.: `\"my_scopes\": [\"resource1:action1\",\"resource3:action7\"]`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "scopes_key": {
      "$id": "#auth/validator/scopes_key",
      "title": "Scopes key",
      "description": "The key name where KrakenD can find the scopes. The key can be a nested object using the `.` dot notation, e.g.: `data.access.my_scopes`.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "type": "string"
    },
    "scopes_matcher": {
      "$id": "#auth/validator/scopes_matcher",
      "title": "Scopes matcher",
      "description": "Defines if the user needs to have in its token at least one of the listed claims (`any`), or `all` of them.\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "default": "any",
      "enum": [ "any", "all" ]
    },
    "secret_url": {
      "$id": "#auth/validator/secret_url",
      "title": "Secret's URL",
      "description": "An URL with a custom scheme using one of the supported providers (e.g.: `awskms://keyID`) (see providers).\n\nSee: https://www.krakend.io/docs/authorization/jwt-validation/",
      "examples": [
        "base64key://smGbjm71Nxd1Ig5FS0wj9SlbzAIrnolCz9bQQ6uAhl4=",
        "awskms://keyID",
        "azurekeyvault://keyID",
        "gcpkms://projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]",
        "hashivault://keyID"
      ],
      "type": "string",
      "pattern": "(base64key|awskms|azurekeyvault|gcpkms|hashivault)://(.*)"
    }
  },
  "patternProperties": {
    "^[@$_#]": {}
  },
  "additionalProperties": false
}