Guide de script : Automatisation de la création d’URL ConnectWise pour macOS

Points à retenir

• Le script automatise la récupération et le stockage des URL ConnectWise de lancement de ConnectWise Control sur macOS, ce qui simplifie considérablement l’assistance à distance.
• Il offre des options de personnalisation pour les identifiants d’instance, les domaines, les groupes de sessions et les champs personnalisés, s’adaptant ainsi à des environnements informatiques particuliers.
• L’inclusion d’une fonction d’aide et la gestion des erreurs améliorent l’orientation de l’utilisateur et le dépannage.
• L’approche du script est plus efficace et mieux organisée que la gestion manuelle des URL ou les solutions de script de base.
• La sécurité et le contrôle de l’accès aux URL générés sont essentiels au maintien de la sécurité informatique.
• Il est recommandé de tester le script dans un environnement macOS spécifique avant de le déployer complètement.
• L’intégration de ce script avec des outils comme NinjaOne permet d’optimiser davantage les tâches d’assistance à distance et de gestion informatique.

Contexte

Dans le monde informatique interconnecté, l’efficacité et la fiabilité de l’assistance à distance ne sont pas seulement des commodités, mais des nécessités. Les scripts avancés, en particulier dans le contexte de la gestion des logiciels d’assistance à distance, jouent un rôle central dans la réalisation de ces objectifs. Le script que nous présentons ici en est un exemple, car il fournit une approche simplifiée de la gestion des sessions ConnectWise Control (anciennement ScreenConnect) sur macOS.

Ce script Bash est conçu pour les professionnels de l’informatique et les fournisseurs de services gérés (MSP) qui utilisent ConnectWise Control pour l’assistance à distance. Sa fonction principale est de récupérer et d’enregistrer les URL de lancement du contrôle ConnectWise, un élément crucial de l’assistance à distance. Ce processus implique l’utilisation d’identifiants d’instance, d’informations de domaine et de groupes de sessions pour créer des URL précises et accessibles. Il permet l’automatisation d’une tâche généralement manuelle et chronophage, ce qui permet d’améliorer la productivité et les temps de réponse des équipes d’assistance informatique.

Le script :

#!/usr/bin/env bash
#
# Description: Retrieves the Connectwise ScreenConnect Launch URL and saves it to a custom field (defaults to screenconnectURL). Requires the domain used for ScreenConnect and a Session Group that all machines are a part of to successfully build the URL.
# By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
# Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
# Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
# Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
# Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
# Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
# Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
# EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#
# Preset Parameter: --instanceId "ReplaceMeWithYourInstanceId"
#   The Instance ID for your instance of ScreenConnect. Used to differentiate between multiple installed ScreenConnect instances.
#   To get the instance ID, you can see it in the program name, e.g., connectwisecontrol-yourinstanceidhere.
#   It's also available in the ScreenConnect Admin Center (Administration > Advanced > Server Information).
#
# Preset Parameter: --screenconnectDomain "replace.me"
#   The domain used for your ScreenConnect instance.
#
# Preset Parameter: --sessionGroup "ReplaceMe"
#   A session group that contains all of your machines (defaults to All Machines)
#
# Preset Parameter: --customField "ReplaceMeWithAnyMultilineCustomField"
#   The custom field you would like to store this information in.
#
# Preset Parameter: --help
#   Displays some help text.

# These are all our preset parameter defaults. You can set these = to something if you would prefer the script defaults to a certain parameter value.
_arg_instanceId=
_arg_screenconnectdomain=
_arg_sessiongroup="All Machines"
_arg_customfield="screenconnectURL"
_fieldValue=

# Help text function for when invalid input is encountered
print_help() {
  printf '\n\n%s\n\n' 'Usage: [--instanceId|-i <arg>] [--screenconnectDomain|-d <arg>] [--sessionGroup|-g <arg>] [--customField|-c <arg>] [--help|-h]'
  printf '%s\n' 'Preset Parameter: --instanceid "ReplaceWithYourInstanceID"'
  printf '\t%s\n' "Replace the text encased in quotes with your instance ID. You can see the instance ID in the ScreenConnect Admin Center (Administration > Advanced > Server Information). It's also usually present in the application name on any installed instance, e.g., connectwisecontrol-yourinstanceid."
  printf '\n%s\n' 'Preset Parameter: --screenconnectDomain "replace.me"'
  printf '\t%s' "Replace the text encased in quotes with the domain used for ConnectWise ScreenConnect, e.g., 'example.screenconnect.com'."
  printf '\n%s\n' 'Preset Parameter: --sessionGroup "Replace Me"'
  printf '\t%s' "Replace the text encased in quotes with the name of a Session Group in ConnectWise ScreenConnect that contains All Machines (defaults to All Machines). ex. 'All Machines'"
  printf '\n%s\n' 'Preset Parameter: --customField "replaceMe"'
  printf '\t%s' "Replace the text encased in quotes with the name of a custom field you'd like to store this information to (defaults to launchUrl). ex. 'screenconnectUrl'"
  printf '\n%s\n' 'Preset Parameter: --help'
  printf '\t%s\n' "Displays this help menu."
}

# Determines whether or not help text is necessary and routes the output to stderr
die() {
  local _ret="${2:-1}"
  echo "$1" >&2
  test "${_PRINT_HELP:-no}" = yes && print_help >&2
  exit "${_ret}"
}

# Grabbing the parameters and parsing through them.
parse_commandline() {
  while test $# -gt 0; do
    _key="$1"
    case "$_key" in
    --screenconnectdomain | --screenconnectDomain | --domain | -d)
      test $# -lt 2 && die "Missing value for the optional argument '$_key'." 1
      _arg_screenconnectdomain=$2
      shift
      ;;
    --screenconnectdomain=*)
      _arg_screenconnectdomain="${_key##--screenconnectdomain=}"
      ;;
    --instanceId | --instanceid | -i)
      test $# -lt 2 && die "Missing value for the optional argument '$_key'." 1
      _arg_instanceId=$2
      shift
      ;;
    --instanceid=*)
      _arg_instanceId="${_key##--instanceid=}"
      ;;
    --sessionGroup | --sessiongroup | -g)
      test $# -lt 2 && die "Missing value for the optional argument '$_key'." 1
      _arg_sessiongroup=$2
      shift
      ;;
    --sessiongroup=*)
      _arg_sessiongroup="${_key##--sessiongroup=}"
      ;;
    --customField | --customfield | -c)
      test $# -lt 2 && die "Missing value for the optional argument '$_key'." 1
      _arg_customfield=$2
      shift
      ;;
    --customfield=*)
      _arg_customfield="${_key##--customfield=}"
      ;;
    --help | -h)
      _PRINT_HELP=yes die 0
      ;;
    *)
      _PRINT_HELP=yes die "FATAL ERROR: Got an unexpected argument '$1'" 1
      ;;
    esac
    shift
  done
}

# Function to set a custom field
setCustomField() {
  echo "$_fieldValue" | /Applications/NinjaRMMAgent/programdata/ninjarmm-cli set --stdin "$_arg_customfield"
}

export PATH=$PATH:/usr/sbin:/usr/bin

parse_commandline "$@"

# If script form is used override commandline agruments
if [[ -n $screenconnectDomain ]]; then
  _arg_screenconnectdomain="$screenconnectDomain"
fi

if [[ -n $sessionGroup ]]; then
  _arg_sessiongroup="$sessionGroup"
fi

if [[ -n $instanceId ]]; then
  _arg_instanceId="$instanceId"
fi

if [[ -n $customFieldName ]]; then
  _arg_customfield="$customFieldName"
fi

# If we weren't given an instance id we should warn that this is not advised.
if [[ -z $_arg_instanceId ]]; then
  echo "WARNING: Without the instance id we will be unable to tell which ScreenConnect instance is yours (if multiple are installed). This may result in the wrong URL being displayed."
  echo "To get the instance id you can find it in ScreenConnect itself (Admin > Advanced > Server Information > Instance Identifier Fingerprint). It's also in the application name on every installed copy 'connectwisecontrol-yourinstanceidhere'"
fi

# --screenconnectDomain and --sessionGroup are required. We should also escape the session group given.
if [[ -z $_arg_screenconnectdomain || -z $_arg_sessiongroup ]]; then
  _PRINT_HELP=yes die "FATAL ERROR: Unable to build the URL without the Domain and Session Group!" 1
else
  _arg_sessiongroup=$(echo "$_arg_sessiongroup" | perl -MURI::Escape -ne 'chomp;print uri_escape($_),"\n"')
fi

# Double check ScreenConnect is installed
installedPkg=$(pkgutil --pkgs | grep "connectwisecontrol-$_arg_instanceId")
if [[ -z $installedPkg ]]; then
  _PRINT_HELP=no die "FATAL ERROR: It appears ConnectWise ScreenConnect is not installed!" 1
fi

# Lets start building some urls
for pkg in $installedPkg; do
  file="/Applications/$pkg.app/Contents/Resources/ClientLaunchParameters.txt.lproj/locversion.plist"
  id=$(grep -Eo 's=.{8}-.{4}-.{4}-.{4}-.{12}' "$file" | sed 's/s=//g' | sed 's/&e=Access//g')
  instanceid=${pkg//"connectwisecontrol-"/}
  # We shouldn't have multiple results but if we do we should warn the technician
  if [[ -n "$launchurls" ]]; then
    echo "WARNING: Multiple installed instances detected and no instance id was given. One of these urls will be incorrect."
    launchurls=$(
      printf '%s\n' "$launchurls"
      printf '%s\t' "$instanceid"
      printf '%s\n' "https://$_arg_screenconnectdomain/Host#Access/$_arg_sessiongroup//$id/Join"
    )
  else
    launchurls=$(
      printf '%s\t\t' "InstanceID"
      printf '%s\n' "LaunchURL"
      printf '%s\t' "$instanceid"
      printf '%s\t' "https://$_arg_screenconnectdomain/Host#Access/$_arg_sessiongroup//$id/Join"
    )
  fi
done

# Check that we were successful
if [[ -n $launchurls ]]; then
  echo "Launch URL(s) Created"
else
  _PRINT_HELP=no die "FATAL ERROR: Failed to create Launch URL(s)!" 1
fi

# Change how we output the results based on how many urls we received.
if [[ $(echo "$launchurls" | wc -l) -gt 2 ]]; then
  _fieldValue="$launchurls"
  echo "$_fieldValue"
else
  _fieldValue=$(echo "$launchurls" | tail -n 1 | awk '{print $2}')
  echo "$_fieldValue"
fi

echo "Setting Custom Field..."
setCustomField
exit 0

 

Description détaillée

Le script opère en plusieurs étapes :

• Initialisation des paramètres: Il commence par définir des valeurs par défaut pour divers paramètres tels que l’identifiant de l’instance, le domaine, le groupe de session et le nom du champ personnalisé.
• Fonction d’aide: Une fonction de texte d’aide est incorporée, qui guide les utilisateurs dans l’utilisation du script, en particulier dans les cas d’entrées non valides.
• Analyse de la ligne de commande: Il analyse les arguments de la ligne de commande pour personnaliser les paramètres tels que le domaine et l’identifiant de l’instance.
• Paramétrage du champ personnalisé: Le script comprend une fonction permettant de définir un champ personnalisé dans l’outil NinjaRMM, où l’URL du contrôle ConnectWise sera stockée.
• Construire des URL de lancement: La fonctionnalité principale consiste à construire les URL de lancement en extrayant les ID nécessaires des paquets installés et en construisant l’URL sur la base des paramètres fournis.
• Traitement des résultats: En fonction du nombre d’URL générés, il les stocke dans un champ personnalisé ou les édite directement.

Cas d’utilisation potentiels

Imaginez un professionnel de l’informatique qui gère un parc d’appareils dans différentes entreprises clientes. Il doit fournir une assistance à distance en temps voulu, mais la gestion des URL des sessions individuelles est fastidieuse. Grâce à ce script, il peut rapidement générer et stocker ces URL, garantissant ainsi un accès à distance rapide et organisé.

Comparaisons

Traditionnellement, les professionnels de l’informatique peuvent configurer manuellement chaque URL de session ou utiliser des scripts moins sophistiqués. Ce script, cependant, automatise l’ensemble du processus et est spécialement conçu pour ConnectWise Control sur macOS, offrant ainsi une solution plus efficace et sans erreur.

FAQs :

• Comment trouver l’identifiant de l’instance ?
  • Vérifiez le ScreenConnect Admin Center ou le nom de l’application sur les instances installées.
• Est-il compatible avec toutes les versions de macOS ?
  • Il est conçu pour une compatibilité générale, mais testez toujours d’abord votre version spécifique.
• Puis-je personnaliser le champ de stockage pour les URL ?
  • Oui, le script permet de définir un champ personnalisé de votre choix.

Implications

Bien que ce script simplifie le processus de gestion des sessions à distance, il est essentiel de tenir compte des implications en matière de sécurité. Il est essentiel pour la sécurité informatique de veiller à ce que les URL soient stockés en toute sécurité et à ce que leur accès soit contrôlé.

Recommandations

• Mettez régulièrement le script à jour pour tenir compte des nouvelles mises à jour de ConnectWise Control.
• Vérifiez les autorisations de sécurité pour les URL stockés.
• Testez le script dans un environnement contrôlé avant de le déployer à grande échelle.

Conclusion :

L’intégration de ces scripts avec des outils comme NinjaOne peut améliorer de manière significative la capacité d’un professionnel de l’informatique à gérer l’assistance à distance de manière efficace et sécurisée. L’approche globale de NinjaOne en matière de surveillance et de gestion à distance complète ces scripts, fournissant une plateforme puissante pour la gestion informatique.