Migration Guide

Upgrading from NiPyAPI 0.x/NiFi 1.x to NiPyAPI 1.x/NiFi 2.x

This guide helps you migrate existing code from NiPyAPI 0.x (targeting Apache NiFi/Registry 1.x) to NiPyAPI 1.x (targeting Apache NiFi/Registry 2.x).

Note

Breaking Changes: This is a major version upgrade with significant breaking changes. Plan for code updates and testing when migrating.

Note

New in 1.x: The Profiles System provides centralized configuration management. You can use profiles, environment variables, or direct configuration - all approaches work with the same underlying system.

Version Overview

Component

Old Version (0.x)

New Version (1.x)

NiPyAPI

0.x

1.x

Apache NiFi

1.x (tested: 1.28.1)| 2.x (tested: 2.5.0)

NiFi Registry

0.x, 1.x

2.x (tested: 2.5.0)

Python

2.7, 3.6+

3.9+

Understanding Migration Scope

Important

NiPyAPI Migration ≠ NiFi Flow Migration

Upgrading NiPyAPI from 0.x to 1.x does not automatically migrate your NiFi flows from NiFi 1.x to 2.x. These are separate migration processes:

What NiPyAPI 1.x Migration Covers:

  • Python client library compatibility with NiFi 2.x APIs

  • Authentication and connection management

  • SDK function names and parameters

  • Configuration and deployment automation

What NiFi Flow Migration Requires Separately:

  • Processor Updates: Many processors have new names, properties, or behaviors in NiFi 2.x

  • Controller Service Changes: Connection pool configurations, SSL contexts, and service properties

  • Expression Language: Some expression language functions and syntax have changed

  • Flow Structure: Deprecated components need replacement with 2.x equivalents

  • Property Validation: New validation rules and required properties

  • Deprecations: Variable Registry and Templates are deprecated, use Parameters and Git versioning instead.

How NiPyAPI 1.x Can Help Your Flow Migration:

NiPyAPI 1.x provides powerful automation tools for flow migration tasks:

  • Flow Analysis: Inventory processors, controller services, and configurations across environments

  • Bulk Updates: Programmatically update processor properties and relationships

  • Version Control: Export, modify, and import flows through NiFi Registry

  • Environment Promotion: Move updated flows between development, staging, and production

  • Migration Scripts: Automate repetitive flow update tasks

  • Validation Functions: Report on invalid processors, controller services, and connections

  • Sandbox Environment: Test different authentication mechanisms with make sandbox target

  • Parameter Management: Manage parameters across environments

You can continue to use NiPyAPI 0.x with NiFi 1.x, and NiPyAPI 1.x with NiFi 2.x to assist with the migration process.

For NiFi-specific migration guidance, consult the Apache NiFi Migration Guide and your organization’s NiFi administrators.

Major Changes Summary

Breaking Changes - Action Required

  • Function renaming: Upstream API specification changes result in operation IDs now using suffixed names (e.g., update_run_status1) and some other functions are also renamed

  • Authentication and configuration overhaul: Significant changes to align with modern API standards and upstream API changes

  • Users must review and update authentication patterns - legacy configuration methods will be different

Removed Features

  • Templates API: Deprecated in NiFi 2.x - use Process Groups and Git or Flow Registry instead

  • Python 2.7 Support: EOL, dropped in favor of modern Python 3.9+

  • Legacy Authentication: Simplified to modern bearer token approach

NEW: Profile Management System

  • Extensible file format (YAML/JSON) with environment variable overrides and sane defaults - familiar workflow like AWS CLI

  • Intelligent authentication method detection: OIDC, mTLS, and Basic authentication based on available configuration parameters

  • Built-in profiles for common deployment patterns: single-user, secure-ldap, secure-mtls, secure-oidc

  • Extensible profiles with provided examples/profiles.yml as a starting point, or create your own

  • 15+ configurable parameters (URLs, credentials, certificates, SSL settings) with environment variable overrides

  • Profile switching with nipyapi.profiles.switch() configures endpoints, authentication, and SSL settings in single function call configurable directly or with NIPYAPI_PROFILE environment variable

Enhanced Development Workflow

  • Comprehensive Makefile targets for all key development and release processes

  • End-to-end automation: entire client generation and testing sequence from test certificates to final integration tests

  • GitHub Actions CI with full Docker NiFi integration tests and coverage reporting

  • Sandbox Docker environment for testing different authentication mechanisms with make sandbox target

Updated APIs

  • Client Generation: Now uses OpenAPI 3.x specs with swagger-codegen v3

  • Authentication: Bearer token-based authentication replacing custom token handling

  • Renamed Operations: Updated to match upstream NiFi 2.x naming (e.g., update_run_status1)

Enhanced Features

  • Docker Profiles: Streamlined LDAP, mTLS, and single-user configurations

  • Security: Enhanced certificate management and authentication flows

  • Documentation: Completely restructured with individual API pages

  • Build System: Modern Python packaging with pyproject.toml and Makefile

Understanding the Profiles System

NiPyAPI 1.x introduces a centralized configuration system that eliminates the need for complex manual setup. The system revolves around two key components:

  1. Configuration File: examples/profiles.yml (or your custom file)

  2. Python Interface: nipyapi.profiles.switch('profile-name')

How it works:

# 1. Profiles file defines your environments
# examples/profiles.yml contains: single-user, secure-ldap, secure-mtls, secure-oidc

# 2. Switch to any environment with one function call
import nipyapi
nipyapi.profiles.switch('single-user')  # Configures everything automatically

# 3. Use NiPyAPI normally - authentication and SSL are handled
about = nipyapi.system.get_nifi_version_info()

Why this matters for migration:

  • 0.x approach: 10+ lines of manual configuration per environment

  • 1.x approach: 1 line switches entire environment configuration

  • Zero code changes needed to switch between dev/staging/production

Understanding the Profiles System

The profiles system was introduced to solve environment configuration complexity in 0.x. Instead of manually configuring multiple services, certificates, and authentication for each environment, profiles provide centralized configuration management through YAML files.

For complete profile configuration and usage details, see docs/profiles.rst.

Migration Strategy: 1. Create profiles.yml defining your environments (or use examples/profiles.yml for testing) 2. Replace manual configuration blocks with nipyapi.profiles.switch('profile-name') calls 3. Test each environment switch to ensure authentication and SSL work correctly

Breaking Changes

Authentication and Configuration

Environment Variables

Old (0.x)

New (1.x)

Notes

test_default = True (in conftest.py)

NIPYAPI_PROFILE

Environment variable replaces file editing

NIFI_CA_CERT

NIFI_CA_CERT_PATH (profiles) or TLS_CA_CERT_PATH (shared)

REMOVED - Use profiles system or direct config

Authentication Migration Strategy

The 1.x authentication approach is profiles-first. Instead of manually configuring each service, define your authentication in profiles.yml and let the system handle the complexity. The old calls are still present, but the new method is intended to remove the complexity of understanding the underlying authentication mechanisms.

Old approach (0.x) - Manual configuration:

# 0.x: Complex manual setup (DO NOT USE in 1.x)
import nipyapi
nipyapi.config.nifi_config.ssl_ca_cert = nipyapi.config.default_ssl_context["ca_file"]
nipyapi.utils.set_endpoint("https://localhost:8443/nifi-api", ssl=True, login=True,
                          username="nobel", password="supersecret1!")

New approach (1.x) - Profiles-based configuration:

# 1.x: Profiles handle everything automatically (RECOMMENDED)
import nipyapi

# For development/testing (uses examples/profiles.yml)
nipyapi.profiles.switch('single-user')

# For your production environment (uses custom profiles.yml)
nipyapi.profiles.switch('production', profiles_file='/etc/nipyapi/profiles.yml')

# Environment variables can override any profile setting
# export NIFI_API_ENDPOINT=https://special.endpoint.com/nifi-api
# export NIFI_USERNAME=override_user
nipyapi.profiles.switch('single-user')  # Uses environment overrides

Manual Configuration:

# 1.x: Manual configuration still supported but more verbose
import nipyapi
from nipyapi import config, utils

# HTTPS is now the default with proper certificate management
config.nifi_config.ssl_ca_cert = "resources/certs/ca/ca.crt"

# Establish authenticated endpoint
utils.set_endpoint("https://localhost:9443/nifi-api", ssl=True, login=True,
                  username="einstein", password="password1234")

What profiles.yml handles for you:

  • Endpoints: NiFi and Registry URLs

  • Authentication: Username/password, certificates, OIDC tokens

  • SSL Configuration: CA certificates, SSL verification, hostname checking, warning suppression

  • Service Integration: NiFi → Registry proxy identity

  • Environment Flexibility: Development vs production settings with smart SSL defaults

Docker Environment and Testing

We now use the Makefile to start and stop the Docker environment, with integrated profiles support.

Integrated Docker + Profiles Workflow

# One-command environment setup
make certs && make up NIPYAPI_PROFILE=secure-ldap && make wait-ready NIPYAPI_PROFILE=secure-ldap

# Python code matches the environment
nipyapi.profiles.switch('secure-ldap')

# Testing with the same profile
make test NIPYAPI_PROFILE=secure-ldap

Old commands:

# 0.x approach
cd resources/docker/some_profile
docker-compose up -d

New commands:

# 1.x approach
make up NIPYAPI_PROFILE=secure-ldap
make wait-ready NIPYAPI_PROFILE=secure-ldap

Development vs Production Security

Development (Self-signed certificates):

# Quick setup for learning and testing
make certs
make up NIPYAPI_PROFILE=single-user
nipyapi.profiles.switch('single-user')

# SSL warnings are safely suppressed in development
nipyapi.config.disable_insecure_request_warnings = True

Production (Trusted certificates):

# Use trusted CA certificates
export TLS_CA_CERT_PATH=/etc/ssl/certs/ca-bundle.crt
export NIFI_API_ENDPOINT=https://nifi.company.com/nifi-api
export NIFI_USERNAME=service_account

# SSL verification is always enabled in production
nipyapi.profiles.switch('production')

API Changes

Removed: Templates

Old code (0.x):

import nipyapi.templates
templates = nipyapi.templates.list_all_templates()

Migration strategy:

# Templates are deprecated in NiFi 2.x
# Use Process Groups and Flow Registry instead:
import nipyapi.canvas
import nipyapi.versioning

# Create reusable flows in Registry
flow = nipyapi.versioning.save_flow_ver(process_group, registry_client, bucket)

Updated: Operation Names

Due to upstream NiFi 2.x API changes, many operation IDs now use suffixed names. You must update your code:

Old Method (0.x)

New Method (1.x)

Status

update_run_status

update_run_status1

Renamed - Action Required

FlowfileQueuesApi

FlowFileQueuesApi

Case change

Various processor operations

Many now have 1 suffix

Check your API calls

Important

Function Renaming: Upstream API specification changes result in operation IDs now using suffixed names. If you get AttributeError exceptions, check for renamed operations - many now have ‘1’ suffix.

Common Migration Pattern:

# Before (0.x)
api.update_run_status(processor_id, request_body)

# After (1.x) - Note the '1' suffix
api.update_run_status1(processor_id, request_body)

Updated: Controller Service Management

Old approach (0.x):

# 0.x pattern
nipyapi.canvas.schedule_controller_service(service_id, scheduled=True)

New approach (1.x):

# 1.x pattern - uses different underlying API endpoint
nipyapi.canvas.schedule_controller_service(service_id, scheduled=True)
# Implementation uses ControllerServicesApi.update_run_status1()

Note

Behavior of the new mthods may be the same, but you should test carefully.

Configuration Changes

SSL/TLS Configuration

NiPyAPI 1.x introduces smart SSL defaults and granular SSL controls:

Smart SSL Defaults (NEW in 1.x):

# SSL verification automatically enabled for HTTPS URLs
nifi_url: https://nifi.company.com/nifi-api     # verify_ssl=true (automatic)
registry_url: http://registry.company.com/      # verify_ssl=false (automatic)

Granular SSL Controls (NEW in 1.x):

# Development profile with self-signed certificates
nifi_verify_ssl: false             # Disable SSL verification (cert + hostname) for HTTPS
suppress_ssl_warnings: true        # Suppress urllib3 warnings for development

# Production profile with trusted certificates
nifi_verify_ssl: true              # Enable full SSL verification (default for HTTPS)
suppress_ssl_warnings: false       # Show all SSL warnings

Key SSL Behavior Changes from 0.x to 1.x:

1. SSL Parameter in set_endpoint()

Old behavior (0.x):

# ssl=True parameter enabled SSL verification with default system behavior
nipyapi.utils.set_endpoint("https://localhost:8443/nifi-api", ssl=True, login=True,
                          username="nobel", password="supersecret1!")
# SSL verification was system-dependent and not granularly controlled

New behavior (1.x):

# ssl=True still works, but now respects granular configuration
nipyapi.config.nifi_config.verify_ssl = True           # Explicit SSL verification control (cert + hostname)
nipyapi.utils.set_endpoint("https://localhost:9443/nifi-api", ssl=True, login=True,
                          username="einstein", password="password1234")

2. SSL Context Configuration

Old approach (0.x):

# NIFI_CA_CERT is no longer supported in 1.x
# Use direct configuration instead
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'

New approach (1.x) - Direct Configuration:

import nipyapi
# Direct configuration (no default_ssl_context needed)
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'
nipyapi.config.registry_config.ssl_ca_cert = '/path/to/ca.pem'  # Per-service control
nipyapi.config.nifi_config.verify_ssl = True                   # Full SSL verification (cert + hostname)

New approach (1.x) - Profiles (Recommended):

# Use profiles with smart defaults - handles all SSL complexity
nipyapi.profiles.switch('production')  # All SSL settings configured automatically

3. SSL Configuration Complexity Reduction

SSL configuration approach changes:

Aspect

0.x Approach

1.x Approach

SSL Configuration

Complex: global settings + env vars + manual config

Simple: profiles with smart defaults

Per-Service Control

Global global_ssl_verify affects both services

Independent nifi_verify_ssl / registry_verify_ssl

Hostname Checking

Global global_ssl_host_check setting

Integrated with nifi_verify_ssl / registry_verify_ssl (when false, hostname checking is disabled)

Certificate Management

Environment variables (NIFI_CA_CERT - REMOVED) + default_ssl_context

Profiles with shared/per-service certificates + smart resolution

Configuration Style

Manual: Set globals, env vars, then configure each service

Declarative: Define environment in profile, apply with one call

4. Enhanced SSL Controls (1.x)

0.x approach - Global settings affecting both services:

# 0.x: Global SSL settings affected both NiFi and Registry
nipyapi.config.global_ssl_verify = True            # Applied to both services
nipyapi.config.global_ssl_host_check = True        # Applied to both services
nipyapi.config.disable_insecure_request_warnings = False

# Direct certificate configuration (NIFI_CA_CERT no longer supported)
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'

1.x approach - Per-service granular control:

# 1.x: Fine-grained per-service SSL control in profiles
nifi_verify_ssl: true              # Independent NiFi SSL verification (cert + hostname)
registry_verify_ssl: false         # Independent Registry SSL control (no verification)
suppress_ssl_warnings: true        # Global warning suppression (cleaner than 0.x)

Complexity Comparison Example:

# 0.x: Complex multi-step configuration (10+ lines)
import os
import nipyapi

# Step 1: Set global SSL settings
nipyapi.config.global_ssl_verify = True
nipyapi.config.global_ssl_host_check = False  # But this affects BOTH services!
nipyapi.config.disable_insecure_request_warnings = True

# Step 2: Direct configuration (NIFI_CA_CERT no longer supported)
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'

# Step 4: Manually configure each service endpoint
nipyapi.utils.set_endpoint("https://localhost:8443/nifi-api", ssl=True, login=True)
# Registry SSL settings? More complex configuration needed...

# vs.

# 1.x: Simple declarative configuration (1 line)
nipyapi.profiles.switch('single-user')  # Everything configured automatically

Common SSL Migration Issues and Solutions:

Issue: “ssl=True doesn’t work like it used to”

In 0.x, ssl=True behavior was system-dependent. In 1.x, it respects explicit configuration:

# 1.x: Configure SSL explicitly before calling set_endpoint
nipyapi.config.nifi_config.verify_ssl = True
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'
nipyapi.utils.set_endpoint(url, ssl=True, login=True)

Issue: “Self-signed certificates cause hostname errors”

0.x had system-dependent hostname checking. 1.x provides granular control:

# For development with self-signed certificates
nipyapi.config.nifi_config.verify_ssl = False          # Accept self-signed certs (disables cert + hostname verification)

Issue: “Different SSL requirements for NiFi vs Registry”

0.x primarily supported NiFi. 1.x supports independent SSL configuration:

# 1.x: Independent SSL control per service
nipyapi.config.nifi_config.verify_ssl = True           # HTTPS with trusted certs
nipyapi.config.registry_config.verify_ssl = False      # HTTP or self-signed

Testing Profiles

Old commands:

pytest tests/

New commands:

make test NIPYAPI_PROFILE=secure-ldap
# or
NIPYAPI_PROFILE=secure-ldap pytest tests/

See the devnotes.rst guide for more details.

New Authentication Methods

NiPyAPI 1.x adds support for modern authentication:

OpenID Connect (OIDC):

# OAuth2 with external identity providers
nipyapi.profiles.switch('secure-oidc')
# Supports Keycloak, Okta, Azure AD, etc.

Enhanced mTLS:

# Certificate-based authentication
nipyapi.profiles.switch('secure-mtls')
# Simplified certificate management

Environment Variable Integration:

# Override any profile setting
export NIFI_API_ENDPOINT=https://production.company.com/nifi-api
export NIFI_USERNAME=production_user
export NIFI_DISABLE_HOST_CHECK=true         # Disable hostname verification
export NIPYAPI_SUPPRESS_SSL_WARNINGS=true   # Suppress SSL warnings
nipyapi.profiles.switch('single-user')  # Uses overrides

Migration Steps

1. Update Dependencies

Update your requirements.txt or pyproject.toml:

# Old
nipyapi>=0.22,<1.0

# New
nipyapi>=1.0,<2.0

2. Choose Your Profiles Strategy

Strategy A: Start with Built-in Profiles (Recommended)

Use the provided examples/profiles.yml for immediate compatibility:

# Test with development Docker environment
nipyapi.profiles.switch('single-user')

# Validate connection
version = nipyapi.system.get_nifi_version_info()
print(f"Connected to NiFi {version}")

Strategy B: Create Custom Profiles

Create your own profiles.yml for your environments:

# Copy the example as a starting point
cp examples/profiles.yml ~/.nipyapi/profiles.yml

# Edit for your environments
vim ~/.nipyapi/profiles.yml

Strategy C: Environment-Driven Configuration

Use profiles with environment variable overrides:

# Code stays the same across environments
nipyapi.profiles.switch('base-profile')

# Environment variables control the actual connection
# export NIFI_API_ENDPOINT=https://nifi.staging.com/nifi-api  # staging
# export NIFI_API_ENDPOINT=https://nifi.company.com/nifi-api  # production

3. Test Your Profile Configuration

Validate your profiles work before migrating production code:

import nipyapi

# Test profile loading
try:
    nipyapi.profiles.switch('your-profile-name')
    print("✓ Profile loaded successfully")
except Exception as e:
    print(f"✗ Profile error: {e}")

# Test connectivity
try:
    version = nipyapi.system.get_nifi_version_info()
    print(f"✓ Connected to NiFi {version}")
except Exception as e:
    print(f"✗ Connection error: {e}")

4. Update Your Application Code

Replace manual configuration with profile switching:

# Before (0.x) - Complex setup
import nipyapi
nipyapi.config.nifi_config.ssl_ca_cert = "/path/to/ca.pem"
nipyapi.utils.set_endpoint("https://nifi.com/nifi-api", ssl=True, login=True,
                          username="user", password="pass")
# ... 10+ more configuration lines ...

# After (1.x) - Simple profile switch
import nipyapi
nipyapi.profiles.switch('production')

# Your existing business logic stays the same
flows = nipyapi.canvas.list_all_process_groups()
about = nipyapi.system.get_nifi_version_info()

Fix renamed function calls:

# Before (0.x)
api.update_run_status(processor_id, request_body)

# After (1.x) - Note the '1' suffix
api.update_run_status1(processor_id, request_body)

5. Update Testing Environment

The 0.x testing used hardcoded boolean flags in conftest.py, not environment variables:

# 0.x approach (edit conftest.py)
# In tests/conftest.py:
test_default = True   # Test against default endpoints
test_ldap = False     # Enable LDAP testing
test_mtls = False     # Enable mTLS testing

# Then run tests directly
pytest tests/

The 1.x approach uses environment-driven profiles:

# 1.x approach (environment-driven)
make up NIPYAPI_PROFILE=secure-ldap
make wait-ready NIPYAPI_PROFILE=secure-ldap
make test NIPYAPI_PROFILE=secure-ldap

See the devnotes.rst guide for more details.

6. Remove Templates Usage

Replace template-based workflows with Process Groups and Registry:

# Before (0.x) - Templates
import nipyapi.templates
template = nipyapi.templates.upload_template('flow.xml')
nipyapi.templates.deploy_template(pg_id, template.id)

# After (1.x) - Registry Flows
import nipyapi.versioning
# Save flow to registry
flow_ver = nipyapi.versioning.save_flow_ver(pg, registry_client, bucket)
# Deploy to other environments
deployed_pg = nipyapi.versioning.deploy_flow_version(
    parent_pg_id, registry_client.id, bucket.identifier, flow_ver.flow.identifier
)

Note

An example of using NiFi Registry is provided in examples/fdlc.py

7. Update Configuration and Ports

Key configuration changes between NiPyAPI 0.x and 1.x:

Component

0.x (NiFi 1.x)

1.x (NiFi 2.x)

Default NiFi

http://localhost:8080/nifi-api

https://localhost:9443/nifi-api

Default Registry

http://localhost:18080/nifi-registry-api

http://localhost:18080/nifi-registry-api

Test Credentials

nobel/supersecret1! (default)

einstein/password1234 (single-user)

LDAP Credentials

nobel/password

einstein/password

Certificate Location

demo/keys/ (localhost-ts.pem)

resources/certs/ (ca.crt)

Docker Test Ports

Default: 8443, LDAP: 9443

Single: 9443, LDAP: 9444, mTLS: 9445

Common Migration Issues

Issue: SSL Certificate Errors

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

Solution: Ensure mounted and presented certificates are valid. Then configure CA certificate properly:

nipyapi.config.nifi_config.ssl_ca_cert = 'resources/certs/ca/ca.crt'

See the authentication.rst guide for more details.

Issue: Authentication Failures

Unauthorized: No valid authentication

Solution: Use proper authentication flow:

nipyapi.profiles.switch('production')

Issue: Operation Not Found

AttributeError: 'ProcessGroupsApi' object has no attribute 'update_run_status'

Solution: Check for renamed operations (many now have ‘1’ suffix):

# Old: update_run_status
# New: update_run_status1

Important

Function Renaming: This is the most common migration issue. Upstream API specification changes result in operation IDs now using suffixed names. If you get AttributeError exceptions, check for renamed operations.

Systematic approach to find renamed functions:

# Use dir() to find available methods
import nipyapi
api = nipyapi.nifi.ProcessGroupsApi()
methods = [m for m in dir(api) if 'update' in m.lower()]
print(methods)  # Will show: ['update_run_status1', ...]

# Or check the API documentation
help(api.update_run_status1)

Issue: Authorization Failures After Authentication

No applicable policies could be found
Forbidden: Access is denied due to insufficient permissions

Note: NiFi 2.x is more strict by default about Authentication and Authorization.

Solution: Bootstrap security policies for secure profiles:

# For NiFi operations
nipyapi.security.bootstrap_security_policies(service='nifi')

# For Registry operations (with proxy identity)
nipyapi.security.bootstrap_security_policies(
    service='registry',
    nifi_proxy_identity='C=US, O=NiPyAPI, CN=nifi'
)

Note

You can find examples of using the boostrap functions in examples/sandbox.py

Issue: Registry Proxy Identity Not Authorized

Untrusted proxy
Unable to list buckets: access denied

Solution: Ensure Registry proxy configuration is set up:

# Registry must trust NiFi as a proxy
nipyapi.security.bootstrap_security_policies(
    service='registry',
    nifi_proxy_identity='C=US, O=NiPyAPI, CN=nifi'
)

The proxy identity must match the NiFi certificate subject DN when using secure profiles.

Important

Reversing the DN will not work, as it’s an exact match.

Issue: OIDC Authentication Setup

No applicable policies could be found
Untrusted proxy identity

Solution: OIDC requires one-time manual setup due to NiFi’s security architecture:

# 1. Use sandbox to discover your OIDC application UUID
make sandbox NIPYAPI_PROFILE=secure-oidc

# 2. Follow the printed instructions to create the user and assign policies in NiFi UI
# 3. Re-run sandbox to complete bootstrap
make sandbox NIPYAPI_PROFILE=secure-oidc

See the security.rst guide for detailed OIDC setup instructions, or follow the sandbox.

Quick Migration Checklist

☐ Update dependencies: nipyapi>=1.0,<2.0

☐ Choose migration approach:

  • ✅ Recommended: Use profiles (nipyapi.profiles.switch('single-user'))

  • Manual: Direct programmatic configuration (more control)

☐ Test with Docker environment:

  • make certs && make up NIPYAPI_PROFILE=single-user for development

  • make test NIPYAPI_PROFILE=single-user to validate

☐ Handle breaking changes:

  • Replace update_run_status with update_run_status1 (check all API calls)

  • Remove templates usage → use Registry flows

  • Remove variable registry usage → use Parameters

  • Replace invalid Processors/Controller Services → use replacement components

  • Update certificate paths (demo/keys/ → resources/certs/)

  • Update default ports (8080 → 9443 for NiFi, credentials: nobel → einstein)

☐ Migrate SSL configuration:

  • Replace nipyapi.config.default_ssl_context pattern with profile configuration

  • Update ssl=True usage to explicitly configure verify_ssl per service

  • Replace NIFI_CA_CERT environment variables (REMOVED) with NIFI_CA_CERT_PATH (profiles), TLS_CA_CERT_PATH (shared), REQUESTS_CA_BUNDLE (standard), or direct config

  • For self-signed certificates, set verify_ssl: false (disables both cert and hostname verification)

  • Configure per-service SSL settings for NiFi and Registry independently

  • Use profiles for centralized SSL management (recommended)

☐ Production deployment:

  • Set environment variables or Profiles for credentials/endpoints

  • Use trusted certificates (not self-signed)

  • Enable SSL verification (default in production profiles)

Testing Your Migration

  1. Start Simple: Begin with single-user profile testing

  2. Incremental Migration: Migrate one authentication mode at a time

  3. Integration Testing: Use make test NIPYAPI_PROFILE=single-user for comprehensive validation

  4. Docker Environment: Test with provided Docker profiles before production

For additional support:

  • Examples: See examples/fdlc.py for modern patterns

  • Sandbox: Use make sandbox NIPYAPI_PROFILE=single-user for experimentation

  • Documentation: Updated profiles guide at docs/profiles.rst and security guide at docs/security.rst

  • Issues: Please raise an issue on GitHub if you encounter any problems.