Microsoft Identity Manager 2016 の BHOLD 開発者向けリファレンス

BHOLD コア モジュールでは、スクリプト コマンドを処理できます。 これを行うには、.NET プロジェクトで bscript.dll を直接使用します。 Web サービス b1scriptservice.asmx インターフェイスとの対話も行います。

スクリプトを実行する前に、スクリプト内のすべての情報を収集して、このスクリプトを作成する必要があります。 この情報は、次のソースから収集できます。

• ユーザー入力
• BHOLD データ
• アプリケーション
• その他

BHOLD データは、スクリプト オブジェクトの GetInfo 関数を使用して取得できます。 BHOLD データベースに格納されているすべてのデータを表示できるコマンドの完全な一覧があります。 ただし、表示されるデータは、ログインしたユーザーの表示アクセス許可の対象となります。 結果は、解析可能な XML ドキュメントの形式になります。

情報のもう 1 つのソースは、BHOLD によって制御されるアプリケーションのいずれかです。 アプリケーション スナップインには特別な関数 FunctionDispatch があり、これを使用してアプリケーション固有の情報を表示できます。 これは XML ドキュメントとしても表示されます。

最後に、他の方法がない場合は、スクリプトに他のアプリケーションまたはシステムに直接コマンドを含めることができます。 NoBHOLDサーバー上の余分なソフトウェアの拡張は、システム全体のセキュリティを損なう可能性があります。

この情報はすべて 1 つの XML ドキュメントに格納され、BHOLD スクリプト オブジェクトに割り当てられます。 オブジェクトは、このドキュメントを定義済みの関数と結合します。 定義済みの関数は、スクリプト入力ドキュメントを BHOLD コマンド ドキュメントに変換する XSL ドキュメントです。

BHOLD スクリプト処理BHOLD Script Processingの

コマンドは、ドキュメントと同じ順序で実行されます。 1 つの関数が失敗すると、実行されたすべてのコマンドがロールバックされます。

Script オブジェクト

このセクションでは、スクリプト オブジェクトの使用方法について説明します。

BHOLD 情報を取得する

GetInfo 関数は、BHOLD 承認システムで使用可能なデータから情報を取得するために使用されます。 この関数には、関数名と最終的に 1 つ以上のパラメーターが必要です。 この関数が成功すると、BHOLD オブジェクトまたはコレクションが XML ドキュメントの形式で返されます。

関数が成功しない場合、GetInfo 関数は空の文字列またはエラーを返します。 エラーの説明と番号を使用して、エラーに関する詳細情報を取得できます。

GetInfo 関数 'FunctionDispatch' を使用して、BHOLD システムによって制御されるアプリケーションから情報を取得できます。 この関数には、アプリケーションの ID、ASI で定義されているディスパッチ関数、および ASI のサポート情報を含む XML ドキュメントの 3 つのパラメーターが必要です。 関数が成功した場合、結果は結果オブジェクトの XML 形式で使用できます。

次のスニペットは、GetInfo の単純な C# の例です。

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

同様に、BScript オブジェクトにも Web サービス b1scriptservice経由でアクセスできます。 これを行うには、http://<サーバー>:5151/BHOLD/Core/b1scriptservice.asmx を使用してプロジェクトに Web 参照を追加します。このサーバー<>は、BHOLD バイナリがインストールされているサーバーです。 詳細については、「Visual Studio プロジェクトへの Web サービス参照の追加」を参照してください。

次の例は、Web サービスから GetInfo 関数を使用する方法を示しています。 このコードは、OrgID が 1 の組織単位を取得し、その組織単位の名前を画面に表示します。

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

        }
    }
}

次の VBScript の例では、SOAP と GetInfo を使用して Web サービスを使用します。 SOAP 1.1、SOAP 1.2、および HTTP POST のその他の例については、「BHOLD マネージド リファレンス」セクションを参照するか、ブラウザーから直接 Web サービスに移動して表示できます。

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

スクリプトの実行

BScript オブジェクトの ExecuteScript 関数を使用してスクリプトを実行できます。 この関数には 2 つのパラメーターが必要です。 最初のパラメーターは、スクリプトで使用されるカスタム情報を含む XML ドキュメントです。 2 番目のパラメーターは、使用する定義済みスクリプトの名前です。 BHOLD の定義済みスクリプト ディレクトリでは、関数と同じ名前の XSL ドキュメントを指定しますが、拡張子は .xsl です。

関数が成功しない場合、ExecuteScript 関数は値 False を返します。 エラーの説明と番号を使用して、問題が発生したことを把握できます。 ExecuteXML Web メソッドの使用例を次に示します。 このメソッドは 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

この GetInfo 関数は、executescript 関数の実行後に使用できます。 この関数は、完全な実行レポートを含む XML 形式の文字列を返します。 [スクリプト] ノードには、実行されたスクリプトの XML 構造が含まれています。

スクリプトの実行中に失敗した関数ごとに、ノード関数がノード名と共に追加されます。 ExecuteXML と Error がドキュメントの末尾に追加され、生成されたすべての ID が追加されます。

エラーを含む関数のみが追加されることに注意してください。 エラー番号 '0' は、関数が実行されていないことを意味します。

<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 パラメーター

ID パラメーターは特別な処理を受けます。 数値以外の値は、BHOLD データ ストア内の対応するエンティティを検索するための検索値として使用されます。 検索値が一意でない場合は、検索値に準拠する最初のエンティティが返されます。

数値検索値と ID を区別するために、プレフィックスを使用できます。 検索値の最初の 6 文字が 'no_id:' と等しい場合、値が検索に使用される前にこれらの文字が削除されます。 SQL ワイルドカード文字 '%' を使用できます。

検索値には、次のフィールドが使用されます。

スクリプトのアクセスとアクセス許可

Active Server Pages のサーバー側コードは、スクリプトの実行に使用されます。 したがって、スクリプトへのアクセスは、これらのページへのアクセスを意味します。 BHOLD システムは、カスタム ページのエントリ ポイントに関する情報を保持します。 この情報には、スタート ページと関数の説明が含まれます (複数の言語をサポートする必要があります)。

ユーザーには、カスタム ページを入力してスクリプトを実行できる権限があります。 各エントリ ポイントはタスクとして表示されます。 ロールまたはユニットを介してこのタスクを取得した各ユーザーは、対応する関数を実行できます。

メニューの新しい関数には、ユーザーが実行できるすべてのカスタム関数が表示されます。 スクリプトは、ログオンしたユーザーとは異なる ID で BHOLD システムでアクションを実行できるためです。 オブジェクトを監督することなく、特定の 1 つのアクションを実行するアクセス許可を付与することができます。 たとえば、これは、会社に新しい顧客を入力することしか許可されていない従業員に役立つ場合があります。 これらのスクリプトを使用して、自己登録ページを作成することもできます。

コマンド スクリプト

コマンド スクリプトには、BHOLD システムによって実行される関数の一覧が含まれています。 このリストは、次の定義に準拠する XML ドキュメントに記述されます。

XML には、特殊文字の次の変換があります。

これらの XML 文字は識別子で使用できますが、推奨されません。

次のコードは、3 つの関数を持つ有効なコマンド ドキュメントの例を示しています。

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

OrgUnitAdd 関数は、作成されたユニットの ID を UnitID という変数に格納します。 この変数は、UserAdd 関数の入力として使用されます。 この関数の戻り値は使用されません。 次のセクションでは、使用可能なすべての関数、必要なパラメーター、およびその戻り値について説明します。

関数の実行

このセクションでは、実行関数を使用する方法について説明します。

ABAAttributeRuleAdd

特定の属性の種類に対して新しい属性ルールを作成します。 属性ルールは、1 つの属性の種類にのみリンクできます。

指定した属性ルールは、使用可能なすべての属性の種類にリンクできます。

RuleType は、"ABAattributeruletypeupdate" コマンドでは変更できません。 属性の説明を一意にする必要があります。

applicationadd

新しいアプリケーションを作成し、新しいアプリケーションの ID を返します。

AttributeSetValue

オブジェクト型に接続されている属性型の値を設定します。 オブジェクト型と属性型の説明が一意である必要があります。

AttributeTypeAdd

新しい属性の型/プロパティ型を挿入します。

AttributeTypeSetAdd

新しい属性の種類セットを挿入します。 属性型セットの説明が一意である必要があります。

AttributeTypeSetAddAttributeType

既存の属性型セットに新しい属性型を挿入します。 属性型セットと属性型の説明が一意である必要があります。

ObjectTypeAddAttributeTypeSet

属性型セットをオブジェクト型に追加します。 オブジェクト型と属性型セットの説明が一意である必要があります。 オブジェクトの種類は、System、OrgUnit、User、Task です。

OrgUnitadd

新しい組織単位を作成し、新しい組織単位の ID を返します。

OrgUnitaddsupervisor

ユーザーを組織単位の監督者にします。

OrgUnitadduser

ユーザーを組織単位のメンバーにします。

OrgUnitdelete

組織単位を削除します。

OrgUnitdeleteuser

組織単位のメンバーとしてユーザーを削除します。

roleadd

新しいロールを作成します。

roleaddOrgUnit

組織単位にロールを割り当てます。

roleaddrole

ロールを別のロールのサブロールとして割り当てます。

roleaddsupervisor

ユーザーをロールのスーパーバイザーにします。

roleadduser

ユーザーにロールを割り当てます。 contextID が指定されていない場合、ロールをコンテキスト適応型ロールにすることはできません。

roledelete

ロールを削除します。

roledeleteuser

ユーザーへのロールの割り当てを削除します。 ユーザーによって継承されたロールは、このコマンドによって取り消されます。

roleproposeOrgUnit

OrgUnit のメンバーとサブ OrgUnit に割り当てるロールを提案します。

taskadd

新しいタスクを作成し、新しいタスクの ID を返します。

taskadditask

2 つのタスクに互換性があることを示します。

taskaddrole

タスクをロールに割り当てます。

taskaddsupervisor

ユーザーをタスクの監督者にします。

useradd

新しいユーザーを作成し、新しいユーザーの ID を返します。

UserAddRole

ユーザー ロールを追加します。

UserDeleteRole

ユーザー ロールを削除します。

Userupdate

ユーザーを更新します。

GetInfo 関数

このセクションで説明する一連の関数を使用して、BHOLD システムに格納されている情報を取得できます。 各関数は、BScript オブジェクトから GetInfo 関数を使用して呼び出すことができます。 一部のオブジェクトにはパラメーターが必要です。 返されるデータは、ログインしたユーザーのビュー権限と監視対象オブジェクトの対象となります。

GetInfo 引数

OrgUnit 情報

ロール情報

アクセス許可 - タスク情報

ユーザー情報

戻り値の型

このセクションでは、GetInfo 関数の戻り値の型について説明します。

サンプル スクリプト

ある会社には BHOLD サーバーがあり、新しい顧客を作成する自動化されたスクリプトが必要です。 会社とその購入マネージャーに関する情報は、カスタマイズされた Web ページに入力されます。 すべての顧客は、ユニット顧客の下のユニットとしてモデルに表示されます。 購入マネージャーは、このユニットの監督者としてもメンバーです。 所有者に新しい顧客の名前で購入する権利を付与するロールが作成されます。

ただし、この顧客はアプリケーションに存在しません。 購入アプリケーションで新しい顧客アカウントを作成する特別な関数が ASI FunctionDispatch に実装されています。 各顧客には顧客の種類があります。

使用できる型は、FunctionDispatch 関数でも表示できます。 AA は、新しい顧客に適した種類を選択します。

購入特権を提示するロールとタスクを作成します。 実際の購入特権は、ASI によってファイル /customers/customer id/purchaseとして提示されます。 このファイルは、新しいタスクにリンクされている必要があります。

情報を収集する Active Server ページは次のようになります。

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

カスタマイズする必要があるページはすべて、適切な情報を要求し、要求された情報を含む XML ドキュメントを作成することです。 この例では、MySubmit ページで XML ドキュメント内のデータを変換し、b1script に割り当てます。パラメーターはオブジェクト し、最後に b1script.ExecuteScript("MyScript") 関数を呼び出します。

次の入力スクリプトは、この例を示しています。

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

この入力スクリプトには、BHOLD のコマンドは含まれません。 これは、このスクリプトが BHOLD によって直接実行されないためです。代わりに、これは定義済みの関数の入力です。 この定義済み関数は、BHOLD コマンドを使用してこのオブジェクトを XML ドキュメントに変換します。 このメカニズムにより、setUser や ASI への関数ディスパッチなど、ユーザーが実行できない関数を含む BHOLD システムにスクリプトを送信できなくなります。

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

次のステップ

• BHOLD の概念ガイド
• BHOLD バージョン履歴 を する