Gestion des thèmes

Introduction

Dans ce guide, vous apprendrez à gérer les thèmes dans votre locataire IBM Security Verify. Les thèmes vous permettent de personnaliser l'aspect et la convivialité des pages web et des e-mails de notification vus par vos utilisateurs finaux.

Vous pouvez avoir plusieurs thèmes dans votre locataire et vous pouvez affecter des thèmes à une ou plusieurs applications. Il y a aussi un thème par défaut qui est utilisé pour rendre les pages qui ne sont pas associées à une application.

Au moment de la rédaction, il n'y a pas d'interface utilisateur associée à la gestion de l'import et de l'export des thèmes dans l'interface d'administration. Au lieu de cela, vous devez utiliser des appels REST. Cet article montrera comment effectuer les appels REST requis en utilisant curl.

L'attribution d'un thème importé à une application fait partie de l'interface d'administration. Ce processus sera également décrit dans ce guide.

Prérequis

Vous devrez obtenir un jeton d'accès autorisé à gérer les thèmes. La façon la plus simple de procéder est de créer un client API avec le droit Manage Templates puis d'exécuter le flux de type Client Credentials pour obtenir un jeton d'accès.

Pour apprécier pleinement les thèmes, vous devrez avoir au moins une application définie dans votre locataire IBM Security Verify. Si vous n'avez pas encore d'application, vous pouvez Connecter une application d'exemple.

Vous aurez besoin de l'utilitaire en ligne de commande curl. Il est intégré à la plupart des systèmes Linux et MacOS. Cependant, si nécessaire, vous pouvez télécharger curl ici.

Optionnellement, si vous voulez automatiser l'analyse des réponses JSON de l'API, vous aurez besoin de l'utilitaire jq. Vous pouvez télécharger jq ici.

Variables

Dans ce guide, les variables suivantes sont utilisées :

Vous devriez définir ces variables sur la ligne de commande comme ceci :

export tenant_url=tenant.verify.ibm.com
export access_token=iZ5Gfz66HsNYSoJxhVe7N3u6cdBCHFYWgDOCAsNF

Obtenir une liste des thèmes disponibles

D'abord, vous utiliserez votre jeton d'accès pour obtenir une liste des thèmes disponibles dans votre locataire. Cela servira également à tester le jeton d'accès.

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes"

Le résultat aura ce format :

{
  "count": 1,
  "limit": 200,
  "page": 1,
  "total": 1,
  "themeRegistrations": [
    {
      "name": "default",
      "description": "Default Theme",
      "id": "default"
    }
  ]

La sortie ci-dessus provenait d'un locataire propre. Vous pouvez voir qu'un seul thème default existe.

Télécharger un paquet de thème et extraire

Un paquet de thème est téléchargé en effectuant une requête GET au point de terminaison REST pour ce thème.
Le point de terminaison REST pour un thème inclut l'ID du thème. Le paquet de thème est retourné comme une archive ZIP.

📘

Obtenir le thème original

Vous pouvez spécifier master comme ID de thème pour télécharger le paquet de thème original. Ceci est utile si vous avez mis à jour le thème par défaut et avez besoin d'obtenir une version non modifiée.

Utilisez la commande curl suivante pour télécharger le thème par défaut dans un fichier nommé default-theme.zip :

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes/default" -o default-theme.zip

Vous devez maintenant extraire le fichier ZIP pour accéder aux fichiers de modèles qu'il contient. Vous pouvez utiliser votre outil d'archive favori ou, si vous avez unzip, utilisez cette commande pour dézipper dans un répertoire appelé extracted-theme :

unzip -d extracted-theme default-theme.zip

Vous avez maintenant un répertoire extracted-theme contenant les modèles de thème exportés.

Explorer la structure des dossiers du thème

Si vous regardez dans le répertoire extracted-theme que vous venez de créer, vous verrez qu'il contient un seul répertoire templates. C'est le répertoire racine pour le paquet de thème. À l'intérieur de ce répertoire, vous trouverez les dossiers suivants qui divisent les fichiers de modèles par but :

Le dernier dossier dans la structure de répertoire est le dossier de locale. Dans le thème par défaut, la plupart du contenu spécifique à la locale est stocké dans le dossier templates/common/labels. Vous verrez qu'il y a de nombreux dossiers de langue là. Dans la plupart des autres endroits, il n'y a qu'un dossier default. Ce dossier est utilisé quand aucun autre dossier ne correspond à la locale demandée. Le dossier par défaut est utilisé pour présenter le contenu en anglais américain.

Apporter des modifications aux fichiers communs

Les ressources dans le répertoire /templates/common sont utilisées par d'autres pages dans le paquet de thème. Vous allez maintenant apporter des modifications à certains de ces fichiers.

Mettre à jour une étiquette

Le fichier template_labels.properties contient des étiquettes qui sont utilisées dans les pages de modèles par défaut. Vous pouvez identifier ces étiquettes dans d'autres fichiers de modèles parce qu'elles sont entourées de signes dollar ($) (par exemple $PRODUCT_NAME$).

Ouvrez le fichier templates/common/default/template_labels.properties dans un éditeur de texte.

Trouvez la définition LOGIN_USER_NAME et changez-la pour quelque chose de nouveau :

# A label for the username input
$LOGIN_USER_NAME$=Email address

Mettre à jour l'en-tête de page

Ouvrez le fichier /templates/common/page_components/page_header.html dans un éditeur de texte. Ce fragment HTML est inclus en haut de chaque page du thème.

Vous pouvez voir que ce fragment charge simplement une image de logo. Cette image est en fait chargée depuis le répertoire /templates/common/logo/default. Notez le ?themeId=@THEME_ID@ à la fin de l'URL. Cette chaîne de requête contrôle quel thème sera utilisé lors du chargement du fichier. La macro THEME_ID sera définie au thème actuel. Les macros sont identifiées parce qu'elles sont entourées de signes at (@).

Ajoutez une ligne supplémentaire au fichier pour qu'il ressemble à ceci :

<div class='heading'>
      <img src="template/v1.0/static/logo.svg?themeId=@THEME_ID@">
      <p>Customized by themes</p>
</div>

Enregistrez le fichier mis à jour.

Créer un nouveau paquet de thème et télécharger comme nouveau thème

Vous allez maintenant compresser le paquet de thème mis à jour et le télécharger vers votre locataire IBM Security Verify comme un nouveau thème.

Pour créer le paquet, utilisez votre outil d'archive favori pour compresser le répertoire templates. Si vous avez l'utilitaire zip, assurez-vous d'être dans le répertoire default-theme et utilisez cette commande :

zip -r test-theme.zip templates

Cela sauvegardera le fichier test-theme.zip dans le répertoire courant.

Pour enregistrer un nouveau thème en utilisant le nouveau paquet de thème, utilisez la commande curl suivante.
Si votre jeton d'accès a expiré, vous pourriez avoir besoin d'exécuter à nouveau le flux de jeton OAuth pour en obtenir un nouveau.

curl -H "Authorization: Bearer ${access_token}" -X POST "https://${tenant_url}/v1.0/branding/themes" -F [email protected] -F configuration='{"name":"test","description":"Test Theme"}'

Rechercher l'ID du thème

Chaque thème a un ID de thème. Vous avez besoin de cet ID de thème pour spécifier manuellement un thème pour le rendu de page (utile pour les tests) ou pour mettre à jour un thème qui existe déjà. Utilisez la commande curl suivante pour rechercher l'ID de thème pour votre nouveau thème de test :

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes"

La sortie ressemblera à ceci :

{
  "count": 2,
  "limit": 200,
  "page": 1,
  "total": 2,
  "themeRegistrations": [
    {
      "name": "test",
      "id": "b18d817b-6409-4fa1-8de4-308519937d25"
    },
    {
      "name": "default",
      "description": "Default Theme",
      "id": "default"
    }
  ]
}

Cherchez l'id associé au thème de test. Dans l'exemple ci-dessus, c'est b18d817b-6409-4fa1-8de4-308519937d25. Le vôtre sera différent. Enregistrez ceci dans la variable d'environnement theme_id :

export theme_id=b18d817b-6409-4fa1-8de4-308519937d25

Si vous avez jq disponible, vous pouvez exécuter cette commande qui effectuera l'appel REST, analysera la réponse JSON et peuplera la variable d'environnement theme_id :

export theme_name=test
export theme_id=`curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes" | jq -r ".themeRegistrations[] | select(.name==\"${theme_name}\") | .id"`
echo ${theme_id}

Tester le thème mis à jour

Connectez-vous à votre locataire en utilisant une URL comme celle-ci :

https://{tenant_url}/idaas/mtfim/sps/idaas/login?runtime=true&themeId={theme_id}

Quand la page se rend, le themeId spécifié dans la chaîne de requête sera utilisé. Vous devriez voir les changements de votre thème de test reflétés dans la page affichée :

Affecter un thème à une application

Un thème peut être appliqué à une application en utilisant l'interface d'administration de votre locataire IBM Security Verify. Si vous ouvrez les propriétés d'une application, vous trouverez le sélecteur de thème sur l'onglet General :

Sélectionnez votre nouveau thème test comme Theme et enregistrez la définition de l'application.

Tester un thème spécifique à l'application

Le thème associé à une application est utilisé quand IBM Security Verify effectue des actions qui sont directement associées à l'application. Par exemple :

• Effectuer une authentification initiale déclenchée par l'accès à l'application
• Effectuer une authentification multi-facteurs lors de la tentative d'accès à l'application
• Recevoir un e-mail lié au workflow d'autorisation pour l'application
• Recevoir des e-mails liés à une campagne de certification pour l'application

Pour tester le thème spécifique à l'application, déconnectez-vous de toutes les sessions IBM Security Verify (ou utilisez une session de navigateur propre) puis déclenchez l'authentification depuis l'application où vous avez affecté le thème de test.

Si vous utilisez l'application SAML d'exemple IBM Security Verify, vous pouvez accéder à
https://verifyapp.mybluemix.net puis cliquer sur Login. Cela déclenchera une authentification dans IBM Security Verify et le thème associé à l'application sera utilisé.

Mettre à jour un paquet de thème

Un thème qui existe déjà peut être mis à jour en appelant le point de terminaison REST pour ce thème.

Le point de terminaison REST pour un thème inclut l'ID du thème. Pour les commandes ci-dessous, il est supposé que l'ID du thème est contenu dans une variable d'environnement nommée theme_id. Si vous avez besoin de le rechercher, consultez les instructions ci-dessus.

Après avoir créé un fichier ZIP de paquet de thème mis à jour, utilisez la commande curl suivante pour appliquer la mise à jour :

curl -H "Authorization: Bearer ${access_token}" -X PUT "https://${tenant_url}/v1.0/branding/themes/${theme_id}" -F [email protected]

Manipuler des fichiers individuels

En plus d'importer et d'exporter des paquets de thèmes, il est également possible d'importer et d'exporter des fichiers de thème individuels.

Exporter un seul fichier

Vous pouvez télécharger un seul fichier depuis un thème. Le point de terminaison REST utilisé pour cela inclut l'ID du thème et le chemin du fichier à exporter. Par exemple, pour télécharger seulement le modèle de pied de page, utilisez la commande curl suivante :

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes/${theme_id}/common/page_components/default/page_footer.html" -o test-page_footer.html

Éditer le fichier téléchargé

Ouvrez le fichier test-page_footer.html téléchargé et éditez-le pour qu'il contienne ce qui suit :

<footer class="login-footer" role="contentinfo">
<p>Themed for sample application</p>
</footer> 

Enregistrez le fichier mis à jour.

Importer un seul fichier

Vous pouvez remplacer (ou ajouter) un seul fichier dans un thème. Le point de terminaison REST utilisé pour cela inclut l'ID du thème et le chemin du fichier à remplacer. Par exemple, pour remplacer seulement le pied de page dans le thème, utilisez la commande curl suivante :

curl -H "Authorization: Bearer ${access_token}" -X PUT "https://${tenant_url}/v1.0/branding/themes/${theme_id}/common/page_components/default/page_footer.html" -F file="@test-page_footer.html"

À ce point, vous pouvez tester le thème mis à jour, soit en spécifiant l'ID du thème directement soit en déclenchant une connexion en utilisant une application qui a le thème configuré.

Rétablir un fichier au défaut

Vous pouvez rétablir un fichier personnalisé à son état original en appelant son point de terminaison avec la méthode DELETE. Par exemple, pour rétablir le fichier page_footer.html, utilisez la commande curl suivante :

curl -H "Authorization: Bearer ${access_token}" -X DELETE "https://${tenant_url}/v1.0/branding/themes/${theme_id}/common/page_components/default/page_footer.html"

Télécharger un fichier ZIP contenant seulement les fichiers mis à jour

Si vous voulez télécharger seulement les fichiers modifiés d'un thème, cela peut être fait en utilisant la commande curl suivante :

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes/${theme_id}?customized_only=true" -o test-theme-updates-only.zip

Vous pouvez également effectuer un PUT d'une archive contenant seulement un sous-ensemble de fichiers de thème. Cela remplacera seulement ces fichiers dans le thème.

Supprimer un thème

Vous pouvez supprimer un thème en utilisant la méthode DELETE sur le point de terminaison REST du thème. Un appel comme celui-ci supprimera un thème :

🚧

Les fichiers de thème seront supprimés

Cet appel d'API supprimera le thème incluant tous les fichiers associés au thème. Assurez-vous d'avoir une copie locale de tous les fichiers de thème que vous pourriez vouloir utiliser à nouveau dans le futur.

curl -H "Authorization: Bearer ${access_token}" -X DELETE "https://${tenant_url}/v1.0/branding/themes/${theme_id}"

Notez qu'un thème ne peut pas être supprimé s'il est référencé dans une ou plusieurs définitions d'application. Si c'est le cas, vous recevrez une erreur (avec le code de statut 405) :

{
  "messageId":"CSIAZ3024E",
  "messageDescription":"The system cannot delete the theme with the ID [b18d817b-6409-4fa1-8de4-308519937d25] because it is used by an application."
}

Réinitialiser le thème par défaut à son état original

Pour réinitialiser le thème par défaut à son état original, exportez le paquet de thème original puis utilisez-le pour remplacer le paquet de thème par défaut. Ces deux commandes curl effectueront ces étapes :

🚧

Les fichiers de thème seront écrasés

Ces appels d'API écraseront tous les fichiers dans le thème par défaut. Assurez-vous d'avoir une copie locale de tous les fichiers de thème que vous pourriez vouloir utiliser à nouveau dans le futur.

curl -H "Authorization: Bearer ${access_token}" -X GET "https://${tenant_url}/v1.0/branding/themes/master" -o original-theme.zip
curl -H "Authorization: Bearer ${access_token}" -X PUT "https://${tenant_url}/v1.0/branding/themes/default" -F [email protected]

Réinitialiser tout le branding

Si vous voulez réinitialiser tout le branding à son état original, vous pouvez utiliser l'API de modèles suivante. Cette demande d'API supprimera tous les thèmes et réinitialisera le thème par défaut à son état original.

Avant d'utiliser cette API, toutes les applications doivent être configurées pour utiliser le thème par défaut. Cette API retournera une erreur si un thème est en cours d'utilisation.

❗️

Cette demande d'API supprimera tous les thèmes

Assurez-vous d'avoir exporté tous les thèmes que vous pourriez vouloir restaurer plus tard.

curl -H "Authorization: Bearer ${access_token}" -X DELETE "https://${tenant_url}/v1.0/branding/reset"

💎

Jon Harry, IBM Security