Authz Keycloak Configuration
Configuration reference for the Authz Keycloak plugin (`authz-keycloak`): the parameters, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
This plugin supports referencing parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin (opens in Apache APISIX docs) and secrets (opens in Apache APISIX docs).
client_id — string · required · since APISIX 2.3 · API7 Gateway 3.2.9.3
Client ID.
client_secret — string · optional · since APISIX 2.3 · API7 Gateway 3.2.9.3
Client secret used when the plugin authenticates to the token endpoint. When field encryption is enabled and configuration is stored in etcd, the gateway encrypts this value before storage.
discovery — string · optional · since APISIX 2.3 · API7 Gateway 3.2.9.3
URL to the discovery document. At least one of discovery and token_endpoint is required.
token_endpoint — string · optional · since APISIX 1.4 · API7 Gateway 3.2.9.3
Token endpoint that supports the urn:ietf:params:oauth:grant-type:uma-ticket grant type for permission evaluation. If provided, it overrides the value from the discovery document. At least one of discovery and token_endpoint is required.
resource_registration_endpoint — string · optional · since APISIX 2.3 · API7 Gateway 3.2.9.3
A UMA-compliant resource registration endpoint. When lazy_load_paths is true, the plugin uses this value first and otherwise obtains the endpoint from the discovery document. Dynamic path loading requires discovery, or both token_endpoint and resource_registration_endpoint.
grant_type — string · optional · default: urn:ietf:params:oauth:grant-type:uma-ticket · since APISIX 1.4 · API7 Gateway 3.2.9.3
Valid values: urn:ietf:params:oauth:grant-type:uma-ticket
UMA ticket grant used for permission evaluation. This is the default and only accepted value.
policy_enforcement_mode — string · optional · default: ENFORCING · since APISIX 1.4 · API7 Gateway 3.2.9.3
Valid values: ENFORCING or PERMISSIVE
Controls how the plugin handles an empty permission list before it requests a decision from Keycloak.
In ENFORCING mode, an empty permission list returns 403 Forbidden, or 307 Temporary Redirect when access_denied_redirect_uri is configured.
In PERMISSIVE mode, the plugin continues to the UMA token request without a permission parameter. Keycloak still determines whether the request is authorized.
permissions — array[string] · optional · default: [] · since APISIX 1.4 · API7 Gateway 3.2.9.3
Permissions representing the resources and scopes the client is seeking access to. Supported forms are RESOURCE_ID#SCOPE_ID, RESOURCE_ID, and #SCOPE_ID. Used when lazy_load_paths is false. See obtaining permissions.
lazy_load_paths — boolean · optional · default: false · since APISIX 2.3 · API7 Gateway 3.2.9.3
If true, dynamically resolve the request URI to Keycloak resources through the resource registration endpoint. See lazy load paths.
Dynamic loading requires the plugin to obtain a service-account access token. Enable Service account roles for the Keycloak client and ensure the token contains the uma_protection role before using the Protection API.
http_method_as_scope — boolean · optional · default: false · since APISIX 2.3 · API7 Gateway 3.2.9.3
If true, use the HTTP method of the request as the scope to check whether access should be granted.
In the case where lazy_load_paths is set to false, the plugin adds the mapped scope to any of the static permissions configured in the permissions attribute, even when they contain one or more scopes already.
timeout — integer · optional · default: 3000 · since APISIX 1.4 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 1000
Timeout in milliseconds for the HTTP connection with the identity provider.
access_token_expires_in — integer · optional · default: 300 · since APISIX 2.13.0 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 1
Lifetime of the access token in seconds if no expires_in attribute is present in the token endpoint response.
access_token_expires_leeway — integer · optional · default: 0 · since APISIX 2.13.0 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 0
Expiration leeway in seconds for access token renewal. When set to a value greater than 0, token renewal will take place the set amount of time before token expiration. This avoids errors in case the access token just expires when arriving to the resource server.
refresh_token_expires_in — integer · optional · default: 3600 · since APISIX 2.13.0 · API7 Gateway 3.2.9.3
Valid values: greater than 0
Expiration time of the refresh token in seconds.
refresh_token_expires_leeway — integer · optional · default: 0 · since APISIX 2.13.0 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 0
Expiration leeway in seconds for refresh token renewal. When set to a value greater than 0, token renewal will take place the set amount of time before token expiration. This avoids errors in case the access token just expires when arriving to the resource server.
ssl_verify — boolean · optional · default: true · since APISIX 2.0 · API7 Gateway 3.2.9.3
If true, verify the OpenID provider's SSL certificates.
cache_ttl_seconds — integer · optional · default: 86400 · since APISIX 2.3 · API7 Gateway 3.2.9.3
Valid values: greater than 0
TTL in seconds for the plugin to cache discovery document and access tokens.
keepalive — boolean · optional · default: true · since APISIX 1.4 · API7 Gateway 3.2.9.3
If true, keep HTTP connections to the identity provider open for reuse.
keepalive_timeout — integer · optional · default: 60000 · since APISIX 1.4 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 1000
Idle time in milliseconds after which an established HTTP connection is closed.
keepalive_pool — integer · optional · default: 5 · since APISIX 1.4 · API7 Gateway 3.2.9.3
Valid values: greater than or equal to 1
Maximum number of connections in the connection pool.
access_denied_redirect_uri — string · optional · since APISIX 2.13.0 · API7 Gateway 3.2.9.3
URI used for a 307 Temporary Redirect when the permission list is empty in ENFORCING mode or Keycloak returns 403 Forbidden.
password_grant_token_generation_incoming_uri — string · optional · since APISIX 2.14.1 · API7 Gateway 3.2.9.3
Legacy compatibility option that exposes an endpoint for the OAuth Resource Owner Password Credentials grant. When a form-encoded POST containing username and password matches this URI, the plugin submits a password-grant request to the configured token_endpoint and returns its response. OAuth 2.0 Security Best Current Practice states that this grant must not be used. Do not configure this field for new deployments. See RFC 9700, section 2.4.
max_req_body_size — integer · optional · default: 67108864 · since APISIX 3.18.0 · API7 Gateway 3.9.17
Valid values: greater than or equal to 1
Maximum request body size in bytes buffered into memory when the plugin generates a password-grant token. If the body exceeds the limit or cannot be read, the plugin returns 503 Service Unavailable. Available in API7 Gateway 3.9.17 and 3.10.4, and in APISIX 3.18.0.