authz-keycloak

Authorizes requests with Keycloak's authorization services.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin authz-keycloakPriority 2000

What it does

authz-keycloak lets a request through only when Keycloak's authorization services grant its caller what the route asks for. The caller sends a bearer token from the Keycloak realm, and the person or client it stands for lives in Keycloak, not on a consumer. Each entry under Permissions names a resource of the realm, with a scope after a #.

The gateway asks Keycloak as the client under Client ID, so the realm's own policies decide who passes. A request without a token is answered 401 with Missing JWT token in request. Authentication explains callers who sign in at an identity provider.

When to use it

• Keycloak already holds who may read or change orders, and the gateway should apply those rules to every call without a copy of them.
• A mobile app signs its users in at Keycloak and sends their bearer token, and only users granted orders#read reach the orders API.
• Permissions that follow the request path and method, with Resolve the resources from the path and Method as the scope on, so a new endpoint needs only a new resource in Keycloak.

Not for signing people in to a web application at an identity provider — see openid-connect (Authenticates users against an OpenID Connect provider), checking a token on the gateway without asking anyone — see jwt-auth (Authenticates consumers with a JSON Web Token they present) or a decision made by an authorization service of your own — see forward-auth (Delegates authentication to an external service).

Set it up

Let through only callers Keycloak grants read access to orders

The caller sends a bearer token from the realm, and the realm's authorization services hold a resource orders with the scope read.

Under Basics set Client ID to api-gateway, set Client secret to <secret>, set Discovery to https://keycloak.example.com/realms/main/.well-known/uma2-configuration and fill Permissions as in the JSON below.

authz-keycloak · as the console saves it

{
  "client_id": "api-gateway",
  "client_secret": "<secret>",
  "discovery": "https://keycloak.example.com/realms/main/.well-known/uma2-configuration",
  "permissions": [
    "orders#read"
  ]
}

Things to know

• Permissions — orders#read asks for the scope read on the resource orders, both held by the realm's authorization services.
• Permissions — Under Enforcing, a request with no permission named here or resolved from its path is refused with 403.
• Resolve the resources from the path — On, a discovery document or a resource registration endpoint must be written too.
• Discovery — A discovery document or a token endpoint has to be written; a configuration with neither is refused when you save.
• Policy enforcement mode — Only ENFORCING and PERMISSIVE can be set; LOOSE is refused when you save.
• Password grant URI — A form POST to exactly this path is answered with a token for the username and password in its body, without authorization. It needs Token endpoint written: with discovery alone the POST answers 503.
• Password grant URI — A path that does not start with / is refused when you save.
• Request body limit — Read only on a form POST to the password grant address above. A body over it is answered 503.
• AdviceGive the gateway a Keycloak client of its own, used only for these checks, so that its Client secret can be replaced without touching other applications.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section.

Basics

Client IDclient_idstringRequired

The client ID of this API in the identity provider, such as payments-api.

1 to 100 characters

Client secretclient_secretstring

The client secret from the identity provider. Stored on the engine and shown only to roles that manage this object.

1 to 100 characters

DiscoverydiscoverystringRequired unless Token endpoint is set

The identity provider's UMA 2 configuration. The endpoints below are read from it unless written there. The password grant address still needs Token endpoint written: with discovery alone its POST answers 503.

1 to 4096 characters · example https://keycloak.example.com/realms/main/.well-known/uma2-configuration

Token endpointtoken_endpointstringRequired unless Discovery is set

1 to 4096 characters

Permissionspermissionsarray of stringsdefault []

Each name is a resource of the identity provider, with a scope written after a # where one is wanted.

each 1 to 100 characters

Behavior

Policy enforcement modepolicy_enforcement_modestringdefault ENFORCING

one of ENFORCING, PERMISSIVE

Grant typegrant_typestringdefault urn:ietf:params:oauth:grant-type:uma-ticket

1 to 100 characters · one of urn:ietf:params:oauth:grant-type:uma-ticket

Resolve the resources from the pathlazy_load_pathsbooleandefault false

On, the resources are looked up from the request path at every request and the list above is not read at all.

Method as the scopehttp_method_as_scopebooleandefault false

The request's method is added to every permission as its scope.

Access denied redirect URIaccess_denied_redirect_uristring

A refusal is answered 307 with this address in a Location header instead of 403.

1 to 2048 characters

Resource registration endpointresource_registration_endpointstring

1 to 4096 characters

Password grant URIpassword_grant_token_generation_incoming_uristring

1 to 4096 characters ·

pattern

^/

Timeouttimeoutintegerdefault 3000

at least 1000 · in milliseconds

SSL verifyssl_verifybooleandefault true

Advanced

Access token expires inaccess_token_expires_inintegerdefault 300

at least 1 · in seconds

Access token expires leewayaccess_token_expires_leewayintegerdefault 0

at least 0 · in seconds

Refresh token expires inrefresh_token_expires_inintegerdefault 3600

at least 1 · in seconds

Refresh token expires leewayrefresh_token_expires_leewayintegerdefault 0

at least 0 · in seconds

Cache lifetimecache_ttl_secondsintegerdefault 86400

at least 1 · in seconds

Request body limitmax_req_body_sizeintegerdefault 67108864

The largest client body, in bytes, read into memory while a password grant token is asked for.

at least 1

Keepalivekeepalivebooleandefault true

Keepalive poolkeepalive_poolintegerdefault 5

at least 1

Keepalive timeoutkeepalive_timeoutintegerdefault 60000

at least 1000 · in milliseconds

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.