Getting Started¶

This guide provides a step-by-step walkthrough for setting up MLflow Secrets Auth with your preferred secret management provider.

Prerequisites¶

Python 3.9 or higher
MLflow 2.20.4 or higher
Access to one of the supported secret managers:
HashiCorp Vault
AWS Secrets Manager
Azure Key Vault

Step 1: Installation¶

Choose your installation method based on your secret management provider:

Basic Installation¶

pip install mlflow-secrets-auth

Provider-Specific Installation¶

# For HashiCorp Vault
pip install mlflow-secrets-auth[vault]

# For AWS Secrets Manager
pip install mlflow-secrets-auth[aws]

# For Azure Key Vault
pip install mlflow-secrets-auth[azure]

# For multiple providers
pip install mlflow-secrets-auth[vault,aws,azure]

Step 2: Provider Setup¶

Option A: HashiCorp Vault¶

Configure Vault Access

export VAULT_ADDR="https://vault.company.com"
export VAULT_TOKEN="hvs.XXXXXXXXXXXXXXXX"
# OR use AppRole authentication
export VAULT_ROLE_ID="role-id-value"
export VAULT_SECRET_ID="secret-id-value"

Set Secret Path

export MLFLOW_VAULT_SECRET_PATH="secret/mlflow/auth"

Store Secret in Vault

# For Bearer token authentication
vault kv put secret/mlflow/auth token="your-mlflow-token"

# For Basic authentication
vault kv put secret/mlflow/auth username="user" password="pass"

Option B: AWS Secrets Manager¶

Configure AWS Credentials

export AWS_REGION="us-east-1"
# AWS credentials via IAM role, profile, or environment variables

Set Secret Name

export MLFLOW_AWS_SECRET_NAME="mlflow/auth"

Create Secret in AWS

aws secretsmanager create-secret \
  --name "mlflow/auth" \
  --secret-string '{"token":"your-mlflow-token"}'

Option C: Azure Key Vault¶

Configure Azure Authentication

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

Set Key Vault Details

export MLFLOW_AZURE_KEY_VAULT_URL="https://your-vault.vault.azure.net/"
export MLFLOW_AZURE_SECRET_NAME="mlflow-auth"

Store Secret in Azure Key Vault

az keyvault secret set \
  --vault-name "your-vault" \
  --name "mlflow-auth" \
  --value '{"token":"your-mlflow-token"}'

Step 3: Enable the Plugin¶

Activate the plugin in MLflow and enable your chosen provider:

# Activate the plugin in MLflow (required)
export MLFLOW_TRACKING_AUTH="mlflow_secrets_auth"

# Enable specific provider
export MLFLOW_SECRETS_AUTH_ENABLE="vault"
# OR
export MLFLOW_SECRETS_AUTH_ENABLE="aws-secrets-manager"
# OR
export MLFLOW_SECRETS_AUTH_ENABLE="azure-key-vault"

# Enable multiple providers (first available will be used)
export MLFLOW_SECRETS_AUTH_ENABLE="vault,aws-secrets-manager,azure-key-vault"

Step 4: Configure Security (Recommended)¶

Set up host allowlisting to restrict which MLflow servers can receive credentials:

# Allow specific hosts
export MLFLOW_SECRETS_ALLOWED_HOSTS="mlflow.company.com,mlflow-staging.company.com"

# Allow wildcard patterns
export MLFLOW_SECRETS_ALLOWED_HOSTS="*.company.com,localhost"

Step 5: Test the Setup¶

Verify Configuration¶

# Check plugin status and configuration
mlflow-secrets-auth info

# Run diagnostics
mlflow-secrets-auth doctor

# Test against your MLflow server
mlflow-secrets-auth doctor --dry-run https://mlflow.company.com

Test with MLflow¶

import mlflow

# Set your MLflow tracking URI
mlflow.set_tracking_uri("https://mlflow.company.com")

# Authentication happens automatically
mlflow.start_run()
mlflow.log_param("test", "setup")
mlflow.log_metric("status", 1.0)
mlflow.end_run()

print("Setup successful!")

Step 6: Environment Variables Summary¶

Create a .env file or set these environment variables in your deployment:

# Plugin Activation (required)
MLFLOW_TRACKING_AUTH=mlflow_secrets_auth

# Provider Selection
MLFLOW_SECRETS_AUTH_ENABLE=vault

# Vault Configuration (if using Vault)
VAULT_ADDR=https://vault.company.com
VAULT_TOKEN=hvs.XXXXXXXXXXXXXXXX
MLFLOW_VAULT_SECRET_PATH=secret/mlflow/auth

# Security Configuration
MLFLOW_SECRETS_ALLOWED_HOSTS=*.company.com,localhost

# Optional: Logging and Performance
MLFLOW_SECRETS_LOG_LEVEL=INFO
MLFLOW_VAULT_TTL_SEC=300

Common Use Cases¶

Development Environment¶

# Local development with Vault
export MLFLOW_TRACKING_AUTH="mlflow_secrets_auth"
export VAULT_ADDR="http://localhost:8200"
export VAULT_TOKEN="dev-token"
export MLFLOW_VAULT_SECRET_PATH="secret/dev/mlflow"
export MLFLOW_SECRETS_ALLOWED_HOSTS="localhost,127.0.0.1"
export MLFLOW_SECRETS_AUTH_ENABLE="vault"

Production Environment¶

# Production with AWS Secrets Manager
export MLFLOW_TRACKING_AUTH="mlflow_secrets_auth"
export AWS_REGION="us-east-1"
export MLFLOW_AWS_SECRET_NAME="production/mlflow/auth"
export MLFLOW_SECRETS_ALLOWED_HOSTS="mlflow.company.com"
export MLFLOW_SECRETS_AUTH_ENABLE="aws-secrets-manager"
export MLFLOW_SECRETS_LOG_LEVEL="WARNING"

CI/CD Pipeline¶

# Azure Key Vault for CI/CD
export MLFLOW_TRACKING_AUTH="mlflow_secrets_auth"
export AZURE_TENANT_ID="${AZURE_TENANT_ID}"
export AZURE_CLIENT_ID="${AZURE_CLIENT_ID}"
export AZURE_CLIENT_SECRET="${AZURE_CLIENT_SECRET}"
export MLFLOW_AZURE_KEY_VAULT_URL="https://ci-vault.vault.azure.net/"
export MLFLOW_AZURE_SECRET_NAME="mlflow-ci-auth"
export MLFLOW_SECRETS_ALLOWED_HOSTS="mlflow-ci.company.com"
export MLFLOW_SECRETS_AUTH_ENABLE="azure-key-vault"

Next Steps¶

Configuration Reference - Complete environment variable reference
Provider Documentation - Provider-specific configuration details
CLI Tools - Command-line utilities and diagnostics
Troubleshooting - Common issues and solutions
Demo Example - Complete working example with Docker Compose

Troubleshooting Quick Start¶

If you encounter issues during setup:

Check Plugin Status
```
mlflow-secrets-auth info
```

Run Diagnostics

mlflow-secrets-auth doctor --dry-run https://your-mlflow-server.com

Enable Debug Logging
```
export MLFLOW_SECRETS_LOG_LEVEL=DEBUG
```

Verify Provider Dependencies

python -c "import hvac; print('Vault OK')"  # For Vault
python -c "import boto3; print('AWS OK')"   # For AWS
python -c "import azure.identity; print('Azure OK')"  # For Azure

For detailed troubleshooting, see the Troubleshooting Guide.

Try the Demo¶

Before configuring your own environment, you can quickly test the plugin with our complete demo:

git clone https://github.com/hugodscarvalho/mlflow-secrets-auth
cd mlflow-secrets-auth/examples/vault-nginx-mlflow
make demo

The demo provides:

Complete Stack: Vault + MLflow + Nginx + Python client
Real Authentication: Nginx enforces auth, plugin handles it transparently
Multiple Auth Modes: Basic auth and Bearer token examples
Working Examples: See actual MLflow experiments being logged
Easy Cleanup: make down removes everything

After running the demo:

MLflow UI: http://localhost:8080
Vault UI: http://localhost:8200 (token: demo-root-token-12345)

This is the fastest way to see the plugin in action before setting up your own infrastructure.