PI Services

Le blog des collaborateurs de PI Services

Desired State Configuration (Partie 5) : Création d’une ressource personnalisée

Introduction

Cet article fait partie d’une série de 5 billets sur Desired State Configuration :

Desired State Configuration est disponible comme Powershell 4.0 sur Windows 2012 R2/8.1, Windows 2012/8 et Windows 2008 R2/7.

Lors du précédent article nous avons vu l'implémentation du mode Pull via un web service.

Desired State Configuration est fourni avec un certain nombre de ressources. Malgré qu'il y en ai peu, et comme évoqué dans le précédent article, Microsoft et la communauté se sont employés à créer des nouvelles ressources. Dans cette cinquième et dernière partie, nous évoquerons la création d’une ressource personnalisée. Cette dernière permettra de prendre en charge un scénario non présent dans les ressources existantes : la présence d'un partage NFS.

Fonctionnement

Une ressource est constituée de plusieurs fichiers :

  • Un fichier .SCHEMA.MOF contenant sa définition et plus particulièrement toutes les propriétés que l'on pourra renseigner.
  • Un module Powershell contenant quelques fonctions obligatoires (.PSM1)
  • Un fichier .PSD1 représentant le manifest du module Powershell. Ce dernier contiendra les fonctions a exporter de notre module. Ce dernier est principalement utilisé pour versionner le module et avoir quelques informations dessus.

Le module Powershell doit obligatoirement comporter trois fonctions. Elles seront appelées lorsqu'un fichier de configuration contiendra une ressource du type que l'on aura créé. “Get-TargetResource” permet de récupérer la configuration telle qu'elle a été définie. “Set-TargetResource” applique une configuration (création, modification et suppression) et “Test-TargetResource” effectue le test de validité (elle retourne un booléen).

Il convient à la personne créant le module de développer le corps de ces fonctions (le squelette étant toujours identique), c'est à dire les paramètres et les process effectués.

Pré-requis

Au lancement de Powershell 4.0, il pouvait être fastidieux de développer ses propres ressources car il fallait respecter une certaine syntaxe. Cependant, Microsoft a développé un module permettant de faciliter la création de ressource à destination de DSC : xDscResourceDesigner. Ce dernier va nous permettre de générer nos fichiers automatiquement. Il est disponible en suivant le lien ci-dessous : http://gallery.technet.microsoft.com/scriptcenter/xDscResourceDesigne-Module-22eddb29

Il suffit ensuite de placer ce module dans le dossier :
C:\Program Files\WindowsPowerShell\Modules”.

DSC xDscResourceDesigner

Création de la ressource

Pour créer la ressource, on commence par définir ses propriétés avec la cmdlet “New-xDscResourceProperty”. Celles-ci possèdent à minima un nom, un type et des attributs. Ces derniers permettent de définir l'accessibilité (lecture, écriture,...). Lorsque l'on définit une nouvelle ressource, au moins une de ses propriétés devra posséder l'attribut “Key” et ne pourra être un tableau. Cet attribut permet d'indiquer la propriété utilisée lors de la recherche d'une ressource.

Dans l'exemple ci-dessous, on définit 3 propriétés :

  • le nom du partage
  • le chemin vers lequel le partage pointe
  • la présence ou l'abscence du partage
Ensuite, il est nécessaire de créer la ressource via la cmdlet “New-xDscResource”. Il faut spécifier toutes les propriétés utilisées dans cette ressource, le nom de la ressource et éventuellement le chemin où l'on va la stocker (sinon il sera placé dans un répertoire “DSCResources” à l’intérieur du répertoire dans lequel on se trouve).
Nous nous retrouvons avec le fichier .MOF ci-dessous :

Un module Powershell qui ne comprend pour l'instant que le fichier .PSM1 a aussi été généré. Il faut maintenant définir la logique de nos 3 fonctions à l'intérieur de ce module.

Get-TargetResource

Le code intégré à la fonction “Get-TargetResource” récupère le partage NFS s'il existe et retourne le chemin vers lequel il pointe. S'il n'y a pas de partage NFS avec ce nom, alors un message est écrit dans l'invite de commande Powershell.

Set-TargetRessource

Dans le code ci-dessous, on récupère un éventuel partage avec le nom défini en paramètre. Si ce dernier existe, alors on le met à jour avec le bon chemin (obligation de supprimer puis de recréer le partage NFS) sinon le partage NFS est créé. Si le partage est présent alors que la propriété “Ensure” a pour valeur “Absent” alors le partage NFS est supprimé. Il est à noter que cette fonction n'est appelée que lors de la modification d'un fichier de configuration d'un serveur ou lorsqu’une configuration est incorrecte.

NB : Lors de la génération du template de module à remplir, il est indiqué dans le corps de la fonction qu'il faut positionné la variable globale “$global:DSCMachineStatus” avec la valeur 1 si une configuration nécessite un reboot après son application.

Test-TargetResource

Cette dernière fonction valide qu'une configuration est bien appliquée. Elle vérifie l'existence du partage ainsi que le chemin vers lequel il pointe si le paramètre “Ensure” a pour valeur “Present”. Si “Ensure” vaut “Absent” alors il est vérifié que le partage NFS n'existe pas. Les différents tests retournent la valeur “$true” si la configuration est bonne et “$false” dans le cas contraire. 

A noter, qu'à la fin de notre module, la cmdlet “Export-ModuleMember” est présente et obligatoire afin que Powershell découvre correctement les méthodes de la ressource.

Génération du manifest

Enfin, il faut générer le fichier de manifest du module. Afin de réaliser cette opération, il faut utiliser la commance New-ModuleManifest en spécifiant les paramètres “FunctionsToExport”, “RequiredModules” et “Path”. Attention, le chemin indiqué doit être la racine de la ressource créée (Au même niveau que le dossier DSCResources), sinon il vous sera impossible d'importer la ressource. De même, le nom du manifest doit être le même que le nom du module.

Les autres champs du fichier .PSD1 généré peuvent aussi être spécifiés via la cmdlet précédente ou en remplissant manuellement le fichier (via un éditeur de texte). Certaines propriétés seront même automatiquement remplies (exemple : auteur avec le samaccountname de l'utilisateur ayant lancé la commande).

Voici un lien menant vers le manifest généré pour cette ressource : Manifest

Import de la ressource et utilisation

Il suffit de placer notre ressource (Répertoire C:\NFSShare dans notre exemple) dans “C:\Program Files\WindowsPowerShell\Modules\

En utilisant la commande “Get-DSCResource”, on remarque que notre ressource NFSShare est disponible. On s'aperçoit aussi que la propriété DependsOn est automatiquement rajouté sur cette ressource. Il s'agit d'une propriété par défaut disponible sur toutes les ressources DSC. Pour rappel elle permet de lier des configurations entre elles en spécifiant qu’une configuration dépend de la réussite d’une autre.
 DSC List Resources
Il est ensuite possible de générer un fichier de configuration pour un serveur. Il est nécessaire d'ajouter la commande “Import-DscResource” en renseignant le paramètre “ModuleName” dans le bloc de configuration lorsque l'on utilise des ressources personnalisées.
Enfin, on applique la configuration via la ligne de commande ci-dessous et on obtient bien la création du partage NFS :

DSC Result

Conclusion

Lors de cet article, nous avons vu la création d'une ressource permettant de gérer des partages NFS. Il est possible de l'améliorer en gérant d'autres propriétés de ce type de partage comme les permissions. 

Customiser ses pages ADFS / Ajout du suffixe UPN automatique dans l'identifiant

Préambule

L'ensemble des manipulations ont été réalisées sur une infrastructure Windows 2012 R2 / ADFS 3.0.

Problématique

Avec quelques connaissances en développement web (CSS et Javascript), il est possible de customiser les pages de logon ADFS. On peut positionner un logo qui remplacera le nom de la federation ou encore changer l'illustration par défaut. De plus, Microsoft offre aussi la possibilité de changer une partie du code Javascript et CSS. Nous verrons donc comment gérer ses templates ADFS puis je détaillerai un script Javascript permettant d'ajouter automatiquement le suffixe UPN de l'utilisateur. Ainsi toute personne souhaitant se connecter n'aura qu'à entrer son samAccountName. Attention, cette méthode n'est fonctionnelle que dans le cas où tous les utilisateurs possèdent le même suffixe UPN.

Gestion des templates ADFS

Microsoft fourni quelques indications pour customiser les pages ADFS sur le lien suivant :
http://technet.microsoft.com/en-us/library/dn280950.aspx . On retrouve notamment les modifications les plus basiques comme les changements d'images ou de messages (erreur, aide,...).

Aussi, dans ADFS 3.0, il est possible de gérer plusieurs templates via les Cmdlets Powershell adéquates. Le template de base se nomme "default". On peut d'ailleurs récupérer la liste des thèmes avec la Cmdlet Get-ADFSWebTheme. On remarque qu'il s'agit bien du template de base grâce à l'attribut IsBuiltinTheme.

Les étapes de customisation d'un thème sont les suivantes :

  • création d'un nouveau thème 
  • export des fichiers du thème 
  • modification des fichiers 
  • import des fichiers modifiés dans le thème créé

Pour ajouter un nouveau thème il suffit d'utiliser la commande New-AdfsWebTheme en spécifiant le nom du thème ainsi que les sources du nouveau thème. En général, on se basera sur le thème par défaut que l'on customisera ultérieurement.

 

Il nous faut ensuite exporter les fichiers de ce thème (vers le dossier C:\ADFSTheme par exemple) :

 

Attention le dossier d'export doit exister (il ne sera pas généré automatiquement).

On remarque que l'on a accès à un certain nombre de fichiers mais pas à tous. En général, ceux que l'on voudra customiser sont le fichier onload.js et le fichier style.css.

2014-04-18 11_53_36-SRV01673 - Remote Desktop Connection Manager v2.2

Une fois modifiée, il ne reste plus qu'à importer le fichier dans le thème nommé custom. Un exemple avec le fichier onload.js :

 

Enfin pour définir le thème custom comme actif il faut utiliser la Cmdlet ci-dessous :

 

Ajout automatique du suffixe UPN

Afin de faciliter l'expérience utilisateur lors d'un usage en situation de mobilité ou via un navigateur ne supportant pas ADFS, il peut être utile d"ajouter automatiquement le suffixe UPN lorsque ce dernier a été omis dans le formulaire d'authentification. Pour les utilisateurs ne connaissant pas les notions de nom de domain Netbios ou d'UPN, cette customisation peut être interessante. Celle-ci nécessite du code Javascript.

ADFS se base sur la valeur entrée dans le champ “UserName” avec l’ID “userNameInput” du fomulaire. Il faut donc modifier cette valeur. Une autre solution (utilisée ici), consiste à changer l’ID et le nom du champ original. Puis, on ajoute un nouveau champ, invisible à l’utilisateur et contenant la bonne valeur ainsi que l’ID et le nom mentionné précédemment. Cette seconde solution est esthétiquement plus réussi (l’utilisateur ne voit pas le changement)

Ci-dessous, se trouve le script a ajouté à la fin du fichier onload.js est à intégrer dans le thème ADFS via la méthode vu précédemment :

 

Voici les opérations réalisées par le script lorsque le formulaire est valider (via la touche “Entrée” ou un clic sur le bouton de connexion) :

  • Récupération du champ contenant l’identifiant utilisateur
  • Vérification de la présence d’un suffixe UPN

Si le suffixe est manquant :

  • On renomme le champ contenant l’identifiant utilisateur (UserName) et on change son ID (userNameInput).
  • On ajoute un nouveau champ non visible portant les valeurs initiales (Id et nom). Il contiendra la valeur entrée par l’utilisateur avec le suffixe UPN. Celles-ci seront transmises à ADFS.

Une amélioration pourrait être d'ajouter une balise “select” contenant une liste de tous les suffixes UPN possibles. Cela permettrait de gérer les infrastructures utilisant de multiples suffixes UPN.