#Auth

#基本概念

#什么是 Auth

Auth 是一种在请求到达实际服务之前进行身份验证的机制。它允许你在 ALB 级别统一处理身份验证，而无需在每个后端服务中实现身份验证逻辑。

#支持的 Auth 方法

ALB 支持两种主要的身份验证方法：

1. Forward Auth（外部身份验证）

   • 发送请求到外部身份验证服务以验证用户身份
   • 适用场景：需要复杂的身份验证逻辑，如 OAuth、SSO 等
   • 工作流程：
     1. 用户请求到达 ALB
     2. ALB 将身份验证信息转发给身份验证服务
     3. 身份验证服务返回验证结果
     4. 根据身份验证结果决定是否允许访问后端服务

2. Basic Auth（基本身份验证）

   • 基于用户名和密码的简单身份验证机制
   • 适用场景：简单访问控制，开发环境保护
   • 工作流程：
     1. 用户请求到达 ALB
     2. ALB 检查请求中的用户名和密码
     3. 与配置的身份验证信息进行比对
     4. 验证通过则转发到后端服务

#Auth 配置方式

1. 全局 Auth

   • 在 ALB 级别配置，适用于所有服务
   • 在 ALB 或 FT CR 上配置

2. 路径级 Auth

   • 在特定 Ingress 路径上配置
   • 在特定 Rule 上配置
   • 可以覆盖全局 Auth 配置

3. 禁用 Auth

   • 针对特定路径禁用身份验证
   • 在 Ingress 上通过注解配置：alb.ingress.cpaas.io/auth-enable: "false"
   • 在 Rule 上通过 CR 配置

#Auth 结果处理

• Auth 成功：请求将被转发到后端服务
• Auth 失败：返回 401 未授权错误
• 可以配置 Auth 失败后的重定向行为（适用于 Forward Auth）

#快速开始

使用 ALB 配置 Basic Auth

#部署 ALB

cat <<EOF | kubectl apply -f -
apiVersion: crd.alauda.io/v2
kind: ALB2
metadata:
  name: auth
  namespace: cpaas-system
spec:
  config:
    networkMode: container
    projects:
    - ALL_ALL
    replicas: 1
    vip:
      enableLbSvc: false
  type: nginx
EOF
export ALB_IP=$(kubectl get pods -n cpaas-system -l service_name=alb2-auth -o jsonpath='{.items[*].status.podIP}');echo $ALB_IP

#配置 Secret 和 Ingress

# echo "Zm9vOiRhcHIxJHFJQ05aNjFRJDJpb29pSlZVQU1tcHJxMjU4L0NoUDE=" | base64 -d #  foo:$apr1$qICNZ61Q$2iooiJVUAMmprq258/ChP1
# openssl passwd -apr1 -salt qICNZ61Q bar # $apr1$qICNZ61Q$2iooiJVUAMmprq258/ChP1

kubectl apply -f - <<'END'
apiVersion: v1
kind: Secret
metadata:
  name: auth-file
type: Opaque
data:
  auth: Zm9vOiRhcHIxJHFJQ05aNjFRJDJpb29pSlZVQU1tcHJxMjU4L0NoUDE=
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: auth-file
  annotations:
    "nginx.ingress.kubernetes.io/auth-type": "basic"
    "nginx.ingress.kubernetes.io/auth-secret": "default/auth-file"
    "nginx.ingress.kubernetes.io/auth-secret-type": "auth-file"
spec:
  rules:
  - http:
      paths:
      - path: /app-file
        pathType: Prefix
        backend:
          service:
            name: app-server
            port:
              number: 80
END

#验证

# echo "Zm9vOiJhYXIi" | base64 -d # foo:bar
curl -v -X GET -H "Authorization: Basic Zm9vOmJhcg==" http://$ALB_IP:80/app-file # 应返回 200
# 错误密码
curl -v -X GET -H "Authorization: Basic XXXXOmJhcg==" http://$ALB_IP:80/app-file # 应返回 401

#相关 Ingress 注解

Ingress-nginx 定义了一系列注解用于配置身份验证过程的细节。以下是 ALB 支持的注解列表，其中“v”表示支持，“x”表示不支持。

#forward-auth

相关注解：

• nginx.ingress.kubernetes.io/auth-url
• nginx.ingress.kubernetes.io/auth-method
• nginx.ingress.kubernetes.io/auth-signin
• nginx.ingress.kubernetes.io/auth-signin-redirect-param
• nginx.ingress.kubernetes.io/auth-response-headers
• nginx.ingress.kubernetes.io/auth-proxy-set-headers
• nginx.ingress.kubernetes.io/auth-request-redirect
• nginx.ingress.kubernetes.io/auth-always-set-cookie

这些注解描述了上述流程中 auth-request、app-request 和 cli-response 的修改。

#构造相关注解

#auth-url

Auth-request 的 URL，值可以是变量。

#auth-method

Auth-request 的请求方法。

#auth-proxy-set-headers

值为格式为 ns/name 的 ConfigMap 引用。 默认情况下，cli-request 的所有头部都会发送给 auth-server。可以通过 proxy_set_header 配置额外的头部。默认发送以下头部：

X-Original-URI          $request_uri;
X-Scheme                $pass_access_scheme;
X-Original-URL          $scheme://$http_host$request_uri;
X-Original-Method       $request_method;
X-Sent-From             "alb";
X-Real-IP               $remote_addr;
X-Forwarded-For         $proxy_add_x_forwarded_for;
X-Auth-Request-Redirect $request_uri;

#构造 app-request 相关注解

#auth-response-headers

值为逗号分隔的字符串，允许将 auth-response 中的特定头部带到 app-request 中。 示例：

nginx.ingress.kubernetes.io/auth-response-headers: Remote-User,Remote-Name

当 ALB 发起 app-request 时，会携带 auth-response 中的 Remote-User 和 Remote-Name 头部。

#Cookie 处理

auth-response 和 app-response 都可以设置 Cookie。默认情况下，只有当 app-response.success 时，auth-response.set-cookie 才会合并到 cli-response.set-cookie 中。

#重定向相关配置

当 auth-server 返回 401 时，可以在 cli-response 中设置重定向头部，指示浏览器跳转到 auth-signin 指定的 URL 进行验证。

#auth-signin

值为 URL，指定 cli-response 中的 location 头部。

#auth-signin-redirect-param

signin-url 中查询参数的名称，默认是 rd。 如果 signin-url 不包含指定的 auth-signin-redirect-param 参数名，alb 会自动添加该参数。参数值设置为 $pass_access_scheme://$http_host$escaped_request_uri，用于记录原始请求 URL。

#auth-request-redirect

在 auth-request 中设置 x-auth-request-redirect 头部。

#basic-auth

basic-auth 是 RFC 7617 中描述的身份验证过程。 交互流程如下：

#auth-realm

受保护区域的描述 即 cli-response 中 WWW-Authenticate 头部的 realm 值。 WWW-Authenticate: Basic realm="$realm"

#auth-type

身份验证方案的类型，目前仅支持 basic

#auth-secret

用户名和密码的 Secret 引用，格式为 ns/name

#auth-secret-type

Secret 支持两种类型：

1. auth-file：Secret 的 data 仅包含一个键 "auth"，其值为 Apache htpasswd 格式的字符串。例如：

   data:
     auth: "user1:$apr1$xyz..."

2. auth-map：Secret 的 data 中每个键代表一个用户名，对应的值是密码哈希（htpasswd 格式中不含用户名）。例如：

   data:
     user1: "$apr1$xyz...."
     user2: "$apr1$abc...."

注意：目前仅支持使用 apr1 算法生成的 htpasswd 格式密码哈希。

#CR

ALB CR 已添加与 Auth 相关的配置项，可在 ALB/Frontend/Rule CR 中配置。 运行时，ALB 会将 Ingress 上的注解转换为规则。

auth:
  # 基本身份验证配置
  basic:
    #  string; 对应 nginx.ingress.kubernetes.io/auth-type: basic
    auth_type: 'basic'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-realm
    realm: 'Restricted Access'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-secret
    secret: 'ns/name'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-secret-type
    secret_type: 'auth-map|auth-file'
  # Forward 身份验证配置
  forward:
    #  boolean; 对应 nginx.ingress.kubernetes.io/auth-always-set-cookie
    always_set_cookie: true
    #  string; 对应 nginx.ingress.kubernetes.io/auth-proxy-set-headers
    auth_headers_cm_ref: 'ns/name'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-request-redirect
    auth_request_redirect: '/login'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-method
    method: 'GET'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-signin
    signin: '/signin'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-signin-redirect-param
    signin_redirect_param: 'redirect_to'
    #  []string; 对应 nginx.ingress.kubernetes.io/auth-response-headers
    upstream_headers:
      - 'X-User-ID'
      - 'X-User-Name'
      - 'X-User-Email'
    #  string; 对应 nginx.ingress.kubernetes.io/auth-url
    url: 'http://auth-service/validate'

Auth 支持在以下位置配置：

• Alb CR 的 .spec.config.auth
• Frontend CR 的 .spec.config.auth
• Rule CR 的 .spec.config.auth

继承顺序为 Alb > Frontend > Rule。如果子 CR 未配置，则使用父 CR 的配置。

#ALB 特殊 Ingress 注解

在处理 Ingress 过程中，ALB 根据注解前缀确定优先级，优先级从高到低为：

• index.$rule_index-$path_index.alb.ingress.cpaas.io
• alb.ingress.cpaas.io
• nginx.ingress.kubernetes.io

这可以处理与 ingress-nginx 的兼容性问题，并在特定 Ingress 路径上指定 Auth 配置。

#Auth-Enable

alb.ingress.cpaas.io/auth-enable: 'false'

ALB 新增的注解，用于指定是否启用该 Ingress 的身份验证功能。

#Ingress-Nginx Auth 相关其他特性

#Global-Auth

在 ingress-nginx 中，可以通过 ConfigMap 设置全局身份验证，相当于为所有 Ingress 配置身份验证。在 ALB 中，可以在 ALB2 和 FT CR 上配置身份验证，其下的规则会继承这些配置。

#No-Auth-Locations

在 ALB 中，可以通过在 Ingress 上配置注解 alb.ingress.cpaas.io/auth-enable: "false" 来禁用该 Ingress 的身份验证功能。

#注意：与 Ingress-Nginx 不兼容的部分

1. 不支持 auth-keepalive
2. 不支持 auth-snippet
3. 不支持 auth-cache
4. 不支持 auth-tls
5. Basic-auth 仅支持 basic，不支持 digest
6. Basic-auth basic 仅支持 apr1 算法，不支持 bcrypt、sha256 等

#故障排查

1. 检查 ALB pod 中 Nginx 容器日志
2. 检查返回中的 X-ALB-ERR-REASON 头部