API Gateway Authentication: Integrating OAuth 2.0, JWT, and OIDC with Apache APISIX

API7.ai

April 3, 2025

API Gateway Guide

Introduction

Apache APISIX is a high-performance API gateway that provides robust authentication mechanisms, including OAuth 2.0, JWT, and OIDC. This article explains how to configure Apache APISIX to secure API access using these authentication protocols.

Why Authentication Matters in API Gateways

Authentication ensures that only authorized clients can access APIs, providing:

  • Access control: Restrict access to authenticated users.
  • Security compliance: Protect sensitive API data.
  • Single sign-on (SSO): Enhance user experience.
  • Delegated authorization: Allow third-party apps to act on behalf of users.

Why Authentication Matters in API Gateways

Authentication Mechanisms in Apache APISIX

1. OAuth 2.0 Authentication with Apache APISIX

Apache APISIX supports OAuth 2.0 by validating tokens issued by an external identity provider (IdP), such as Keycloak, Auth0, or Ota.

Enabling OAuth 2.0 Authentication

To configure OAuth 2.0 authentication in Apache APISIX:

  1. Enable the authz-keycloak plugin.
  2. Set up your OAuth 2.0 provider (Keycloak in this example).
  3. Define the authentication and authorization endpoints.
{
  "route": {
    "uri": "/secure-api",
    "plugins": {
      "authz-keycloak": {
        "token_endpoint": "https://auth.example.com/realms/demo/protocol/openid-connect/token",
        "authorization_endpoint": "https://auth.example.com/realms/demo/protocol/openid-connect/auth",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "scopes": ["read", "write"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "backend-service:80": 1
      }
    }
  }
}

How It Works

  1. The API client obtains an access token from the OAuth provider.
  2. The client includes the token in API requests (e.g., Authorization: Bearer <token>).
  3. Apache APISIX validates the token before forwarding the request to the backend service.

2. JWT Authentication with Apache APISIX

JWT (JSON Web Token) authentication allows stateless token validation without contacting an external server.

Enabling JWT Authentication

  1. Enable the jwt-auth plugin.
  2. Configure the secret key used for signing JWTs.
  3. Define user-specific tokens for authentication.
{
  "consumer": {
    "username": "api-user",
    "plugins": {
      "jwt-auth": {
        "key": "api-user-key",
        "secret": "super-secret-key",
        "algorithm": "HS256"
      }
    }
  }
}

Example JWT Token

A sample JWT token (encoded using HS256):

{
  "alg": "HS256",
  "typ": "JWT"
}.
{
  "sub": "1234567890",
  "name": "API User",
  "iat": 1712012345,
  "exp": 1712617145
}.
<signature>

How It Works

  1. The client sends a request with a JWT token in the Authorization header.
  2. Apache APISIX decodes the token and validates its signature.
  3. If valid, the request is forwarded to the backend service.

3. OpenID Connect (OIDC) Authentication with Apache APISIX

OIDC extends OAuth 2.0 with identity verification, allowing authentication using an external IdP.

Enabling OIDC Authentication

  1. Enable the openid-connect plugin.
  2. Configure the discovery endpoint of your OIDC provider.
{
  "route": {
    "uri": "/oidc-secure",
    "plugins": {
      "openid-connect": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "discovery": "https://auth.example.com/.well-known/openid-configuration",
        "scope": "openid profile email"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "backend-service:80": 1
      }
    }
  }
}

How It Works

  1. Clients are redirected to the OIDC provider for authentication.
  2. After authentication, the provider returns an ID token.
  3. Apache APISIX validates the token and extracts user identity claims.

Best Practices for API Authentication in Apache APISIX

  • Use OAuth 2.0 and OIDC for identity-based authentication.
  • Enable JWT validation to reduce external authentication calls.
  • Configure rate limiting on authentication endpoints.
  • Monitor authentication logs for security auditing.
  • Use mTLS (Mutual TLS) to secure token validation requests.

Best Practices for API Authentication in Apache APISIX

Conclusion

Apache APISIX provides a flexible authentication framework integrating OAuth 2.0, JWT, and OIDC. By implementing these authentication mechanisms, organizations can enhance API security while maintaining a seamless user experience.

FAQ

1. Can Apache APISIX act as an OAuth 2.0 Authorization Server?

A: No, Apache APISIX only validates OAuth tokens. You need an external authorization server (e.g., Keycloak, Auth0).

2. How does Apache APISIX verify JWT tokens?

A: APISIX decodes JWTs and validates the signature using a predefined secret key or a public key.

3. Is OpenID Connect required for authentication?

A: No, but OIDC provides identity information, making it useful for authentication scenarios.

Next Steps

Stay tuned for our upcoming column on the API gateway Guide, where you'll find the latest updates and insights!

Eager to deepen your knowledge about API gateways? Follow our Linkedin for valuable insights delivered straight to your inbox!

If you have any questions or need further assistance, feel free to contact API7 Experts.