Skip to content

Configuration

Jump to bottom
Jeffrie Budde edited this page Apr 10, 2026 · 1 revision

Configuration

The toolkit supports two configuration approaches:

  1. Secure storage (v0.2.0+, recommended) - Credentials in system keyring, settings in JSON
  2. Legacy YAML - All settings in YAML files (backward compatible)

This page explains all available configuration options for both approaches.

Configuration approaches

Secure storage (v0.2.0+, recommended)

Credentials: Stored in system keyring (encrypted by OS)

  • macOS: Keychain Access.app
  • Windows: Windows Credential Manager
  • Linux: Secret Service (GNOME Keyring, KWallet)

Settings: ~/.onelogin-migration/settings.json

  • Non-sensitive configuration only
  • Safe to backup and share
  • Auto-created on first run

Migration from YAML:

onelogin-migration-tool credentials migrate config/migration.yaml

Legacy YAML configuration

  • Your config: config/migration.yaml - Create from template
  • Template: config/migration.template.yaml - Provided with project
  • Note: Contains plaintext credentials (migrate to secure storage recommended)

Complete example

# Migration behavior
dry_run: true
chunk_size: 200
export_directory: artifacts
concurrency_enabled: false
max_workers: 4
bulk_user_upload: false

# Source provider
source:
  provider: okta                  # Current options: okta (more providers: see Architecture wiki)
  domain: company.okta.com        # Provider domain (e.g. company.okta.com for Okta)
  token: YOUR_SOURCE_API_TOKEN    # API token — store in keyring, not here
  rate_limit_per_minute: 600
  page_size: 200

# OneLogin target
onelogin:
  client_id: YOUR_ONELOGIN_CLIENT_ID
  client_secret: YOUR_ONELOGIN_CLIENT_SECRET
  region: us
  subdomain: company
  rate_limit_per_hour: 5000

# Categories to migrate
categories:
  users: true
  groups: true
  applications: true
  policies: false

# Application connector mappings
metadata:
  application_connectors:
    "slack":
      "saml": 123456
    "github":
      "openid": 789012

Source settings

The source: section configures the identity provider you are migrating from. The provider field selects which implementation is used; okta is supported out of the box. See the Architecture wiki page for how to add a new provider.

Required fields

Field Description Example
provider Source provider identifier okta
domain Source provider domain (without https://) company.okta.com
token Admin/API token for the source provider For Okta: Security → API → Tokens

Optional fields

Field Default Description
rate_limit_per_minute 600 API rate limit (adjust based on your Okta tier)
page_size 200 Items per page for pagination

Getting your source provider token (Okta):

  1. Log into Okta Admin Console
  2. Navigate to Security → API → Tokens
  3. Create token with admin privileges
  4. Store securely: onelogin-migration credentials set source token (never put it in the YAML)

Legacy config key: Earlier versions used okta: instead of source:. The okta: key still works but is deprecated and will emit a warning. Rename it to source: to silence the warning.

OneLogin settings

Required fields

Field Description Example
client_id OAuth client ID Generate in: Developers → API Credentials
client_secret OAuth client secret (same location as client_id)
region API region us or eu

Optional fields

Field Default Description
subdomain "" Your OneLogin subdomain (e.g., company for company.onelogin.com)
rate_limit_per_hour 5000 API rate limit per hour

Getting OneLogin credentials:

  1. Log into OneLogin Admin portal
  2. Navigate to Developers → API Credentials
  3. Create new credentials with these permissions:
    • Manage users
    • Manage roles
    • Manage apps
    • Manage custom attributes
  4. Copy client_id and client_secret

Region selection:

  • us - API endpoint: https://api.us.onelogin.com
  • eu - API endpoint: https://api.eu.onelogin.com

Migration options

Field Default Description
dry_run true When true, simulates migration without writing to OneLogin
chunk_size 200 Batch size for processing operations
export_directory artifacts Where to save exports and state files
concurrency_enabled false Enable multi-threaded processing
max_workers Auto-calculated Worker threads (leave unset for automatic calculation)
bulk_user_upload false Generate CSV instead of API calls for users
pass_app_parameters true Extract and pass SAML/OIDC parameters to OneLogin during app migration

Safety controls

dry_run mode:

  • Enabled by default for safety
  • Runs full migration logic without writes
  • Validates all data and transformations
  • Safe to run against production OneLogin

State persistence:

  • Saves progress to migration_state.json
  • Enables resume after interruption
  • Stores source → OneLogin ID mappings
  • Auto-cleaned on successful completion

Performance tuning

Worker calculation: When max_workers is omitted, the toolkit calculates optimal concurrency:

source_limit   = rate_limit_per_minute / 150
onelogin_limit = (rate_limit_per_hour / 60) / 30
recommended    = min(source_limit, onelogin_limit, 16)

Concurrency recommendations:

  • Small migrations (<1000 users): Leave concurrency_enabled: false
  • Large migrations (>1000 users): Enable with concurrency_enabled: true
  • Let max_workers auto-calculate for best results
  • Override only if you have specific rate limits

Bulk upload mode:

  • Generates OneLogin CSV format instead of API calls
  • Requires manual upload to OneLogin Admin Console
  • Custom attributes still provisioned via API
  • Useful when API access is restricted

Categories

Control which objects to migrate:

categories:
  users: true        # Migrate user accounts
  groups: true       # Migrate groups as OneLogin roles
  applications: true # Migrate SAML/OIDC apps
  policies: false    # Policies not yet supported

Default behavior: Migrates users, groups, and applications (not policies).

Metadata

Application connectors

Maps source application names to OneLogin connector IDs. Labels are matched case-insensitively — the manager also searches the connector database automatically, so only add entries here when automatic matching fails or you want to override the result:

metadata:
  application_connectors:
    "Slack":
      "saml": 123456    # OneLogin connector ID for Slack SAML
    "GitHub":
      "openid": 789012  # OneLogin connector ID for GitHub OIDC

Finding connector IDs:

  1. Create the app manually in OneLogin once
  2. Inspect the app configuration URL or API response
  3. Note the connector ID
  4. Add mapping to config for automated creation

Protocol types:

  • saml - SAML 2.0 applications
  • openid - OpenID Connect / OAuth applications
  • wsfed - WS-Federation applications

Validation

GUI validation: The GUI wizard validates:

  • Required fields are populated
  • Credentials format is correct
  • Placeholders like YOUR_* are replaced
  • Region is us or eu
  • Paths and directories are valid

CLI validation: Use show-config to verify parsed configuration:

onelogin-migration-tool show-config --config config/migration.yaml

Output: JSON with secrets redacted (safe to share for troubleshooting).

Environment-specific configs

Development:

dry_run: true
concurrency_enabled: false
export_directory: ./test-artifacts

Production:

dry_run: false
concurrency_enabled: true
# Let max_workers auto-calculate
export_directory: /var/log/migrations

Testing:

dry_run: true
bulk_user_upload: true  # Generate CSV for review
categories:
  users: true
  groups: false
  applications: false

Secure credential management (v0.2.0+)

Storing credentials

Interactive storage:

# Source provider credentials (service name matches provider key in config)
onelogin-migration credentials set source token
onelogin-migration credentials set source domain --value "company.okta.com"

# OneLogin credentials
onelogin-migration credentials set onelogin client_id --value "abc123"
onelogin-migration credentials set onelogin client_secret
onelogin-migration credentials set onelogin region --value "us"

List stored credentials:

onelogin-migration-tool credentials list

Test authentication:

onelogin-migration credentials test source
onelogin-migration credentials test onelogin

Where credentials are stored

Platform Storage Location
macOS Keychain Access → login keychain
Windows Credential Manager → Windows Credentials
Linux Secret Service (GNOME Keyring, KWallet, etc.)

Security benefits:

  • OS-level encryption
  • Requires authentication to access
  • Never written to files
  • Automatic backup with system
  • Audit logging available

Advanced credential backends

Encrypted vault (portable, password-protected):

onelogin-migration-tool credentials set okta token \
  --backend vault --vault-password "strongpassword"

Memory-only (testing, non-persistent):

onelogin-migration-tool credentials set okta token \
  --backend memory --value "test-token"

Audit logging

View credential access history:

onelogin-migration-tool credentials audit --limit 20

Audit log location: ~/.onelogin-migration/audit.log

Security best practices

v0.2.0+ (secure storage):

  1. ✅ Use system keyring (default) - OS-managed encryption
  2. ✅ Enable audit logging for compliance
  3. ✅ Test credentials before migration: credentials test
  4. ✅ Rotate API tokens regularly using credentials set
  5. ✅ Delete old YAML files after migration
  6. ✅ Backup ~/.onelogin-migration/settings.json (safe, no secrets)
  7. ❌ Never use memory backend in production

Legacy YAML (pre-v0.2.0):

  1. Migrate to secure storage: credentials migrate config/migration.yaml
  2. Never commit YAML files with real credentials
  3. Use environment variables for CI/CD pipelines
  4. Restrict file permissions: chmod 600 config/migration.yaml
  5. Review .gitignore - ensure config files are excluded

Clone this wiki locally