> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-authentication.md).
# Authentication plugins
Plugins in this category check who is calling the gateway before the request reaches the upstream. Attach exactly one authentication plugin to a route or a service to require credentials; the AILIX developer portal lets your consumers manage those credentials themselves. The catalogue ships 15 Authentication plugins.
{% hint style="info" %}
**In this category:** [`authz-casbin`](#authz-casbin), [`authz-casdoor`](#authz-casdoor), [`authz-keycloak`](#authz-keycloak), [`basic-auth`](#basic-auth), [`cas-auth`](#cas-auth), [`forward-auth`](#forward-auth), [`hmac-auth`](#hmac-auth), [`jwe-decrypt`](#jwe-decrypt), [`jwt-auth`](#jwt-auth), [`key-auth`](#key-auth), [`ldap-auth`](#ldap-auth), [`multi-auth`](#multi-auth), [`opa`](#opa), [`openid-connect`](#openid-connect), [`wolf-rbac`](#wolf-rbac)
{% endhint %}
### `authz-casbin`
The `authz-casbin` Plugin is an authorization Plugin based on [Lua Casbin](https://github.com/casbin/lua-casbin/). This Plugin supports powerful authorization scenarios based on various [access control models](https://casbin.org/docs/en/supported-models).
{% hint style="info" %}
**Priority** `2560` · **Category** Authentication
{% endhint %}
Configuration and details
| Name | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------------------------------------------- |
| model\_path | string | True | Path of the Casbin model configuration file. |
| policy\_path | string | True | Path of the Casbin policy file. |
| model | string | True | Casbin model configuration in text format. |
| policy | string | True | Casbin policy in text format. |
| username | string | True | Header in the request that will be used in the request to pass the username (subject). |
### `authz-casdoor`
The `authz-casdoor` Plugin can be used to add centralized authentication with [Casdoor](https://casdoor.org/).
{% hint style="info" %}
**Priority** `2559` · **Category** Authentication · **Required** `callback_url`, `endpoint_addr`, `client_id`, `client_secret`
{% endhint %}
Configuration and details
| Name | Type | Required | Description |
| -------------- | ------ | -------- | -------------------------------------------- |
| endpoint\_addr | string | True | URL of Casdoor. |
| client\_id | string | True | Client ID in Casdoor. |
| client\_secret | string | True | Client secret in Casdoor. |
| callback\_url | string | True | Callback URL used to receive state and code. |
### `authz-keycloak`
The `authz-keycloak` Plugin can be used to add authentication with [Keycloak Identity Server](https://www.keycloak.org/).
{% hint style="info" %}
**Priority** `2000` · **Category** Authentication · **Required** `client_id`
{% endhint %}
Configuration and details
:::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](https://www.keycloak.org/docs/latest/authorization_services/) for more information on Keycloak.
| Name | Type | Required | Default | Valid values | Description |
| ------------------------------------------------- | -------------- | -------- | --------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| discovery | string | False | | | URL to [discovery document](https://www.keycloak.org/docs/latest/authorization_services/index.html) of Keycloak Authorization Services. |
| token\_endpoint | string | False | | | 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 | | | A UMA-compliant resource registration endpoint. If provided, overrides the value from discovery. |
| client\_id | string | True | | | The identifier of the resource server to which the client is seeking access. |
| client\_secret | string | False | | | The client secret, if required. You can use AILIX secret to store and reference this value. AILIX currently supports storing secrets in two ways. Environment Variables and HashiCorp Vault |
| 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. |
### `basic-auth`
The `basic-auth` Plugin adds [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) for Consumers to authenticate themselves before being able to access Upstream resources.
{% hint style="info" %}
**Priority** `2520` · **Category** Authentication
{% endhint %}
Configuration and details
When a Consumer is successfully authenticated, AILIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
**Consumer/Credentials**
| Name | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------ |
| username | string | True | Unique basic auth username for a consumer. |
| password | string | True | Basic auth password for the consumer. |
**Route**
| Name | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------- |
| hide\_credentials | boolean | False | false | If true, do not pass the authorization request header to Upstream services. |
| anonymous\_consumer | boolean | False | false | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
| realm | string | False | basic | The realm to include in the `WWW-Authenticate` header when authentication fails. |
### `cas-auth`
The `cas-auth` Plugin can be used to access CAS (Central Authentication Service 2.0) IdP (Identity Provider) to do authentication, from the SP (service provider) perspective.
{% hint style="info" %}
**Priority** `2597` · **Category** Authentication · **Required** `idp_uri`, `cas_callback_uri`, `logout_uri`
{% endhint %}
Configuration and details
| Name | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------------------------------------------- |
| `idp_uri` | string | True | URI of IdP. |
| `cas_callback_uri` | string | True | redirect uri used to callback the SP from IdP after login or logout. |
| `logout_uri` | string | True | logout uri to trigger logout. |
### `forward-auth`
The `forward-auth` Plugin implements a classic external authentication model. When authentication fails, you can have a custom error message or redirect the user to an authentication page.
{% hint style="info" %}
**Priority** `2002` · **Category** Authentication · **Required** `uri`
{% endhint %}
Configuration and details
This Plugin moves the authentication and authorization logic to a dedicated external service. AILIX forwards the user's requests to the external service, blocks the original request, and replaces the result when the external service responds with a non 2xx status code.
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | -------------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uri | string | True | | | URI of the authorization service. |
| ssl\_verify | boolean | False | true | | When set to `true`, verifies the SSL certificate. |
| request\_method | string | False | GET | \["GET","POST"] | HTTP method for a client to send requests to the authorization service. When set to `POST` the request body is sent to the authorization service. (not recommended - see section on [Using data from POST body](#using-data-from-post-body-to-make-decision-on-authorization-service)) |
| request\_headers | array\[string] | False | | | Client request headers to be sent to the authorization service. If not set, only the headers provided by AILIX are sent (for example, `X-Forwarded-XXX`). |
| extra\_headers | object | False | | | Extra headers to be sent to the authorization service passed in key-value format. The value can be a variable like `$request_uri`, `$post_arg.xyz` |
| upstream\_headers | array\[string] | False | | | Authorization service response headers to be forwarded to the Upstream. If not set, no headers are forwarded to the Upstream service. |
| client\_headers | array\[string] | False | | | Authorization service response headers to be sent to the client when authorization fails. If not set, no headers will be sent to the client. |
| timeout | integer | False | 3000ms | \[1, 60000]ms | Timeout for the authorization service HTTP call. |
| keepalive | boolean | False | true | | When set to `true`, keeps the connection alive for multiple requests. |
| keepalive\_timeout | integer | False | 60000ms | \[1000, ...]ms | Idle time after which the connection is closed. |
| keepalive\_pool | integer | False | 5 | \[1, ...]ms | Connection pool limit. |
| allow\_degradation | boolean | False | false | | When set to `true`, allows authentication to be skipped when authentication server is unavailable. |
| status\_on\_error | integer | False | 403 | \[200,...,599] | Sets the HTTP status that is returned to the client when there is a network error to the authorization service. The default status is “403” (HTTP Forbidden). |
### `hmac-auth`
The `hmac-auth` Plugin supports HMAC (Hash-based Message Authentication Code) authentication as a mechanism to ensure the integrity of requests, preventing them from being modified during transmissions. To use the Plugin, you would configure HMAC secret keys on Consumers and enable the Plugin on Routes or Services.
{% hint style="info" %}
**Priority** `2530` · **Category** Authentication
{% endhint %}
Configuration and details
When a Consumer is successfully authenticated, AILIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header and check that incoming requests are from trusted sources. Specifically, when AILIX receives an HMAC-signed request, the key ID is extracted from the `Authorization` header. AILIX then retrieves the corresponding Consumer configuration, including the secret key. If the key ID is valid and exists, AILIX generates an HMAC signature using the request's `Date` header and the secret key. If this generated signature matches the signature provided in the `Authorization` header, the request is authenticated and forwarded to Upstream services.
The Plugin implementation is based on [draft-cavage-http-signatures](https://www.ietf.org/archive/id/draft-cavage-http-signatures-12.txt).
| Name | Type | Required | Default | Valid values | Description |
| ----------- | ------ | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| key\_id | string | True | | | Unique identifier for the Consumer, which identifies the associated configurations such as the secret key. |
| secret\_key | string | True | | | Secret key used to generate an HMAC. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
| Name | Type | Required | Default | Valid values | Description |
| ----------------------- | -------------- | -------- | ------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allowed\_algorithms | array\[string] | False | \["hmac-sha1","hmac-sha256","hmac-sha512"] | combination of "hmac-sha1","hmac-sha256",and "hmac-sha512" | The list of HMAC algorithms allowed. |
| clock\_skew | integer | False | 300 | >=1 | Maximum allowable time difference in seconds between the client request's timestamp and AILIX server's current time. This helps account for discrepancies in time synchronization between the client’s and server’s clocks and protect against replay attacks. The timestamp in the Date header (must be in GMT format) will be used for the calculation. |
| signed\_headers | array\[string] | False | | | The list of HMAC-signed headers that should be included in the client request's HMAC signature. |
| validate\_request\_body | boolean | False | false | | If true, validate the integrity of the request body to ensure it has not been tampered with during transmission. Specifically, the Plugin creates a SHA-256 base64-encoded digest and compare it to the `Digest` header. If the `Digest` header is missing or if the digests do not match, the validation fails. |
| hide\_credentials | boolean | False | false | | If true, do not pass the authorization request header to Upstream services. |
| anonymous\_consumer | string | False | | | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
| realm | string | False | hmac | | The realm to include in the `WWW-Authenticate` header when authentication fails. |
### `jwe-decrypt`
The `jwe-decrypt` Plugin is used to decrypt [JWE](https://datatracker.ietf.org/doc/html/rfc7516) authorization headers in requests to an AILIX Service or Route.
{% hint style="info" %}
**Priority** `2509` · **Category** Authentication · **Required** `header`, `forward_header`
{% endhint %}
Configuration and details
This Plugin adds an endpoint `/ailix/plugin/jwe/encrypt` for JWE encryption. For decryption, the key should be configured in Consumer.
**Consumer**
| Name | Type | Required | Default | Valid values | Description |
| ------------------- | ------- | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| key | string | True | | | Unique key for a Consumer. |
| secret | string | True | | | The decryption key. Must be 32 characters. The key could be saved in a secret manager using the Secret resource. |
| is\_base64\_encoded | boolean | False | false | | Set to true if the secret is base64 encoded. |
**Route**
| Name | Type | Required | Default | Description |
| --------------- | ------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| header | string | True | Authorization | The header to get the token from. |
| forward\_header | string | True | Authorization | Set the header name that passes the plaintext to the Upstream. |
| strict | boolean | False | true | If true, throw a 403 error if JWE token is missing from the request. If false, do not throw an error if JWE token cannot be found. |
### `jwt-auth`
The `jwt-auth` Plugin supports the use of [JSON Web Token (JWT)](https://jwt.io/) as a mechanism for clients to authenticate themselves before accessing Upstream resources.
{% hint style="info" %}
**Priority** `2510` · **Category** Authentication
{% endhint %}
Configuration and details
Once enabled, the Plugin exposes an endpoint to create JWT credentials by Consumers. The process generates a token that client requests should carry to identify themselves to AILIX. The token can be included in the request URL query string, request header, or cookie. AILIX will then verify the token to determine if a request should be allowed or denied to access Upstream resources.
When a Consumer is successfully authenticated, AILIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
**Consumer/Credential**
| Name | Type | Required | Default | Valid values | Description |
| ----------------------- | ------- | ---------------------------------------------------------------- | ------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | True | | non-empty | Unique key for a Consumer. |
| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
| public\_key | string | True if `RS256` or `ES256` is set for the `algorithm` attribute. | | | RSA or ECDSA public key. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
| algorithm | string | False | HS256 | \["HS256","HS512","RS256","ES256"] | Encryption algorithm. |
| exp | integer | False | 86400 | \[1,...] | Expiry time of the token in seconds. |
| base64\_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
| lifetime\_grace\_period | integer | False | 0 | \[0,...] | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
| key\_claim\_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
**Routes or Services**
| Name | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| header | string | False | authorization | The header to get the token from. |
| query | string | False | jwt | The query string to get the token from. Lower priority than header. |
| cookie | string | False | jwt | The cookie to get the token from. Lower priority than query. |
| hide\_credentials | boolean | False | false | If true, do not pass the header, query, or cookie with JWT to Upstream services. |
| key\_claim\_name | string | False | key | The name of the JWT claim that contains the user key (corresponds to Consumer's key attribute). |
| anonymous\_consumer | string | False | false | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
| store\_in\_ctx | boolean | False | false | Set to true will store the JWT payload in the request context (`ctx.jwt_auth_payload`). This allows lower-priority plugins that run afterwards on the same request to retrieve and use the JWT token. |
| realm | string | False | jwt | The realm to include in the `WWW-Authenticate` header when authentication fails. |
### `key-auth`
The `key-auth` Plugin supports the use of an authentication key as a mechanism for clients to authenticate themselves before accessing Upstream resources.
{% hint style="info" %}
**Priority** `2500` · **Category** Authentication
{% endhint %}
Configuration and details
To use the plugin, you would configure authentication keys on Consumers and enable the Plugin on routes or services. The key can be included in the request URL query string or request header. AILIX will then verify the key to determine if a request should be allowed or denied to access Upstream resources.
When a Consumer is successfully authenticated, AILIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
**Consumer/Credential**
| Name | Type | Required | Description |
| ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| key | string | True | Unique key for a Consumer. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
**Route**
| Name | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------- |
| header | string | False | apikey | The header to get the key from. |
| query | string | False | apikey | The query string to get the key from. Lower priority than header. |
| hide\_credentials | boolean | False | false | If true, do not pass the header or query string with key to Upstream services. |
| anonymous\_consumer | string | False | false | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
| realm | string | False | key | The realm to include in the `WWW-Authenticate` header when authentication fails. |
### `ldap-auth`
The `ldap-auth` Plugin can be used to add LDAP authentication to a Route or a Service.
{% hint style="info" %}
**Priority** `2540` · **Category** Authentication · **Required** `base_dn`, `ldap_uri`
{% endhint %}
Configuration and details
This Plugin works with the Consumer object and the consumers of the API can authenticate with an LDAP server using [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
This Plugin uses lua-resty-ldap for connecting with an LDAP server.
**Consumer**
| Name | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_dn | string | True | User dn of the LDAP client. For example, `cn=user01,ou=users,dc=example,dc=org`. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
**Route**
| Name | Type | Required | Default | Description |
| ----------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| base\_dn | string | True | | Base dn of the LDAP server. For example, `ou=users,dc=example,dc=org`. |
| ldap\_uri | string | True | | URI of the LDAP server. |
| use\_tls | boolean | False | `false` | If set to `true` uses TLS. |
| tls\_verify | boolean | False | `false` | Whether to verify the server certificate when `use_tls` is enabled; If set to `true`, you must set `ssl_trusted_certificate` in `config.yaml`, and make sure the host of `ldap_uri` matches the host in server certificate. |
| uid | string | False | `cn` | uid attribute. |
| realm | string | False | ldap | The realm to include in the `WWW-Authenticate` header when authentication fails. |
### `multi-auth`
The `multi-auth` Plugin is used to add multiple authentication methods to a Route or a Service. It supports plugins of type 'auth'. You can combine different authentication methods using `multi-auth` plugin.
{% hint style="info" %}
**Priority** `2600` · **Category** Authentication · **Required** `auth_plugins`
{% endhint %}
Configuration and details
This plugin provides a flexible authentication mechanism by iterating through the list of authentication plugins specified in the `auth_plugins` attribute. It allows multiple consumers to share the same route while using different authentication methods. For example, one consumer can authenticate using basic authentication, while another consumer can authenticate using JWT.
**Route**
| Name | Type | Required | Default | Description |
| ------------- | ----- | -------- | ------- | --------------------------------------------------------------------- |
| auth\_plugins | array | True | - | Add supporting auth plugins configuration. expects at least 2 plugins |
### `opa`
The `opa` Plugin can be used to integrate with [Open Policy Agent (OPA)](https://www.openpolicyagent.org). OPA is a policy engine that helps defininig and enforcing authorization policies, which determines whether a user or application has the necessary permissions to perform a particular action or access a particular resource. Using OPA with AILIX decouples authorization logics from AILIX.
{% hint style="info" %}
**Priority** `2001` · **Category** Authentication · **Required** `host`, `policy`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | ------- | -------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| host | string | True | | | Host address of the OPA service. For example, `https://localhost:8181`. |
| ssl\_verify | boolean | False | true | | When set to `true` verifies the SSL certificates. |
| policy | string | True | | | OPA policy path. A combination of `package` and `decision`. While using advanced features like custom response, you can omit `decision`. When specifying a namespace, use the slash format (`examples/echo`) instead of dot notation (`examples.echo`). |
| timeout | integer | False | 3000ms | \[1, 60000]ms | Timeout for the HTTP call. |
| keepalive | boolean | False | true | | When set to `true`, keeps the connection alive for multiple requests. |
| keepalive\_timeout | integer | False | 60000ms | \[1000, ...]ms | Idle time after which the connection is closed. |
| keepalive\_pool | integer | False | 5 | \[1, ...]ms | Connection pool limit. |
| with\_route | boolean | False | false | | When set to true, sends information about the current Route. |
| with\_service | boolean | False | false | | When set to true, sends information about the current Service. |
| with\_consumer | boolean | False | false | | When set to true, sends information about the current Consumer. Note that this may send sensitive information like the API key. Make sure to turn it on only when you are sure it is safe. |
### `openid-connect`
The `openid-connect` Plugin supports the integration with [OpenID Connect (OIDC)](https://openid.net/connect/) identity providers, such as Keycloak, Auth0, Microsoft Entra ID, Google, Okta, and more. It allows AILIX to authenticate clients and obtain their information from the identity provider before allowing or denying their access to upstream protected resources.
{% hint style="info" %}
**Priority** `2599` · **Category** Authentication · **Required** `client_id`, `client_secret`, `discovery`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ------------------------------------------------- | -------------- | -------- | --------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_id | string | True | | | OAuth client ID. |
| client\_secret | string | True | | | OAuth client secret. |
| discovery | string | True | | | URL to the well-known discovery document of the OpenID provider, which contains a list of OP API endpoints. The Plugin can directly utilize the endpoints from the discovery document. You can also configure these endpoints individually, which takes precedence over the endpoints supplied in the discovery document. |
| scope | string | False | openid | | OIDC scope that corresponds to information that should be returned about the authenticated user, also known as [claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This is used to authorize users with proper permission. The default value is `openid`, the required scope for OIDC to return a `sub` claim that uniquely identifies the authenticated user. Additional scopes can be appended and delimited by spaces, such as `openid email profile`. |
| required\_scopes | array\[string] | False | | | Scopes required to be present in the access token. Used in conjunction with the introspection endpoint when `bearer_only` is `true`. If any required scope is missing, the Plugin rejects the request with a 403 forbidden error. |
| realm | string | False | ailix | | Realm in [`WWW-Authenticate`](https://www.rfc-editor.org/rfc/rfc6750#section-3) response header accompanying a 401 unauthorized request due to invalid bearer token. |
| bearer\_only | boolean | False | false | | If true, strictly require bearer access token in requests for authentication. |
| logout\_path | string | False | /logout | | Path to activate the logout. |
| post\_logout\_redirect\_uri | string | False | | | URL to redirect users to after the `logout_path` receive a request to log out. |
| redirect\_uri | string | False | | | URI to redirect to after authentication with the OpenID provider. Note that the redirect URI should not be the same as the request URI, but a sub-path of the request URI. For example, if the `uri` of the Route is `/api/v1/*`, `redirect_uri` can be configured as `/api/v1/redirect`. If `redirect_uri` is not configured, AILIX will append `/.ailix/redirect` to the request URI to determine the value for `redirect_uri`. |
| timeout | integer | False | 3 | \[1,...] | Request timeout time in seconds. |
| ssl\_verify | boolean | False | false | | If true, verify the OpenID provider 's SSL certificates. |
| introspection\_endpoint | string | False | | | URL of the [token introspection](https://datatracker.ietf.org/doc/html/rfc7662) endpoint for the OpenID provider used to introspect access tokens. If this is unset, the introspection endpoint presented in the well-known discovery document is used [as a fallback](https://github.com/zmartzone/lua-resty-openidc/commit/cdaf824996d2b499de4c72852c91733872137c9c). |
| introspection\_endpoint\_auth\_method | string | False | client\_secret\_basic | | Authentication method for the token introspection endpoint. The value should be one of the authentication methods specified in the `introspection_endpoint_auth_methods_supported` [authorization server metadata](https://www.rfc-editor.org/rfc/rfc8414.html) as seen in the well-known discovery document, such as `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `client_secret_jwt`. |
| token\_endpoint\_auth\_method | string | False | client\_secret\_basic | | Authentication method for the token endpoint. The value should be one of the authentication methods specified in the `token_endpoint_auth_methods_supported` [authorization server metadata](https://www.rfc-editor.org/rfc/rfc8414.html) as seen in the well-known discovery document, such as `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `client_secret_jwt`. If the configured method is not supported, fall back to the first method in the `token_endpoint_auth_methods_supported` array. |
| public\_key | string | False | | | Public key used to verify JWT signature id asymmetric algorithm is used. Providing this value to perform token verification will skip token introspection in client credentials flow. You can pass the public key in `-----BEGIN PUBLIC KEY-----\\n……\\n-----END PUBLIC KEY-----` format. |
| use\_jwks | boolean | False | false | | If true and if `public_key` is not set, use the JWKS to verify JWT signature and skip token introspection in client credentials flow. The JWKS endpoint is parsed from the discovery document. |
| use\_pkce | boolean | False | false | | If true, use the Proof Key for Code Exchange (PKCE) for Authorization Code Flow as defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636). |
| token\_signing\_alg\_values\_expected | string | False | | | Algorithm used for signing JWT, such as `RS256`. |
| set\_access\_token\_header | boolean | False | true | | If true, set the access token in a request header. By default, the `X-Access-Token` header is used. |
| access\_token\_in\_authorization\_header | boolean | False | false | | If true and if `set_access_token_header` is also true, set the access token in the `Authorization` header. |
| set\_id\_token\_header | boolean | False | true | | If true and if the ID token is available, set the value in the `X-ID-Token` request header. |
| set\_userinfo\_header | boolean | False | true | | If true and if user info data is available, set the value in the `X-Userinfo` request header. |
| set\_refresh\_token\_header | boolean | False | false | | If true and if the refresh token is available, set the value in the `X-Refresh-Token` request header. |
| session | object | False | | | Session configuration used when `bearer_only` is `false` and the Plugin uses Authorization Code flow. |
| session.secret | string | True | | 16 or more characters | Key used for session encryption and HMAC operation when `bearer_only` is `false`. |
| session.cookie | object | False | | | Cookie configurations. |
| session.cookie.lifetime | integer | False | 3600 | | Cookie lifetime in seconds. |
| session\_contents | object | False | | | Session content configurations. If unconfigured, all data will be stored in the session. |
| session\_contents.access\_token | boolean | False | | | If true, store the access token in the session. |
| session\_contents.id\_token | boolean | False | | | If true, store the ID token in the session. |
| session\_contents.enc\_id\_token | boolean | False | | | If true, store the encrypted ID token in the session. |
| session\_contents.user | boolean | False | | | If true, store the user info in the session. |
| unauth\_action | string | False | auth | \["auth","deny","pass"] | Action for unauthenticated requests. When set to `auth`, redirect to the authentication endpoint of the OpenID provider. When set to `pass`, allow the request without authentication. When set to `deny`, return 401 unauthenticated responses rather than start the authorization code grant flow. |
| proxy\_opts | object | False | | | Configurations for the proxy server that the OpenID provider is behind. |
| proxy\_opts.http\_proxy | string | False | | | Proxy server address for HTTP requests, such as `http://:`. |
| proxy\_opts.https\_proxy | string | False | | | Proxy server address for HTTPS requests, such as `http://:`. |
| proxy\_opts.http\_proxy\_authorization | string | False | | Basic \[base64 username:password] | Default `Proxy-Authorization` header value to be used with `http_proxy`. Can be overridden with custom `Proxy-Authorization` request header. |
| proxy\_opts.https\_proxy\_authorization | string | False | | Basic \[base64 username:password] | Default `Proxy-Authorization` header value to be used with `https_proxy`. Cannot be overridden with custom `Proxy-Authorization` request header since with HTTPS, the authorization is completed when connecting. |
| proxy\_opts.no\_proxy | string | False | | | Comma separated list of hosts that should not be proxied. |
| authorization\_params | object | False | | | Additional parameters to send in the request to the authorization endpoint. |
| client\_rsa\_private\_key | string | False | | | Client RSA private key used to sign JWT for authentication to the OP. Required when `token_endpoint_auth_method` is `private_key_jwt`. |
| client\_rsa\_private\_key\_id | string | False | | | Client RSA private key ID used to compute a signed JWT. Optional when `token_endpoint_auth_method` is `private_key_jwt`. |
| client\_jwt\_assertion\_expires\_in | integer | False | 60 | | Life duration of the signed JWT for authentication to the OP, in seconds. Used when `token_endpoint_auth_method` is `private_key_jwt` or `client_secret_jwt`. |
| renew\_access\_token\_on\_expiry | boolean | False | true | | If true, attempt to silently renew the access token when it expires or if a refresh token is available. If the token fails to renew, redirect user for re-authentication. |
| access\_token\_expires\_in | integer | False | | | Lifetime of the access token in seconds if no `expires_in` attribute is present in the token endpoint response. |
| refresh\_session\_interval | integer | False | | | Time interval to refresh user ID token without requiring re-authentication. When not set, it will not check the expiration time of the session issued to the client by the gateway. If set to 900, it means refreshing the user's id\_token (or session in the browser) after 900 seconds without requiring re-authentication. |
| iat\_slack | integer | False | 120 | | Tolerance of clock skew in seconds with the `iat` claim in an ID token. |
| accept\_none\_alg | boolean | False | false | | Set to true if the OpenID provider does not sign its ID token, such as when the signature algorithm is set to `none`. |
| accept\_unsupported\_alg | boolean | False | true | | If true, ignore ID token signature to accept unsupported signature algorithm. |
| access\_token\_expires\_leeway | integer | False | 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. |
| force\_reauthorize | boolean | False | false | | If true, execute the authorization flow even when a token has been cached. |
| use\_nonce | boolean | False | false | | If true, enable nonce parameter in authorization request. |
| revoke\_tokens\_on\_logout | boolean | False | false | | If true, notify the authorization server a previously obtained refresh or access token is no longer needed at the revocation endpoint. |
| jwk\_expires\_in | integer | False | 86400 | | Expiration time for JWK cache in seconds. |
| jwt\_verification\_cache\_ignore | boolean | False | false | | If true, force re-verification for a bearer token and ignore any existing cached verification results. |
| cache\_segment | string | False | | | Optional name of a cache segment, used to separate and differentiate caches used by token introspection or JWT verification. |
| introspection\_interval | integer | False | 0 | | TTL of the cached and introspected access token in seconds. The default value is 0, which means this option is not used and the Plugin defaults to use the TTL passed by expiry claim defined in `introspection_expiry_claim`. If `introspection_interval` is larger than 0 and less than the TTL passed by expiry claim defined in `introspection_expiry_claim`, use `introspection_interval`. |
| introspection\_expiry\_claim | string | False | exp | | Name of the expiry claim, which controls the TTL of the cached and introspected access token. |
| introspection\_addon\_headers | array\[string] | False | | | Used to append additional header values to the introspection HTTP request. If the specified header does not exist in origin request, value will not be appended. |
| claim\_validator | object | False | | | JWT claim validation configurations. |
| claim\_validator.issuer.valid\_issuers | array\[string] | False | | | An array of trusted JWT issuers. If unconfigured, the issuer returned by discovery endpoint will be used. If both are unavailable, the issuer will not be validated. |
| claim\_validator.audience | object | False | | | [Audience claim](https://openid.net/specs/openid-connect-core-1_0.html) validation configurations. |
| claim\_validator.audience.claim | string | False | aud | | Name of the claim that contains the audience. |
| claim\_validator.audience.required | boolean | False | false | | If true, audience claim is required and the name of the claim will be the name defined in `claim`. |
| claim\_validator.audience.match\_with\_client\_id | boolean | False | false | | If true, require the audience to match the client ID. If the audience is a string, it must exactly match the client ID. If the audience is an array of strings, at least one of the values must match the client ID. If no match is found, you will receive a `mismatched audience` error. This requirement is stated in the OpenID Connect specification to ensure that the token is intended for the specific client. |
| claim\_schema | object | False | | | JSON schema of OIDC response claim. Example: `{"type":"object","properties":{"access_token":{"type":"string"}},"required":["access_token"]}` - validates that the response contains a required string field `access_token`. |
### `wolf-rbac`
The `wolf-rbac` Plugin provides a [role-based access control](https://en.wikipedia.org/wiki/Role-based_access_control) system with [wolf](https://github.com/iGeeky/wolf) to a Route or a Service. This Plugin can be used with a Consumer.
{% hint style="info" %}
**Priority** `2555` · **Category** Authentication
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Description |
| -------------- | ------ | -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| server | string | False | "" | Service address of wolf server. |
| appid | string | False | "unset" | App id added in wolf console. This field supports saving the value in Secret Manager using the AILIX Secret resource. |
| header\_prefix | string | False | "X-" | Prefix for a custom HTTP header. After authentication is successful, three headers will be added to the request header (for backend) and response header (for frontend) namely: `X-UserId`, `X-Username`, and `X-Nickname`. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.