authz-keycloak

Description

The authz-keycloak Plugin can be used to add authentication with Keycloak Identity Server.

tip

Although this Plugin was developed to work with Keycloak, it should work with any OAuth/OIDC and UMA compliant identity providers as well.

Refer to Authorization Services Guide for more information on Keycloak.

Attributes

Name	Type	Required	Default	Valid values	Description
discovery	string	False		https://host.domain/auth/realms/foo/.well-known/uma2-configuration	URL to discovery document of Keycloak Authorization Services.
token_endpoint	string	False		https://host.domain/auth/realms/foo/protocol/openid-connect/token	An OAuth2-compliant token endpoint that supports the urn:ietf:params:oauth:grant-type:uma-ticket grant type. If provided, overrides the value from discovery.
resource_registration_endpoint	string	False		https://host.domain/auth/realms/foo/authz/protection/resource_set	A UMA-compliant resource registration endpoint. If provided, overrides the value from discovery.
client_id	string	False			The identifier of the resource server to which the client is seeking access. Either client_id or audience is required.
audience	string	False			Legacy parameter now replaced by client_id kept for backwards compatibility. Either client_id or audience is required.
client_secret	string	False			The client secret, if required.
grant_type	string	False	"urn:ietf:params:oauth:grant-type:uma-ticket"	["urn:ietf:params:oauth:grant-type:uma-ticket"]
policy_enforcement_mode	string	False	"ENFORCING"	["ENFORCING", "PERMISSIVE"]
permissions	array[string]	False			An array of strings, each representing a set of one or more resources and scopes the client is seeking access.
lazy_load_paths	boolean	False	false		When set to true, dynamically resolves the request URI to resource(s) using the resource registration endpoint instead of the static permission.
http_method_as_scope	boolean	False	false		When set to true, maps the HTTP request type to scope of the same name and adds to all requested permissions.
timeout	integer	False	3000	[1000, ...]	Timeout in ms for the HTTP connection with the Identity Server.
access_token_expires_in	integer	False	300	[1, ...]	Expiration time(s) of the access token.
access_token_expires_leeway	integer	False	0	[0, ...]	Expiration leeway(s) for access_token renewal. When set, the token will be renewed access_token_expires_leeway seconds before expiration. This avoids errors in cases where the access_token just expires when reaching the OAuth Resource Server.
refresh_token_expires_in	integer	False	3600	[1, ...]	The expiration time(s) of the refresh token.
refresh_token_expires_leeway	integer	False	0	[0, ...]	Expiration leeway(s) for refresh_token renewal. When set, the token will be renewed refresh_token_expires_leeway seconds before expiration. This avoids errors in cases where the refresh_token just expires when reaching the OAuth Resource Server.
ssl_verify	boolean	False	true		When set to true, verifies if TLS certificate matches hostname.
cache_ttl_seconds	integer	False	86400 (equivalent to 24h)	positive integer >= 1	Maximum time in seconds up to which the Plugin caches discovery documents and tokens used by the Plugin to authenticate to Keycloak.
keepalive	boolean	False	true		When set to true, enables 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	False	60000	positive integer >= 1000	Idle time after which the established HTTP connections will be closed.
keepalive_pool	integer	False	5	positive integer >= 1	Maximum number of connections in the connection pool.
access_denied_redirect_uri	string	False		[1, 2048]	URI to redirect the user to instead of returning an error message like "error_description":"not_authorized".
password_grant_token_generation_incoming_uri	string	False		/api/token	Set this to generate token using the password grant type. The Plugin will compare incoming request URI to this value.

Discovery and endpoints

It is recommended to use the discovery attribute as the authz-keycloak Plugin can discover the Keycloak API endpoints from it.

If set, the token_endpoint and resource_registration_endpoint will override the values obtained from the discovery document.

Client ID and secret

The Plugin needs the client_id or audience (for backwards compatibility) attribute for identification and to specify the context in which to evaluate permissions when interacting with Keycloak.

If both are configured, client_id is preferred.

If the lazy_load_paths attribute is set to true, then the Plugin additionally needs to obtain an access token for itself from Keycloak. In such cases, if the client access to Keycloak is confidential, you need to configure the client_secret attribute.

Policy enforcement mode

The policy_enforcement_mode attribute specifies how policies are enforced when processing authorization requests sent to the server.

ENFORCING mode

Requests are denied by default even when there is no policy associated with a resource.

The policy_enforcement_mode is set to ENFORCING by default.

PERMISSIVE mode

Requests are allowed when there is no policy associated with a given resource.

Permissions

When handling incoming requests, the Plugin can determine the permissions to check with Keycloak statically or dynamically from the properties of the request.

If the lazy_load_paths attribute is set to false, the permissions are taken from the permissions attribute. Each entry in permissions needs to be formatted as expected by the token endpoint's permission parameter. See Obtaining Permissions.

note

A valid permission can be a single resource or a resource paired with on or more scopes.

If the lazy_load_paths attribute is set to true, the request URI is resolved to one or more resources configured in Keycloak using the resource registration endpoint. The resolved resources are used as the permissions to check.

note

This requires the Plugin to obtain a separate access token for itself from the token endpoint. So, make sure to set the Service Accounts Enabled option in the client settings in Keycloak.

Also make sure that the issued access token contains the resource_access claim with the uma_protection role to ensure that the Plugin is able to query resources through the Protection API.

Automatically mapping HTTP method to scope

The http_method_as_scope is often used together with lazy_load_paths but can also be used with a static permission list.

If the http_method_as_scope attribute is set to true, the Plugin maps the request's HTTP method to the scope with the same name. The scope is then added to every permission to check.

If the lazy_load_paths attribute is set to false, the Plugin adds the mapped scope to any of the static permissions configured in the permissions attribute—even if they contain on or more scopes already.

Generating a token using password grant

To generate a token using password grant, you can set the value of the password_grant_token_generation_incoming_uri attribute.

If the incoming URI matches the configured attribute and the request method is POST, a token is generated using the token_endpoint.

You also need to add application/x-www-form-urlencoded as Content-Type header and username and password as parameters.

The example below shows a request if the password_grant_token_generation_incoming_uri is /api/token:

curl --location --request POST 'http://127.0.0.1:9080/api/token' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<User_Name>' \
--data-urlencode 'password=<Password>'

Enabling the Plugin

The example below shows how you can enable the authz-keycloak Plugin on a specific Route. ${realm} represents the realm name in Keycloak.

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/get",
    "plugins": {
        "authz-keycloak": {
            "token_endpoint": "http://127.0.0.1:8090/auth/realms/${realm}/protocol/openid-connect/token",
            "permissions": ["resource name#scope name"],
            "audience": "Client ID"
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'

Example usage

Once you have enabled the Plugin on a Route you can use it.

First, you have to get the JWT token from Keycloak:

curl \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "username=<YOUR_USERNAMED>" \
  -d "password=<YOUR_PASSWORD>" \
  -d "grant_type=password" \
  "http://<YOUR_KEYCLOAK_HOST>/auth/realms/${realm}/protocol/openid-connect/token"

Now you can make requests with the obtained JWT token:

curl http://127.0.0.1:9080/get -H 'Authorization: Bearer {JWT Token}'

To learn more about how you can integrate authorization policies into your API workflows you can checkout the unit test authz-keycloak.t.

Run the following Docker image and go to http://localhost:8090 to view the associated policies for the unit tests.

docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=123456 -p 8090:8080 sshniro/keycloak-apisix

The image below shows how the policies are configured in the Keycloak server:

Disable Plugin

To disable the authz-keycloak Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/get",
    "plugins": {
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'

Plugin roadmap

• Currently, the authz-keycloak Plugin requires you to define the resource name and the required scopes to enforce policies for a Route. Keycloak's official adapted (Java, Javascript) provides path matching by querying Keycloak paths dynamically and lazy loading the paths to identity resources. Upcoming releases of the Plugin will support this function.

• To support reading scope and configurations from the Keycloak JSON file.