> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/plugins/auth-security.md). # Authentication and security plugins Kangal supports route authentication plugins and managed consumer credentials. Authentication plugins validate callers in the plugin chain. Managed credentials identify a consumer so ACL, rate-limit, and scoped policies can use that identity. Attach an authentication policy to every protected gateway or route. Add an ACL when access must also depend on a consumer group, role, user, or tenant. ## Supported authentication plugins | Plugin | Required configuration | Use | | ------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `api_key_auth` | `valid_keys`; optional `header_name` | Validates configured keys and managed API keys sent in `X-API-Key`. | | `basic_auth` | `allowed_users` entries with `username` and `password` | Validates HTTP Basic credentials over TLS. | | `oauth2` | `introspection_url` or `valid_tokens`; optional client credentials and `required_scopes` | Validates bearer tokens by introspection or an explicit token allowlist. | | `oidc` | `public_key`, issuer, audience, allowed algorithms; optional scopes | Validates signed bearer tokens against configured trust and claim requirements. | | `ldap_auth` | `server_url`, `user_dn_template`, and TLS settings | Validates Basic credentials with LDAP. | | `mtls_client_certificate_auth` | A trusted CA/fingerprint or verified-header requirement; optional identity restrictions | Validates a client certificate supplied by a trusted TLS terminator. | | `session_cookie_auth` | `valid_session_ids` or `valid_sessions` | Validates an allowlisted session identifier. | | `vault_authentication` | `secret_ref` and injection mode | Resolves and injects Kangal's credential for an upstream service. | `hide_credentials` removes the incoming credential before proxying when the plugin supports it. `upstream_headers` controls normalized identity headers. Review both settings for every protected route. ## Managed API key with group ACL Create a consumer and API key as described in [Consumers](/consumers/consumers.md), then attach both policies. An empty `valid_keys` array allows managed API keys without adding static keys. ```json { "name": "api_key_auth", "tenant_id": "tenant-a", "scope": "gateway", "gateway_id": "gateway-1", "trigger": "before_request", "priority": 200, "enabled": true, "config": { "valid_keys": [], "header_name": "X-API-Key" } } ``` ```json { "name": "acl_control", "tenant_id": "tenant-a", "scope": "gateway", "gateway_id": "gateway-1", "trigger": "before_request", "priority": 100, "enabled": true, "config": { "allowed_groups": ["payments"] } } ``` The authentication plugin returns `401` for a missing or invalid API key. After successful identification, the ACL returns `403` when the consumer is not in an allowed group. ## Access policies | Plugin | Main configuration | Use | | --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `acl_control` | `allowed_users`, `allowed_roles`, `allowed_groups`, `allowed_tenants` | Requires every configured identity dimension; group matching accepts any configured group. | | `ip_whitelist` | `allowed_ips` | Allows exact client IP values. | | `ip_blacklist` | `blocked_ips` | Rejects exact client IP values. | | `bot_detection_basic` | User-Agent allow/deny patterns and response controls | Applies ordered regular-expression filtering. | | `request_termination` | `header_equals`, `status_code`, `message` | Stops matching requests before upstream proxying. | | `oas_validation` | `spec`, validation flags, and size/status controls | Validates requests against an OpenAPI 3.x contract. | ## Security requirements * Use TLS for every credential-bearing request. Never place API keys in URLs or logs. * Generate high-entropy API keys, store them in an approved secret manager, and replace them on a defined rotation schedule. * For OAuth2 introspection, use an HTTPS endpoint, restrict outbound access, and keep client credentials in a secret manager. * For OIDC, configure an explicit verification key, allowed algorithms, expected issuer, and audience. Update the configured key during provider key rotation. * Use TLS for LDAP connections and restrict the directory endpoint with network policy. * A trusted TLS terminator must remove client-supplied certificate headers and set the certificate and verification headers itself. * Use high-entropy session identifiers and remove expired or revoked sessions from the configured allowlist. * Keep `vault_authentication.fail_open` disabled on protected upstream calls. * Consumer and group scopes select identified traffic; they do not replace an authentication requirement. ## Managed consumer credentials Managed `api_key` credentials are the recommended consumer authentication method and integrate directly with `api_key_auth` through `X-API-Key`. Managed `basic` credentials are available for controlled compatibility workflows. Send them only over TLS and enforce the resulting consumer or group identity with `acl_control`. ## Troubleshooting | Symptom | Check | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Managed API key is rejected | Use `X-API-Key`; verify the credential tenant, key, and expiry; include `valid_keys: []` in `api_key_auth`. | | OAuth2 token is rejected | Verify the introspection URL, client credentials, token activity, and required scopes. | | OIDC token is rejected | Verify the configured key, algorithm, issuer, audience, token expiry, and required scopes. | | LDAP authentication fails | Verify TLS connectivity, the directory endpoint, DN template, and bind credentials. | | mTLS authentication fails | Verify the trusted terminator, certificate header, verification header, validity period, and configured trust policy. | | Session authentication fails | Verify the configured cookie or header name, allowlisted session identifier, and role/group requirements. | --- # 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.kangal.dev/plugins/auth-security.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.