メインコンテンツにスキップ

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.

APISIXのCasdoorプラグインを介してCasdoorに接続する​

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.

注意

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.

属性​

名前タイプ要件説明
endpoint_addrstringrequiredBase URL of the Casdoor deployment.
client_idstringrequiredClient ID of the Casdoor application.
client_secretstringrequiredClient Secret of the Casdoor application.
callback_urlstringrequiredCallback 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.

APISIXのOIDCプラグインを介してCasdoorに接続する​

CasdoorはOIDCプロトコルを使用してAPISIXに接続でき、このドキュメントではそれをどのように行うかを示します。

以下は設定で使用されるいくつかの名前です：

CASDOOR_HOSTNAME：Casdoorサーバーがデプロイされているドメイン名またはIP。

APISIX_HOSTNAME：APISIXがデプロイされているドメイン名またはIP。

ステップ1：CasdoorとAPISIXをデプロイする​

Deploy Casdoor and APISIX. After deployment, ensure:

  1. Casdoorは正常にログインして使用できます。
  2. Casdoorのorigin値（conf/app.conf）をCASDOOR_HOSTNAMEに設定します。 Casdoor conf

ステップ2：Casdoorアプリケーションを設定する​

  1. 新しいCasdoorアプリケーションを作成するか、既存のものを使用します。
  2. Add a redirect URL: https://APISIX_HOSTNAME/REDIRECTWHATYOUWANT, and replace REDIRECTWHATYOUWANT with the desired redirect URL.
  3. トークン形式オプションに「JWT-Empty」を選択します。
  4. 望むプロバイダーを追加し、他の設定を構成します。

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

ステップ3：APISIXを設定する​

APISIXには公式のOIDCサポートがあり、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. APISIX_Result