Skip to content

Authentication Methods Guide

This guide explains the three authentication methods available in pyfabricops and when to use each one.

Overview

pyfabricops supports three authentication methods:

  1. env - Environment variables (Service Principal or User / ROPC credentials)
  2. oauth - Interactive browser authentication
  3. fabric - Fabric notebook authenticated user (NEW!)

Method 1: Environment Variables (env)

Use when: Running in CI/CD pipelines, GitHub Actions, Azure DevOps, or when you have service principal credentials.

Setup:

Create a .env file or set environment variables:

FAB_CLIENT_ID=your_client_id_here
FAB_CLIENT_SECRET=your_client_secret_here  # Required for SPN flow
FAB_TENANT_ID=your_tenant_id_here
FAB_USERNAME=your_username_here    # Required for user (ROPC) flow
FAB_PASSWORD=your_password_here    # Required for user (ROPC) flow

Usage — Service Principal (default):

import pyfabricops as pf

pf.set_auth_provider("env")                       # default: credential_type="spn"
pf.set_auth_provider("env", credential_type="spn")  # explicit equivalent

workspaces = pf.list_workspaces()

Usage — User / ROPC (CI/CD without a Service Principal):

import pyfabricops as pf

pf.set_auth_provider("env", credential_type="user")

workspaces = pf.list_workspaces()

Note: The ROPC flow sends FAB_USERNAME and FAB_PASSWORD directly to Azure AD. It is incompatible with accounts that have MFA or Conditional Access policies enforced.

Pros: - ✅ Works everywhere (local, CI/CD, containers) - ✅ Service principal and user (ROPC) support - ✅ Secure credential management - ✅ No user interaction required

Cons: - ❌ Requires credential management - ❌ Need to configure environment variables - ❌ ROPC flow is incompatible with MFA / Conditional Access

Method 2: OAuth Interactive (oauth)

Use when: Running locally in VSCode, Jupyter notebooks (outside Fabric), or any interactive environment.

Setup:

No setup required, but you need Azure AD permissions.

Usage:

import pyfabricops as pf

pf.set_auth_provider("oauth")

# First call will open a browser for authentication
workspaces = pf.list_workspaces()

Pros: - ✅ Easy to use - no credentials to manage - ✅ Uses your Azure AD account - ✅ Token is cached for reuse - ✅ Great for development

Cons: - ❌ Requires browser access - ❌ Not suitable for automation - ❌ Doesn't work in headless environments

Method 3: Fabric Notebook (fabric) 🆕

Use when: Running inside Microsoft Fabric notebooks where the user is already authenticated.

Setup:

No setup required! The authenticated user's token is automatically retrieved.

Usage:

import pyfabricops as pf

pf.set_auth_provider("fabric")

# Uses the authenticated user's token automatically
workspaces = pf.list_workspaces()

How it works:

Under the hood, this method uses: 

from notebookutils import credentials
access_token = credentials.getToken("pbi")

Pros: - ✅ Zero configuration needed - ✅ No browser popup - ✅ Uses logged-in user's permissions - ✅ Perfect for Fabric notebooks - ✅ Token automatically cached and refreshed

Cons: - ❌ Only works inside Microsoft Fabric notebooks - ❌ Will fail outside Fabric environment

Comparison Table

Feature env (spn) env (user) oauth fabric
Works in Fabric notebooks ✅ ✅ ✅ ✅
Works in VSCode ✅ ✅ ✅ ❌
Works in CI/CD ✅ ✅ ❌ ❌
Requires credentials ✅ ✅ ❌ ❌
Requires browser ❌ ❌ ✅ ❌
Service Principal support ✅ ❌ ❌ ❌
User token ❌ ✅ ✅ ✅
MFA / Conditional Access ✅ ❌ ✅ ✅
Auto-refresh ✅ ✅ ✅ ✅

Examples

Example 1: Local Development (VSCode)

import pyfabricops as pf

# Use OAuth for easy local development
pf.set_auth_provider("oauth")
pf.setup_logging(level="info")

workspaces = pf.list_workspaces()
print(f"Found {len(workspaces)} workspaces")

Example 2: Fabric Notebook

import pyfabricops as pf

# Use fabric method - no credentials needed!
pf.set_auth_provider("fabric")

# Get current workspace info
workspace = pf.get_workspace("my-workspace-name")
print(workspace)

# List items
items = pf.list_items(workspace["id"])
for item in items:
    print(f"- {item['displayName']} ({item['type']})")

Example 3: CI/CD Pipeline — Service Principal

import pyfabricops as pf
import os

# Use env method with service principal (default)
pf.set_auth_provider("env")

# Credentials come from environment variables
# These should be set in GitHub Secrets or Azure DevOps variables
workspaces = pf.list_workspaces()

# Deploy items
pf.deploy_item("my-workspace", "my-item", source_path="./artifacts")

Example 4: CI/CD Pipeline — User (ROPC, no Service Principal)

import pyfabricops as pf

# Use ROPC flow when a Service Principal is not available
pf.set_auth_provider("env", credential_type="user")

# FAB_USERNAME and FAB_PASSWORD must be set in the environment
workspaces = pf.list_workspaces()

Switching Between Methods

You can switch authentication methods at runtime:

import pyfabricops as pf

# Start with OAuth
pf.set_auth_provider("oauth")
workspaces = pf.list_workspaces()

# Switch to env for deployment
pf.set_auth_provider("env")
pf.deploy_item("workspace", "item", "./path")

# Switch to fabric if in Fabric notebook
try:
    pf.set_auth_provider("fabric")
    print("Running in Fabric!")
except Exception:
    print("Not in Fabric, using current method")

Troubleshooting

Error: "notebookutils is not available"

This means you're trying to use fabric authentication outside of a Microsoft Fabric notebook.

Solution: Use oauth or env instead: 

pf.set_auth_provider("oauth")  # or "env"

Error: "client_secret is required for client_credentials" (AADSTS7000216)

This happens when using set_auth_provider("env") (default SPN flow) without FAB_CLIENT_SECRET set.

Solution A: Provide FAB_CLIENT_SECRET for Service Principal authentication.

Solution B: Switch to the user (ROPC) flow and provide user credentials: 

pf.set_auth_provider("env", credential_type="user")
# Requires FAB_USERNAME and FAB_PASSWORD in the environment

Error: "Failed to retrieve token"

For env method, check that all required environment variables are set: 

import os
print("Client ID:", os.getenv("FAB_CLIENT_ID"))
print("Tenant ID:", os.getenv("FAB_TENANT_ID"))

For oauth method, ensure you have permissions to authenticate.

Token Cache Issues

If you're having authentication issues, try clearing the token cache: 

pf.clear_token_cache()
pf.set_auth_provider("oauth")  # Re-authenticate

Best Practices

  1. Use fabric in Fabric notebooks - It's the simplest and most secure option when available
  2. Use oauth for local development - Easy and no credential management
  3. Use env for automation - Required for CI/CD and production deployments
  4. Never commit credentials - Always use environment variables or secrets management
  5. Clear the cache to sign in with another account - Use pf.clear_token_cache() before signing in again with oauth; with env, each identity already has its own cache entry

Security Notes

  • Tokens are cached in pyfabricops/token_cache.json in your user cache folder (%LOCALAPPDATA% on Windows, ~/Library/Caches on macOS, $XDG_CACHE_HOME or ~/.cache on Linux), in a folder and a file only you can read
  • With env, each identity (tenant, client ID and, for credential_type="user", the username) has its own cache entry, so switching credentials never reuses another identity's token
  • Tokens automatically expire and are refreshed
  • Service principal credentials should be stored securely (Key Vault, GitHub Secrets, etc.)
  • The fabric method is the most secure for notebooks as it uses the platform's authentication