APISIX

You can use Casdoor to protect APIs behind Apache APISIX in two ways:

• Use APISIX's dedicated authz-casdoor plugin for a browser-based OAuth 2.0 authorization code flow and session-based authentication.
• Use APISIX's openid-connect plugin with Casdoor's OpenID Connect discovery endpoint when you need standard OIDC features or explicit identity and token propagation.

Conectar Casdoor a través del plugin de Casdoor de APISIX

The authz-casdoor plugin redirects unauthenticated browser requests to Casdoor and allows authenticated sessions to access the upstream API. APISIX handles the OAuth 2.0 callback, so the upstream application does not need to implement the authorization code flow.

Prerequisites

Before configuring the plugin, prepare:

• A running Casdoor deployment and an Apache APISIX release that includes authz-casdoor.
• A Casdoor application whose Redirect URL is exactly the URL that you will configure as callback_url.
• The Casdoor application's Client ID and Client Secret.
• An APISIX Route whose URI matches both the protected path and the callback path.

Enable the plugin

Store the APISIX Admin API key in an environment variable, then create a Route with authz-casdoor enabled. Replace the example hostnames and credentials with values from your environment.

export APISIX_ADMIN_KEY="<APISIX_ADMIN_KEY>"

curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
  -H "X-API-KEY: ${APISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data '
{
  "methods": ["GET"],
  "uri": "/anything/*",
  "plugins": {
    "authz-casdoor": {
      "endpoint_addr": "https://casdoor.example.com",
      "callback_url": "https://gateway.example.com/anything/callback",
      "client_id": "<CASDOOR_CLIENT_ID>",
      "client_secret": "<CASDOOR_CLIENT_SECRET>"
    }
  },
  "upstream": {
    "scheme": "https",
    "type": "roundrobin",
    "nodes": {
      "<UPSTREAM_HOST>:443": 1
    }
  }
}'

This example protects /anything/* and sends authorized requests to a user-controlled HTTPS upstream after you replace <UPSTREAM_HOST>. The callback path /anything/callback is covered by the same Route, allowing the plugin to handle Casdoor's authorization response.

precaución

Production configuration

Use HTTPS for endpoint_addr and callback_url. Do not commit the APISIX Admin API key or Casdoor Client Secret to source control, and redact authorization codes, tokens, and session cookies from logs.

Use a trusted HTTPS upstream. The plugin does not add Casdoor token or identity headers, but the browser's original Cookie header, including the APISIX Session Cookie, can continue to the upstream unless it is removed. Remove or filter that header before proxying when the upstream application does not need it.

Before using the plugin in production, validate the complete login, callback, and session flow with the exact APISIX release and worker topology that you deploy. Session behavior can vary between releases.

Atributos

Nombre	Tipo	Requisito	Descripción
endpoint_addr	cadena	requerido	Base URL of the Casdoor deployment.
client_id	cadena	requerido	Client ID of the Casdoor application.
client_secret	cadena	requerido	Client Secret of the Casdoor application.
callback_url	cadena	requerido	Callback URL used to receive the authorization response.

endpoint_addr and callback_url must not end with /. The path in callback_url must be matched by the APISIX Route because the plugin handles the callback before proxying the request upstream.

If encrypted storage fields are enabled in APISIX, the plugin's client_secret is stored encrypted in etcd.

Understand the authorization flow

1. When an unauthenticated browser requests the protected Route, the plugin creates a session, stores the original request path and a state value, and redirects the browser to Casdoor.
2. After authentication, Casdoor redirects the browser to callback_url with code and state parameters. The plugin validates the state and exchanges the authorization code for an access token.
3. The plugin stores the access token in the APISIX session and redirects the browser to the original request path. The plugin stores the path, not the original query string, so applications should not rely on query parameters being restored after login.
4. A subsequent request with a valid session can reach the upstream API without another login redirect.

The authz-casdoor plugin uses the access token to establish the APISIX session. It does not automatically add the Casdoor Access Token, ID Token, or user identity to upstream request headers. Use the openid-connect integration below if the upstream service requires explicit token or identity propagation.

Conectar Casdoor a través del plugin OIDC de APISIX

Casdoor puede usar el protocolo OIDC para conectarse a APISIX, y este documento te mostrará cómo hacerlo.

Los siguientes son algunos de los nombres utilizados en la configuración:

CASDOOR_HOSTNAME: Nombre de dominio o IP donde se despliega el servidor de Casdoor.

APISIX_HOSTNAME: Nombre de dominio o IP donde se despliega APISIX.

Paso 1: Desplegar Casdoor y APISIX

Deploy Casdoor and APISIX. After deployment, ensure:

1. Casdoor se puede iniciar sesión y usar normalmente.
2. Establece el valor de origin de Casdoor (conf/app.conf) a CASDOOR_HOSTNAME.

Paso 2: Configurar la aplicación Casdoor

1. Crea una nueva aplicación Casdoor o usa una existente.
2. Add a redirect URL: https://APISIX_HOSTNAME/REDIRECTWHATYOUWANT, and replace REDIRECTWHATYOUWANT with the desired redirect URL.
3. Selecciona "JWT-Empty" para la opción de formato de Token.
4. Añade el proveedor deseado y configura otros ajustes.

Note Client ID and Client Secret for the next step. OIDC discovery: https://<CASDOOR_HOSTNAME>/.well-known/openid-configuration.

Paso 3: Configurar APISIX

APISIX tiene soporte oficial de OIDC, que se implementa usando lua-resty-openidc.

Customize settings per APISIX OIDC. Example routing:

export APISIX_ADMIN_KEY="<APISIX_ADMIN_KEY>"

curl "http://127.0.0.1:9180/apisix/admin/routes" \
  -H "X-API-KEY: ${APISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '
{
  "uri": "/get",
  "name": "apisix_casdoor_test",
  "plugins": {
    "openid-connect": {
      "client_id": "<CASDOOR_CLIENT_ID>",
      "client_secret": "<CASDOOR_CLIENT_SECRET>",
      "discovery": "https://CASDOOR_HOSTNAME/.well-known/openid-configuration",
      "introspection_endpoint_auth_method": "client_secret_basic",
      "logout_path": "/logout",
      "realm": "master",
      "redirect_uri": "https://APISIX_HOSTNAME/REDIRECTWHATYOUWANT",
      "bearer_only": false,
      "set_id_token_header": false,
      "access_token_in_authorization_header": true,
      "set_access_token_header": true,
      "set_userinfo_header": false
    }
  },
  "upstream": {
    "scheme": "https",
    "type": "roundrobin",
    "nodes": {
      "<UPSTREAM_HOST>:443": 1
    }
  }
}'

This OIDC configuration forwards an access token to the upstream, so replace <UPSTREAM_HOST> with a trusted HTTPS service. Visit https://APISIX_HOSTNAME/get; the browser redirects to the Casdoor login page. After login, the request is forwarded to the configured upstream. The following screenshot shows an example response.