Authz Keycloak Configuration

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 · optional

Client secret. The value is encrypted with AES before being stored in etcd.
discovery — string · optional

URL to the discovery document. At least one of discovery and token_endpoint is required.
token_endpoint — string · optional

Token endpoint that supports the urn:ietf:params:oauth:grant-type:uma-ticket grant type to obtain access token. If provided, override the value from the discovery document. At least one of discovery and token_endpoint is required.
resource_registration_endpoint — string · optional

A UMA-compliant resource registration endpoint. Required when lazy_load_paths is true. The plugin will first look for the resource registration endpoint from this configuration option; if not found, look for the resource registration endpoint from the discovery document.
grant_type — string · optional · default: urn:ietf:params:oauth:grant-type:uma-ticket

Valid values: urn:ietf:params:oauth:grant-type:uma-ticket

Must be set to urn:ietf:params:oauth:grant-type:uma-ticket.
policy_enforcement_mode — string · optional · default: ENFORCING

Valid values: ENFORCING or PERMISSIVE

The mode of policy enforcement.

In ENFORCING mode, requests are denied when there is no policy associated with a given resource.

In PERMISSIVE mode, requests are allowed when there is no policy associated with a given resource.
permissions — array[string] · optional · default: []

An array of permissions representing a set of resources and scopes the client is seeking access. The format could be RESOURCE_ID#SCOPE_ID,RESOURCE_ID, or #SCOPE_ID. Used when lazy_load_paths is false. See obtaining permissions.
lazy_load_paths — boolean · optional · default: false

If true, require discovery or resource registration endpoint to dynamically resolve the request URI to resources. See lazy-load-paths.

Note that this requires the plugin to obtain a separate access token for itself from the token endpoint. Therefore, make sure you check the Service Accounts Enabled option in Keycloak to allow for client credentials grant. Also make sure that the issued access token contains the resource_access claim with the uma_protection role for plugin to query resources through the Protection API.
http_method_as_scope — boolean · optional · 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 · optional · default: 3000

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

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

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

Valid values: greater than 0

Expiration time of the refresh token in seconds.
refresh_token_expires_leeway — integer · optional · default: 0

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

If true, verify the OpenID provider's SSL certificates.
cache_ttl_seconds — integer · optional · default: 86400

Valid values: greater than 0

TTL in seconds for the plugin to cache discovery document and access tokens.
keepalive — boolean · optional · default: true

If true, enable HTTP keep-alive to keep connections open after use. Set to true if you are expecting a lot of requests to Keycloak.
keepalive_timeout — integer · optional · default: 60000

Valid values: greater than or equal to 1000

Idle time after which the established HTTP connections will be closed.
keepalive_pool — integer · optional · default: 5

Valid values: greater than or equal to 1

Maximum number of connections in the connection pool.
access_denied_redirect_uri — string · optional

URI to redirect the user to instead of returning an error message like "error_description":"not_authorized" when access is denied.
password_grant_token_generation_incoming_uri — string · optional

The URI incoming requests hit to generate token in the password grant, for example, /api/token. If the incoming request's URI matches the configured value, the request method is POST, and Content-Type is application/x-www-form-urlencoded, a token is generated at the token_endpoint.
max_req_body_size — integer · optional · default: 67108864

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 Enterprise 3.9.17 and 3.10.4, and in APISIX 3.18.0.