Informations de référence sur les développeurs BHOLD pour Microsoft Identity Manager 2016

Le module BHOLD-core peut traiter les commandes de script. Elle peut être effectuée directement à l’aide de l'bscript.dll dans un projet .NET. Interaction avec l’interface b1scriptservice.asmx du service web.

Avant l’exécution d’un script, toutes les informations contenues dans le script doivent être collectées pour composer ce script. Ces informations peuvent être collectées à partir des sources suivantes :

• Entrée utilisateur
• Données BHOLD
• Applications
• Autre

Les données BHOLD peuvent être récupérées à l’aide de la fonction GetInfo de l’objet de script. Il existe une liste complète des commandes qui peuvent présenter toutes les données stockées dans la base de données BHOLD. Toutefois, les données présentées sont soumises aux autorisations d’affichage de l’utilisateur connecté. Le résultat est sous la forme d’un document XML qui peut être analysé.

Une autre source d’informations peut être l’une des applications contrôlées par BHOLD. Le composant logiciel enfichable d’application a une fonction spéciale, FunctionDispatch, qui peut être utilisée pour présenter des informations spécifiques à l’application. Il s’agit également d’un document XML.

Enfin, s’il n’existe aucun autre moyen, le script peut contenir des commandes directement vers d’autres applications ou systèmes. NoThenstallation d’un logiciel supplémentaire sur le serveur BHOLD peut compromettre la sécurité de l’ensemble du système.

Toutes ces informations sont placées dans un document XML et affectées à l’objet de script BHOLD. L’objet combine ce document avec une fonction prédéfinie. La fonction prédéfinie est un document XSL qui traduit le document d’entrée de script en document de commande BHOLD.

de traitement de script BHOLD

Les commandes sont exécutées dans le même ordre que dans le document. Si une fonction échoue, toutes les commandes exécutées sont restaurées.

Objet script

Cette section explique comment utiliser l’objet de script.

Récupérer les informations BHOLD

La fonction GetInfo est utilisée pour récupérer des informations à partir des données disponibles dans le système d’autorisation BHOLD. La fonction nécessite un nom de fonction et finalement un ou plusieurs paramètres. Si cette fonction réussit, un objet ou une collection BHOLD est retourné sous la forme d’un document XML.

Si la fonction ne réussit pas, la fonction GetInfo retourne une chaîne vide ou une erreur. La description et le nombre d’erreurs peuvent être utilisés pour obtenir plus d’informations sur l’échec.

La fonction GetInfo « FunctionDispatch » peut être utilisée pour récupérer des informations d’une application contrôlée par le système BHOLD. Cette fonction nécessite trois paramètres : l’ID de l’application, la fonction de répartition telle qu’elle est définie dans l’ASI et un document XML avec des informations de prise en charge pour l’ASI. Si la fonction réussit, le résultat est disponible au format XML dans l’objet de résultat.

L’extrait de code ci-dessous est un exemple C# simple de GetInfo :

ScriptProcessor myScriptProcessor = new ScriptProcessor();
myScriptProcessor.Initializae("CORP\\b1user");
myScriptProcessor.GetInfo("OrgUnit", "1");

De même, l’objet BScript est également accessible via le service web b1scriptservice. Pour ce faire, ajoutez une référence web à votre projet à l’aide de http://<serveur>:5151/BHOLD/Core/b1scriptservice.asmx où <serveur> est le serveur avec les fichiers binaires BHOLD installés. Pour plus d’informations, consultez Ajout d’une référence de service web à un projet Visual Studio.

L’exemple suivant montre comment utiliser la fonction GetInfo à partir d’un service web. Ce code récupère l’unité d’organisation qui a un ORGID de 1, puis affiche le nom de cette unité d’organisation à l’écran.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml;

namespace bhold_console
{
    class Program
    {
        static void Main(string[] args)
        {
             var bholdService = new BHOLDCORE.B1ScriptService();
             bholdService.Url = "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx";
             string orgname= "";

             if (args.Length == 3)
             {
                 //Use explicit credentials from command line
                 bholdService.UseDefaultCredentials = false;
                 bholdService.Credentials = new System.Net.NetworkCredential(args[0], args[1], args[2]);
                 bholdService.PreAuthenticate = true;
             }
             else
             {
                 bholdService.UseDefaultCredentials = true;
                 bholdService.PreAuthenticate = true;
             }

             //Load BHOLD information into an xml document and loop through document to find the bholdDescription value
             var myOrgUnit = new System.Xml.XmlDocument();
             myOrgUnit.LoadXml(bholdService.GetInfo("OrgUnit","1","","");

            XmlNodeList myList = myOrgUnit.SelectNodes(("//item");

            foreach (XmlNode myNode in myList)
            {
                for (int i = 0; i < myNode.ChildNodes.Count; i++)
                {
                    if (myNode.ChildNodes[i].InnerText.ToString() == "bholdDescription")
                    {
                        orgname = myNode.ChildNodes[i + 1].InnerText.ToString();
                    }
                }
            }

            System.Console.WriteLine("The Organizational Unit Name is: " + orgname);

        }
    }
}

L’exemple VBScript suivant utilise le service web via SOAP et à l’aide de GetInfo. Pour obtenir des exemples supplémentaires pour SOAP 1.1, SOAP 1.2 et HTTP POST, consultez la section Référence managée BHOLD, ou vous pouvez accéder au service web directement à partir d’un navigateur et les afficher.

Dim SOAPRequest
Dim SOAPParameters
Dim SOAPResponse
Dim xmlhttp

Set xmlhttp = CreateObject("Microsoft.XMLHTTP")

xmlhttp.open "POST", "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx", False, "CORP\Administrator", "abc123*2k"

xmlhttp.setRequestHeader "Content-type", "text/xml; charset=utf-8"
xmlhttp.setRequestHeader "SOAPAction", "http://B1/B1ScriptService/GetInfo"

SOAPRequest = "<?xml version='1.0' encoding='utf-8'?> <soap:Envelope" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:xsi=""http://" & vbCRLF
SOAPRequest = SOAPRequest & " www.w3.org/2001/XMLSchema-instance""" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:xsd=""http://www.w3.org/2001/XMLSchema""" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"">" & vbCRLF
SOAPRequest = SOAPRequest & " <soap:Body>" & vbCRLF
SOAPRequest = SOAPRequest & " <GetInfo xmlns=""http://B1/B1ScriptService"">" & vbCRLF
SOAPRequest = SOAPRequest & " <functionName>OrgUnit</functionName>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter1>1</parameter1>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter2></parameter2>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter3></parameter3>" & vbCRLF
SOAPRequest = SOAPRequest & " </GetInfo>" & vbCRLF
SOAPRequest = SOAPRequest & " </soap:Body>" & vbCRLF
SOAPRequest = SOAPRequest & " </soap:Envelope>"
MsgBox SOAPRequest

xmlhttp.send SOAPRequest 

SOAPResponse = xmlhttp.responseText

MsgBox SOAPResponse

Exécuter des scripts

La fonction ExecuteScript de l’objet BScript peut être utilisée pour exécuter des scripts. Cette fonction nécessite deux paramètres. Le premier paramètre est le document XML qui contient les informations personnalisées à utiliser par le script. Le deuxième paramètre est le nom du script prédéfini à utiliser. Dans le répertoire de scripts prédéfinis BHOLD, il doit s’agir d’un document XSL portant le même nom que la fonction, mais avec l’extension .xsl.

Si la fonction ne réussit pas, la fonction ExecuteScript retourne la valeur False. La description et le nombre d’erreurs peuvent être utilisés pour savoir ce qui s’est passé. Voici un exemple d’utilisation de la méthode web ExecuteXML. Cette méthode appelle ExecuteScript.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Sample
{
    class Program
    {
        static void Main(string[] args)
        {
            var bholdService = new BHOLDCORE.B1ScriptService();
            bholdService.Url = "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx";

            if (args.Length == 3)
            {
                //Use explicit credentials from command line
                bholdService.UseDefaultCredentials = false;
                bholdService.Credentials = new System.Net.NetworkCredential(args[0], args[1], args[2]);
                bholdService.PreAuthenticate = true;
            }
            else
            {
                bholdService.UseDefaultCredentials = true;
                bholdService.PreAuthenticate = true;
            }
            System.Console.WriteLine( "Add user #3 to role #44, result: {0}", bholdService.ExecuteXml(roleAddUser("44", "3")) );
            System.Console.WriteLine("Add user D1 to role 'MR-OU2 No Users', result: {0}", bholdService.ExecuteXml(roleAddUser("MR-OU2 No Users", "D1")));

        }

        private static System.Xml.XmlNode roleAddUser(string roleId, string userId)
        {
            var script = new System.Xml.XmlDocument();
            script.LoadXml(string.Format("<functions>"
                                        +"  <function name='roleadduser' roleid='{0}' userid='{1}' />"
                                        +"</functions>",
                                        roleId,
                                        userId)
                           );
            return script.DocumentElement;

BholdScriptResult

Cette fonction GetInfo est disponible une fois que la fonction d’exécution est exécutée. La fonction retourne une chaîne au format XML qui contient le rapport d’exécution complet. Le nœud Script contient la structure XML du script exécuté.

Pour chaque fonction qui échoue pendant l’exécution du script, une fonction de nœud est ajoutée avec le nom des nœuds. ExecuteXML et Error est ajouté à la fin du document, tous les ID générés sont ajoutés.

Notez que seules les fonctions qui contiennent une erreur sont ajoutées. Un nombre d’erreurs de « 0 » signifie que la fonction n’est pas exécutée.

<Bhold>
  <Script>
    <functions>
      <function name="OrgUnitadd" description="OrgUnit1" parentid="root" orgtypeid="root" return="@ID@"/>     
      <function name="roleaddOrgUnit" OrgUnitid="OrgUnit1" roleid="Role1_OrgUnit1" return="@ID@"/>      
    </functions>
  </Script>
  <Function>
    <Name>OrgUnitadd</Name>
    <ExecutedXML>
      <function name="OrgUnitadd" description="OrgUnit1" parentid="root" orgtypeid="root" return="@ID@"/>
    </ExecutedXML>
    <Error Number="5" Description="Violation of UNIQUE KEY constraint 'IX_OrgUnits'. Cannot insert duplicate key in object 'dbo.OrgUnits'.
The statement has been terminated."/>
  </Function>
  <Function>
    <Name>roleaddOrgUnit</Name>
    <ExecutedXML>
      <function name="roleaddOrgUnit" OrgUnitid="OrgUnit1" roleid="Role1_OrgUnit1" return="@ID@"/>
    </ExecutedXML>
    <Error Number="0" Description=""/>
  </Function>
  <IDS>
    <ID name="@ID@">35</ID>
  </IDS>
</Bhold>

Paramètres d’ID

Les paramètres d’ID reçoivent un traitement spécial. Les valeurs non numériques sont utilisées comme valeur de recherche pour localiser les entités correspondantes dans le magasin de données BHOLD. Lorsque la valeur de recherche n’est pas unique, la première entité conforme à la valeur de recherche est retournée.

Pour distinguer les valeurs de recherche numériques des ID, il est possible d’utiliser un préfixe. Lorsque les six premiers caractères de la valeur de recherche sont égaux à « no_id : », ces caractères sont supprimés avant que la valeur ne soit utilisée pour la recherche. Les caractères génériques SQL '%' peuvent être utilisés.

Les champs suivants sont utilisés avec la valeur de recherche :

Accès et autorisations de script

Le code côté serveur dans les pages Active Server est utilisé pour exécuter les scripts. Par conséquent, l’accès au script signifie l’accès à ces pages. Le système BHOLD conserve des informations sur les points d’entrée des pages personnalisées. Ces informations incluent la page de démarrage et la description de la fonction (plusieurs langues doivent être prises en charge).

Un utilisateur est autorisé à entrer les pages personnalisées et à exécuter un script. Chaque point d’entrée est présenté sous la forme d’une tâche. Chaque utilisateur ayant obtenu cette tâche via un rôle ou une unité est en mesure d’exécuter la fonction correspondante.

Une nouvelle fonction dans le menu présente toutes les fonctions personnalisées qui peuvent être exécutées par l’utilisateur. Étant donné qu’un script peut effectuer des actions dans le système BHOLD sous une identité différente de celle de l’utilisateur connecté. Il est possible de donner l’autorisation d’effectuer une action spécifique sans avoir de supervision sur un objet. Par exemple, cela peut être utile pour un employé qui n’est autorisé qu’à entrer de nouveaux clients dans l’entreprise. Ces scripts peuvent également être utilisés pour créer des pages auto-inscrites.

Script de commande

Le script de commande contient une liste de fonctions exécutées par le système BHOLD. La liste est écrite dans un document XML conforme aux définitions suivantes :

XML contient les traductions suivantes de caractères spéciaux :

Ces caractères XML peuvent être utilisés dans des identificateurs, mais ils ne sont pas recommandés.

Le code suivant montre un exemple de document de commande valide avec trois fonctions :

<functions>

   <functionname="OrgUnitAdd" parentID="34" description="Acme Inc." orgtypeID="5" return="@UnitID@" />

   <function name="UserAdd" description="John Doe" alias="jdoe" languageID="1" OrgUnitID="@UnitID@" />

   <function name="TaskAddFile" taskID="93" path="/customers/purchase">
      <parameters>
         <parameter name="history"> True</parameter>
      </parameters>
   </function>

</functions>

La fonction OrgUnitAdd stocke l’ID de l’unité créée dans une variable appelée UnitID. Cette variable est utilisée comme entrée pour la fonction UserAdd. La valeur de retour de cette fonction n’est pas utilisée. Les sections suivantes décrivent toutes les fonctions disponibles, les paramètres requis et leurs valeurs de retour.

Exécuter des fonctions

Cette section explique comment utiliser les fonctions d’exécution.

ABAAttributeRuleAdd

Créez une règle d’attribut sur un type d’attribut spécifique. Les règles d’attribut ne peuvent être liées qu’à un seul type d’attribut.

La règle d’attribut spécifiée peut être liée à tous les types d’attributs possibles.

Le RuleType ne peut pas être modifié avec la commande « ABAattributeruletypeupdate ». Exige que la description de l’attribut soit unique.

applicationadd

Crée une application, retourne l’ID de la nouvelle application.

AttributeSetValue

Définit la valeur d’un type d’attribut connecté au type d’objet. Nécessite que les descriptions du type d’objet et du type d’attribut soient uniques.

AttributeTypeAdd

Insère un nouveau type d’attribut/type de propriété.

AttributeTypeSetAdd

Insère un nouveau jeu de types d’attributs. Exige que la description d’un jeu de types d’attributs soit unique.

AttributeTypeSetAddAttributeType

Insère un nouveau type d’attribut dans un jeu de types d’attributs existant. Exige que les descriptions du jeu de types d’attributs et du type d’attribut soient uniques.

ObjectTypeAddAttributeTypeSet

Ajoute un type d’attribut défini à un type d’objet. Nécessite que la description du type d’objet et le jeu de types d’attributs soient uniques. Les types d’objets sont : System, OrgUnit, User, Task.

OrgUnitad

Crée une unité d’organisation, retourne l’ID de la nouvelle unité organisationnelle.

OrgUnitadsupervisor

Faire d’un utilisateur un superviseur d’une unité organisationnelle.

OrgUnitadduser

Faire d’un utilisateur un membre d’une unité organisationnelle.

OrgUnitdelete

Supprime une unité d’organisation.

OrgUnitdeleteuser

Supprime un utilisateur en tant que membre d’une unité organisationnelle.

roleadd

Crée un rôle.

roleaddOrgUnit

Attribue un rôle à une unité organisationnelle.

roleaddrole

Attribue un rôle en tant que sous-rôle d’un autre rôle.

roleaddsupervisor

Faire d’un utilisateur un superviseur d’un rôle.

roleadduser

Attribue un rôle à un utilisateur. Le rôle ne peut pas être un rôle adaptable au contexte lorsqu’aucun contextID n’est donné.

roledelete

Supprime un rôle.

roledeleteuser

Supprime l’attribution de rôle à un utilisateur. Les rôles hérités par l’utilisateur sont révoqués par cette commande.

roleproposeOrgUnit

Propose un rôle pour l’affecter aux membres et aux sous-OrgUnits d’un OrgUnit.

taskadd

Crée une tâche, retourne l’ID de la nouvelle tâche.

taskadditask

Indiquez que deux tâches sont incompatibles.

taskaddrole

Affecte une tâche à un rôle.

taskaddsupervisor

Faire d’un utilisateur un superviseur d’une tâche.

useradd

Crée un utilisateur, retourne l’ID du nouvel utilisateur.

UserAddRole

Ajoute un rôle d’utilisateur.

UserDeleteRole

Supprime un rôle d’utilisateur.

Userupdate

Met à jour un utilisateur.

GetInfo Functions

L’ensemble de fonctions décrites dans cette section peut être utilisé pour récupérer des informations stockées dans le système BHOLD. Chaque fonction peut être appelée à l’aide de la fonction GetInfo à partir de l’objet BScript. Certains objets nécessitent des paramètres. Les données retournées sont soumises aux autorisations d’affichage et aux objets supervisés de l’utilisateur connecté.

Arguments GetInfo

OrgUnit Info

Informations sur les rôles

Autorisation - Informations sur les tâches

Informations utilisateur

Types de retour

Dans cette section, les types de retour de la fonction GetInfo sont décrits.

Exemple de script

Une entreprise dispose d’un serveur BHOLD et souhaite un script automatisé qui crée de nouveaux clients. Les informations sur l’entreprise et son responsable d’achat entrent dans une page web personnalisée. Chaque client est présenté dans le modèle en tant qu’unité sous les clients de l’unité. Le responsable de l’achat est aussi bien membre qu’un superviseur de cette unité. Un rôle est créé qui donne aux propriétaires le droit d’acheter en nom du nouveau client.

Toutefois, ce client n’existe pas dans l’application. Une fonction spéciale est implémentée dans asI FunctionDispatch qui crée un compte client dans l’application d’achat. Chaque client a un type de client.

Les types possibles peuvent également être présentés par la fonction FunctionDispatch. L’AA choisit le type approprié pour le nouveau client.

Créez un rôle et une tâche pour présenter les privilèges d’achat. Le privilège d’achat réel est présenté par l’ASI en tant que fichier /customers/customer id/purchase. Ce fichier doit être lié à la nouvelle tâche.

La page Active Server qui collecte les informations ressemble à ceci :

<%@ Language=VBScript %>
<% Option Explicit %>
<html>
<body>
<form action="MySubmit.asp" method=post>
<input type="hidden" name="OrgUnitID" 
     value="<% = Request("ID") %>">
Company <input type="text" name="Description"> <br>
Type <select name="OrgType">
<%Dim oOrgType
For Each oOrgType on bscript.getinfo("Orgtypes") %>
<option value="<% = oOrgType.OrgTypeID %>">
<% = oOrgType.Description %>
</option> <%
Next %>
</select>  <br>
Manager <input type="text" name=" manager"> <br>
Alias <input type=" text" name=" alias"> <br>
e-mail <input type=" text" name=" email"> <br>
<input type="submit">
</form>
</body>
</html>

Toutes les pages personnalisées doivent effectuer une demande d’informations appropriées et créer un document XML avec les informations demandées. Dans cet exemple, la page MySubmit transforme les données dans le document XML, l’assignez au b1script. Les paramètres objet et appellent enfin la fonction b1script.ExecuteScript("MyScript").

Le script d’entrée suivant montre cet exemple :

<customer>
<description>ACME inc.</description>
<orgtype>5<orgtype>
<name>John Doe</name>
<alias>jdoe</alias>
<email>jdoe@acme.com</email>
</customer>

Ce script d’entrée ne contient aucune commande pour BHOLD. Cela est dû au fait que ce script n’est pas exécuté directement par BHOLD ; Au lieu de cela, il s’agit de l’entrée d’une fonction prédéfinie. Cette fonction prédéfinie traduit cet objet en document XML avec des commandes BHOLD. Ce mécanisme empêche l’utilisateur d’envoyer des scripts au système BHOLD qui contiennent des fonctions que l’utilisateur n’est pas autorisé à exécuter, telles que setUser et les répartitions de fonction vers un ASI.

<?xml version="1.0" encoding="utf-8" ?> 
- <functions xmlns="http://tempuri.org/BscriptFunctions.xsd">

  <function name="roleadduser" roleid="" userid="" /> 
  <function name="roledeleteuser" roleid="" userid="" /> 
  </functions>

Étapes suivantes

• guide des concepts BHOLD
• historique des versions BHOLD