跳到主要内容

OpenID Connect (OIDC)

概述​

OIDC (OpenID Connect) Policy 通过与 OIDC 提供者集成，为 API 提供身份验证和授权。这确保只有经过身份验证的用户才能访问 API，无论是通过基于令牌的方法还是授权流程。

配置详情​

必需路径 / 非必需路径​

  • Required Path: OIDC 身份验证仅在列出的路径上强制执行。
  • Not Required Path: OIDC 身份验证在列出的路径上被跳过，但在所有其他路径上强制执行。
  • 如果未指定路径，则 OIDC 身份验证适用于所有路径。
  • 在路径选项之间切换将需要确认。

授权类型配置​

OIDC 策略支持两种 Grant Types，它们决定了身份验证流程：

  • Authorization Code Grant: 将用户重定向到 OIDC 提供者进行身份验证。
  • Password Grant: 直接用用户凭据交换 ID 令牌。

每种授权类型都有其自己的配置集：

Authorization Code Grant:

此流程主要用于 web applications，用户通过登录页面进行身份验证。

Configuration FieldDescription
领域身份验证领域的名称。示例：realms_name
客户端 IDOIDC 提供者分配的唯一标识符。
客户端密钥身份验证所需的客户端密钥。
发现提供者的发现端点的 URL（例如，https://oidcprovider/.well-known/openid-configuration）。
登出路径用户的登出端点（例如，/logout）。
登出后的重定向 URI登出路径的重定向 URI 参数和值
仅限持有者定义是否需要持有者令牌：是（仅令牌身份验证）或否（允许令牌和登录重定向）。
范围指定访问级别（默认：openid）。
令牌检查端点令牌验证的 URL。
登录 URL用户登录的 API 端点。
Cookie 域与身份验证 Cookie 相关联的域（例如，skapim.com。
跳过头名称允许使用头键（例如，x-oidc-api-key）跳过特定请求的身份验证。
跳过密钥实际的跳过密钥值。
刷新令牌过期令牌过期时间（默认：3600 秒）。
SameSite控制跨站请求处理的 Cookie 设置。选项：Lax、Strict 或 None。
安全启用或禁用安全 Cookie（默认：false）。
未授权操作定义身份验证失败时的行为。选项：重定向到登录页面或返回 401（拒绝）。
允许 IP / 拒绝 IP允许或阻止特定 IP 进行 OIDC 身份验证。

授权码授权

Password Grant:

此流程通常用于 machine-to-machine authentication 或受信任的客户端。

Configuration FieldDescription
领域身份验证领域的名称。示例：auth
客户端 IDOIDC 提供者分配的唯一标识符（例如，account）。
客户端密钥身份验证所需的客户端密钥。
发现提供者的发现端点的 URL（例如，https://oidcprovider/.well-known/openid-configuration）。
登出路径用户的登出端点（例如，/Logout）。
重定向 URI 路径登录后重定向用户的端点 (例如，/auth/api/login)。
范围指定访问级别 (默认: openid)。
SameSite控制跨站请求处理的 Cookie 设置。选项: Lax, Strict 或 None。
安全切换以开启/关闭安全选项
刷新令牌过期时间令牌过期时间 (默认: 3600 秒)。
登录 URL用户登录的 API 端点。
会话名称定义会话存储名称 (例如，apim_prod_session)。
Cookie 域与身份验证 Cookie 相关联的域 (例如， skapim.com)。
跳过头名称允许使用头键 (例如，x-oidc-api-key) 跳过特定请求的身份验证。
跳过密钥实际的跳过密钥值。
登录后重定向 URI成功登录后重定向用户的 URL。
登出后重定向 URI登出后重定向用户的 URL。

注意：

  • Authorization Code Grant 需要登录页面重定向，而 Password Grant 是直接的 API 请求。
  • Bearer Only Mode：
    • 如果设置为是，则只允许基于令牌的身份验证。
    • 如果设置为否，则支持登录重定向和令牌身份验证。

Redis 数据库选择​

会话数据可以存储在不同类型的 Redis 数据库中。所选的 Redis type 决定需要设置哪些配置。

APIM Redis (Default)
  • 使用内置的 APIM Redis 进行会话存储。
  • 不需要额外的配置。
Custom Redis
  • 允许连接到外部 Redis 实例。
Configuration FieldDescription
Redis HostRedis 服务器的地址 (例如，127.0.0.1)。
Redis PortRedis 服务器的端口号 (例如，6379)。
Redis Password认证密码。
Redis Database指定要使用的数据库索引（例如，1）。
Redis Pool SizeRedis 连接池中的最大连接数（默认：1000）。
Redis Pool Backlog等待可用连接的最大请求数（默认：30）。

Redis Cluster
  • 使用分布式 Redis 设置进行会话存储。
Configuration FieldDescription
Redis Cluster Nodes集群节点地址（例如，redis-cluster.apim:6379）。
Redis Cluster Password认证密码。
Redis Cluster Name指定集群名称（例如，kong_redis_cluster）。
Redis Connect Timeout建立 Redis 连接的超时时间（默认：1000ms）。
Redis Read Timeout从 Redis 读取数据的超时时间（默认：1000ms）。
Redis Send Timeout向 Redis 发送数据的超时时间（默认：1000ms）。
Redis Pool SizeRedis 连接池中的最大连接数（默认：1000）。
Redis Pool Backlog最大待处理连接数（默认：30）。
Redis Keepalive TimeoutRedis 连接关闭前的最大空闲时间（默认：55000ms）。

OIDC 认证行为的附加说明​

OIDC（OpenID Connect）使客户端应用程序能够通过外部 OIDC 提供者对用户进行身份验证。

登出路径和重定向 URI 行为​

在配置登出路径和登出后的重定向 URI 时，行为取决于您的 API 网关的结构：

  • 假设您的网关 URL 是 https://your.domain.com ，API 的基本路径是 /basePath。
  • 如果您在 OIDC 策略中将注销路径设置为 /logout，则完整的注销 URL 变为： https://your.domain.com/basePath/logout
  • 当调用此 URL 时，注销由 OIDC 提供者内部处理。
  • 注销后，浏览器将被重定向到注销后的重定向 URI（即 redirect_uri 值），该值必须在请求中明确定义。
备注

如果完整的注销 URL 和 redirect_uri 没有正确设置，注销过程可能不会按预期重定向。

支持的两种身份验证方法​

OIDC 允许两种方式进行身份验证：

  1. 浏览器重定向登录屏幕：浏览器被重定向到 OIDC 登录页面进行用户身份验证。
  2. 请求中的 ID 令牌：客户端通过 HTTP 直接发送 ID 令牌，而不重定向用户。

这些方法的行为取决于 bearerOnly 设置：

bearerOnly 值行为
no允许两种方法 (1) 和 (2)。
yes仅允许方法 (2)。系统不会重定向到登录页面。

令牌验证和头格式​

  • 要使用方法 (2) 验证 ID 令牌，您必须配置 introspection 端点——检查令牌有效性的端点。
  • 在使用 ID 令牌调用 API 时，请使用以下格式在请求头中包含令牌：
Authorization: bearer your_ID_token