MLflow:Auth

MLflow Tracking Server에 대한 API 요청 시 JWT(JSON Web Token) 기반 인증 흐름을 정의한다.

개요

커스텀 MLflow Tracking Server에 모델을 등록하거나 실험 데이터를 기록할 때, 모든 API 요청에 JWT 인증이 필요하다.

MLflow Python SDK는 MLFLOW_TRACKING_TOKEN 환경변수를 통해 Bearer Token 인증을 지원한다.

인증 흐름 상세

1단계: 크리덴셜 발급 (사전 협의)

지오소프트가 아이티엘에 API 접근용 크리덴셜을 발급한다.

항목	내용
발급 항목	`client_id`, `client_secret`
발급 주체	지오소프트 (MLOps 플랫폼 운영)
수령 주체	아이티엘 (모델 개발)
전달 방식	보안 채널을 통한 사전 전달
관리 책임	아이티엘이 크리덴셜을 안전하게 보관

2단계: JWT 토큰 획득

아이티엘이 인증 엔드포인트에 크리덴셜을 제출하여 JWT를 수령한다.

요청

POST /auth/token HTTP/1.1
Host: <tracking-server>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

응답

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

필드	타입	설명
`access_token`	`STRING`	JWT 액세스 토큰
`token_type`	`STRING`	항상 `Bearer`
`expires_in`	`INT`	토큰 유효 시간 (초)

3단계: API 요청

획득한 JWT를 Authorization 헤더에 포함하여 MLflow API를 호출한다.

POST /api/2.0/mlflow/runs/log-batch HTTP/1.1
Host: <tracking-server>
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

{
  "run_id": "abc123",
  "metrics": [{"key": "accuracy", "value": 0.95, "timestamp": 1711000000000}]
}

4단계: 토큰 만료 및 갱신

JWT가 만료되면 Tracking Server는 401 Unauthorized를 반환한다. 아이티엘은 2단계를 반복하여 새 토큰을 획득한다.

[토큰 유효]  API 호출 → 200 OK
[토큰 만료]  API 호출 → 401 Unauthorized → 토큰 재발급 → API 재호출

MLflow Python SDK 연동

환경변수 설정

MLflow Python SDK는 다음 환경변수를 인식하여 자동으로 인증 헤더를 삽입한다.

환경변수	용도	비고
`MLFLOW_TRACKING_URI`	Tracking Server 주소	`https://` 필수
`MLFLOW_TRACKING_TOKEN`	JWT 액세스 토큰	설정 시 `Authorization: Bearer`<token> 자동 삽입

사용 예시

# 1. JWT 획득
TOKEN=$(curl -s -X POST https://<tracking-server>/auth/token \
  -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}" \
  | jq -r .access_token)

# 2. 환경변수 설정
export MLFLOW_TRACKING_URI=https://<tracking-server>
export MLFLOW_TRACKING_TOKEN=$TOKEN

# 3. Python SDK 사용 (인증 헤더 자동 삽입)
python train.py

import mlflow

# 환경변수가 설정되어 있으면 별도 인증 코드 불필요
mlflow.set_experiment("quality-inspection")

with mlflow.start_run():
    mlflow.log_param("model_type", "yolov8")
    mlflow.log_metric("accuracy", 0.95)
    mlflow.log_artifact("model.pth")
    # 모든 호출에 Authorization: Bearer <JWT> 헤더가 자동 포함됨

SDK 내부 인증 처리 순서

MLflow SDK는 다음 우선순위로 인증 방식을 결정한다.

우선순위	환경변수	결과 헤더
1	`MLFLOW_TRACKING_TOKEN`	`Authorization: Bearer`<token>
2	`MLFLOW_TRACKING_USERNAME` + `MLFLOW_TRACKING_PASSWORD`	`Authorization: Basic`<base64>
3	`MLFLOW_TRACKING_HEADERS` (JSON)	임의의 커스텀 헤더

INFORMATION
SDK는 토큰을 그대로 전달만 하며, JWT 발급·갱신·만료 처리는 수행하지 않는다. 토큰 만료 시 API 호출이 `401`로 실패하므로, 장시간 실행되는 학습 파이프라인에서는 토큰 갱신 로직을 별도로 구현해야 한다.

보안 요구사항

항목	요구사항
통신 암호화	TLS(HTTPS) 필수. 평문 HTTP를 통한 토큰 전송 금지
크리덴셜 보관	`client_secret`은 환경변수 또는 시크릿 관리 도구에 보관. 소스 코드에 하드코딩 금지
토큰 유효 기간	운영 정책에 따라 설정 (예: 1시간). 과도하게 긴 만료 시간 지양
토큰 갱신	만료 전 사전 갱신 권장. 학습 중 토큰 만료로 인한 데이터 유실 방지
접근 제어	크리덴셜별 권한 범위(scope) 설정. 최소 권한 원칙 적용