在启用身份验证和 RBAC 的情况下使用 MLflow Python SDK

在 Alauda AI 中,MLflow Tracking Server 运行在单点登录和多租户之后:OAuth proxy 会对每个调用方进行身份验证,服务器会按调用用户记录每次运行,并根据 Kubernetes RBAC 对其进行授权。本指南将标准 MLflow Python SDK 通过该 OAuth proxy 进行调用,使用你自己的身份,且无需浏览器,通过针对平台登录脚本化的 OAuth2 授权码 流程(带 PKCE)完成——不使用密码授权,也绝不直接访问 MLflow 容器端口。

有两种无需浏览器即可提供身份的方式;请选择其一:

  • Bearer 令牌(推荐)。 从 CLI 或 Python 获取 Dex id 令牌,并将其作为 MLFLOW_TRACKING_TOKEN 传入;再通过 refresh token 进行续期。需要一项平台设置(见下文)。
  • Session cookie(无需平台更改)。 驱动 proxy 自身的登录流程,获取其 _oauth2_proxy cookie,并将其附加到请求中。可在任何安装环境中直接使用(见下文)。

身份验证的工作方式

你的运行记录前有两层:

  1. OAuth proxy(oauth2-proxy)对请求进行身份验证——可以是以 Authorization: Bearer … 形式发送的 Dex id 令牌(令牌方式),也可以是它自己的 _oauth2_proxy session cookie(cookie 方式)。
  2. MLflow 服务器的 kubernetes-auth 插件从该凭证中读取你的身份,将其记录为运行的所有者,并根据你在工作区中的 Kubernetes 权限对其进行授权。

客户端始终通过 OAuth proxy 访问——不要直接连接到 MLflow 容器端口。

前提条件

  • mlflow 3.10 或更高版本(pip install "mlflow>=3.10")。工作区选择(mlflow.set_workspace)是 3.10+ 的功能。Python 令牌助手还使用 requests 和 cryptography。
  • 能够访问目标工作区的平台 用户名和密码(参见工作区与访问控制)。这是一种普通的平台登录——不是 Kubernetes ServiceAccount——普通用户账户即可。对于共享或自动化使用场景(流水线、无头任务),建议使用专用的非个人账户,而不是个人登录,因为凭证/令牌会存储在 Secret 中,并且每次运行都会记录为你所使用的身份。
  • 平台的 OAuth client id 和 secret——即 MLflow proxy 使用的 client(由你的管理员提供)。在 Alauda 上,这就是平台认证 client,例如 alauda-auth;其 secret 存放在 Kubernetes Secret 中(例如 cpaas-oidc-secret)。

令牌方式的平台设置(管理员,一次性)

Bearer 令牌方式需要 MLflow OAuth proxy 接受 Dex id 令牌。请在 MLflow plugin 中添加 --skip-jwt-bearer-tokens=true ——这里指的是工作负载集群上的 MLflow proxy,不是平台的全局认证服务器:

# MLflow plugin values
auth:
  oauth:
    extraArgs:
      - --skip-jwt-bearer-tokens=true

无需对 Dex 或 global-auth 进行更改:下面的登录使用的是平台 client 已经允许的 authorization_code 授权。cookie 方式则完全不需要任何设置——如果你使用该方式,可跳过本节。

从命令行获取令牌(无需浏览器)

平台登录是一个 SSO 页面,但其 API 支持带 PKCE 的标准 OAuth 授权码 流程,因此你可以通过脚本完成——无需浏览器重定向。密码会使用登录服务的公钥(/dex/pubkey)进行 RSA 加密,与登录页面的处理方式完全一致,然后交换得到 id 令牌(以及用于无头续期的 refresh token)。

Python helper

import base64, hashlib, json, os, secrets
from urllib.parse import urlparse, parse_qs
import requests
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.serialization import load_pem_public_key

PLATFORM      = os.environ["PLATFORM_ADDRESS"].rstrip("/")    # https://<platform>
CLIENT_ID     = os.environ["DEX_CLIENT_ID"]                   # the MLflow proxy's client, e.g. alauda-auth
CLIENT_SECRET = os.environ["DEX_CLIENT_SECRET"]
USERNAME      = os.environ["MLFLOW_USERNAME"]
PASSWORD      = os.environ["MLFLOW_PASSWORD"]
REDIRECT_URI  = f"{PLATFORM}/oauth2/callback"                 # any URI the client has registered
VERIFY_TLS    = os.environ.get("PLATFORM_CA", False)         # CA bundle path, or False to skip (lab only)

s = requests.Session(); s.verify = VERIFY_TLS
_b64url = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()

def get_tokens() -> dict:
    """Run the authorization-code + PKCE flow headlessly. Returns the Dex token response."""
    verifier  = _b64url(secrets.token_bytes(48))
    challenge = _b64url(hashlib.sha256(verifier.encode()).digest())
    # 1) start the flow -> auth-request id
    req = s.get(f"{PLATFORM}/dex/api/v1/authorize", params={
        "client_id": CLIENT_ID, "redirect_uri": REDIRECT_URI, "response_type": "code",
        "scope": "openid email groups offline_access", "state": "cli",
        "code_challenge": challenge, "code_challenge_method": "S256"}).json()["req"]
    # 2) RSA-encrypt the password, then log in via the local connector -> auth code
    pk  = s.get(f"{PLATFORM}/dex/pubkey").json()              # {"ts": ..., "pubkey": "<PEM>"}
    payload = json.dumps({"ts": pk["ts"], "password": PASSWORD}, separators=(",", ":")).encode()
    enc = base64.b64encode(load_pem_public_key(pk["pubkey"].encode()).encrypt(payload, padding.PKCS1v15())).decode()
    redirect = s.post(f"{PLATFORM}/dex/api/v1/authorize/local", params={"req": req},
        json={"account": USERNAME, "password": enc}).json()["redirect_url"]
    code = parse_qs(urlparse(redirect).query)["code"][0]
    # 3) exchange the code (with the PKCE verifier) -> id_token + refresh_token
    return s.post(f"{PLATFORM}/dex/token", data={
        "grant_type": "authorization_code", "code": code, "redirect_uri": REDIRECT_URI,
        "code_verifier": verifier, "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}).json()

def refresh(refresh_token: str) -> str:
    """Mint a fresh id token from a refresh token — no login, no browser."""
    return s.post(f"{PLATFORM}/dex/token", data={
        "grant_type": "refresh_token", "refresh_token": refresh_token,
        "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET,
        "scope": "openid email groups"}).json()["id_token"]

Shell 等价实现(curl + openssl,无 Python 依赖)

PLATFORM=https://<platform>; CLIENT_ID=<client>; CLIENT_SECRET=<secret>
USERNAME='<user>'; PASSWORD='<password>'; REDIRECT_URI="$PLATFORM/oauth2/callback"

V=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=' | cut -c1-64)                       # PKCE verifier
C=$(printf %s "$V" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
RU=$(jq -rn --arg u "$REDIRECT_URI" '$u|@uri'); SC=$(jq -rn '"openid email groups offline_access"|@uri')
REQ=$(curl -sk "$PLATFORM/dex/api/v1/authorize?client_id=$CLIENT_ID&redirect_uri=$RU&response_type=code&scope=$SC&state=cli&code_challenge=$C&code_challenge_method=S256" | jq -r .req)
PK=$(curl -sk "$PLATFORM/dex/pubkey"); TS=$(echo "$PK"|jq -r .ts); echo "$PK"|jq -r .pubkey >/tmp/dex_pub.pem
ENC=$(printf '{"ts":"%s","password":"%s"}' "$TS" "$PASSWORD" | openssl pkeyutl -encrypt -pubin -inkey /tmp/dex_pub.pem -pkeyopt rsa_padding_mode:pkcs1 | openssl base64 -A)
CODE=$(curl -sk -X POST "$PLATFORM/dex/api/v1/authorize/local?req=$REQ" -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg a "$USERNAME" --arg p "$ENC" '{account:$a,password:$p}')" | jq -r .redirect_url | sed -E 's/.*code=([^&]+).*/\1/')
curl -sk "$PLATFORM/dex/token" -d grant_type=authorization_code -d code="$CODE" \
  --data-urlencode redirect_uri="$REDIRECT_URI" -d code_verifier="$V" \
  -d client_id="$CLIENT_ID" --data-urlencode client_secret="$CLIENT_SECRET" | jq -r .id_token

连接 SDK

import os, mlflow

tok = get_tokens()
os.environ["MLFLOW_TRACKING_TOKEN"] = tok["id_token"].strip()           # → Authorization: Bearer
mlflow.set_tracking_uri("http://mlflow-tracking-server.kubeflow:5000")  # in-cluster Service (fronted by the OAuth proxy)
mlflow.set_workspace("team-a")                                          # workspace namespace → X-MLFLOW-WORKSPACE
mlflow.set_experiment("my-experiment")

with mlflow.start_run(run_name="sdk-quickstart") as run:
    mlflow.log_param("learning_rate", 2e-4)
    mlflow.log_metric("loss", 0.123)
    print("run:", run.info.run_id)

该运行会显示在 Alauda AI → Tools → MLFlow 下,所有者为你进行身份验证时使用的用户。(在一个受保护的安装环境中已端到端验证:run owner 就是 token 的用户身份。)

当客户端在集群内部运行时(流水线组件、Workbench notebooks),请使用集群内 Service URL http://mlflow-tracking-server.kubeflow:5000。从集群外部访问时,请改为使用平台路由 https://<platform>/clusters/<cluster>/mlflow——两者都指向同一个 OAuth proxy(如果你的机器不信任平台证书,请设置 MLFLOW_TRACKING_INSECURE_TLS=true)。

WARNING

对于共享或无头使用场景,建议使用专用的非个人账户(普通的平台登录,而不是 Kubernetes ServiceAccount),并将其凭证和 client secret 存放在 Kubernetes Secret 中,绝不要写入代码中。务必对 token 调用 .strip()(末尾换行会导致 Invalid … character(s) in header value: 'Bearer …\n')。id 令牌会过期(默认 24 小时);对于长时间运行的任务,请使用 refresh(tok["refresh_token"]) 续期,而不是重新登录。

选择工作区

运行会记录在你选择的工作区中;如果未选择,则使用服务器的默认工作区。以下任一方式都可设置它(SDK 会将其转换为 X-MLFLOW-WORKSPACE header):

  • 在代码中使用 mlflow.set_workspace("team-a"),
  • 使用环境变量 MLFLOW_WORKSPACE=team-a。

你只能使用你账户有访问权限的工作区;参见工作区与访问控制。

注册模型

模型 registry 以工作区为作用域,并且授权方式相同,因此一旦连接成功,常规 SDK 调用即可正常工作:

mlflow.set_workspace("team-a")
with mlflow.start_run():
    mlflow.sklearn.log_model(sk_model, name="model", registered_model_name="fraud-detector")

可以在 MLflow UI 中将已注册版本提升为 Staging 或 Production。

如果你无法启用 --skip-jwt-bearer-tokens,可以驱动 proxy 自身的登录流程来获取其 _oauth2_proxy cookie,并将其附加到请求中——这在任何安装环境中都可直接使用,无需改动。proxy 会为你启动 OAuth 流程(它自己的 PKCE 和 redirect_uri);你只需通过同样的脚本化登录过程重放该流程,并将 code 返还给 proxy callback:

PLATFORM=https://<platform>; CLUSTER=<cluster>
USERNAME='<user>'; PASSWORD='<password>'
JAR=$(mktemp)
# 1) start the MLflow proxy login -> the Dex auth query it wants
LOC=$(curl -sk -c "$JAR" -D - -o /dev/null "$PLATFORM/clusters/$CLUSTER/mlflow/" \
  | awk 'BEGIN{IGNORECASE=1}/^location:/{print $2}' | tr -d '\r')
QS=${LOC#*\?}
# 2) authorize -> req, then 3) scripted local login -> the proxy callback URL
REQ=$(curl -sk -b "$JAR" -c "$JAR" "$PLATFORM/dex/api/v1/authorize?$QS" | jq -r .req)
PK=$(curl -sk "$PLATFORM/dex/pubkey"); TS=$(echo "$PK"|jq -r .ts); echo "$PK"|jq -r .pubkey >/tmp/dex_pub.pem
ENC=$(printf '{"ts":"%s","password":"%s"}' "$TS" "$PASSWORD" | openssl pkeyutl -encrypt -pubin -inkey /tmp/dex_pub.pem -pkeyopt rsa_padding_mode:pkcs1 | openssl base64 -A)
CB=$(curl -sk -b "$JAR" -c "$JAR" -X POST "$PLATFORM/dex/api/v1/authorize/local?req=$REQ" -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg a "$USERNAME" --arg p "$ENC" '{account:$a,password:$p}')" | jq -r .redirect_url)
# 4) the proxy callback exchanges the code and sets the _oauth2_proxy cookie
curl -sk -b "$JAR" -c "$JAR" -o /dev/null "$CB"
COOKIE=$(awk -F'\t' '$6 ~ /^_oauth2_proxy/{printf "%s=%s; ",$6,$7}' "$JAR" | sed 's/; $//')   # includes any _oauth2_proxy_N chunks
echo "$COOKIE"

然后使用一个 header provider 附加 cookie(cookie 会携带你的身份——不需要 token,也不需要平台设置):

import os, mlflow
from mlflow.tracking.request_header.abstract_request_header_provider import RequestHeaderProvider
from mlflow.tracking.request_header.registry import _request_header_provider_registry

class ProxySessionHeader(RequestHeaderProvider):
    def in_context(self):
        return bool(os.environ.get("MLFLOW_PROXY_COOKIE"))     # export MLFLOW_PROXY_COOKIE='_oauth2_proxy=<value>'
    def request_headers(self):
        return {"Cookie": os.environ["MLFLOW_PROXY_COOKIE"]}

_request_header_provider_registry.register(ProxySessionHeader)
mlflow.set_tracking_uri("https://<platform>/clusters/<cluster>/mlflow")
mlflow.set_workspace("team-a")

在集群内部,请改为使用集群内 Service URL http://mlflow-tracking-server.kubeflow:5000(不会有 TLS 问题)。在外部 https://<platform>/… 路由上,平台证书是自签名的,因此请设置 MLFLOW_TRACKING_INSECURE_TLS=true(或者将 REQUESTS_CA_BUNDLE 指向平台 CA)。

你也可以从浏览器会话中复制 _oauth2_proxy cookie(DevTools → Application/Storage → Cookies)。session cookie 会过期——当调用开始返回登录重定向时,请重新生成。

故障排查

症状检查
/dex/api/v1/authorize 返回 PKCE code_challenge is required客户端强制要求 PKCE。请发送 code_challenge 和 code_challenge_method=S256(helper 已经这样做了)。
本地登录返回 captcha challenge / CaptchaError最近失败登录次数过多,触发了重试验证码。请等待、修正凭证,然后重试——正常的首次登录不需要 captcha。
/dex/token 返回 invalid_grantauth code 或 PKCE verifier 已过期或被重复使用。请从头重新执行流程(authorize → 登录 → token);code 只能使用一次。
调用返回 HTML 或重定向(302 到登录页)令牌方式: proxy 拒绝了 bearer token——请确认已启用 --skip-jwt-bearer-tokens,且该 token 是有效的 Dex id 令牌(aud = proxy 的 client)。cookie 方式: _oauth2_proxy cookie 缺失或已过期。
Invalid … character(s) in header value: 'Bearer …\n'token 末尾有空白字符。请将 MLFLOW_TRACKING_TOKEN 设置为经过 .strip() 处理后的值。
Failed to query /api/3.0/mlflow/server-info, 且常伴随 SSLCertVerificationError: self-signed certificateproxy 拒绝了你的凭证,并重定向(302)到登录页;随后 SDK 跟随该重定向访问平台自签名的 HTTPS 终端并失败于 TLS。请修复凭证,而不是 TLS:对于令牌方式,请确认已启用 --skip-jwt-bearer-tokens 且 token 有效;对于cookie 方式,请重新生成 cookie。只有当你有意使用外部 https://<platform>/… 路由时,才需要同时设置 MLFLOW_TRACKING_INSECURE_TLS=true(或将 REQUESTS_CA_BUNDLE 指向平台 CA)。
403 PERMISSION_DENIED你的账户没有该工作区 namespace 的访问权限。请申请该工作区的访问权限(参见工作区与访问控制);这里不涉及 ServiceAccount。
Run 显示了错误的所有者或工作区所有者是你通过身份验证时使用的身份;工作区由 set_workspace() / MLFLOW_WORKSPACE 决定(否则使用服务器默认值)。请同时检查这两项。