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

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

[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/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 会用授权码交换 Token、创建浏览器会话，并继续处理原始请求。

## 前置条件[​](#前置条件 "前置条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker/)。
* 安装 [cURL](https://curl.se/) 和 [OpenSSL](https://www.openssl.org/)。
* 按照[入门指南](https://docs.apiseven.com/apisix/getting-started.md)使用 Docker 启动 APISIX。
* 拥有 Microsoft Entra 租户的访问权限和注册应用的权限。Application Developer 或权限更高的角色即可满足要求。
* 如果计划使用 ADC，请先[安装并配置 ADC](https://docs.apiseven.com/apisix/reference/adc.md)。
* 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 `ADMIN_API_KEY`。请在 `deployment.admin.admin_key` 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

## 配置 Microsoft Entra ID[​](#配置-microsoft-entra-id "配置 Microsoft Entra ID的直接链接")

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

### 注册应用[​](#注册应用 "注册应用的直接链接")

登录 [Microsoft Entra 管理中心](https://entra.microsoft.com/)。选择 **Entra ID → App registrations → New registration**，并按以下步骤配置应用：

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

![使用 APISIX 回调 URI 注册 Microsoft Entra 应用](https://static.api7.ai/uploads/2026/09/08/B3MFcBQI_entra-register-application-full.png)

重定向 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 建议改用[证书凭证](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials#add-a-certificate)。

![为 Microsoft Entra 应用创建客户端密钥](https://static.api7.ai/uploads/2026/09/08/j9qreXGE_entra-create-client-secret-full.png)

将租户 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[​](#配置-apisix "配置 APISIX的直接链接")

配置一条路由，在将浏览器请求转发到公共 HTTP 请求与响应服务 [httpbin.org](https://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 \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --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 将访问 Token、ID Token 和用户信息添加到上游请求头中。

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

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

adc.yaml

```
services:

  - name: entra-sso

    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 将访问 Token、ID Token 和用户信息添加到上游请求头中。

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

ADC 会将服务作为期望状态进行协调。标签选择器将此示例限制在其自身带标签的资源内。请先预览限定范围的变更，并确认其中没有意外更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=entra-sso
```

同步已审查的服务配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=entra-sso
```

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

## 验证身份认证[​](#验证身份认证 "验证身份认证的直接链接")

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

![登录 Microsoft Entra ID 以访问受保护的 APISIX 路由](https://static.api7.ai/uploads/2023/09/01/caen60yH_azure-ad-successful-authentication.png)

登录页面可以使用组织专属的徽标、颜色和其他视觉元素。有关要求和配置选项，请参阅[配置公司品牌](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-customize-branding)。

如果系统提示，请完成 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` 插件参考](https://docs.apiseven.com/hub/openid-connect/configuration.md)。
