Authz Keycloak | APISIX & API7 API Gateway Docs

Parameters

See plugin common configurations 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 and secrets.

client_id
string
required
Client ID.
client_secret
string
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
URL to the discovery document. At least one of discovery and token_endpoint is required.
token_endpoint
string
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
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
default: urn:ietf:params:oauth:grant-type:uma-ticket
vaild vaule:
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
default: ENFORCING
vaild vaule:
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]
default: []
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
default: false
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
default: false
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
default: 3000
vaild vaule:
greater than or equal to 1000
Timeout in milliseconds for the HTTP connection with the identity provider.
access_token_expires_in
integer
default: 300
vaild vaule:
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
vaild vaule:
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
default: 3600
vaild vaule:
greater than 0
Expiration time of the refresh token in seconds.
refresh_token_expires_leeway
integer
vaild vaule:
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
default: true
If true, verify the OpenID provider's SSL certificates.
cache_ttl_seconds
integer
default: 86400
vaild vaule:
greater than 0
TTL in seconds for the plugin to cache discovery document and access tokens.
keepalive
boolean
default: true
If true, keep HTTP connections to the identity provider open for reuse.
keepalive_timeout
integer
default: 60000
vaild vaule:
greater than or equal to 1000
Idle time in milliseconds after which an established HTTP connection is closed.
keepalive_pool
integer
default: 5
vaild vaule:
greater than or equal to 1
Maximum number of connections in the connection pool.
access_denied_redirect_uri
string
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
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
default: 67108864
vaild vaule:
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.

Parameters​

Parameters