cloudshell-user-sync

A CLI tool to Sync LDAP / Active Directory Groups with Cloudshell groups. This package will pull LDAP data, compare state of cloudshell group, and add/remove users to sync the groups.

Sync job can be run as scheduled cron job, windows task, or wrapped into linux / windows service.

Important Notes

• This package does NOT import/create users from LDAP - only syncs already imported users across groups.
  • Users are NOT deleted from system during sync - only add/remove to group action performed.
  • Users must be first manually imported or auto-imported on login to a default group.
• Non-imported cloudshell users will NOT be evicted from a synced group.
  • This tool only aims to manage the imported ldap users.
  • Groups can be hybrid with "regular" users.
• This tool can be configured to manage only a subset of cloudshell groups.
• If possible, to improve performance of LDAP search, place target ldap users together under common root in LDAP Tree.
  • This will allow to set a lower base root Distinguished Name to allow quicker ldap searches.
  • Note that LDAP groups and users are not necessarily in same location of ldap tree. The Base DN must be where the users are not the groups.

Installation

Install with pip or download from Github releases

pip install cloudshell-user-sync

Commands

Commands:
  config        View or Set Config - Pass no params to view config
  credential    Set Credentials For Cloudshell and LDAP
  mapping       Set LDAP group --> Cloudshell Groups Mapping
  run           Pull LDAP Data and sync to Cloudshell
  runscheduler  Run sync on infinite scheduler
  version       Display CLI version

Basic Usage

1. Configure venv and install package
2. configure credentials (stored in OS specific credential manager)
3. set config values for target cloudshell server
4. Set config values for target LDAP server
5. set LDAP -> Cloudshell Group Mappings
6. Do manual sync run to test
7. Configure scheduled task to run automatically

Configure Credentials

Set Cloudshell Credential

usersync credential admin admin --target cloudshell

Set LDAP Credential

usersync credential CN=Administrator,CN=Users,DC=samplecorp,DC=example,DC=com LDAP_DN_Password --target ldap

• LDAP User is the full Distinguished Name
• To find DN can use AD Explorer or LDAP Explorer

Set Config Values

Credentials must be set through CLI to be stored in credential manager. The other values can be set directly in file or optionally in CLI

Default Config Path:

• Windows: C:\ProgramData\QualiSystems\CloudshellUserSync\ldap_config.json
• Linux: /opt/CloudshellUserSync/ldap_config.json

View current config state by running usersync config:

{
  "service_config": {
    "job_frequency_seconds": 30,
    "log_level": "DEBUG"
  },
  "cloudshell_details": {
    "user": "admin",
    "password": "************",
    "server": "192.168.85.114",
    "domain": "Global"
  },
  "ldap_details": {
    "user_dn": "CN=Administrator,CN=Users,DC=testcorp,DC=example,DC=com",
    "password": "************",
    "server": "192.168.85.115",
    "base_dn": "DC=testcorp,DC=example,DC=com"
  },
  "ldap_mappings": [
    {
      "ldap_dn": "CN=testgroup,DC=testcorp,DC=example,DC=com",
      "cloudshell_groups": [
        "QA"
      ]
    }
  ]
}

CLI Set config actions follows the pattern:

usersync config <target> <key> <value>

Set cloudshell server details:

usersync config cloudshell server localhost

Set LDAP details:

usersync config ldap server 10.0.0.7
usersync config ldap base_dn DC=samplecorp,DC=example,DC=com

• base_dn is where the ldap search will start from
• Filter scheme used is: (&(objectClass=user)(memberOf=<GROUP_DN>))

Set LDAP mappings

Can map one LDAP source group to multiple cloudshell groups (ie a list)

View only mapping config:

usersync mapping

Set mapping follows pattern:

usersync mapping <LDAP_GROUP_DN> --csgroups <CSGROUP1>,<CSGROUP2>,<CSGROUP3>

sample:

usersync mapping CN=nattigroup,DC=natticorp,DC=example,DC=com --csgroups <CSGROUP1>,<CSGROUP2>,<CSGROUP3>

Configure Scheduled Task

To set command to run automatically with OS level scheduler.

• Get path to "usersync.exe" executable installed in venv and schedule the run command
• Set logon for task with same user that set credentials with usersync credential command

path-to-usersync.exe run

Windows Scheduled Task

Configure Task Scheduler according to article

Linux Cron Job

Configure according to article

Service creation

Run scheduler uses the schedule module to run job infinitely at configured frequency.

• Set the job frequency seconds in config
• set credentials via cli usersync credential
• configure the runscheduler command into nssm or systemd
• Set service logon as same user that configured the credentials (requirement for keyring module to work properly)
• Alternatively, for windows, see the python util install script option
• usersync.exe will be installed inside python/Scripts of python environment

Runscheduler command (give full path to exe)

usersync.exe runscheduler

Logs

Both manual runs and scheduled runs log to the same rotating log file.

• Windows: C:\ProgramData\QualiSystems\CloudshellUserSync\Logs\UserSync.log
• Linux: /opt/CloudshellUserSync/Logs/UserSync.log

Dependencies

• cloudshell-automation-api to update cloudshell groups
• LDAP3 for pulling source LDAP/AD data
• Schedule as cross-platform cron-like scheduler
• Keyring to store credentials in OS
• Dacite for json to dataclass conversion
• Pywin32 - windows service installer util script

License

Free Software: MIT License