Gestion des thèmes

Introduction

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

Vous pouvez avoir plusieurs thèmes dans votre locataire et vous pouvez assigner des thèmes à une ou plusieurs applications. Il existe également 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 du présent document, il n'y a pas d'interface utilisateur associée à la gestion de l'importation et de l'exportation des thèmes dans l'interface d'administration. Au lieu de cela, vous devez utiliser les appels REST. Cet article montre comment créer la classe REST requise à l'aide de 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 devez 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 l'habilitation Manage Templates, puis d'exécuter le flux de subvention Client Credentials pour obtenir un jeton d'accès.

Afin d'apprécier pleinement les thèmes, vous devez avoir au moins une application définie dans votre locataire IBM Verify. Si vous n'avez pas encore de demande, vous pouvez connecter un exemple de demande.

Vous aurez besoin de l'utilitaire de ligne de commande curl. Cette fonction est intégrée dans la plupart des systèmes Linux et MacOS. Toutefois, si nécessaire, vous pouvez télécharger curl ici.

En option, si vous souhaitez 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 devez définir ces variables sur la ligne de commande comme suit :

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

Obtenir une liste des thèmes disponibles

Tout d'abord, vous utiliserez votre jeton d'accès pour obtenir une liste des thèmes disponibles dans votre locataire. Cela permettra également de 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 le format suivant :

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

Le résultat ci-dessus provient d'un locataire propre. Vous pouvez constater qu'il n'existe qu'un seul thème default.

Télécharger un paquet de thèmes et l'extraire

Un paquet de thèmes est téléchargé en effectuant une requête GET au point de terminaison REST pour ce thème.
Le point de terminaison REST d'un thème comprend l'identifiant du thème. Le paquet de thèmes est renvoyé sous la forme d'une archive ZIP.

📘

Obtenir un thème original

Vous pouvez spécifier master comme ID du thème pour télécharger le package original du thème. Ceci est utile si vous avez mis à jour le thème par défaut et que vous avez besoin d'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'archivage favori ou, si vous avez unzip, utiliser cette commande pour décompresser dans un répertoire appelé extracted-theme :

unzip -d extracted-theme default-theme.zip

Vous disposez maintenant d'un répertoire de thèmes extraits contenant les modèles de thèmes exportés.

Explorer la structure du dossier du thème

Si vous regardez dans le répertoire du thème extrait que vous venez de créer, vous verrez qu'il contient un seul répertoire de modèles. Il s'agit du répertoire racine du paquetage du thème. À l'intérieur de ce répertoire, vous trouverez les dossiers suivants, qui répartissent les fichiers de modèles en fonction de leur finalité :

Le dernier dossier de la structure des répertoires est le dossier locale. Dans le thème par défaut, la plupart des contenus locaux sont stockés dans le dossier templates/common/labels. Vous verrez qu'il y a de nombreux dossiers linguistiques. Dans la plupart des autres endroits, il n'y a qu'un dossier default. Ce dossier est utilisé lorsqu'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.

Modifier les fichiers communs

Les ressources du répertoire /templates/common sont utilisées par d'autres pages du thème. Vous allez maintenant modifier certains de ces fichiers.

Mise à jour d'une étiquette

Le fichier template_labels.properties contient des étiquettes qui sont utilisées dans les pages 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 de dollar ($) (par exemple $PRODUCT_NAME$ ).

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

Trouvez la définition de LOGIN_USER_NAME et remplacez-la par quelque chose de nouveau :

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

Mise à jour de l'en-tête de la page

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

Vous pouvez voir que cet extrait charge simplement une image de logo. Cette image est en fait chargée à partir du répertoire /templates/common/logo/default. Remarquez le ?themeId=@THEME_ID@ à la fin de l' URL. Cette chaîne de requête détermine le thème qui sera utilisé lors du chargement du fichier. La macro THEME_ID sera définie sur le 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èmes et le télécharger en tant que nouveau thème

Vous allez maintenant ZIPer le paquet de thème mis à jour et le télécharger sur votre locataire IBM Verify en tant que nouveau thème.

Pour créer le paquet, utilisez votre outil d'archivage favori pour ZIP le répertoire des modèles. Si vous disposez de l'utilitaire zip, assurez-vous d'être dans le répertoire default-theme et utilisez cette commande :

zip -r test-theme.zip templates

Cette opération permet d'enregistrer le fichier test-theme.zip dans le répertoire actuel.

Pour enregistrer un nouveau thème à l'aide du paquet "nouveau thème", utilisez la commande curl suivante.
Si votre jeton d'accès a expiré, vous devrez peut-être exécuter à nouveau le flux de jetons 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"}'

Recherche de l'identifiant du thème

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

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

Le résultat sera le suivant :

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

Recherchez le site id associé au thème du test. Dans l'exemple ci-dessus, il s'agit de b18d817b-6409-4fa1-8de4-308519937d25. Le vôtre sera différent. Enregistrez cette information dans la variable d'environnement theme_id :

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

Si vous disposez de `jq`, vous pouvez exécuter cette commande qui effectuera l'appel REST, analysera la réponse JSON et remplira la variable d'environnement theme_id :

```curl curl+jq
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}

Lors du rendu de la page, le themeId spécifié dans la chaîne de requête sera utilisé. Vous devriez voir les modifications apportées à votre thème de test reflétées dans la page affichée :

Attribuer un thème à une application

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

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

Tester un thème spécifique à une application

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

• Réalisation d'une authentification initiale déclenchée par l'accès à l'application
• Effectuer une authentification à plusieurs facteurs lors de la tentative d'accès à l'application
• Réception d'un e-mail relatif au processus d'autorisation de l'application
• Réception d'e-mails relatifs à une campagne de certification pour l'application

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

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

Mise à jour d'un paquet de thèmes

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 d'un thème comprend l'identifiant du thème. Pour les commandes ci-dessous, on suppose que l'identifiant du thème est contenu dans une variable d'environnement nommée theme_id. Si vous avez besoin de vérifier cela, consultez les instructions ci-dessus.

Après avoir créé un fichier ZIP de mise à jour du paquet de thèmes, 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]

Manipulation de fichiers individuels

Outre l'importation et l'exportation de paquets de thèmes, il est également possible d'importer et d'exporter des fichiers de thèmes individuels.

Exporter un seul fichier

Vous pouvez télécharger un seul fichier à partir d'un thème. Le point de terminaison REST utilisé à cet effet comprend l'identifiant du thème et le chemin d'accès au fichier à exporter. Par exemple, pour télécharger uniquement 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

Modifier le fichier téléchargé

Ouvrez le fichier test-page_footer.html téléchargé et modifiez-le de manière à ce qu'il contienne les éléments suivants :

<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é à cet effet comprend l'identifiant du thème et le chemin d'accès au fichier à remplacer. Par exemple, pour remplacer uniquement 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 stade, vous pouvez tester le thème mis à jour, soit en spécifiant directement l'ID du thème, soit en déclenchant une connexion à l'aide d'une application dans laquelle le thème est configuré.

Rétablir la valeur par défaut d'un fichier

Vous pouvez rétablir l'état initial d'un fichier personnalisé en appelant son point de terminaison avec la méthode DELETE. Par exemple, pour inverser 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 uniquement les fichiers mis à jour

Si vous souhaitez télécharger uniquement les fichiers modifiés d'un thème, vous pouvez le faire 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 placer une archive ne contenant qu'un sous-ensemble de fichiers de thème. Cela remplacera uniquement ces fichiers dans le thème.

Suppression d'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 de ce type permet de supprimer un thème :

🚧

Les fichiers du thème seront supprimés

Cet appel de l'API supprimera le thème ainsi que tous les fichiers associés au thème. Assurez-vous de disposer d'une copie locale de tous les fichiers de thème que vous souhaiteriez réutiliser à l'avenir.

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 un code d'état 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établir le thème par défaut dans son état d'origine

Pour rétablir le thème par défaut dans son état d'origine, exportez le paquet de thèmes original et utilisez-le pour remplacer le paquet de thèmes par défaut. Ces deux commandes curl permettent de réaliser ces étapes :

🚧

Les fichiers du thème seront écrasés

Ces appels à l'API écraseront tous les fichiers du thème par défaut. Assurez-vous de disposer d'une copie locale de tous les fichiers de thème que vous souhaiteriez réutiliser à l'avenir.

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 toutes les marques

Si vous souhaitez rétablir l'état d'origine de toutes les marques, vous pouvez utiliser les modèles API suivants. Cette demande d'API supprimera tous les thèmes et rétablira le thème par défaut dans son état d'origine.

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

❗️

Cette requête API supprimera tous les thèmes

Assurez-vous d'avoir exporté tous les thèmes que vous souhaiteriez restaurer ultérieurement.

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

jon Harry, IBM Sécurité