Authentication Middlewares

All authentication middlewares set the standard consumer identity headers — x-auth-consumer and x-auth-consumer-groups — so downstream authorization plugins (notably acl) don’t need to know which auth plugin produced them.

• jwt-auth — JWT Bearer tokens with RS256/HS256 signatures
• apikey-auth — API keys from header or query parameter
• oauth2-auth — Bearer tokens via RFC 7662 token introspection
• oidc-auth — OpenID Connect discovery + JWKS
• basic-auth — HTTP Basic per RFC 7617

jwt-auth

Validates JWT tokens with RS256/HS256 signatures.

x-barbacane-middlewares:
  - name: jwt-auth
    config:
      issuer: "https://auth.example.com"  # Optional: validate iss claim
      audience: "my-api"                  # Optional: validate aud claim
      groups_claim: "roles"               # Optional: claim name for consumer groups
      skip_signature_validation: true     # Required until JWKS support is implemented

Accepted algorithms: RS256, RS384, RS512, ES256, ES384, ES512. HS256/HS512 and none are rejected.

Note: Cryptographic signature validation is not yet implemented. Set skip_signature_validation: true in production until JWKS support lands. Without it, all tokens are rejected with 401 at the signature step.

Configuration

Context headers

Sets headers for downstream:

• x-auth-consumer — Consumer identifier (from sub claim)
• x-auth-consumer-groups — Comma-separated groups (from groups_claim, if configured)
• x-auth-sub — Subject (user ID)
• x-auth-claims — Full JWT claims as JSON

apikey-auth

Validates API keys from header or query parameter.

x-barbacane-middlewares:
  - name: apikey-auth
    config:
      key_location: header        # or "query"
      header_name: X-API-Key      # when key_location is "header"
      query_param: api_key        # when key_location is "query"
      keys:
        - key: "env://API_KEY_PRODUCTION"
          id: key-001
          name: Production Key
          scopes: ["read", "write"]
        - key: sk_test_xyz789
          id: key-002
          name: Test Key
          scopes: ["read"]

The key field supports secret references (env://, file://) which are resolved at gateway startup. See Secrets for details.

Configuration

Context headers

Sets headers for downstream:

• x-auth-consumer — Consumer identifier (from key id)
• x-auth-consumer-groups — Comma-separated groups (from key scopes)
• x-auth-key-id — Key identifier
• x-auth-key-name — Key human-readable name
• x-auth-key-scopes — Comma-separated scopes

oauth2-auth

Validates Bearer tokens via RFC 7662 token introspection.

x-barbacane-middlewares:
  - name: oauth2-auth
    config:
      introspection_endpoint: https://auth.example.com/oauth2/introspect
      client_id: my-api-client
      client_secret: "env://OAUTH2_CLIENT_SECRET"  # resolved at startup
      required_scopes: "read write"                 # space-separated
      timeout: 5.0                                  # seconds

The client_secret uses a secret reference (env://) which is resolved at gateway startup. See Secrets for details.

Configuration

Context headers

Sets headers for downstream:

• x-auth-consumer — Consumer identifier (from sub, fallback to username)
• x-auth-consumer-groups — Comma-separated groups (from scope)
• x-auth-sub — Subject
• x-auth-scope — Token scopes
• x-auth-client-id — Client ID
• x-auth-username — Username (if present)
• x-auth-claims — Full introspection response as JSON

Error responses

• 401 Unauthorized — Missing token, invalid token, or inactive token
• 403 Forbidden — Token lacks required scopes

Includes RFC 6750 WWW-Authenticate header with error details.

oidc-auth

OpenID Connect authentication via OIDC Discovery and JWKS. Automatically fetches the provider’s signing keys and validates JWT tokens with full cryptographic verification.

x-barbacane-middlewares:
  - name: oidc-auth
    config:
      issuer_url: https://accounts.google.com
      audience: my-api-client-id
      required_scopes: "openid profile email"
      issuer_override: https://external.example.com  # optional
      clock_skew_seconds: 60
      jwks_refresh_seconds: 300
      timeout: 5.0
      allow_query_token: false  # RFC 6750 §2.3 query param fallback

Configuration

How it works

1. Extracts the Bearer token from the Authorization header (or from the access_token query parameter if allow_query_token is enabled and no header is present)
2. Parses the JWT header to determine the signing algorithm and key ID (kid)
3. Fetches {issuer_url}/.well-known/openid-configuration (cached)
4. Fetches the JWKS endpoint from the discovery document (cached with TTL)
5. Finds the matching public key by kid (or kty/use fallback)
6. Verifies the signature using host_verify_signature (RS256/RS384/RS512, ES256/ES384)
7. Validates claims: iss, aud, exp, nbf
8. Checks required scopes (if configured)

Context headers

Sets headers for downstream:

• x-auth-consumer — Consumer identifier (from sub claim)
• x-auth-consumer-groups — Comma-separated groups (from scope, space→comma)
• x-auth-sub — Subject (user ID)
• x-auth-scope — Token scopes
• x-auth-claims — Full JWT payload as JSON

Error responses

• 401 Unauthorized — Missing token, invalid token, expired token, bad signature, unknown issuer
• 403 Forbidden — Token lacks required scopes

Includes RFC 6750 WWW-Authenticate header with error details.

basic-auth

Validates credentials from the Authorization: Basic header per RFC 7617. Useful for internal APIs, admin endpoints, or simple services that don’t need a full identity provider.

x-barbacane-middlewares:
  - name: basic-auth
    config:
      realm: "My API"
      strip_credentials: true
      credentials:
        - username: admin
          password: "env://ADMIN_PASSWORD"
          roles: ["admin", "editor"]
        - username: readonly
          password: "env://READONLY_PASSWORD"
          roles: ["viewer"]

Configuration

Each credential entry:

Context headers

Sets headers for downstream:

• x-auth-consumer — Consumer identifier (username)
• x-auth-consumer-groups — Comma-separated groups (from roles)
• x-auth-user — Authenticated username
• x-auth-roles — Comma-separated roles (only set if the user has roles)

Error responses

Returns 401 Unauthorized with WWW-Authenticate: Basic realm="<realm>" and Problem JSON:

{
  "type": "urn:barbacane:error:authentication-failed",
  "title": "Authentication failed",
  "status": 401,
  "detail": "Invalid username or password"
}

ldap-auth

Authenticates Authorization: Basic credentials (RFC 7617) against an LDAP or Active Directory server. The user entry is located with a search as a service account, the password is verified with a bind as that entry, and groups come from the entry’s membership attribute (memberOf by default) or from a group search. Verified and rejected credentials are cached for cache_ttl_seconds, so repeated requests with the same credentials do not reach the directory again until the entry expires. Attempts with different passwords each reach the directory; put rate-limit in front of ldap-auth to bound them.

x-barbacane-middlewares:
  - name: ldap-auth
    config:
      url: "ldaps://directory.example.com:636"
      bind_dn: "cn=gateway,ou=services,dc=example,dc=com"
      bind_password: "env://LDAP_BIND_PASSWORD"
      user_base_dn: "ou=people,dc=example,dc=com"
      user_filter: "(uid={username})"
      required_groups: ["api-users"]

Active Directory uses different attribute names:

      user_filter: "(sAMAccountName={username})"
      user_attr: "sAMAccountName"
      group_attr: "memberOf"

Configuration

Usernames are escaped before they reach the filter, so a value such as *)(uid=* matches nothing. An empty password is rejected without contacting the directory, because an LDAP bind with an empty password is an anonymous bind and would succeed for any DN.

Context headers

Sets headers for downstream:

• x-auth-consumer: consumer identifier (user_attr of the entry, or the username)
• x-auth-consumer-groups: comma-separated group names (only set when the user has groups)
• x-auth-user: the submitted username
• x-auth-dn: the user entry’s DN

Error responses

401 Unauthorized with WWW-Authenticate: Basic realm="<realm>" and Problem JSON when credentials are missing, malformed or rejected. An unknown user and a wrong password produce the same response.

{
  "type": "urn:barbacane:error:authentication-failed",
  "title": "Authentication failed",
  "status": 401,
  "detail": "Invalid username or password"
}

403 Forbidden (urn:barbacane:error:forbidden) when required_groups is set and the user is in none of them.

503 Service Unavailable (urn:barbacane:error:ldap-unavailable) when the directory cannot be reached or a search or bind fails for a reason other than the credentials. Directory failures are never cached.

Directory connectivity

The gateway opens directory connections through the plugin SSRF guard, which blocks loopback, private-network and link-local addresses by default. A directory on the same host or network requires BARBACANE_ALLOW_INTERNAL_EGRESS=true on the gateway process. Use ldaps:// or starttls so passwords do not cross the network in the clear: with a plain ldap:// URL and no StartTLS, the gateway refuses to send passwords unless allow_plaintext: true is set.