SiPass Agent

SiPass agent is the DirX Identity agent that handles the synchronization of SiPass user entries between DirX Identity and a SiPass database.

SiPass agent is implemented in C#. SiPass agent supports SiPass 2.11 SP2 and higher and runs with all platforms that are supported by the SiPass Human Resources Interface which is based on the Windows COM interface.

SiPass agent can:

  • Perform a full export of card holders and workgroups from a SiPass system.

  • Perform a delta import of users into a SiPass system, including creation, modification and deletion of new users and assignment or removal of users to workgroups.

  • Generate a trace file that reports the processed objects and the results of the corresponding operations.

Prerequisites

The SiPass agent has the following requirements:

  • The .NET framework to be correctly installed on the machine where the agent (that is, DirX Identity server) should run. The .NET framework can be downloaded from Microsoft’s web pages (http://www.microsoft.com).

  • To run properly, the account that the agent uses to connect must have the access rights for general user management (read, modify, and delete user).

  • The agent must run on the SiPass server machine. Install a secondary C++-based Server on this machine to satisfy this condition.

  • The agent may require additional files copied in the install_path/bin directory. This may be needed when working with SiPass versions newer than 2.3. These files are indirectly referenced by the SiPass agent and can be located in the SiPass installation directory. In this case the .NET framework writes error messages describing missing files to standard output when running the agent. For example version 2.5 requires copies of the files GenuineChannels.dll and SiPass.ClientServices.Interfaces.dll.

Overview

The following figures illustrate the components of the SiPass agent export and import operations.

SiPass Agent Export Components
Figure 1. SiPass Agent Export Components

SiPass agent reads its configuration from the configuration file, the search request from the SPML request file and performs the search in the SiPass server. An LDIF content file contains the output information, a trace file contains the trace information.

SiPass Agent Import Components
Figure 2. SiPass Agent Import Components

SiPass agent reads its configuration from the configuration file, the input information from an LDIF change file and performs the necessary operations in the SiPass server. A trace file and an SPML response file are generated.

This section describes:

  • General information

  • SiPass agent command line format for export and import operations

  • SiPass agent configuration files for export and import operations

  • The export and import data file formats

  • The search request file format that SiPass agent recognizes

General Notes

On the directory side, the DN (distinguished name) is used to identify an entry. There is no DN in the SiPass user management. For SiPass users, the reference number is the key (stored by default in dxrName attribute). Therefore, the DN attribute from incoming requests is internally mapped to the reference number during the import action. If you want to export the Reference attribute, you must have this attribute name in your list of selected attributes.

SiPass agent does currently not support encryption of bind profiles nor user attributes (set the switch 'Disable Encryption' in the relevant bind profile).

Command Line Format

The command line format to invoke SiPass agent is:

SiPassAgent.bat action configuration_file [-f filter_file]

Parameters

action

Specifies the action type to be preformed. The supported actions are:

  • Export

  • Import

configuration_file

Specifies the name of the file that contains the configuration of the export or import procedure. All parameters of SiPass agent operation are defined in the agent’s configuration file in XML format.

-f filter_file

This is a mandatory attribute for Export action. It specifies the name of the file that contains the specification of the search criteria in for export mode (which are described in a separate Service Provisioning Markup Language (SPML) file).

Exit Codes

The following table describes the codes provided when SiPass agent finishes running:

Exit Code Description

0

Agent completed successfully.

10

SiPass agent completed with fatal errors, which are described in the specified tracefile unless this file cannot be created due to a file exception error, in such a case error is logged to the standard output (system console).

60

SiPass agent completed with warnings or non-fatal errors, which are described in the specified tracefile.

Configuration Files

SiPass agent uses the following configuration files:

  • SiPass export configuration file - controls the export of data from a SiPass system

  • SiPass import configuration file - controls the import of data into an a SiPass system

This section also describes the general structure of a configuration file.

General Structure of a Configuration File

A SiPass agent configuration file is in XML format.

The SiPass agent is composed of multiple sub-units, that are configured in the configuration file. Different types of sub-units are used for export and import. Consequently, you must not change the general structure of SiPass agent import/export configuration files. Instead, you configure some well-defined attribute values to the specific environment in which the meta agent runs.

Tags

The configuration files contain the tags job, connector, logging and connection.

  • job - Defines the file’s document tag, with connector sub-tags

  • connector - Configures the properties of one connector, has connection and/or logging sub-tags

  • connection - Configures connection parameters, for example, filename for a reader/writer or host/credentials for a network connector

  • logging - Configures the logging properties of a connector

Attributes

A connector tag can have the following attributes:

  • name - The connector’s name

  • role - One of reader, controller, connector or responseWriter

The connection parameters of the specific connectors are described in their connection sub-tags.

Each connection tag has the attribute

  • type - The type of connection (file format, protocol)

Readers and response writers are configured by the attribute

  • filename - The pathname of the input or output file.

A connection to the target system is configured by some attributes that might differ dependent on the target system. Typical attributes are:

  • server - The host name or IP address of the SiPass system

  • user - The user for binding to the SiPass system

  • password - The user password

The agent’s logging is configured in the controller’s logging tag by the attributes:

  • level -The integers 0-9, where 0 indicates no logging and 9 indicates full logging
    0 - none
    1 - FatalError and Error
    2 - FatalError, Error and Warning
    3 - FatalError, Error and Warning
    4 - FatalError, Error and Warning
    5 - FatalError, Error, Warning and Trace
    6 - FatalError, Error, Warning and Trace
    7 - FatalError, Error, Warning and Trace
    8 - FatalError, Error, Warning and Trace
    9 - FatalError, Error, Warning and Trace (and additional HTML files)

  • filename -The name of the trace file

Example of an Export Configuration File

The export configuration file has the format defined above The following generic example describes shows the general layout. The attribute values that can be configured are shown in bold italic, e.g. level:

<?xml version="1.0" encoding="UTF-8" ?>
<job>
  <connector name="Default Controller" role="controller">
    <logging level="level" filename="traceFileName"/>
  </connector>
  <connector name="SiPass Connector" role="connector">
    <connection type="SiPass"
      user="account"
      password="password"
      server="server">
      <property name="Export_Date_Format" value="validSiPassDate"/>
    </connection>
  </connector>
  <connector name="LDIF File Writer" role="responseWriter">
    <connection type="LDIF" filename="outputFile" />
  </connector>
</job>

Specific Parameters of the SiPass Export Configuration File

This section describes the specific information for the SiPass agent for the export operation. For the general structure of this file and standard parameters see the section Configuration File Formats in the General Configuration section.

The SiPass agent export operation is configured by the attributes shown in the following table:

Connector Parameter Description

Default Controller

level

The logging level (for details, see the General Structure of a Configuration File).

filename

The trace file name.

SiPass Connector

user

The user for binding to the SiPass system.

password

The user password.

server

The host name or the IP address of the SiPass system.

Export_Date_Format

The date format used internally in SiPass DB. The SiPass agent needs to know what kind of date format can be obtained from the SiPass API in order to be able to automatically convert this value to DirX Identity native date format (generalized time format). To get a validSiPassDate only a permutation of the string “dmy“ (day/month/year) with separator “/“ or “.“ can be used. For example format string “m/d/y“ means that the month is followed by the day and the year. Use trace level 9 to set this format string to the correct values.

LDIF File Writer

filename

The name of the LDIF response file that contains the exported card holder or workgroup entries.

Example of an Import Configuration File

The import configuration file has the format defined in the general section. The following template describes its configuration. The attribute values that you can configure are shown in bold italic, e.g. level:

<?xml version="1.0" encoding="UTF-8" ?>
<job>
  <connector name="Default Controller" role="controller">
    <logging level="level" filename="traceFileName"/>
  </connector>
  <connector name="LDIF-change File Reader" role="reader">
    <connection filename="inputFileName"/>
  </connector>
  <connector name="SiPass Connector" role="connector">
    <connection type="SiPass"
      user="account"
      password="password"
      server="server">
      <property name="Exact_Add_Action" value="true or false"/>
      <property name="Exact_Modify_Action" value="true or false"/>
      <property name="Import_Date_Format" value="validSiPassDate"/>
    </connection>
  </connector>
</job>

Specific Parameters of the SiPass Import Configuration File

This section describes the specific information for the SiPass agent for the import operation. For general structure of this file and standard parameters see the section Configuration File Formats in the General Configuration section.

The SiPass agent import operation is configured by the following attributes:

Connector Parameter Description

Default Controller

level

The logging level (for details, see the General Structure of a Configuration File).

filename

The trace file name.

LDIF-change File Reader

filename

The name of the LDIF-change formatted input file.

SiPass Connector

user

The user for binding to the SiPass system.

password

The user password.

server

The host name or the IP address of the SiPass system.

Exact_Add_Action

Only an add action is allowed for incoming add requests if this switch is set to true. If set to false, a modify operation can be performed alternatively if a card holder with the specified reference number already exists in the SiPass system.

Exact_Modify_Action

Only a modify action is allowed for incoming modify requests if this switch is set to true. If set to false an add operation is automatically performed if no user with the specified reference number could be found in the SiPass system.

Import_Date_Format

The date format used internally in the SiPass DB. The SiPass agent needs to know what kind of date format is expected by the SiPass API in order to be able to automatically convert strings with DirX Identity native date format (generalized time format) to valid SiPass date format. This conversion is done only if an incoming generalized time format for SiPass attributes StartDate and EndDate is detected. validSiPassDate can be only a permutation of the string “dmy“ (day/month/year) with separator “/“ or “.“.For example format string “m/d/y“ means that the month is followed by the day and the year. Use trace level 9 in order to set this format string to the correct values.

Data File Formats

A search request creates an export file in LDIF content format that contains the search result. Note that the identifiers of the card holders (employees) are Reference attributes. Workgroups are always exported with their name and void status.

Import Data File Format

The import data file format recognized by the SiPass meta agent is LDIF-change file format. The data has to be provided in UTF-8 character set (or US-ASCII), not in ISO8859-1 (Latin-1).

The supported change types are add, modify, and delete; modifyDN is not supported.

The SiPass agent does not process multi-value attributes. An error is issued if a multi-value attribute is detected and the whole LDIF-entry with such an attribute is ignored.

During add operations, the SiPass system requires the mandatory attributes CardNumber, FirstName, LastName, Reference number, StartDate and EndDate.

If StartDate is not provided in the input file, it is set to the current date.

If EndDate is not provided in the input file, it is set to the current date plus 100 years.

If the Workgroup attribute or the corresponding value is missing or invalid the user cannot be added.

Examples

This section provides some examples of input data files.

Example 1. Create User
dn:5367
changetype:add
CardNumber:367
FirstName:Aliza
LastName:Dasrath
StartDate:30/3/2005
EndDate:20050531121745Z
Workgroup:Developers

A user with the reference number 5367 for the person Aliza Dasrath with card number 367 valid from 30/03/05 is created. Mandatory attributes for creating a user are CardNumber, FirstName, LastName and Reference number (internally produced from the DN attribute).

The mandatory attributes StartDate, EndDate are automatically generated by the SiPass agent.

Example 2. Change User
dn:5367
changetype:modify
replace:Workgroup
Workgroup:ProjectLeaders
-

A new workgroup is assigned to the card holder with reference number 5367.

Example 3. Delete User
dn:5367
changetype:delete

The card holder with the reference number 5367 will be deleted.

Search Request File

The search request file defines the search to be performed in the SiPass server. It is SPML compliant.

Example of a Search Request File Format

The objects to be exported are defined in a Service Provisioning Markup Language (SPML) search request. SPML is a specialized XML format. The following template describes its configuration. The attribute values that can be configured are shown in bold (blue) italic, e.g., typeOfExportedObject:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:searchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core" xmlns:spml="urn:oasis:names:tc:SPML:1:0" requestID="search-01">
  <spml:filter>
    <dsml:substring name="objecttype">
      <dsml:value>
        typeOfExportedObject
      </dsml:value>
    </dsml:substring>
  </spml:filter>
  <spml:attributes>
    <attribute name="firstAttribute"/>
    ...
    <attribute name="lastAttribute"/>
  </spml:attributes>
</spml:searchRequest>
spml:filter

smpl:filter specifies what kind of SiPass object shall be exported. The value typeOfExportedObject can be either “employee“ for exporting SiPass card holders or “workgroup“ for exporting workgroups.

spml:attributes

smpl:attributes specifies the attributes firstAttribute …​ lastAttribute to be returned by the search (only necessary for exporting card holders).