BHOLD-Entwicklerreferenz für Microsoft Identity Manager 2016

Das BHOLD-Core-Modul kann Skriptbefehle verarbeiten. Dies kann mithilfe der bscript.dll in einem .NET-Projekt direkt erfolgen. Interagiert auch mit dem Webdienst b1scriptservice.asmx-Schnittstelle.

Bevor ein Skript ausgeführt wurde, sollten alle Informationen innerhalb des Skripts gesammelt werden, um dieses Skript zu verfassen. Diese Informationen können aus den folgenden Quellen gesammelt werden:

• Benutzereingabe
• BHOLD-Daten
• Anträge
• Andere

Die BHOLD-Daten können mithilfe der GetInfo-Funktion des Skriptobjekts abgerufen werden. Es gibt eine vollständige Liste der Befehle, die alle in der BHOLD-Datenbank gespeicherten Daten darstellen können. Die angezeigten Daten unterliegen jedoch den Ansichtsberechtigungen des angemeldeten Benutzers. Das Ergebnis ist in Form eines XML-Dokuments, das analysiert werden kann.

Eine weitere Informationsquelle kann eine der Anwendungen sein, die von BHOLD gesteuert werden. Das Anwendungs-Snap-In verfügt über eine spezielle Funktion, die FunctionDispatch, die verwendet werden kann, um anwendungsspezifische Informationen darzustellen. Dies wird auch als XML-Dokument dargestellt.

Wenn es keine andere Möglichkeit gibt, kann das Skript Befehle direkt für andere Anwendungen oder Systeme enthalten. NoThenstallation von zusätzlicher Software auf dem BHOLD-Server kann die Sicherheit des gesamten Systems untergraben.

Alle diese Informationen werden in ein XML-Dokument eingefügt und dem BHOLD-Skriptobjekt zugewiesen. Das Objekt kombiniert dieses Dokument mit einer vordefinierten Funktion. Die vordefinierte Funktion ist ein XSL-Dokument, das das Skripteingabedokument in ein BHOLD-Befehlsdokument übersetzt.

Die Befehle werden in der gleichen Reihenfolge ausgeführt wie im Dokument. Wenn eine Funktion fehlschlägt, werden alle ausgeführten Befehle zurückgesetzt.

Script-Objekt

In diesem Abschnitt wird die Verwendung des Skriptobjekts beschrieben.

Abrufen von BHOLD-Informationen

Die GetInfo--Funktion wird verwendet, um Informationen aus den verfügbaren Daten im BHOLD-Autorisierungssystem abzurufen. Die Funktion erfordert einen Funktionsnamen und schließlich einen oder mehrere Parameter. Wenn diese Funktion erfolgreich ist, wird ein BHOLD-Objekt oder eine Auflistung in Form eines XML-Dokuments zurückgegeben.

Wenn die Funktion nicht erfolgreich ist, gibt die GetInfo-Funktion eine leere Zeichenfolge oder einen Fehler zurück. Die Fehlerbeschreibung und -nummer können verwendet werden, um weitere Informationen zum Fehler zu erhalten.

Die GetInfo-Funktion 'FunctionDispatch' kann verwendet werden, um Informationen aus einer Anwendung abzurufen, die vom BHOLD-System gesteuert wird. Diese Funktion erfordert drei Parameter: Die ID der Anwendung, die Dispatch-Funktion, wie sie in der ASI definiert ist, und ein XML-Dokument mit unterstützenden Informationen für die ASI. Wenn die Funktion erfolgreich ist, ist das Ergebnis im XML-Format im Ergebnisobjekt verfügbar.

Der folgende Codeausschnitt ist ein einfaches C#-Beispiel für GetInfo:

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

Ebenso kann auf das BScript--Objekt auch über den Webdienst b1scriptservicezugegriffen werden. Dazu fügen Sie einen Webverweis zu Ihrem Projekt mithilfe von http://<Server>:5151/BHOLD/Core/b1scriptservice.asmx hinzu, wobei <Server> der Server ist, auf dem die BHOLD-Binärdateien installiert sind. Weitere Informationen finden Sie unter Hinzufügen eines Webdienstverweises zu einem Visual Studio-Projekt.

Das folgende Beispiel zeigt, wie Sie die GetInfo-funktion aus einem Webdienst verwenden. Dieser Code ruft die Organisationseinheit mit einer OrgID von 1 ab und zeigt dann den Namen dieser Organisationseinheit auf dem Bildschirm an.

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);

        }
    }
}

Im folgenden VBScript-Beispiel wird der Webdienst über SOAP und getInfo verwendet. Weitere Beispiele für SOAP 1.1, SOAP 1.2 und HTTP POST finden Sie im Abschnitt "BHOLD Managed Reference", oder Sie können direkt über einen Browser zum Webdienst navigieren und dort anzeigen.

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

Ausführen von Skripts

Die ExecuteScript--Funktion des BScript--Objekts kann zum Ausführen von Skripts verwendet werden. Für diese Funktion sind zwei Parameter erforderlich. Der erste Parameter ist das XML-Dokument, das die benutzerdefinierten Informationen enthält, die vom Skript verwendet werden sollen. Der zweite Parameter ist der Name des zu verwendenden vordefinierten Skripts. In the BHOLD predefined scripts directory, here should be an XSL document with the same name as the function, but with the .xsl extension.

Wenn die Funktion nicht erfolgreich ist, gibt die ExecuteScript-Funktion den Wert False zurück. Die Fehlerbeschreibung und -nummer können verwendet werden, um zu wissen, was schief gelaufen ist. Im Folgenden sehen Sie ein Beispiel für die Verwendung der ExecuteXML-Webmethode. Diese Methode ruft ExecuteScript auf.

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

Diese GetInfo-Funktion ist verfügbar, nachdem die executescript--Funktion ausgeführt wurde. Die Funktion gibt eine XML-formatierte Zeichenfolge zurück, die den vollständigen Ausführungsbericht enthält. Der Skriptknoten enthält die XML-Struktur des ausgeführten Skripts.

Für jede Funktion, die während der Ausführung des Skripts fehlschlägt, wird eine Node-Funktion mit dem Knotennamen hinzugefügt. ExecuteXML und Error werden am Ende des Dokuments alle generierten IDs hinzugefügt.

Beachten Sie, dass nur die Funktionen, die einen Fehler enthalten, hinzugefügt werden. Eine Fehlernummer von "0" bedeutet, dass die Funktion nicht ausgeführt wird.

<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>

ID-Parameter

ID-Parameter erhalten eine spezielle Behandlung. Nicht numerische Werte werden als Suchwert zum Suchen der entsprechenden Entitäten im BHOLD-Datenspeicher verwendet. Wenn der Suchwert nicht eindeutig ist, wird die erste Entität zurückgegeben, die dem Suchwert entspricht.

Um numerische Suchwerte von IDs zu unterscheiden, ist es möglich, ein Präfix zu verwenden. Wenn die ersten sechs Zeichen des Suchwerts gleich "no_id:" sind, werden diese Zeichen entfernt, bevor der Wert für die Suche verwendet wird. SQL-Wildcardzeichen '%' können verwendet werden.

Die folgenden Felder werden mit dem Suchwert verwendet:

Skriptzugriff und -berechtigungen

Serverseitiger Code in den Active Server Pages wird verwendet, um die Skripts auszuführen. Daher bedeutet der Zugriff auf das Skript Zugriff auf diese Seiten. Das BHOLD-System verwaltet Informationen über die Einstiegspunkte der benutzerdefinierten Seiten. Zu diesen Informationen gehören Startseite und Funktionsbeschreibung (mehrere Sprachen sollten unterstützt werden).

Ein Benutzer ist berechtigt, die benutzerdefinierten Seiten einzugeben und ein Skript auszuführen. Jeder Einstiegspunkt wird als Aufgabe dargestellt. Jeder Benutzer, der diese Aufgabe über eine Rolle oder eine Einheit gewonnen hat, kann die entsprechende Funktion ausführen.

Eine neue Funktion im Menü stellt alle benutzerdefinierten Funktionen dar, die vom Benutzer ausgeführt werden können. Da ein Skript Aktionen im BHOLD-System unter einer Identität ausführen kann, die sich von dem angemeldeten Benutzer unterscheidet. Es ist möglich, eine bestimmte Aktion auszuführen, ohne eine Aufsicht über ein Objekt zu haben. Dies kann z. B. für einen Mitarbeiter nützlich sein, der nur neue Kunden in das Unternehmen aufnehmen darf. Diese Skripts können auch zum Erstellen von Selbstregisterseiten verwendet werden.

Befehlsskript

Das Befehlsskript enthält eine Liste von Funktionen, die vom BHOLD-System ausgeführt werden. Die Liste wird in einem XML-Dokument geschrieben, das den folgenden Definitionen entspricht:

XML verfügt über die folgenden Übersetzungen von Sonderzeichen:

Diese XML-Zeichen können in Bezeichnern verwendet werden, aber sie werden nicht empfohlen.

Der folgende Code zeigt ein Beispiel für ein gültiges Befehlsdokument mit drei Funktionen:

<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>

Die Funktion OrgUnitAdd speichert die ID der erstellten Einheit in einer Variablen namens UnitID. Diese Variable wird als Eingabe für die UserAdd-Funktion verwendet. Der Rückgabewert dieser Funktion wird nicht verwendet. In den folgenden Abschnitten werden alle verfügbaren Funktionen, die erforderlichen Parameter und deren Rückgabewerte beschrieben.

Ausführen von Funktionen

In diesem Abschnitt wird die Verwendung der Ausführungsfunktionen beschrieben.

ABAAttributeRuleAdd

Erstellen Sie eine neue Attributregel für einen bestimmten Attributtyp. Attributregeln können nur mit einem Attributtyp verknüpft werden.

Die angegebene Attributregel kann mit allen möglichen Attributtypen verknüpft werden.

Der RuleType kann nicht mit dem Befehl "ABAattributeruletypeupdate" geändert werden. Erfordert, dass die Beschreibung des Attributs durch eindeutig ist.

applicationadd

Erstellt eine neue Anwendung, gibt die ID der neuen Anwendung zurück.

AttributeSetValue

Legt den Wert eines Attributtyps fest, der mit dem Objekttyp verbunden ist. Erfordert, dass die Beschreibungen des Objekttyps und der Attributtyp eindeutig sind.

AttributeTypeAdd

Fügt einen neuen Attributtyp /Eigenschaftstyp ein.

AttributeTypeSetAdd

Fügt einen neuen Attributtypsatz ein. Erfordert, dass die Beschreibung eines Attributtypsatzes eindeutig ist.

AttributeTypeSetAddAttributeType

Fügt einen neuen Attributtyp in einen vorhandenen Attributtypsatz ein. Erfordert, dass die Beschreibungen des Attributtypsatzes und des Attributtyps eindeutig sind.

ObjectTypeAddAttributeTypeSet

Fügt einem Objekttyp einen Attributtypsatz hinzu. Erfordert, dass die Beschreibung des Objekttyps und der Attributtypsatz eindeutig sind. Die Objekttypen sind: System, OrgUnit, User, Task.

OrgUnitadd

Erstellt eine neue Organisationseinheit, gibt die ID der neuen Organisationseinheit zurück.

OrgUnitaddsupervisor

Machen Sie einen Benutzer zu einem Vorgesetzten einer Organisationseinheit.

OrgUnitadduser

Machen Sie einen Benutzer zu einem Mitglied einer Organisationseinheit.

OrgUnitdelete

Entfernt eine Organisationseinheit.

OrgUnitdeleteuser

Entfernt einen Benutzer als Mitglied einer Organisationseinheit.

roleadd

Erstellt eine neue Rolle.

roleaddOrgUnit

Weist einer Organisationseinheit eine Rolle zu.

roleaddrole

Weist eine Rolle als Unterrole einer anderen Rolle zu.

roleaddsupervisor

Machen Sie einen Benutzer zu einem Vorgesetzten einer Rolle.

roleadduser

Weist einem Benutzer eine Rolle zu. Die Rolle kann keine kontextanpassungsfähige Rolle sein, wenn keine Kontext-ID angegeben wird.

roledelete

Löscht eine Rolle.

roledeleteuser

Entfernt die Rollenzuweisung für einen Benutzer. Geerbte Rollen durch den Benutzer werden von diesem Befehl widerrufen.

roleproposeOrgUnit

Schlägt eine Rolle vor, die sie den Mitgliedern und den Unter-OrgUnits einer OrgUnit zuweist.

taskadd

Erstellt einen neuen Vorgang, gibt die ID des neuen Vorgangs zurück.

taskadditask

Gibt an, dass zwei Vorgänge nicht kompatibel sind.

taskaddrole

Weist einer Rolle eine Aufgabe zu.

taskaddsupervisor

Machen Sie einen Benutzer zu einem Vorgesetzten einer Aufgabe.

useradd

Erstellt einen neuen Benutzer, gibt die ID des neuen Benutzers zurück.

UserAddRole

Fügt eine Benutzerrolle hinzu.

UserDeleteRole

Löscht eine Benutzerrolle.

UserUpdate

Aktualisiert einen Benutzer.

GetInfo-Funktionen

Die in diesem Abschnitt beschriebenen Funktionen können verwendet werden, um Informationen abzurufen, die im BHOLD-System gespeichert sind. Jede Funktion kann mithilfe der GetInfo-Funktion aus dem BScript-Objekt aufgerufen werden. Für einige Objekte sind Parameter erforderlich. Die zurückgegebenen Daten unterliegen den Ansichtsberechtigungen und den überwachten Objekten des angemeldeten Benutzers.

GetInfo-Argumente

OrgUnit-Informationen

Rolleninformationen

Berechtigung – Vorgangsinformationen

Benutzerinformationen

Rückgabetypen

In diesem Abschnitt werden die Rückgabetypen der GetInfo-Funktion beschrieben.

Skriptbeispiel

Ein Unternehmen verfügt über einen BHOLD-Server und möchte ein automatisiertes Skript, das neue Kunden erstellt. Die Informationen über das Unternehmen und dessen Einkaufsmanager geben auf einer angepassten Webseite ein. Jeder Kunde wird im Modell als Einheit unter den Einheitenkunden präsentiert. Der Einkaufsmanager ist ebenso Mitglied wie ein Vorgesetzter dieser Einheit. Eine Rolle wird erstellt, die den Besitzern das Recht gibt, im Namen des neuen Kunden zu kaufen.

Dieser Kunde ist jedoch in der Anwendung nicht vorhanden. In der ASI FunctionDispatch wird eine spezielle Funktion implementiert, die ein neues Kundenkonto in der Einkaufsanwendung erstellt. Jeder Kunde hat einen Kundentyp.

Die möglichen Typen können auch von der FunctionDispatch-Funktion dargestellt werden. Die AA wählt den richtigen Typ für den neuen Kunden aus.

Erstellen Sie eine Rolle und Aufgabe, um die Kaufberechtigungen darzustellen. Das echte Kaufrecht wird von der ASI als Datei /customers/customer id/purchasepräsentiert. Diese Datei sollte mit der neuen Aufgabe verknüpft werden.

Die Active Server-Seite, die die Informationen sammelt, sieht wie folgt aus:

<%@ 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>

Alle angepassten Seiten müssten die richtigen Informationen anfordern und ein XML-Dokument mit den angeforderten Informationen erstellen. In diesem Beispiel transformiert die Seite "MySubmit" die Daten im XML-Dokument, weisen Sie sie dem b1script zu. Parameter Objekt und ruft schließlich die b1script.ExecuteScript("MyScript")-Funktion auf.

Das folgende Eingabeskript zeigt dieses Beispiel:

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

Dieses Eingabeskript enthält keine Befehle für BHOLD. Dies liegt daran, dass dieses Skript nicht direkt von BHOLD ausgeführt wird; anstelle dessen ist dies die Eingabe für eine vordefinierte Funktion. Diese vordefinierte Funktion übersetzt dieses Objekt in ein XML-Dokument mit BHOLD-Befehlen. Mit diesem Mechanismus wird verhindert, dass der Benutzer Skripts an das BHOLD-System sendet, das Funktionen enthält, die der Benutzer nicht ausführen darf, z. B. setUser und Funktionsverteilungen an eine 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>

Nächste Schritte

• BHOLD Konzepte
• BHOLD-Versionsverlauf