如何配置Nginx-Ingress规则结合Keycloak实现应用认证

一、先明确Keycloak里Nginx客户端的作用 #

• 这个客户端是Nginx Ingress和Keycloak交互的「身份凭证」：用户访问受保护应用时，Nginx会把请求转去Keycloak做认证，Keycloak靠这个客户端的信息判断请求来源合法，同时用它生成、验证授权码和令牌。
• 你建的services realm就是专门管这些应用访问认证的域，所有相关的认证逻辑都在这个域下走。

二、解决Ingress注解404的核心问题 #

Keycloak 17+版本已经删掉了旧的/auth前缀，OpenID Connect的端点直接从根路径开始。你之前加/auth肯定会404，正确的端点格式是https://<你的Keycloak域名>/realms/services/protocol/openid-connect/xxx。

正确的Ingress配置示例 #

假设你的Keycloak域名是keycloak.example.com，要保护的应用Ingress这么写：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  annotations:
    # 启用OAuth认证，指定Keycloak的授权端点
    nginx.ingress.kubernetes.io/auth-url: "https://keycloak.example.com/realms/services/protocol/openid-connect/auth"
    # 登录跳转地址，确保登录后能回到原请求页面
    nginx.ingress.kubernetes.io/auth-signin: "https://keycloak.example.com/realms/services/protocol/openid-connect/auth?redirect_uri=$scheme://$host$request_uri"
    # 令牌验证端点，用来校验用户登录后的令牌合法性
    nginx.ingress.kubernetes.io/auth-token-url: "https://keycloak.example.com/realms/services/protocol/openid-connect/token"
    # 填入Keycloak里Nginx客户端的ID和Secret
    nginx.ingress.kubernetes.io/auth-client-id: "你的Nginx客户端ID"
    nginx.ingress.kubernetes.io/auth-client-secret: "你的Nginx客户端Secret"
    # 可选：指定需要获取的用户信息范围
    nginx.ingress.kubernetes.io/auth-scope: "openid email profile"
spec:
  ingressClassName: nginx
  rules:
  - host: your-app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: your-app-service
            port:
              number: 80

配置关键点 #

1. 绝对不要加/auth前缀：这是你之前404的主要原因，Keycloak 20版本已经不用这个旧路径了。
2. 客户端ID和Secret怎么找：打开Keycloak后台，进入services realm，找到你创建的nginx客户端：
   • Client ID就是客户端的名称（或者配置页里的Client ID字段）
   • Secret在Credentials标签页里，前提是你把客户端的Access Type设为confidential（必须设成这个，否则不会生成Secret）
3. redirect_uri要正确：用$scheme://$host$request_uri能动态获取用户原本请求的地址，保证登录后能跳回去。

三、Keycloak客户端的必配项 #

在Keycloak的nginx客户端配置页，检查这几个地方：

• Access Type：选confidential，不然Nginx没法用Secret和Keycloak交互
• Valid Redirect URIs：必须包含你要保护的应用域名，比如https://your-app.example.com/*，不然Keycloak会拒绝重定向请求
• Web Origins：设为*或者你的应用域名，避免跨域报错

四、验证配置是否生效 #

1. 应用Ingress配置：kubectl apply -f your-ingress.yaml
2. 访问你的应用域名，应该自动跳转到Keycloak登录页
3. 如果还是有问题，先测试Keycloak的端点是否能访问：

curl -v https://keycloak.example.com/realms/services/protocol/openid-connect/auth

返回200或跳转页面就是正常的；如果还是404，检查Keycloak自己的Ingress配置有没有加多余的/auth前缀。

内容的提问来源于stack exchange，提问作者peppie