使用 Microsoft Entra ID（Azure AD）配置 SSO

OpenID Connect（OIDC）在 OAuth 2.0 之上增加了身份层，使应用能够验证最终用户的身份，并从身份提供商（IdP）获取基本的用户资料信息。在单点登录（SSO）部署中，用户通过 IdP 完成身份认证后，即可访问已连接的应用，无需分别登录每个应用。

Microsoft Entra ID 的前身是 Azure Active Directory，是 Microsoft 提供的云端身份与访问管理服务。它可以作为企业用户的集中式 IdP，并提供 SSO、多因素身份认证和访问策略等功能。在本集成中，Apache APISIX 会先把浏览器身份认证委托给 Microsoft Entra ID，再将请求代理到上游服务。

本指南介绍如何配置 APISIX 和 Microsoft Entra ID，以使用带有用于代码交换的证明密钥（PKCE）的 OIDC 授权码流程。当请求没有有效的 APISIX 会话时，APISIX 会将浏览器重定向到 Microsoft Entra ID。身份认证成功后，APISIX 会用授权码交换令牌、创建浏览器会话，并继续处理原始请求。

前置条件

安装 Docker。
安装 cURL 和 OpenSSL。
按照入门指南使用 Docker 启动 APISIX。
拥有 Microsoft Entra 租户的访问权限和注册应用的权限。Application Developer 或权限更高的角色即可满足要求。
如果计划使用 ADC，请先安装并配置 ADC。

配置 Microsoft Entra ID

在 Microsoft Entra ID 中注册一个 OIDC Web 应用，然后保存其租户和客户端凭证，供 APISIX 路由使用。

注册应用

输入 APISIX Authorization Code 作为应用名称。
在 Supported account types 下，为本示例选择 Single tenant only。
在 Redirect URI 下，选择 Web 并输入 http://localhost:9080/anything/user/callback。
选择 Register。

使用 APISIX 回调 URI 注册 Microsoft Entra 应用

重定向 URI 用于标识身份认证后 Microsoft Entra ID 将浏览器返回到的 APISIX 端点。在生产环境中，请使用用户可访问的 HTTPS 端点，并在 Microsoft Entra ID 中注册完全相同的 URI。

创建客户端密钥

在已注册应用的 Overview 页面，记录 Application (client) ID 和 Directory (tenant) ID。然后选择 Certificates & secrets → Client secrets → New client secret。输入说明，选择符合组织凭证轮换策略的有效期，然后选择 Add。

立即复制客户端密钥的 Value。Microsoft Entra ID 只显示一次该值。不要将 Secret ID 用作客户端密钥。

本示例使用客户端密钥进行本地测试。对于生产应用，Microsoft 建议改用证书凭证。

为 Microsoft Entra 应用创建客户端密钥

将租户 ID、客户端 ID、客户端密钥和发现 URL 保存到环境变量中，并替换示例值：

export ENTRA_TENANT_ID=replace-with-your-tenant-id
export ENTRA_CLIENT_ID=replace-with-your-client-id
export ENTRA_CLIENT_SECRET=replace-with-your-client-secret
export ENTRA_DISCOVERY="https://login.microsoftonline.com/${ENTRA_TENANT_ID}/v2.0/.well-known/openid-configuration"

配置 APISIX

配置一条路由，在将浏览器请求转发到公共 HTTP 请求与响应服务 httpbin.org 之前执行身份认证。/anything/user/* 端点会返回请求详情以供验证。

生成一个唯一的会话密钥，供 APISIX 用于加密浏览器会话 Cookie 并验证其完整性：

export APISIX_SESSION_SECRET="$(openssl rand -hex 32)"

选择使用 Admin API 或 ADC 配置路由。

Admin API
ADC

创建一条使用 Microsoft Entra ID 对浏览器请求进行身份认证的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes/entra-browser" -X PUT \
  --data-binary @- <<EOF
{
  "uri": "/anything/user/*",
  "plugins": {
    "openid-connect": {
      "client_id": "$ENTRA_CLIENT_ID",
      "client_secret": "$ENTRA_CLIENT_SECRET",
      "discovery": "$ENTRA_DISCOVERY",
      "scope": "openid profile",
      "redirect_uri": "http://localhost:9080/anything/user/callback",
      "bearer_only": false,
      "use_pkce": true,
      "session": {
        "secret": "$APISIX_SESSION_SECRET"
      },
      "set_access_token_header": false,
      "set_id_token_header": false,
      "set_userinfo_header": false
    },
    "proxy-rewrite": {
      "headers": {
        "remove": ["Cookie"]
      }
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}
EOF

❶ discovery：租户专属的 Microsoft Entra ID OIDC 发现文档 URI。

❷ redirect_uri：身份认证后 Microsoft Entra ID 将浏览器返回到的 URI。它必须与为应用注册的重定向 URI 一致。

❸ bearer_only：设置为 false，使 APISIX 在请求没有有效会话时启动浏览器身份认证流程。

❹ use_pkce：设置为 true，在授权过程中发送 S256 PKCE 质询。

❺ set_access_token_header、set_id_token_header 和 set_userinfo_header：设置为 false，防止 APISIX 将访问令牌、ID 令牌和用户信息添加到上游请求头中。

❻ proxy-rewrite.headers.remove：包含 Cookie，在代理请求前移除整个 Cookie 请求头，其中也包括 APISIX 会话 Cookie。如果上游应用需要 Cookie，请重新评估此设置。

创建包含相同路由配置的 adc.yaml 文件：

adc.yaml
services:
  - name: httpbin
    routes:
      - name: entra-browser
        uris:
          - /anything/user/*
        plugins:
          openid-connect:
            client_id: "${ENTRA_CLIENT_ID}"
            client_secret: "${ENTRA_CLIENT_SECRET}"
            discovery: "${ENTRA_DISCOVERY}"
            scope: openid profile
            redirect_uri: http://localhost:9080/anything/user/callback
            bearer_only: false
            use_pkce: true
            session:
              secret: "${APISIX_SESSION_SECRET}"
            set_access_token_header: false
            set_id_token_header: false
            set_userinfo_header: false
          proxy-rewrite:
            headers:
              remove:
                - Cookie
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

❶ discovery：租户专属的 Microsoft Entra ID OIDC 发现文档 URI。

❷ redirect_uri：身份认证后 Microsoft Entra ID 将浏览器返回到的 URI。它必须与为应用注册的重定向 URI 一致。

❸ bearer_only：设置为 false，使 APISIX 在请求没有有效会话时启动浏览器身份认证流程。

❹ use_pkce：设置为 true，在授权过程中发送 S256 PKCE 质询。

❺ set_access_token_header、set_id_token_header 和 set_userinfo_header：设置为 false，防止 APISIX 将访问令牌、ID 令牌和用户信息添加到上游请求头中。

将配置同步到 APISIX：

adc sync -f adc.yaml

该文件将客户端密钥保留为环境变量引用。不要把凭证写入文件或提交到版本控制系统。

验证身份认证

在浏览器中访问 http://localhost:9080/anything/user/get。APISIX 会将你重定向到 Microsoft Entra ID。如果浏览器没有有效的 Microsoft Entra 会话，Microsoft Entra ID 会提示你登录。

登录页面可以使用组织专属的徽标、颜色和其他视觉元素。有关要求和配置选项，请参阅配置公司品牌。

如果系统提示，请完成 Microsoft Entra 登录。身份认证成功后，Microsoft Entra ID 会将浏览器返回到 APISIX，随后 APISIX 把请求转发到 httpbin.org。你应会看到包含以下字段的响应：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate",
    "Accept-Language": "en-CA,en-US;q=0.9,en;q=0.8",
    "Host": "localhost",
    "Priority": "u=0, i",
    "Sec-Fetch-Dest": "document",
    "Sec-Fetch-Mode": "navigate",
    "Sec-Fetch-Site": "cross-site",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15",
    "X-Amzn-Trace-Id": "Root=1-...",
    "X-Forwarded-Host": "localhost:9080"
  },
  "json": null,
  "method": "GET",
  "origin": "192.168.155.1, xxx.xxx.xxx.xxx",
  "url": "http://localhost:9080/anything/user/get"
}

请求头值和报告的源地址会因浏览器及网络环境而异。

上游请求头不应包含 APISIX 会话 Cookie、访问 Token、ID Token 或用户信息请求头。重新加载页面，验证 APISIX 会复用浏览器会话，而不会将你再次重定向到 Microsoft Entra ID。

后续步骤

至此，你已将 APISIX 配置为使用 Microsoft Entra ID 对浏览器请求进行身份认证。有关更多配置选项，请参阅 openid-connect 插件参考。

前置条件​

配置 Microsoft Entra ID​

注册应用​

创建客户端密钥​

配置 APISIX​

验证身份认证​

后续步骤​