Target audience: Filespace administrators
This article is part of the LucidLink Single Sign-On (SSO): "Just-in-Time" Provisioning for Users and Groups series of articles.
Overview
LucidLink's single sign-on (SSO) mechanism authenticates users using their organization's existing identity provider (currently Okta or Azure AD).
We have redesigned our SSO implementation to address some deficiencies in our legacy SSO implementation, making it easier to set up for small and large organizations alike.
This new version of SSO supports all existing LucidLink 2.0 Filespaces.
The purpose of this article is to guide you through the process of capturing your configuration for import after you've upgraded.
"Just-in-Time" SSO Filespaces, users and their groups are only created within the Filespace configuration as users log in, we can however pre-create the users and assign their Admin roles, create your groups to assign the permissions in advance.
Upgrade Requirements
All LucidLink users and administrators will require the LucidLink version 2.1 client or later installed to use the new SSO implementation.
Your Legacy SSO integration will need to be removed. Removing an integration, removes all SSO users, groups and their permission assignments.
You will need to implement and distribute your Filespace key to your users. Your Filespace key will be available once you complete the integration. You will need to plan ahead and coordinate distribution in order to minimise downtime.
It is recommended you use your root password, or a non-SSO admin user. Do not use an SSO admin user will lose administrative access when you remove your Legacy SSO integration.
You can create a new Filespace and migrate your Legacy SSO to a "Just-in-Time" utilizing the backup importation scripts, simply skip Step 3 and connect to your alternate Filespace.
You will need to duplicate your folder structure to import your permissions. Consult Step 2 in this article on backing up and duplicating your directory structure.
Compatibility
- All existing LucidLink 2.0 Filespaces
- All major operating systems (macOS, Windows, Linux)
Upgrade process
Step 1. Capture your users, groups and permissions configuration by exporting your configuration.
The backups will be the basis for our import scripts and provide security that your configuration can be recreated in the unlikely event of an import issue.
Connect to your Filespace as root or admin user. You will be required to backup your users, groups and permissions via the command-line.
lucid user --password <password> > sso_users_backup.txt
lucid group --password <password> > sso_groups_backup.txt
lucid permission --configured --password <password> > sso_permissions_backup.txt
Please note, as of Filespace format 2.2 the legacy term “Shares” has been changed to “Permissions.” The scripts will detect your Filespace format automatically.lucid share --configured --password <password> > sso_shares_backup.txt
Continue with the remaining steps determined by your operating environment, Linux, macOS and Windows sections below.
Linux and macOS (Bash)
Step 2. Download sso_users_script.sh, sso_groups_script.sh, sso_permissions_script.sh and make each script executable.
curl -O https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_users_script.sh
curl -O https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_groups_script.sh
curl -O https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_permissions_script.sh
chmod u+x *_script.sh
Step 3. Remove your Legacy SSO integration and implement Just-in-Time SSO following the KB appropriate to your integration.
Open the control panel, navigate to SSO, select the three-dot vertical menu in the top right-hand corner and choose remove integration. You will be prompted, to proceed press remove.
It is recommended you create a new application integration within your single sign-on provider vs. amend an existing.
Step 4. Once you've successfully configured your Just-in-Time SSO integration, you can now begin the importation process.
Lists users from backup, imports users and assigns user roles.
./sso_users_script.sh <password>
Step 5. List groups and import.
./sso_groups_script.sh <password>
Step 6. Allocate listed permissions for users and groups.
./sso_permissions_script.sh <password>
Step 7. Check Filespace users, groups and permissions
lucid user --password <password>
lucid group --password <password>
lucid permission --configured --password <password>
Step 8. Clean up temporary files, scripts, optionally the bash history and backups after taking special consideration ensure your users, groups and permission allocations are correct.
Consult these output files to identify any allocations which might not have been assigned correctly due to edge cases.
rm sso_users_import.txt sso_users_commands.txt sso_users_output.txt sso_users_roles_import.txt sso_users_roles_commands.txt sso_users_roles_output.txt sso_groups_import.txt sso_groups_commands.txt sso_groups_output.txt sso_permissions_import.txt sso_permissions_commands.txt sso_permissions_output.txt
rm sso_users_script.sh sso_groups_script.sh sso_permissions_script.sh
rm sso_users_backup.txt sso_groups_backup.txt sso_permissions_backup.txt
Remove Bash shell history
for i in $(history | grep 'lucid' | awk '{print$1}' | sort -nr); do history -d $i;done
for i in $(history | grep '_script.sh' | awk '{print$1}' | sort -nr); do history -d $i;done
sed -i -e '/lucid/d' ~/.bash_history
sed -i -e '/_script.sh/d' ~/.bash_history
Windows (PowerShell)
Step 2. Download sso_users_script.ps1, sso_groups_script.ps1, sso_permissions_script.ps1
Invoke-WebRequest https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_users_script.ps1 -OutFile sso_users_script.ps1
Invoke-WebRequest https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_groups_script.ps1 -OutFile sso_groups_script.ps1
Invoke-WebRequest https://lucidlink-support.s3.amazonaws.com/scripts/SSO/sso_permissions_script.ps1 -OutFile sso_permissions_script.ps1
Step 3. Remove your Legacy SSO integration and implement Just-in-Time SSO following the KB appropriate to your integration.
Open the control panel, navigate to SSO, select the three-dot vertical menu in the top right-hand corner and choose remove integration. You will be prompted, to proceed press remove.
It is recommended you create a new application integration within your single sign-on provider vs. amend an existing.
Step 4. Once you've successfully configured your Just-in-Time SSO integration, you can now begin the importation process.
Lists users from backup, imports users and assigns user roles.
.\sso_users_script.ps1 <password>
Step 5. List groups and import.
.\sso_groups_script.ps1 <password>
Step 6. Allocate listed permissions for users and groups.
.\sso_permissions_script.ps1 <password>
Step 7. Check Filespace users, groups and permissions
lucid user --password <password>
lucid group --password <password>
lucid permission --configured --password <password>
Step 8. Clean up temporary files, scripts, optionally your command history and backups after taking special consideration ensure your users, groups and permission allocations are correct.
Consult these output files to identify any allocations which might not have been assigned correctly due to edge cases.
remove-item sso_user_output.txt,sso_user_error_output.txt,sso_user_log.txt,sso_user_role_output.txt,sso_user_role_error_output.txt,sso_user_role_log.txt,sso_group_output.txt,sso_group_error_output.txt,sso_group_log.txt,sso_permissions_output.txt,sso_permissions_error_output.txt,sso_permissions_log.txt
remove-item sso_users_script.ps1,sso_groups_script.ps1,sso_permissions_script.ps1
remove-item sso_users_backup.txt,sso_groups_backup.txt,sso_permissions_backup.txt
Remove PowerShell command-line shell history
clear-history -CommandLine *lucid*
clear-history -CommandLine *_script.ps1*
$HistorySavePath = (Get-PSReadlineOption).HistorySavePath; (Get-Content "$HistorySavePath") -notmatch "lucid" | Out-File "$HistorySavePath"
$HistorySavePath = (Get-PSReadlineOption).HistorySavePath; (Get-Content "$HistorySavePath") -notmatch "_script.ps1" | Out-File "$HistorySavePath"
Edge cases might be caused by special characters and/or unusual spacings within your permissions. These will hopefully be an anomaly in your configuration and can be simply recreated manually.
Alternatively adjust the default script regular expressions to account for your configuration. Please do not hesitate to reach out to support via a ticket.