Home

OneLogin Migration Wizard

A production-ready Python toolkit for migrating identity data from a source identity provider into OneLogin, with a powerful CLI and an interactive GUI wizard.

Key capabilities

• Multi-provider: Pluggable source provider architecture — Okta supported out of the box, straightforward to extend to Azure AD, Google Workspace, and others
• Multi-interface: CLI for automation and scripting, step-by-step GUI wizard with analysis tools
• Secure credential storage: System keyring integration — credentials never stored in files
• Safe by default: Dry-run mode, field validation, resumable migrations with state persistence
• Concurrent processing: Thread-safe with automatic rate limiting and exponential backoff
• Flexible data export: JSON snapshots or OneLogin bulk CSV format
• Smart field mapping: Automatic custom attribute discovery, normalization, and provisioning
• Application catalog: Database-driven OneLogin connector matching with confidence scoring
• Analysis & reporting: Pre-migration environment analysis exportable to CSV/XLSX

Getting started

Prerequisites

• Python 3.10–3.13
• Git

Verify your Python version:

python3 --version

Installation

1. Clone the repository:

   git clone <repository-url>
   cd onelogin-migration-wizard

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate    # macOS/Linux
   .venv\Scripts\activate       # Windows

3. Install all packages:

   ./scripts/dev-install.sh

4. Verify:

   python -m onelogin_migration_cli.app --help

   If you see ModuleNotFoundError, set PYTHONPATH manually:

   export PYTHONPATH=packages/cli/src:packages/core/src

First run

# 1. Store credentials securely in the system keyring (done once per environment)
python -m onelogin_migration_cli.app credentials set source token
python -m onelogin_migration_cli.app credentials set onelogin client_secret

# 2. Create your config from the template and fill in non-secret settings
cp config/migration.template.yaml config/migration.yaml
#    Set: source.provider, source.domain, onelogin.subdomain, onelogin.region, etc.
#    Leave token/client_secret blank — they are injected from the keyring at runtime.

# 3. Test read-only export from your source provider
python -m onelogin_migration_cli.app plan --config config/migration.yaml

# 4. Run migration in dry-run mode (safe default)
python -m onelogin_migration_cli.app migrate --config config/migration.yaml

Or launch the GUI wizard (no config file needed — credentials entered in the UI):

python -m onelogin_migration_gui.main

Available commands

plan                  Export from source provider (read-only)
migrate               Execute full migration workflow
provision-attributes  Pre-create custom attributes in OneLogin
show-config           Display sanitized configuration for troubleshooting
credentials           Manage secure credentials (keyring/vault)
db                    Manage the application connector database
telemetry             View migration analytics and statistics

What's in this wiki

• Architecture — System design, module overview, and how to add a new source provider
• Configuration — YAML settings, credential management, and security best practices
• Command-Line — CLI reference and usage examples
• GUI — Interactive wizard walkthrough
• Development — Local setup, testing, and contributing

Continue through the wiki pages for comprehensive guides on using and extending the toolkit.