Lorsqu’on pense à Parallels RAS (Remote Application Server), on pense souvent à son interface graphique — la console d’administration — pour gérer les ressources publiées, les serveurs, les certificats, les utilisateurs. Mais on peut aller bien au-delà de cette console avec le PowerShell API de Parallels RAS .
Grâce à l’API Powershell de Parallels (module RASAdmin), il est possible d’automatiser l’intégralité des opérations d’administration : publication d’applications, gestion des filtres d’accès, provisionnement de certificats, intégration de tenants… Le tout scriptable, versionnable, et intégrable dans vos pipelines CI/CD ou vos outils d’ITSM.
Cet article vous propose :
- Une présentation des possibilités offertes par le PowerShell API
- Les avantages concrets pour les équipes IT
- Les prérequis techniques
- Une série de labs progressifs pour pratiquer
Voici pourrez retrouver un exemple concret d’utilisation pour Automatiser la sauvegarde de la configuration Parallels RAS avec PowerShell ou un outil développé en Powershell : Licensing Monitor Parallels RAS : Le Tool indispensable
Ce que permet le PowerShell API de Parallels RAS
La règle d’or est simple : tout ce qui est faisable dans la console graphique Parallels RAS peut être réalisé via l’API PowerShell. Voici les principales catégories d’opérations :
1. Gestion des ressources publiées
- Publier des applications et des bureaux distants
- Appliquer des filtres d’accès (utilisateurs/groupes, plages IP, types de clients…)
- Gérer les règles d’autorisation/refus sur les items publiés
2. Gestion des certificats
- Créer et déployer des certificats SSL (manuels ou Let’s Encrypt)
- Configurer les renouvellements automatiques
- Associer les certificats aux Secure Gateways ou aux load balancers
3. Architecture multi-tenant
- Rejoindre un Tenant Broker depuis un script
- Générer des clés secrètes pour l’enregistrement des tenants
- Automatiser l’onboarding de nouveaux environnements
4. Configuration globale de la ferme
- Gérer les brokers, les gateways, les pools de serveurs RDS
- Appliquer des configurations de manière idempotente
- Intégrer Parallels RAS dans des workflows Ansible, Terraform ou des scripts de déploiement
| ℹ️ Le module PowerShell RASAdmin expose également l’ensemble des ressources via une API REST (port 20443), permettant ainsi l’intégration depuis n’importe quel langage ou plateforme (Python, Go, JavaScript, etc.). |
Avantages de l’automatisation via PowerShell API
Gain de temps et cohérence
Plutôt que de reproduire manuellement les mêmes opérations pour chaque nouvel environnement, un script PowerShell garantit une configuration identique à chaque exécution. Fini les oublis, fini les erreurs de configuration humaines.
Intégration dans les pipelines DevOps
Les scripts RASAdmin peuvent être exécutés depuis des pipelines Azure DevOps, GitHub Actions, Jenkins ou tout autre système CI/CD. Cela ouvre la voie à un provisionnement « infrastructure as code » pour vos environnements Parallels RAS.
Traçabilité et auditabilité
Un script versionné dans Git représente un historique clair de chaque modification apportée à l’infrastructure. En cas d’incident, il est possible de rejouer ou d’annuler une configuration précise.
Scalabilité
Que vous gériez 5 ou 500 tenants, l’effort d’administration reste constant. Un seul script peut provisionner des dizaines d’environnements en quelques secondes.
Compatibilité multi-plateforme via REST
Au-delà de PowerShell, l’API REST de Parallels RAS permet d’interagir depuis n’importe quel outil capable d’émettre des requêtes HTTP : Postman, Python, applications web, etc.
Prérequis
Environnement requis
- Windows Server (ou poste Windows) avec PowerShell 5.1 ou PowerShell 7+
- Parallels RAS installé (version Connection Broker en place)
- Accès réseau au serveur hébergeant le Connection Broker
- Compte administrateur RAS avec les droits suffisants
Installation du module RASAdmin
Le module PowerShell RASAdmin (version 4.0 au moment de la rédaction) peut être installé de deux façons :
Option 1 — Installation graphique
Lancer l’installeur standard Parallels RAS, choisir « Custom installation », puis sélectionner le composant « Parallels RAS PowerShell ». Lors d’une installation par défaut du broker, les modules PowerShell sont automatiquement inclus.
Option 2 — Installation silencieuse (MSI)
| msiexec /i RASInstaller-*.msi ADDLOCAL=F_PowerShell /qn |
| ℹ️ Important : la version du binaire PowerShell RAS doit impérativement correspondre à la version du RAS Connection Broker installé sur votre infrastructure. Une incompatibilité de version entraîne des erreurs de connexion. |
Vérification et import du module
Une fois installé, importez le module dans votre session PowerShell :
Import-Module RASAdmin |
Pour lister tous les cmdlets disponibles :
Get-Command -Module RASAdmin |
La documentation de PowerShell API de Parallels RAS complète est disponible à l’adresse :
https://docs.parallels.com/landing/ras-powershell-api-guide
Série de Labs — Mise en pratique
Les labs suivants sont conçus pour être réalisés de manière progressive. Chaque lab s’appuie sur les notions du précédent. Les scripts sont commentés pour faciliter la compréhension.
Lab 0 — Connexion et première commande
Avant tout, il faut établir une session RAS. Le cmdlet New-RASSession crée une connexion authentifiée vers le Connection Broker. Toutes les opérations suivantes s’exécutent dans le contexte de cette session.
# Paramètres de connexion
$username = "apiuser"
$password = "VotreMotDePasse!"
$server = "rasbroker.votre-domaine.local"
# Conversion du mot de passe en SecureString
$passwordEnc = ConvertTo-SecureString $password -AsPlainText -Force
# Ouverture de la session RAS
New-RASSession -Username $username -Password $passwordEnc -Server $server
# Vérification : lister les brokers
Get-RASBroker
# Fermeture propre de la session
Remove-RASSession| 🧪 Lab 0 — À vous de jouer |
| Installez le module RASAdmin sur votre poste ou serveur de test. Adaptez les variables $username, $password et $server à votre environnement.Exécutez le script et vérifiez que Get-RASBroker retourne votre broker.Explorez d’autres cmdlets : Get-RASSite, Get-RASGateway, Get-RASRDSHostPool. |
Vous devriez avoir un résultat similaire à celui-ci en fonction du nombre de Connection Broker dont vous disposez :
Lab 1 — Publier une application et un bureau
Ce lab illustre la publication d’une application (ici Paint) et d’un bureau distant depuis le pool par défaut. Notez l’utilisation de Invoke-RASApply pour valider les changements — sans cette commande, les modifications restent en attente et ne sont pas appliquées.
$username = "apiuser"
$password = "VotreMotDePasse!"
$server = "rasbroker.votre-domaine.local"
$passwordEnc = ConvertTo-SecureString $password -AsPlainText -Force
New-RASSession -Username $username -Password $passwordEnc -Server $server
#Récupération du pool par défaut
$pool = Get-RASRDSHostPool -Name "RDSH Pool"
#Publication d'un bureau distant (taille adaptée à l'écran disponible)
$desktop = New-RASPubRDSDesktop -Name "MonBureau" `
-PublishFrom HostPool `
-PublishFromHostPoolIds $pool.Id `
-DesktopSize UseAvailableArea
#Publication de l'application Paint
$app = New-RASPubRDSApp -Name "Paint" `
-PublishFrom HostPool `
-PublishFromHostPoolIds $pool.Id `
-Target "%windir%system32mspaint.exe"
#Application des changements (indispensable)
Invoke-RASApply
Remove-RASSession| 🧪 Lab 1 — À vous de jouer |
| Exécutez le script et vérifiez dans la console RAS que l’application et le bureau apparaissent. Modifiez le script pour publier une autre application (ex : Notepad, Calculator). Consultez la documentation : https://docs.parallels.com/landing/ras-powershell-api-guide Testez la suppression d’une ressource publiée avec Remove-RASPubItem. |
Le résultat devrait ressembler à celui-ci sur votre portail RAS :
- Publication d’un bureau et de Paint
Lab 2 — Ajouter des filtres d’accès sur une application
Parallels RAS permet de contrôler finement l’accès aux ressources publiées via des règles et des critères. Ce lab ajoute à l’application Paint une règle nommée « MonFiltre » avec deux critères : restriction par groupe d’utilisateurs et par plage IP. Le comportement par défaut est configuré en mode « Deny » (refus si aucune règle ne correspond).
$username = "apiuser"
$password = "VotreMotDePasse!"
$server = "rasbroker.votre-domaine.local"
$passwordEnc = ConvertTo-SecureString $password -AsPlainText -Force
New-RASSession -Username $username -Password $passwordEnc -Server $server
#Récupération de l'application publiée
$app = Get-RASPubRDSApp -Name "Paint"
#Ajout d'une nouvelle règle
Add-RASRule -Id $app.Id -ObjType PubItem -RuleName "MonFiltre"
#Récupération de la règle créée
$rules = Get-RASRule -Id $app.Id -ObjType PubItem
#Activation des critères : groupe ET IP
Set-RASCriteria -Id $app.Id `
-ObjType PubItem `
-SecurityPrincipalsEnabled $true `
-IPsEnabled $true `
-RuleId $rules[0].Id
#Critère 1 : restreindre au groupe "Guests"
Add-RASCriteriaSecurityPrincipal -Id $app.Id - `
ObjType PubItem `
-RuleId $rules[0].Id `
-Account "Guests"
#Critère 2 : restreindre à une plage IP
Add-RASCriteriaIP -Id $app.Id `
-ObjType PubItem `
-RuleId $rules[0].Id `
-IPType Version4
-IP "192.168.1.1-192.168.1.50"
#Comportement par défaut : refuser si aucune règle ne correspond
Set-RASPubItemFilter -Id $app.Id -Default Deny
Invoke-RASApply
Remove-RASSession| 🧪 Lab 2 — À vous de jouer |
| Appliquez le script et vérifiez les règles dans la console (onglet Filtering de l’app). Ajoutez un second critère de type ‘Client OS’ (ex : Windows uniquement). Testez avec Default Allow pour inverser le comportement par défaut.Explorez le cmdlet Get-RASCriteria pour lire les filtres existants. |
L’exécution de ce script vous donnera les résultats suivants :
- Création d’une règle et modification de la règle par défaut
2. Création de 2 critères dans la règle
Lab 3 — Créer un certificat Let’s Encrypt automatiquement
La gestion des certificats SSL est souvent une tâche fastidieuse. Avec le PowerShell API, il est possible de provisionner un certificat Let’s Encrypt en quelques lignes. Ce lab illustre l’acceptation des conditions d’utilisation, puis la création du certificat associé à la Secure Gateway.
$username = "apiuser"
$password = "VotreMotDePasse!"
$labServer = "rasbroker.votre-domaine.local"
$passwordEnc = ConvertTo-SecureString $password -AsPlainText -Force
New-RASSession -Username $username -Password $passwordEnc -Server $Server
#Acceptation des conditions Let's Encrypt (obligatoire avant la première émission)
Set-RASLetsEncryptSettings -SiteID 1 -TermsAccepted $true
Invoke-RASApply
#Définition du FQDN public et de l'email de contact
$publicFQDN = "ras.votre-domaine-public.com"
$email = "[email protected]"
#Création du certificat
New-RASCertificate -Name "CertGateway" `
-CommonName $publicFQDN `
-Email $email `
-LetsEncrypt `
-Enabled $true `
-Organisation "Votre Organisation" `
-KeySize KeySize2048 `
-Usage Gateway
Invoke-RASApply
Remove-RASSession| ℹ️ Pour que Let’s Encrypt fonctionne, le port 80 (HTTP) doit être accessible depuis Internet sur l’adresse IP publique de votre Secure Gateway. Let’s Encrypt utilise ce port pour valider la propriété du domaine. |
| 🧪 Lab 3 — À vous de jouer |
| Vérifiez dans la console RAS que le certificat a bien été créé (section Certificates). Modifiez le script pour créer un second certificat avec Usage ‘HALB’ (load balancer). Explorez le cmdlet Get-RASCertificate pour lister les certificats existants. Testez la rotation automatique : consultez les paramètres de renouvellement. |
Après avoir exécuté ce script, une demande de certificat doit apparaître dans la console :
Lab 4 — Rejoindre un Tenant Broker
Dans les architectures multi-tenant (MSP ou grandes entreprises), le Tenant Broker centralise la gestion de plusieurs sites Parallels RAS. Ce lab automatise l’enregistrement d’un tenant via une clé secrète générée programmatiquement.
$username = "apiuser"
$password = "VotreMotDePasse!"
$tenantBroker = "tb.votre-domaine.local"
#Tenant Broker
$labServer = "lab1.votre-domaine.local"
#Serveur tenant à intégrer
#---- Étape 1 : connexion au Tenant Broker ----
New-RASSession -Username $username -Password $password -Server $tenantBroker
#Autoriser l'enregistrement via clé secrète
Set-RASTenantBrokerSettings -AllowRegistrationWithSecretKey $true
Invoke-RASApply
#Générer la clé secrète
$secretKey = Invoke-RASTenantBrokerSettings -Command GenerateHash
Invoke-RASApply
Remove-RASSession
#---- Étape 2 : connexion au serveur tenant ----
New-RASSession -Username $username -Password $password -Server $labServer
$publicFQDN = "lab1.votre-domaine-public.com"
#Enregistrement du tenant dans le Tenant Broker
Invoke-RASTenantBroker -Join `
-HashKey $secretKey`
-TenantBroker $tenantBroker `
-PublicDomainAddresses $publicFQDN`
-TenantName $labServer
Invoke-RASApply
Remove-RASSession| 🧪 Lab 4 — À vous de jouer |
| Vérifiez dans la console Tenant Broker que le nouveau tenant apparaît dans la liste. Explorez le cmdlet Get-RASTenantBrokerSettings pour lire la configuration. Testez la déconnexion d’un tenant avec Invoke-RASTenantBroker -Leave. Réfléchissez à comment intégrer ce script dans un pipeline d’onboarding automatique. |
Bonnes pratiques
Ne jamais stocker les mots de passe en clair
Les exemples de cette série utilisent des variables en clair pour la lisibilité. En production, utilisez systématiquement des solutions sécurisées : Windows Credential Manager, Azure Key Vault, HashiCorp Vault, ou des secrets d’environnement CI/CD.
# Exemple avec Windows Credential Manager $cred = Get-Credential New-RASSession -Username $cred.UserName -Password $cred.Password -Server $server |
Toujours appeler Invoke-RASApply
Sans cet appel, toutes les modifications restent en attente et ne sont jamais appliquées. Pensez-y comme à un « commit » dans Git : c’est ce qui valide et déploie vos changements.
Fermer proprement la session
Utilisez toujours Remove-RASSession en fin de script, idéalement dans un bloc try/finally pour garantir la fermeture même en cas d’erreur :
try { New-RASSession -Username $username -Password $passwordEnc -Server $server # ... vos commandes ... Invoke-RASApply } |
Versionner vos scripts
Stockez vos scripts RASAdmin dans un dépôt Git. Chaque modification devient traçable, réversible, et peut déclencher des révisions de code avant application en production.
Pour aller plus loin
Cet article couvre les bases du PowerShell API. Parallels RAS offre également :
- Une API REST complète (port 20443) pour l’intégration depuis n’importe quel langage
- Un Web Client API pour lancer directement des ressources depuis un portail web
- Un URL scheme (tuxclient://) pour interagir avec le client local installé
- Une CLI Windows (AppServerClientCLI.exe) pour l’automatisation côté utilisateur
Ressources officielles :
- Documentation PowerShell API : https://docs.parallels.com/landing/ras-powershell-api-guide
- Documentation REST API : https://docs.parallels.com/landing/ras-rest-api-guide
- Essai gratuit Parallels RAS : https://parallels.com/products/ras/try
Conclusion
Le PowerShell API de Parallels RAS transforme la gestion de l’infrastructure de publication en un processus reproductible, auditable et scalable. Que vous soyez administrateur système cherchant à gagner du temps sur les tâches répétitives, ou architecte souhaitant intégrer Parallels RAS dans un pipeline DevOps, les cmdlets RASAdmin vous offrent le niveau de contrôle nécessaire.
La série de labs proposée dans cet article vous donne une base solide pour démarrer. N’hésitez pas à explorer la documentation officielle et à expérimenter — chaque cmdlet est documenté avec ses paramètres et des exemples d’utilisation.
