Connectors

Synchronization Server Connectors

⏰ Getting started

Introduction

Soffid provides the connectors needed to provision accounts on the most widely used systems. To set up this connection it is necessary a specific connector addon that you must install and configure in the Soffid console.

First of all, yo must download the specific connector for your system, then install it in the Soffid console, and finally configure an agent in the Soffid console.

Download

The open-source connectors available for Soffid IAM can be found on the project website http://www.soffid.com/download in the Connectors section.

To download enterprise connectors from http://download.soffid.com/download/enterprise/ a Soffid user with authorization is required to access this functionality.

Installation

1. Once the connector is downloaded, please log in to IAM Console.

You need to be an administrator user of the Soffid console or a user with permission to upload addons.

2. In the Soffid console, please go to:

Main Menu > Administration > Configure Soffid > Global Settings > Plugins

3.  Then, click the add button (+) and pick the file and Soffild will upload the addon file.

4. Finally, when the addon is installed, it will be required to restart the Soffid Sync server.

5. Once the Sync server is restarted, you could check the plugin was uploaded properly on the plugins page:

Main Menu > Administration > Configure Soffid > Global Settings > Plugins

6. Now, you can set up the connector.

Configure Agent

Once the plugin has been uploaded and installed, the next step will be to set up the agent, this is the step where you establish a relation between Soffid and your managed system.

Main Menu > Administration > Configure Soffid > Integration engine > Agents

More information about how to configure agents can be found on the Agents page.

Connector List

Here you will find all the information needed about the available Soffid connectors to integrate external managed systems. If you miss something important, don't mind making suggestions using contact@soffid.com.

  1. AWS Connector
  2. CSV Connector
  3. Google Apps Connector
  4. JSON REST Web Services Connector
  5. LDAP Connector
  6. Oracle Connector
  7. Oracle EBS Connector
  8. SAP Connector
  9. SCIM Connector
  10. Shell Connector
  11. SQL Connector
  12. Windows Connector
  13. Zarafa Connector
  14. SQL Server Connector



AWS Connector

AWS Connector

AWS Connector

Introduction

Description

AWS Connector allows to manage the Amazon AWS IAM (Identity and Access Management)

Managed Systems

This connector is specific for integration with the Amazon AWS IAM (Identity and Access Management) through the CLI AWS IAM

For more information to check if your system may be synchronized with this connector, do not hesitate to contact us through our Contact form

Prerequisites

It is needed a AWS IAM user with access and privileges to the required operations.

It cannot detect password changes to be propagated to other systems.

Download and install

This addon is located in the Connectors section and its name is AWS plugin.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this AWS connector you must select "Amazon WS" in the attribute "Type" of the generic parameters section in the agents page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter
Description
Access Key Access key provided by the AWS IAM account
Secret Key
Secret key provided by the AWS IAM account
AWS Endpoint AWS endpoint provided by the AWS IAM account
Enable debug Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

Attribute mappings

This connector could manage Users and Roles 

Properties

The following properties are defined for each object type:

Property
Meaning
preventDeletion (optional)

Two options: [ True / False ].
If true, it will prevent the deletion of any object that is no longer needed.

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound and outbound attribute mappings.

Users

The following attributes can be mapped on User objects

Attribute
Value
userName User name
path User path
arn AWS arn (read only)
createDate Creation date (read only)
passwordLastUsed Passsword last use (read only)
userId Internal user id
Groups

The following attributes can be mapped on Role (AWS Group) objects:

Attribute
Value
groupName Group name
path Group path
arn AWS arn (read only)
createDate Creation date (read only)
groupId Internal group id

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

image-1641816933566.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into target objects. 

To view some examples, visit the Outgoing triggers examples page.

Load triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects.

To view some examples, visit the Incoming triggers examples page.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you could check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user or role", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


CSV Connector

CSV Connector

CSV Connector

Introduction

Description

The CSV Connector provides a way to load authoritative data from fixed record size files.

Managed System

This connector has been performed to charge authoritative data from files with CSV format or other format in other extension files.

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

The file must be placed in the same Synchronization Server host.

The file must has the correct permissions to be readed for the Synchronization Server.

Download and Install

This addon is located in the Connectors section and its name is Flat file plugin.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

This connector could only be used as an identity source, no output file could be generated yet.

Usually, this connector is used the first time to charge manually the user information of the identities from the HR applications o database.

As example, this is the flow to shows how the "Customizable fixed-columns file v2.0" works.

CSV Connector.png

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

This addon has 5 available types:

To configure this CSV plugin, you could select one of the previous agent in the attribute "Type" of the generic parameters section in the agents page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

The main parameters for this connectors are:

Customizable fixed-columns file v2.0
Parameter
Description
Enable debug Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log
Character set (utf-8)
Charset used to load files. Despite it in uncommon, multi-byte character sets, as UTF-8, are allowed. Nevertheless, single byte character sets as ISO-8859-1 are recommended
Customizable CSV file
Parameter
Description
Enable debug Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log
CSV file test agent
Parameter
Description
User's file Directory where the CSV file is placed
Dummy password agent
Parameter
Description
Dummy Password
Dummy Password
Test
Parameter
Description
CSV file
Path of the CSV file

Attribute mapping

Only the "Customizable fixed-columns file v2.0" and the "Customizable CSV file" agents have this functionality implemented.

Properties

Customizable fixed-columns file v2.0

This agent requires two properties:

Property
Description
file Path where the file is placed in the directory system
recordSize

Total number of characters of the rows.

This property must have a number value.

The file will be split into records of this size in bytes. Mind the record size must include any line terminator character as "carriage return" or "line feed".

And after that you must specify the number of rows of every row as follow:

Property
Description
N-M

Where N is the position of the first character and M the position of the last character, both included.

Column numbers start with 1 (not 0).

And for instance, if the property is defined as "1-10" with the value "NAME", Soffid will extract characters from columns 1 to 10 (both inclusive) into a field named NAME in Soffid.

For instance for this file:

abernal   Antonio        Bernal         world      YES
jwayne2   John           Wayne          world      YES

These are its properties:

CSV Connector - properties.png

Customizable CSV file

This agent only needs the next properties:

Property
Description

file

Mandatory: Path where the file is placed in the directory system

key

Mandatory: The field to be used as key 

Attributes

Customizable fixed-columns file v2.0

The mapping in only available for USER object.

Now we could map the system attribute defined as property values agains Soffid attributes, for instance:

System attribute
Soffid attribute

USER

userName

FIRSTNAME

firstName

LASTNAME

lastName

GROUPNAME

primaryGroup

ACTIVE.equals("YES")

active

For instance:

image-1641824416700.png

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

Customizable CSV file

The mapping in only available for USER object.

The first row of the file must include the name of the attribute.

USER,FIRSTNAME,LASTNAME,GROUPNAME,ACTIVE
abernal,Antonio,Bernal,world,YES
jwayne2,John,Wayne, world,YES

Now we could map the system attribute (file) with the Soffid attributes, for instance:

System attribute
Soffid attribute

USER

userName

FIRSTNAME

firstName

LASTNAME

lastName

GROUPNAME

primaryGroup

ACTIVE.equals("YES")

active

Load Triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects.

To view some examples, visit the Incoming triggers examples page.

Account metadata

Accounts are default objects in Soffid. Agents allow you to create additional custom data, on the "Account metadata" tab, to customize the accounts created only for that agent.

The attributes which you define here, will be shown when you click on the proper account, on the Accounts Tabs at user page.

At this tab you could add or delete custom attributes. You can visit the Metadata page for more information about the standard attributes.

Operational

Monitoring

After the agent configuration you could check in the monitoring page if the service is running in the Synchronization Server, please go to: 

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to 

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If your are configured the "Attribute Mapping" tab with some of our objects: "user", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


CSV Connector

Customizable CSV file (CSV Connector type)

Introduction

Description

The CSV connector type allows users to load a collection of data stored into a plain CSV file.

In the following page, the process to complete the CSV connector setup will be explained.

To begin with,  address to the quick start section. 

Quick start

The core of Customizable CSV file connector is located under the 'Attribute Mapping'  tab.

There are two important sections:

Property

File information related configuration.

Property
Description
file Mandatory: Path where the file is placed in the directory system
key Mandatory: The field to be used as key 

 System attribute

Mapping between CSV fields and Soffid objects.

CSV Connector - customizable CSV file.png

Taking a look to the configuration used, we can see that:

To demonstrate Soffid flexibility in terms of agent customization, notice that:

USERNAME, NAME, LASTNAME fields, correspond to default fields from User object.

NDI is a custom field defined into the User object.

"I" is a 'char' literal that indicates the UserType.

Example

Type
File
data (file used in this configuration guide)

file.csv

attribute-mapping (file used in this configuration guide)

csv-agent-config.xml

Useful information

System objects
User
Account
Group
Role


Google Apps Connector

Google Apps Connector

Google Apps Connector

Introduction

Description

Google Apps Connector allows you to manage users and groups using the Google Directory API.

Managed System

This connector is specific for integration with the Google domain.

For more information to check if your system may be synchronized with this connector do not hesitate to contact us through our Contact form

Prerequisites

To get a service account and a private key, please follow this link: Creating a service account. You must:

Furthermore, you will need to follow this guide to enable the recently created account to use directory API services. The scopes to grant are:

Download and Install

This addon is located in the Connectors section and its name is Google Apps plugin.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this Google Apps Connector you must select "GoogleApps" in the attribute "Type" of the generic parameters section in the agents page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter
Description

Admin user

Administrator account name

Service account client email

Extract it from generated json file. It is tagged as client_email

Service account private key

Extract it from generated json file. It is tagged as private_key. As the private key is JSON encoded, mind to replace unicode escape chars by it's ASCII equivalents

Google domain

Base google domain

Attribute mapping

This connector could manage users and groups.

Properties

Nothing to configure.

Attributes

Users

Users and shared accounts can be customized. The next attributes are required:

Attribute
Value

suspended

"True" if the account is disabled. "False" otherwise

name{"givenName"}

User given name

name{"familyName"}

User last name

name{"fullName"}

User full name

primaryEmail

Account name

To get an extensive list of attributes supported by Google, browse to Google User API

Soffid groups can be mapped as OrgUnits.

Attribute
Value

name

Org Unit Name

Groups

Mails alias will be automatically bound to users without any further configuration.

Roles and Mail Lists will also be created and maintained as Google Apps groups.

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

image-1641828269243.png

Triggers

Nothing to configure. This option is not available to Google apps connector.

Load Triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects.

To view some examples, visit the Incoming triggers examples page.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you could check in the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user or group", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


JSON REST Web Services Connector

JSON REST Web Services Connector

JSON REST Web Services Connector

Introduction

Description

This connector allows the integration with any Web Service able to consume and generate JSON documents through REST communication.

Managed System

Every commercial product or custom web application allows REST communication with JSON documents.

There are a lot of products that use this standard, for instance:

If your system is not in the previous list, it's possible to include it easily!

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

It is needed a user with access and permissions to the endpoints and operations required in the scope of the integration.

Also, the documentation, specification, or tutorial of the implementation of the JSON REST Web Service is required to apply the mapping configuration.

Download and Install

This addon is located in the Connectors section and its name is REST (json) plugin.

You can visit the Addons Getting started page for more information about the installation process.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this JSON REST Web Service Connector you must select "JSON Rest Webservice" in the attribute "Type" of the generic parameters section in the agents' page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

image-1658998971348.png

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter
Description

Server URL

URL of the REST web service.  

Base URL for making calls.

Authentication method

Available options:

  • None: no authentication (User and Password are not used).
  • Basic: it uses the User and Password to generate the authentication token.
  • Bearer token: it is provided by the application to which we are trying to connect.
  • Token: generate a token from a specific authentication URL. It is no longer used.
  • Token oAuth Client Credentials: authenticates based on a client ID and a client secret.
  • Token oAuth Password Grant:  authenticates based on a client ID and a client secret plus a user name and a password.

(*) You can find more information in the Authentication method section.

Enable debug

Two options: "Yes", "No": it enables or not more log traces in the Synchronization Server log

Proxy host

Only when the proxy is needed.

Proxy port

Only when the proxy is needed.

XML Templates

Allows you to add new XML templates with SOAP requests and then configure them at attribute mappings.


Authentication method

None: no authentication is needed. There are no parameters to configure.

image-1658916253736.png

Basic: the username and password are sent with each request.

image-1658916073500.png

Bearer token

image-1658916094610.png

Token: calls the authentication URL with the POST method and with the username and password, and the response will be the token. It is no longer used.

image-1658916132666.png

Token oAuth Client Credentials

image-1658916165066.png

Token oAuth Password Grant

image-1658916206788.png


Attribute mapping

This connector can manage users, accounts, roles, groups, and grants.

Note that any changes made to the methods will affect the properties and vice versa.

Methods

This agent allows you to define methods to be called using the defined properties. There are some default methods, but you can customize your own methods.

Default methods:

For each method, the properties to set up are as follows:

Properties
Description
Path A valid URL to call. This path must be the continuation of the Server URL for making calls.
Method Available methods to call a Rest API (GET, POST, PUT, DELETE, PATCH)
Encoding

The specific type of encoded data that will be used. There are three supported types:

  • application/x-www-form-urlencoded
  • application/json
  • text/xml
XML Template Applies only if it is text/xml. You need to write the name of the corresponding template defined on the XML Templates.
Parameters

Applies with application/x-www-form-urlencoded and application/json

  • You must type which attributes, defined on the System attributes, will be sent.
  •  If none are to be sent, you must write the hyphen character "-".  
  • If nothing is typed, all parameters are sent.
Success HTTP Codes

HTTP codes that should be interpreted as OK. If no code is entered, Soffid will take as valid codes the following:  200, 201, 204 and 404.

If you type the Success HTTP codes, it will be not necessary to type the Failure HTTP codes.


204 201 200
200,212

You can use blanks or commas to separate the codes.

Failure HTTP Codes

Soffid will take by default as failure all codes not indicated in Success HTTP Codes.

If you type the Failure HTTP codes, it will be not necessary to type the Success HTTP codes. 


400 403
403,405, 400

You can use blanks or commas to separate the codes.

Results

Gets the object or object list from the response received. You need to indicate a  JSON attribute name to check and get the data. If this element is not present, or empty, the connector will conclude the user does not exist yet. You can type simple attribute names or even complex scripts.

Pagination URL

Often, the response from the API Rest service does not contain all the data because the data is too large. In these cases, you can use the paging options to request the data in blocks. 

When the response gives us the URL of the next page to fetch, you must type the tag name of this attribute.


return links{"next"};

You have to choose one of the paging methods, using both is not compatible.

Pagination script

Often, the response from the API Rest service does not contain all the data because the data is too large. In these cases, you can use the paging options to request the data in blocks.

You can type a complex script to get the next call that has to be done. There are two available objects:

  • response: JSON response as received 
  • request: allows you to update the attributes and return true if you want to make a new call or false in another case
o = response{"paging"};
if (o{"has_next_page"}) {
  nextPage = o{"page_number"} + 1;
  request.put("page", nextPage);
  return true;
} else { 
  return false;
}

You have to choose one of the paging methods, using both is not compatible.

Condition script Return false if you want to prevent a call.
Optional header

 Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties Optional Header1.
The value of the header is "HEADER:VALUE", for instance, "Accept:application/json".

Load

image-1658840538394.png

Select

image-1658840570200.png

Insert

image-1658840500870.png

Update

image-1658840611561.png

Delete

image-1658840656509.png

Properties

In this agent, the configuration of the properties attributes is very important due to they define the functionality of the integration:

This agent has five families of properties:

Family
Description
Load Used to retrieve all the objects in the target system
Select Used to retrieve an object in the target system
Insert Used to create an object in the target system
Update Used to update an object in the target system
Delete Used to remove an object in the target system

These families are involved in the following processes:

Process
Families
Reconcile automatic task Load + select
Authoritative automatic task Load + select
Sync new object Select + Insert
Sync updated object Select + Update
Sync deleted object Select + Delete

These are the pictures of the mechanisms used to synchronize objects:

Sync object


Remove object


You can find more information by visiting the Properties attributes page.

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound and outbound attribute mappings.

You may map the attributes of the target system with the Soffid available attributes.

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

As an example, below is how JSON connector will look like in order to manage JIRA accounts:

image-1658843268020.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects. 

To view some examples, visit the Outgoing triggers examples page.

JSON REST Web Services Connector

JSON REST Web Services Connector - Properties

In this agent, the configuration of the properties attributes is very important due to they define the functionality of the integration:

This agent has five families of properties:

Family
Description
Load Used to retrieve all the objects in the target system
Select Used to retrieve an object in the target system
Insert Used to create an object in the target system
Update Used to update an object in the target system
Delete Used to remove an object in the target system

These families are involved in the following processes:

Process
Families
Reconcile automatic task Load + select
Authoritative automatic task Load + select
Sync new object Select + Insert
Sync updated object Select + Update
Sync deleted object Select + Delete

These are the properties attributes grouped by family:

Load

Property

Description

loadPath (required)

Denotes the path (relative to webserver root) where the WebService is located. It can contain variable names in the form of ${variableName}. JSON connector will replace that name for the actual value. Eventually, complex expressions can be written in, but it's discouraged

loadMethod (required)

Denotes the HTTP method to use: PUT, POST, GET and DELETE are allowed

loadEncoding  (required)

Type of encoded data that will be used.

loadParams (optional)

Put the character '-' in case you would avoid its value

loadTemplate (optional)

Name of the corresponding template defined on the XML Templates.

loadResults (optional)

But highly recommended) denotes the JSON portion that contains current data for the object. If this element is not present, or empty, the connector will conclude the object does not exist yet. This property will contain a simple JSON attribute name, but complex scripts are also allowed.

loadSuccessCodes (optional)

The HTTP codes to be interpreted as OK.

loadFailureCodes (optional)

The HTTP codes to be interpreted as Error.

loadNext (optional)

Next page to fetch. When the response gives us the URL of the next page to fetch, you must type the tag name of this attribute.

loadPagination (optional)

Complex script to get the next call that has to be done.

loadCondition (optional)

Script to prevent a call. To prevent the call must return false.

loadHeader (optional)

Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties loadHeader1, loadHeader2, and so on.
The value of the header is "HEADER:VALUE", for example "Accept:application/json".

Select


Property

Description

selectPath (required)

Denotes the path (relative to webserver root) where the WebService is located. It can contain variable names in the form of ${variableName}. JSON connector will replace that name for the actual value. Eventually, complex expressions can be written in, but it's discouraged

selectMethod (required)

Denotes the HTTP method to use: PUT, POST, GET and DELETE are allowed

selectEncoding (required)

Denotes the encoding used to send to the target webservice. application/json and application/x-www-form-urlencoded are supported. The first one is used by default to POST and PUT requests. The second one is used by default for GET and DELETE requests

selectParams (optional)

Put the character '-' in case you would avoid its value

selectTemplate (optional)

Name of the corresponding template defined on the XML Templates.

selectResults (optional)

Denotes the JSON portion that contains current data for the object. If this element is not present, or empty, the connector will conclude the object does not exist yet. This property will contain a simple JSON attribute name, but complex scripts are also allowed

selectSuccessCodes (optional)

The HTTP codes to be interpreted as OK.

selectFailureCodes (optional)

The HTTP codes to be interpreted as Error.

selectNext (optional)

Next page to fetch. When the response gives us the URL of the next page to fetch, you must type the tag name of this attribute.

selectPagination (optional)

Complex script to get the next call that has to be done.

selectCondition (optional)


Script to prevent a call. To prevent the call must return false.

selectHeader (optional)

Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties selectHeader1, selectHeader2, and so on.
The value of the header is "HEADER:VALUE", for instance, "Accept:application/json".

Insert
Property
Description

insertPath (required)

Denotes the path (relative to webserver root) where the webservice is located.

insertMethod (required)

Denotes the HTTP method to use: PUT, POST, GET and DELETE are allowed

insertEncoding (required)

Denotes the encoding used to send to the target webservice. application/json and application/x-www-form-urlencoded are supported. The first one is used by default to POST and PUT requests. The second one is used by default for GET and DELETE requests

insertTemplate (optional)

Name of the corresponding template defined on the XML Templates.

insertParams (optional)

Type in the attributes that will be sent to the rest server. If this property is not set, all attributes will be sent.

insertResults (optional)

Denotes the JSON portion that contains current data for the object. If this element is not present, or empty, the connector will conclude the object does not exist yet. This property will contain a simple JSON attribute name, but complex scripts are also allowed

insertSuccessCodes (optional)

The HTTP codes to be interpreted as OK.

insertFailureCodes (optional)

The HTTP codes to be interpreted as Error.

insertCondition (optional)

Script to prevent a call. To prevent the call must return false.

insertHeader (optional)

Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties insertHeader1, insertHeader2, and so on.
The value of the header is "HEADER:VALUE", for example "Accept:application/json".

Update
Property
Description

updatePath (required)

Denotes the path (relative to webserver root) where the webservice is located

updateMethod (required)

Denotes the HTTP method to use: PUT, POST, GET and DELETE are allowed

updateEncoding (required)

Denotes the encoding used to send to the target webservice. application/json and application/x-www-form-urlencoded are supported. The first one is used by default to POST and PUT requests. The second one is used by default for GET and DELETE requests

updateParams (optional)

Type in the attributes that will be sent to the rest server. If this property is not set, all attributes will be sent.

updateResults (optional)

Denotes the JSON portion that contains current data for the object. If this element is not present, or empty, the connector will conclude the object does not exist yet. This property will contain a simple JSON attribute name, but complex scripts are also allowed

updateSuccessCodes (optional)

The HTTP codes to be interpreted as OK.

updateFailureCodes (optional)

The HTTP codes to be interpreted as Error.

updateCondition (optional)

Script to prevent a call. To prevent the call must return false.

updateHeader (optional)

Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties updateHeader1, updateHeader2, and so on.
The value of the header is "HEADER:VALUE", for example "Accept:application/json".

Delete
Property
Description

deletePath (required)

Denotes the path (relative to webserver root) where the webservice is located

deleteMethod (required)

Denotes the HTTP method to use: PUT, POST, GET and DELETE are allowed

deleteEncoding (required)

Denotes the encoding used to send to the target webservice. application/json and application/x-www-form-urlencoded are supported. The first one is used by default to POST and PUT requests. The second one is used by default for GET and DELETE requests

deleteParams (optional)

Type in the attributes that will be sent to the rest server. If this property is not set, all attributes will be sent.

deleteResults (optional)

Denotes the JSON portion that contains current data for the object. If this element is not present, or empty, the connector will conclude the object does not exist yet. This property will contain a simple JSON attribute name, but complex scripts are also allowed

deleteSuccessCodes (optional)

The HTTP codes to be interpreted as OK.

deleteFailureCodes (optional)

The HTTP codes to be interpreted as Error.

deleteCondition (optional)

Script to prevent a call. To prevent the call must return false.

deleteHeader (optional)

Use this property to send HTTP header(s).
More than one header can be sent by adding multiple properties deleteHeader1, deleteHeader2, and so on.
The value of the header is "HEADER:VALUE", for example "Accept:application/json".

How to retrieve data from the response with the *Results properties

a) One level

If the JSON has one level you have to avoid the property
{
    "userName" : "soffid"
}

b) Two level

If the JSON has two levels you have to create the property *Result and put the name of the parent attribute, for example:
{
    "user" : {    
        "userName" : "soffid"
    }
}
And the property must be for example loadResults = user

c) More than two levels

If the JSON has more than two levels you have to create the property *Result and put the atributes in the next pattern

*Results = attribure1{"attribute2"}{"attribute3"}...

For example:
{
	"data" : {
        "user" : {    
            "userName" : {
                "string" : "soffid"
            }
        }
    }
}

And the property must be for example:

loadResults = data{"user"}{"userName"}

JSON REST Web Services Connector

How to configure the Office 365 agent?

Office 365 integration

Prerequisites

Configuration

Configure the Basic data to establish the connection

image-1658931279840.png

Then, configure the attribute mappings

image-1658932645128.png

Soffid provides you versions of the attribute mappings to import into the agent configuration:



JSON REST Web Services Connector

How to configure the Jira Atlassian agent?

Jira integration

Prerequisites

Configuration

Configure the Basic data to establish the connection

image-1658994257906.png

Then, configure the attribute mappings

image-1658994301791.png

Soffid provides you an XML file with the basic attribute mappings to import into the agent configuration JIRA Soffid agent-config.xml

LDAP Connector

LDAP Connector

LDAP Connector

Introduction

Description

This connector implements the LDAP standard and it is used to connect the Sync-Server with every server that allows this communication protocol.

Managed System

There are a lot of servers and products that use this standard, for instance, the most known systems are:

For more information: List of LDAP software.

If your system is not in the previous list, it's possible to include it easily!

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

It is needed a user with full administrator access.

Download and Install

This addon is located in the Connectors section and its name is LDAP plugin.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this LDAP Connector you must select "LDAP-Custom (with triggers)" in the attribute "Type" of the generic parameters section in the agent's page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

image-1715077578477.png

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User name

User name in DN format, including base name if needed

Password

Password

Host name

Host name of the server

Enable SSL


Base DN

LDAP Base name

PasswordAttribute


Password hash algorithm

The algorithm is used to encrypt the password. For instance SHA-1, SHA-256, MD5, etc

Password hash prefix


LDAP Query page size


Enable debug

Two options: Yes, No. When it is enabled more log traces are printed in the Synchronization Server log


Attribute mapping

This connector can manage users, accounts, roles, groups, and grants.

image-1715077940898.png

As a limitation, it cannot detect password changes to be propagated to other systems.

Properties

Some agents require to configure some custom attributes, you will use the properties section to do that.

Property
Value

rename

true

key

LDAP attribute where Soffid account name is stored. If the property is not present, object will be searched by its distinguishedName

modificationTimestamp

LDAP attribute

removeDisabledAccounts

Set to true to remove disabled accounts from LDAP server

If a key value is set, LDAP connector will search for objects based on this LDAP attribute value, rather than its DN. Thus, an index on this attributed is highly recommended.

Renaming

To support object renaming, Soffid needs to store the Soffid account name on a specific LDAP attribute. It's highly recommended to index such a field. To enable it, add the following properties to each object mapping. At any time, object renaming can be disabled by setting the property rename to false.

Property
Value

rename

true

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound or outbound attribute mappings.

Using a windows connector you can map users, groups, and role objects. Active Directory membership is automatically managed based on user and group mappings.

You can map users, groups, and role objects. User membership must be managed on the role members' attribute expression.

Any object mapping must have the following system attributes:

System attribute
Value

objectClass

LDAP Object Class. It can evaluate to an array of objects

dn

Full qualified object name

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

image-1659087931478.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects. 

To view some examples, visit the Outgoing triggers examples page.

Oracle Connectors

Oracle Connectors

Oracle Connector

Introduction

Description

Oracle Connector could manage an Oracle database.

Soffid's Oracle connector supports Profiles since version 2.2.6.14

Managed System

This connector is specific for integration with an Oracle database, if you want to connect a generic SQL database, please visit the following page: SQL Connector.

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

It is needed a user with sysdba access and permissions.

User management

Criteria:

Exceptions:

Download and Install

This addon is located in the Connectors section and its name is Oracle Connector.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

This connector could manage User and Role objects.

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this Oracle Connector you must select "OracleAgent" in the attribute "Type" of the generic parameters section in the agents' page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

image-1704283498429.png

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User

Sysdba user name to authenticate

Oracle password

Password of the user to authenticate

Connection string to database

Database URL. Use something like jdbc:oracle:thin:@host:port:sid

Password to protect roles

Optional password to use on password protected roles

Default user profile

Optional profile to set limits on the database resources and the user password

Default tablespace

Optional tablespace for user creation

Temporary tablespace

Optional temporary tablespace for user creation

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

image-1704283537855.png

Load triggers

You can define JavaScript or BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects. 

To view some examples, visit the Incoming triggers examples page.

Access Control

Oracle connector can establish an access control for Oracle Users.

If the access control checkbox is enabled, only the users and applications that are listed on the access control page will be allowed to log in. So, you can restrict the IP address and application a user can connect from.

This restriction does not apply to DBA users.

image-1706003656568.png

Check that the user/account is not unmanaged.

When the Enable access control to the database check box is checked, the UpdateAccessControl task will be launched. The following tables will be created on the SQL Server:

When you try to connect to SQL Server, the logon_audit_trigger is launched to check if you have access or not.

You can check the Access Logs page for access controls.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes that you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you can check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will do something like "Import authoritative data from <AGENT_NAME>".

Reconcile

To manage an automatic task to synchronize user objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


Oracle Connectors

Oracle EBS Connector

Introduction

Description

Oracle Connector could manage an Oracle E-Business Suite.

Managed System

This connector is specific for integration with an Oracle E-Business Suite, if you want to connect a generic SQL database, please visit the following page: SQL Connector.

For more information about the Oracle E-Business Suite, please visit the following page: Oracle E-Business Suite

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

It is needed a user with access and permissions to the database.

Download and Install

This addon is located in the Connectors section and its name is Oracle EBS Connector.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

This connector could manage only User objects.

Users created on Soffid will be created on EBS, in the same way disabled users on Soffid will be disabled on EBS.

The responsibilities that exist in EBS can be assigned to the users. They must be created like roles on Soffid System previously, with the same name that the responsibility has on EBS.

For instance: FND_RESP | CSF | CSF_FS_PDA_REP | STANDARD.

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this Oracle EBS Connector you must select "OracleEBudsinessAgent" in the attribute "Type" of the generic parameters section in the agents' page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User

User name to authenticate

Oracle password

Password of the user to authenticate

Connection string to database

Database URL. Use something like jdbc:oracle:thin:@host:port:sid

Load triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects.

To view some examples, visit the Incoming triggers examples page.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you could check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

To manage an automatic task to synchronize user objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


SAP Connector

SAP Connector

SAP Connector

Introduction

Description

SAP Connector could manage an SAP system.

Managed System

This connector is specific for integration with a SAP system through its interface BAPIs under the RFC standard.

For more information about SAP, please visit the following page: SAP

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

  1. The SAP Java Connector (JCO) must be installed in the host where the syncserver is running.
  2. A SAP account must be created with permission to execute user administration BAPIs using RFC. Additionally, the attached SAP Role definition Y_SOFFID.SAP can be used to assign permissions to SOFFID RFC user.
  3. The following transport order should be applied in order to synchronize passwords: K953376.de1 R953376.de1

Download and Install

This addon is located in the Connectors section and its name is SAP Connector.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

This connector could manage User, Account and Role objects.

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

This addon has2 available agents:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User Name

User name to authenticate

Password

Password of the user to authenticate

Host

Host of the instance of the SAP

System Type

- Standar SAP R/3

- Central User Administration (CUA)

Systen Number

System number of the server

Message server name


Message server port


Message server logon group


Message server system id


SAP Router string


Client number 

Client number of the server

Language

Language of the server

Unlock users

Values [ YES | NO ]. If "YES"  allows to Soffid to unblock blocked users

Method to set productive passwords

- Z_SOFFID_UPDATE_PASSWORD

- BAPI_USER_CHANGE

- SUSR_USER_CHANGE_PASSWORD_RFC

- Z_SOFFID_SET_PWD_CHILD_SYSTEMS (CUA only)

Manage SAP roles

Values [ YES | NO ]. If "YES" allows to Soffid manage Roles

SAP Payroll to get employee data

SAP payroll to get employee data

Enable debug

Values [ YES | NO ].

Attribute mappings

The attribute mappings are only available for SAP (Complete) configuration.

Properties

Nothing to configure. There are no properties

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound and outbound attribute mappings.

Using SAP connector you can map users.

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

Load triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects.

To view some examples, visit the Incoming triggers examples page.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you could check in the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user, account or role,", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


SCIM Connector

SCIM Connector

SCIM Connector

Introduction

Description

SCIM connector can manage every target system with a published API that allows the SCIM protocol for communication.

SCIM is basically a REST JSON web service with specific HTTP requests and responses, and also a specific JSON format for attributes and values.

For more information about SCIM protocol you could visit its home page: SCIM protocol, or to visit the introduction page of our SCIM addon: Introduction to SCIM

Managed System

The official web of SCIM shows all the possible target systems that allow SCIM protocol: SCIM implementations

Some of the most popular implementations:

For more information to check if your system may be synchronized with this connector, you do not hesitate to contact us through our Contact form

Prerequisites

t is needed a user with access and permissions to the endpoints and operations required in the scope of the integration.

Also, the documentation, specification or tutorial of the web service, despite SCIM defining a schema for the objects, most applications or servers use to implement extended or customized versions of it.

Download and Install

This addon is located in the Connectors section and its name is SICM connector.

For more information about the installation process, you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this SCIM Connector you must select "SCIM" in the attribute "Type" of the generic parameters section in the agents page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

Server URL

URL of the SCIM web service. It is used as the basis of the URL mapped to call the operations.

Authentication method

Options:

  • "None": no authentication.

  • "Basic": it uses "User name" and "Password" parameters to generate a basic authentication token to connect with the "Server URL"

  • "Token": it uses a token bearer generated from a specific "Authentication URL" using "username" and "password" in a GET HTTP request. The token bearer is used in the next requests to connect with the "Server URL"

  • "TokenBasic": it uses a token bearer generated from a specific "Authentication URL" using "User name" and "Password" as a basic authentication token. The token bearer is used in the next requests to connect with the "Server URL"

User name

User to authenticate

Password

Password of the user to authenticate

Authentication URL

URL to retrieve the token bearer used to authenticate with the "Server URL"

Enable debug

Two options: "Yes", "No": it enables or not more log traces in the Synchronization Server log

Attribute mapping

This connector can manage users and groups.

Properties

The following properties are defined for each object type:

Property

Meaning

path (required)

Path relative to main service URL where this type of object is to be managed

keyAttribute (required)

The SCIM attribute is used to find objects on SCIM repository

changeProperty (optional)

For authoritative identity sources that support delta changes, this property sets the SCIM attribute used to identify the change number of any object

preventDeletion (optional)

Set to true to prevent Soffid from removing objects

Attributes

You may map the attributes of the target system with the Soffid available attributes.

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

If you are trying to connect to WSO2IS server, you must enable the WSO2 workaround setting, in order to bypass some WSO2 buggy implementations. You can get default mappings for WSO2IS here: wso2is-config.xml. Download it and import it into the Soffid agent attribute mappings form.

For example:

SCIM Connector - example.png

Triggers


Load triggers

 

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs on the users' page.

Operational

Monitoring

After the agent configuration you could check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user, account, role, group or grant", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


Shell Connector

Shell Connector

Shell Connector

Introduction

Description

Linux Connector could manage a lot of services running on Linux systems (either 32 or 64 bits).

Managed System

This connector has implemented several ways to communicate with services on Linux, below, the list of those services:

If your system is not in the previous list, it's possible to include it easily!

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

A Soffid Synchronization Server must be installed on the managed Linux system.

Download and Install

This addon is located in the Connectors section and its name is Shell Connector.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this Shell Connector you could select one agent, from the next list of available agents, in the attribute "Type" of the generic parameters section in the agents' page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below, there are the specific parameters for each agent implementation.

Shell Agent

Parameter

Description

Shell

Shell to assign to new users

Persistent

Two options [ Yes , No ].

Prompt


Password hash algorithm

For instance SHA1, SHA-256

Password hash prefix

For instance SHA

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

SSH Agent

Parameter

Description

User name

User Linux for the SSH connection

SSH Key file (optional)


SSH Key (optional)


Password

The password of the user Linux

Server

Host or IP of the server for the SSH connection

Password hash algorithm

For instance SHA1, SHA-256

Password hash prefix

For instance SHA

Charset

For instance: UTF-8

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

Cisco ASA Agent

Parameter

Description

User name

User Linux

Key file (optional)


Password

The password of the user Linux

Privileged password


Server

Host or IP of the server

Charset

For instance: UTF-8

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

Exchange Agent

Parameter

Description

User name

Exchange user (with administrator permissions)

Password

The password of the exchange user

Exchange server PS script (RemoteExchange.ps1 / exshell.psc1)

For instance "E:\Microsoft\Exchange Server\V15\Bin\exshell.psc1"

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

Exchange version

Options: [ 2007 | 2010+ ]

Power Shell Agent

Parameter

Description

Startup script


Password hash algorithm

For instance SHA1, SHA-256

Password hash prefix

For instance SHA

Enable debug

Two options: [ Yes / No ]. When it is enabled more log traces are printed in the Synchronization Server log

Attribute mapping

This connector could manage Users, Groups and Roles.

Users

Groups

Roles

Properties

You can map user, groups and role objects. These are some of the properties to be mapped in those objects:

Property

Description

check

fgrep $user /etc/passwd

delete

userdel $user

insert

useradd $user

selectAll

cat /etc/passwd

selectAllParse

([^:]*):[^\n]*

selectByAccountName

fgrep $user /etc/passwd

selectByAccountNameParse

([^:]*):[^\n]*

update

usermod $user

updatePassword

-

validatePassword

-

For the "Cisco ASA Agent" has these attributes:

Property

Description

check

show run user $user

checkAttributes

user level

checkParse

username ([^ ]+) password.*privilege (\d+)\r\n

delete

no username $user

insert

username $user password $password encrypted privilege $level

selectAll

show run user

selectAllAttributes

user level

selectAllParse

username ([^ ]+) password.*privilege (\d+)\r\n

selectByAccountName

show run user

selectByAccountNameParse

username ([^ ]+) password.*privilege (\d+)\r\n

selectByAccountNamelAttributes

user level

update

username $user password $password encrypted privilege $level

updatePassword

username $user password $password encrypted privilege $level

The "Exchange Agent" has these attributes:

Property

Description

check

fgrep $user /etc/passwd

delete

userdel $user

insert

New-Mailbox -UserPrincipalName "${UserPrincipalName}" -Name "Shell plugin" -Alias "${Alias}" -Room

selectAll

Get-Mailbox

selectByAccountName

Get-Mailbox "Shell plugin"

update

usermod $user

updatePassword

-

validatePassword

-

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound and outbound attribute mappings.

You can map user, groups and role objects. These are some of the attributes to be mapped in those objects:

System attribute

Description

user

accountName

this{"1"}

accountName

The "Cisco ASA Agent" has these attributes:

System attribute

Description

level

attributes{"level"}

user

accountName

password

password

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

Shell Connector - example.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects. 

"Cisco ASA Agent" has not implemented this feature.

To view some examples, visit the Outgoing triggers examples page.

Load triggers

You can define BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects. 

To view some examples, visit the Incoming triggers examples page.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs at user page.

Operational

Monitoring

After the agent configuration you could check in the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user, account, role, group or grant", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


Shell Connector

Invoker interface

Any agent, trigger or mapping can use the invoker method for the ActiveDirectory agent. The invoker method is available in the dispatcherService class as well as the in the serverService.

The invoker method is not specific of the Shell agent. Many other connectors support this method. The expected arguments are:

Here you have an example of a post-update trigger to create the home server for a user:

map = new HashMap();
map.put("user", source{"accountName"});
// Create folder
dispatcherService.invoke("invoke", "mkdir /home/${user}", map);
dispatcherService.invoke("invoke", "mkdir /home/${user}/Desktop", map);

There is a chance to execute operation across agents. For instance, if the system has an ActiveDirectory agent and an Exchange agent, here is a post-insert trigger to place in the post-insert trigger of the ActiveDirectory agent to execute a command in the Exchange one.

map = new HashMap();
map.put("user", source{"accountName"});
// Create folder
serverService.invoke("Exchange", "invoke", "EnableMailbox ${user}", map);

The list of allowed commands are:

Command

Object name

Parameters

Comments

invoke

Sentence to execute

Sentence parameters

Executes the command and return the results

SQL Connector

SQL Connector

SQL Connector

Introduction

Description

The SQL connector allows an easy way to configure and manage relational databases.

Managed System

There are a lot of relational databases, currently, these are the supported databases.

For more information: List of relational databases

If your system is not in the previous list, it's possible to include it easily!

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

It is needed a user with access and permissions to the schemes and tables required in the scope of the integration.

To configure DB2/400  or Sybase it is mandatory to install the drivers in the lib directory of the Sync Server.

The Java-ODBC bridge is deprecated in Java, and the support will be removed shortly.

Download and Install

The SQL is part of the default connectors, you do not need to install it, but you can upgrade it from the download management section.

You can visit the Connector Getting started page for more information about the installation process.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this SQL connector you must select "Customizable SQL agent" in the attribute "Type" of the generic parameters section in the agent's page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

image-1658999019877.png

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User name

Database user name to authenticate

Password

The password of the database user

Driver

Identifies the driver of the relational database to use.

Currently, these are the supported databases: MySQL (& MariaDB), PostgreSQL, Oracle, MS SQL Server, Informix, DB2/400, DB2 Universal, Sybase, ODBC

DB URL

URL that identifies the connection properties. Please refer to the specific database vendor documentation to build this URL.


jdbc:mariadb://<HOST>/<DATA_BASE>
jdbc:mysql://<HOST>/<DATA_BASE>
jdbc:postgresql://<HOST>/<DATA_BASE>
jdbc:oracle:<drivertype>:@<database>
jdbc:sqlserver://<HOST>;databaseName=<DATA_BASE>


 (*) More documentation about the DB URL 


SQL Sentence to execute at startup

Each time the connection to the agent is established, this SQL statement will be executed.

Password hash algorithm

The algorithm is used to encrypt the password. For instance SHA1, SHA256, MD5, etc

Password hash prefix

Prefix to add it to the password.


{SHA1}BzE/DjIPIsv6Nc/CIFCOs/9FfH4=
{SHA256}AIEM+LlNb8ucXeSE077EGHYgs+KHblmquQ2FL+Dxj7Y=

Enable debug

Two options: Yes, and No.

It enables or not more log traces in the Synchronization Server log

Synchronization method

  • Full synchronization: persists the changes made in Soffid, regardless of the possible changes made in the final system.
  • Incremental synchronization: this type of synchronization is used to avoid losing changes that have been made to the target system. First, Soffid's changes will be propagated to the target system, and then the changes on the target system will be made in the Soffid system. If the changes are in the same attribute, the Soffid value is the one that will persist.

(**)

image-1658999086220.png

Attribute mapping

This connector can manage users, accounts, roles, groups, and grants.

Properties

Some agents require to configure some custom attributes, you will use the properties section to do that.

Any SQL sentence gets its parameters in three step process:

  1. The synchronization engine creates the Soffid object.
  2. The Soffid object is translated into a managed system object, using the attribute translation rules.
  3. Soffid parser looks for any identifier preceded by a colon (:) symbol. For any symbol found, the symbol is replaced by a parameter whose value is the managed system attribute with the replaced identifier.

Once the SQL sentence has been executed, in the case of SELECT clauses, the column names are used to generate a virtual managed system object. The last step is to apply the attribute translation to generate the Soffid object to be populated.

These are the properties required to map every object of the mapping:

Property

Value

selectAll

SQL sentence that needs to be executed to retrieve all the objects that currently exist on the database.

  • Applies to authoritative identity sources.

  • On non-authoritative identity sources, only the columns needed to calculate the name soffid attribute are needed.

You can use this property with the following objects: user, account, role, and authoritative change.


SELECT * FROM USERS
SELECT * FROM ROLES

check

SQL sentence that will return when a single object already exists on the database.

You can use this property with all the Soffid objects.


SELECT ID FROM USERS WHERE USER=:USER
SELECT ID FROM ROLES WHERE ROLE=:ROLE

insert

SQL sentence to create a new object.

You can use this property with all the Soffid objects.


INSERT INTO USERS VALUES (:USER, :FIRST_NAME, :LAST_NAME, :MAIL, :GROUP)
INSERT INTO USER_ROLES (USETNAME, ROLNAME) VALUES (:USERNAME, :ROLNAME)

update

SQL sentence to update an existing object.

You can use this property with all the Soffid objects.


UPDATE USERS SET FIRST_NAME=:FIRST_NAME, LAST_NAME=:LAST_NAME, MAIL=:MAIL, GROUP=:GROUP WHERE ID=:ID
UPDATE ROLES SET DESCRIPTION=:DESCRIPTION WHERE ROLE=:ROLE

delete

SQL sentence to remove (or disable) an existing object.

You can use this property with all the Soffid objects.


DELETE FROM USERS WHERE ID=:ID
DELETE FROM USER_ROLES WHERE ID=:ID

selectByAccount

SQL sentence to retrieve all the role grants made to an account (for single account information).

You can use this property with the following objects: grant.


SELECT * FROM USER_ROLES WHERE USERNAME=:USER

selectByName

SQL sentence to fetch role information based on its name (for single role information).

You can use this property with the following objects: role.


SELECT * FROM ROLES WHERE ROLE=:ROLE

updatePassword

SQL sentence to update the user password.

You can use this property with the following objects: user and account.


UPDATE USERS SET PASS=:PASS WHERE USER=:USER

validatePassword

SQL sentence to check the user password.

You can use this property with the following objects: user and account.


SELET 1 FROM USERS WHERE PASS=:PASS AND USER=:USER

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound or outbound attribute mappings.

You may map the attributes of the target system with the Soffid available attributes.

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

Example for roles:

image-1659003794802.png

Example for accounts:

image-1659003867652.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects.

To view some examples, visit the Outgoing triggers examples page.

Integration flows

Update User

Visit the Integration flows Update user page for more information

Update Account

Visit the Integration flows Update account page for more information



(*)

https://mariadb.com/kb/en/about-mariadb-connector-j/

https://docs.microsoft.com/es-es/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver16


(**) Soffid provides two synchronization types:

The first type, the full synchronization method, persists the changes made in Soffid, regardless of the possible changes made in the target system.

For the second type, the incremental synchronization method, Soffid has developed a synchronization system, using custom internal attributes, to check what changes have been made to the different attributes of an object. Thus, it tries to avoid losing the changes that have been made in the target system. First, Soffid's changes will be propagated to the target system, and then the changes on the target system will be made in the Soffid system. If the changes are in the same attribute, the Soffid value is the one that will persist.


SQL Connector

SQL Integration flows - Update user

Update user

Introduction

Soffid provides a workflow to create, modify, and delete a user in the final system. One can see the steps of the process in the following diagram. 

This process only applies to account type single users.

Diagram


image-1659448091093.png


Step by Step

In this document, we will explain the process that Soffid performs to modify a user for the SQL connector.

1. Initial step

First of all, Soffid checks if the user exists in Soffid and then checks the operation to perform, update or delete. 

1.1. If the user does not exist in Soffid, then Soffid asks to delete the user in the target System. 

❓ Warning message image-1659534714096.png

1.1.1. Yes: If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

1.1.2. No:  If the answer is Yes, the process finishes [10. End]

 

1.2. If the user exists in Soffid, the process continues through [2. User to remove?]. to check if the 

2. User to remove?

📌 By clicking on the User to remove? step,...

You can configure all the properties related to the user object for this step. image-1660224430017.png

2.1. If the user is marked for Deletion, Soffid will ask for user consent to continue with the process or to cancel it. If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

❓ Warning message image-1659534714096.png

2.2. If the user is marked for Update, it continues with the flow following through the No branch, [4. Insert or Update branch].

3. Delete branch

📊 Diagram image-1660653153427.png

3.1. When the operation to perform is to delete a user, first of all, Soffid has to check if the user exists in the target system. To do this, Soffid executes the property check of the User object. This property executes the SQL command to check if the user exists or not.

📌 By clicking on the User exists? step,...

You can configure all the properties related to the user object for this step.

image-1660294676813.png

3.1.1. If the user does not exist, there are no actions to perform in the target system, so the process finishes [10. End].

3.1.2. If the user exists, the flow continues executing the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user delete, and the result (true or false) determines if the main action will be performed or not.

3.1.2.1. False: if the result is false for one or more of these triggers, the process finishes [10. End].

3.1.2.2.True: if the result is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-delete triggers step,...

You can configure all the pre-delete triggers related to the user object for this step.

image-1660295438225.png

3.1.3. Soffid removes the user. To do that, Soffid executes the property delete of the User object.

📌 By clicking on the Remove user step,...

You can configure the properties related to the user object for this step.

image-1660297226512.png

3.1.3.  Then Soffid executes the post-delete triggers if any. These triggers can be used to perform a specific action just after performing the remove user operation on the target object.

📌 By clicking on the Post-delete triggers step,...

You can configure the post-delete triggers related to the user object for this step.

image-1660228753412.png

3.1.3.  Then the process finishes [10. End].

4. Insert or Update branch

4.1. When the operation to perform is to update a user, first of all, Soffid generates the columns values.  That is, Soffid calculates the values of the columns from the original values of Soffid.

📌 By clicking on the generate column values step,...

You can configure the attributes related to the user object for this step.

image-1660287889319.png

4.2.Then Soffid asks if the user exists in the target system to decide the action to execute, this action can be an update or an insert. Soffid executes the property check of the User object.

4.2.1. If the user does not exist in the target system, the process continues through [5. Insert user branch]

4.2.2. If the user exists in the target system, the process continues through [6. Update user branch].

📌 By clicking on the User exists? step,...

You can configure the properties related to the user object for this step.

image-1660287995689.png

5. Insert user branch

📊 Diagram image-1660653294372.png

5.1. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user create, and the result (true or false) determines if the main action will be performed or not.

5.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not created.

5.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

5.2. Soffid creates the user. To do that, Soffid executes the property insert of the User object.

📌 By clicking on the Create user step,...

You can configure the properties related to the user object for this step.

image-1660290443410.png

5.3. Then Soffid executes post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create user operation on the target object.

📌 By clicking on the Post-insert triggers step,...

You can configure the Post-insert triggers related to the user object for this step.

image-1660290613568.png

5.4. Then the process continues through [7. Grants].

6. Update user branch

📊 Diagram image-1660653234222.png

6.1. Soffid fetches the current values of the user.  Soffid executes the property selectByAccountName of the User object.

&&TODO&& IMAGEN

6.2. Then compute delta changes, if the property Synchronization method selected is Full Synchronization, then Soffid has to keep the columns values of the last update. If  there was any change in the target system:

&&TODO&& IMAGEN

6.3. And finally execute the pre-update triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user update, and the result (true or false) determines if the main action will be performed or not.

6.3.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not updated

6.3.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-update triggers step,...

You can configure the Pre-update triggers related to the user object for this step.

image-1660305125794.png

6.4. Soffid updates the user. To do that, Soffid executes the property update of the or User object.

📌 By clicking on the update user step,...

 You can configure the properties related to the user object for this step.

image-1660305271649.png

6.5. Then Soffid executes the post-update triggers if any. These triggers can be used to perform a specific action just after performing the update user operation on the target object.

📌 By clicking on the Post-update triggers step,...

You can configure the Post-update triggers related to the user object for this step.

image-1660305556302.png

6.6. Then the process continues through [7. Grants].

7. Grants

At this point, soffid runs the actions relative to the grants

7.1. Once the process arrives at this step, Soffid generates account column values.  That is, Soffid creates a dummy object with only the account name, this object will be used later.

📌 By clicking on the generates account columns values step,...

You can configure the attribute mappings related to the grant object for this step.

image-1660297529635.png

7.2. Then, Soffid fetches the current grants for the user.  Soffid executes the property selectByAccount of the grant object with the values of the previous step

📌 By clicking on the fetch current grants step,...

 You can configure the properties related to the grant object for this step.

image-1660298601931.png

7.3. Finally, Soffid parses grant rows, that is Soffid makes the mappings defined 

📌 By clicking on the parse grant rows step,...

 You can configure the attribute mappings related to the grant object for this step.

image-1660298660328.png

7.3. Then the process continues through [8. Grant to add]

8. Grant to add

This is a loop while there are grants to add. This grants list comes from the previous step [7. Grants].

📊 Diagram image-1660657837165.png

8.1. If there are No grants to add, the process goes to [9. Grant to Remove].

8.2. Yes, there are grants to add:

8.2.1. Soffid generates grant column values and  Soffid checks if the grant exists in the target system, Soffid executes the property check of the grant object.

📌 By clicking on the generate grant column values step,...

 You can configure the attribute mappings related to the grant object for this step.

image-1660306333224.png

8.2.2. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, a grant create, and the result (true or false) determines if the main action will be performed or not.

8.2.2.1. False: if the response is false for one or more of these triggers, the process goes to [8. Grant to add] and the grant is not created.

8.2.2.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-insert triggers step,...

 You can configure the Pre-insert triggers related to the grant object for this step.

image-1660651106043.png

8.2.3. If the result of the triggers is true, then Soffid creates the grant. To do that, Soffid executes the property insert of the grant object.

📌 By clicking on the create grant step,...

 You can configure the properties related to the grant object for this step.

image-1660306637374.png

8.2.4. Then Soffid executes the post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create grant operation on the target object.

📌 By clicking on the Post-insert triggers column values step,...

 You can configure the Post-Update related to the grant object for this step.

image-1660651171773.png

8.2.5.  Then the process continues through  [8. Grant to add].

9. Grant to remove

📊 Diagram image-1660657874513.png

This is a loop while there are grants to remove. This grants list comes from the previous step [7. Grants].

9.1 No: If there are No grants to add, the process goes to [10. End].

9.2. Yes,  there are grants to remove:

9.2.1. Soffid executes the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, a grant delete, and the result (true or false) determines if the main action will be performed or not.

9.2.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the grant is not deleted.

9.2.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the pre-delete trigger step,...

 You can configure the Pre-delete triggers related to the grant object for this step.

image-1660651495130.png

9.2.2. If the result of the triggers is true, then Soffid deletes the grant. To do that, Soffid executes the property delete of the grant object. This operation can return a true or false result.

9.2.2.1. False: the delete action could not be performed and the process check for another grant [9. Grant to remove].

9.2.2.2. True: the delete action could be performed properly. Soffid continues to the next step.

📌 By clicking on the delete grant step,...

 You can configure the properties related to the grant object for this step.

image-1660651418301.png

9.2.3. Then Soffid executes the post-delete triggers if any. These triggers can be used to perform a specific action just after performing the delete grant operation on the target object.

📌 By clicking on the post-delete trigger step,...

 You can configure the Post-delete triggers related to the grant object for this step.

image-1660661955749.png

9.2.4. Then the process continues through [9. Grant to remove].

10. End

The process finishes and the log is displayed, and you can download it by clicking the Download button.

📑 Log detail image-1660662018857.png

Windows Connector

Windows Connector

Windows Connector

Introduction

Description

This connector implements the LDAPS protocol and it is used to connect the Sync-Server with every server that allows this communication protocol.

Managed System

This connector has been performed to connect to the Active Directory system, it's a fork of our LDAP Connector with custom features.

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

To enable LDAPS in your Active Directory, please read the following guide: SSL access to Active Directory.

It is needed an Active Directory user with full administrator access.

Download and Install

This addon is located in the Connectors section and its name is Windows (including Active Directory).

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

This addon has 5 available agents:


For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation, "Active Directory"

Parameter

Description

Hostname

Host name of the server

LDAP base DN

LDAP Base name

Principal name

User name in DN format, including base name if needed

Password

Password for the user to connect.

Enable debug

Two options: [ Yes / No ].

When it is enabled more log traces are printed in the Synchronization Server log

Accepted certificates

Two options: [ Only trusted certificates / Any (insecure) ]

Follow referrals

Two options: [ Don't / Yes ]

If you select the Yes option, Soffid could follow the references to other systems if Soffid has the proper permissions.

Manage child domains

Two options: [ No / Yes ]

If you select the Yes option, Soffid will manage the domain referrals.

Create OUs when needed

Two options: [ No / Yes ]

If you select the Yes option and the OUs do not exist, these OUs will be created in the Active Directory. 

Real time load last login attribute

Two options: [ No / Yes ]

Real time load identity changes

Two options: [ No / Yes ]

You can check this option to synchronize the identities when Soffid is the authoritative data source.

You must enable periodic synchronization.

Attribute mapping

Active Directory connector could manage Users and Groups by using LDAPS protocol.

Properties

Some agents require to configure some custom attributes, you will use the properties section to do that.

To enable it, add the following properties to each object mapping:

Property

Description

rename

AD agent will always map account and group names to the SAMAccount attribute. BaseDN and cn can be calculated based on user attributes. AD agent is able to move and rename AD objects. If you don't desire users or groups to be renamed or moved, an object property named "rename" with the value "false" can be added to some object mappings.

searchBase

You can configure it if you want the reconciliation process to search accounts on a directory subtree other than AD root, put a searchBase property with the relative tree to look for.

key

The AD attribute works as the primary key. Usually, it's the sAMAccountName and can be omitted.

createDisabledAccounts

Set to true if you want the connector to create disabled accounts in the active directory. By default, disabled accounts are not created until enabled.

For instance:

image-1654785307110.png

Attributes

You can customize attribute mappings, you only need to select system objects and the Soffid objects related, manage their attributes, and make either inbound or outbound attribute mappings.

Using a windows connector you can map users, groups, and role objects. Active Directory membership is automatically managed based on user and group mappings.

Any object mapping must have the following system attributes:

System attribute

Description

objectClass

Active Directory object class. The following values mostly used "user", "group" or "organizationalUnit"

baseDn

Active Directory container where user or group should be created. Its value should be absolute, containing Active Directory DC parts

relativeBaseDn

Active Directory container where user or group should be created. Its value should be relative to Active Directory DC parts.

cn

Object name

There is a bunch of AD special attributes that need some special treatment:

System attribute

Description

sAMAccontName

Is automatically mapped. It is internally mapped to role name or account name, without further customization

accountExpires

Sets the last date (in nanoseconds since 1600) in which the account will be valid. A common mapping expression is:

if ( attributes {"expirationDate"} == null)
   return 9223372036854775807L;
else
   return attributes{"expirationDate"}.getTime() * 10000L + 116445528000000000L;

samAccountType

Can be used to identify distribution lists. A value of 268435457 or 268435456 means the AD group is a distribution list group rather than a security group.

lastLogon

The attribute can be used to get the last time an account was used. Soffid attribute is named lastLogin and the right mapping could be the following one. Mind when you make a reference to lastLogon attribute, every domain controller is queried about this attribute, as its value is not replicated across AD controllers:

if ( lastLogon == null || lastLogon == void) return null;
Long v = Long.decode(lastLogon);
v = v / 10000000L;
v-=11644473600L;
return new Date(v*1000);
=>
lastLogin

userCannotChangePassword

true/false

This is a virtual attribute that can be used to indicate if a user can or cannot change the password. You can't assign this permission by directly modifying the UserAccountControl attribute. 


For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

image-1654785419948.png

image-1654785472665.png

Triggers

You can define BeanShell scripts that will be triggered when data is loaded into the target system (outgoing triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects. 

To view some examples, visit the Outgoing triggers examples page.

Avoid incremental load authoritative

The Customizable Active Directory connector has an incremental load authoritative process. 

When this process is executed, it requests the changes to Active Directory after the uSNChanged

The value of this field is saved in Soffid in the parameter soffid.sync.authoritative.change.NAME_OF_THE_AGENT

If you want to launch a complete load authoritative process, remove this parameter first. At the end of the process, the parameter will be generated automatically.

For more information, go to the Soffid Parameters page.


Windows Connector

HOWTO SSL access to Active Directory

Table of Contents

Introduction

This howto will show you how to install the Certificate Services in Windows Acive Directory Servers.

Before beginning, make sure the Internet Information Server (IIS) is installed in your server.

Installing the Certificate Services

1. Click Start, select Control Panel and click Add or Remove Programs.

WIN Connector - Installing 1.png

2. In the Add or Remove Programs window, click Add/Remove Windows Components, check the Certificate Services and click Next.

WIN Connector - Installing 2.png

3. Click Next in the CA Type page.

WIN Connector - Installing 3.png

4. Fill up the Common name for this CA and click Next.

WIN Connector - Installing 4.png

5. Click Next in the Certificate Database Settings page.

WIN Connector - Installing 5.png

6. The Certificate Services will now be installed.

WIN Connector - Installing 6.png

7. Click Finish and restart your server.

WIN Connector - Installing 7.png

Configuring Automatic Certificate Request for Domain Controllers

1. Click Start, select Administrative Tools and click Domain Controller Security Policy.

WIN Connector - Configuring 1.png

2. In the Default Domain Controller Security Settings window, click the Public Key Policies folder.

WIN Connector - Configuring 2.png

3. Right click Automatic Certificate Request Settings, select New and click Automatic Certificate Request.

WIN Connector - Configuring 3.png

4. Click Next in the Automatic Certificate Request Setup Wizard

WIN Connector - Configuring 4.png

5. Select Domain Controller in the Certificate Template page and click Next

WIN Connector - Configuring 5.png

6. Click Finish and reboot your server.

WIN Connector - Configuring 6.png

Check for Issued Certificate

1. Click Start, select Administrative Tools and click Certification Authority. This will launch the Certification Authority application.

WIN Connector - Check 1.png

2. In Certification Authority, click the + sign and check the Issued Certificates folder if your server has been issued a certificate.

WIN Connector - Check 2.png

Import certificate

1. Select the certificate and open it. Select the "Certification Path" tab and select the root certificate.

WIN Connector - Import 1.png

2. Click on "View Certificate" button and navigate to "Details" tab.

WIN Connector - Import 2.png

3. Click on "Copy to File..." button and follow the export steps to obtain the certificate.

WIN Connector - Import 3.png

4. Open cmd and go to the soffid-iam-sync instalation directory and execute:

jre\bin\keytool -import -file “file” -keystore conf\cacerts -alias AD_CERT

Afterwards, the console will ask you for a password. Type the default password: changeit and press enter.



Windows Connector

Invoker interface for Active Directory

Any agent, trigger or mapping can use the invoker method for the ActiveDirectory agent. The invoker method is available in the dispatcherService class.

The invoker method is not specific of the Active Directory agent. Many other connectors support this method. The expected arguments are:

Here you have an example of a post-update trigger to create the home server for a user:

map = new HashMap();
String server = "//"+source{"homeServer"}+"/"+source{"accountName"};
// Create folder
f = dispatcherService.invoke("smb:mkdir", server, map);
   
// Add administrator ACL
map.put("user", "soffid_admin");
map.put("permission", "GENERIC_ALL");
map.put("flags", "CONTAINER_INHERIT_ACE OBJECT_INHERIT_ACE");
f = dispatcherService.invoke("smb:addacl", path, map);
 
// Add user ACL
map.put("user", source{"accountName"});
f = dispatcherService.invoke("smb:addacl", path, map);
// Change folder ownership using a domain admin account
map.put("_auth_user", "user1");
map.put("_auth_domain", "domain1");
map.put("_auth_password", "SuperSecret");
f = dispatcherService.invoke("smb:setOwner", path, map);

The example above uses the smb:mkdir action to create the folder, the smb:addacl to add a new access control list entry. Other commands allow the query and modification of Active Directory objects like users and groups.

The list of allowed commands are:

Command

Object name

Parameters

Comments

insert

Object distinguished name

Object attributes

Creates a new active directory object

update

Object distinguished name

Object attributes

Modifies an existing active directory object. Only the attributes present in the map will be updated

delete

Object distinguished name

-

Removes an existing active directory object.

select

Base distinguished name

Object criteria attribute

Search for any object with the values specified in the parameters map, starting in the specified base DN. 

The return value is a list of maps. Each element in the list is an Active Directory object

get

Object distinguished name

-

Returns the object with the specified object DN.

The return value is a list containing one or no maps. The map, if exists, contain the object attributes

smb:mkdir

Shared file

Optionally:

  • _auth_user
  • _auth_password
  • _auth_domain

Creates the shared folder.

The shared folder name should follow the syntax //server/sharedFolder/Path or \\server\\sharedFolder\Path

It is recommended to use the first syntax because the second one requires the script to escape any backslash character, leading to a harder to read script

smb:exist

Shared file

Optionally:

  • _auth_user
  • _auth_password
  • _auth_domain

Returns a list with a single map. The map has the attribute exist with a boolean value indicating whether the file exists or not

smb:rmdir

Shared file

Optionally:

  • _auth_user
  • _auth_password
  • _auth_domain

Removes the full  directory and any file or directory within

smb:rm

Shared file

Optionally:

  • _auth_user
  • _auth_password
  • _auth_domain

Removes the file or directory. The command will fail if the directory is not empty.

smb:getacl

Shared file

Optionally:

  • _auth_user
  • _auth_password
  • _auth_domain

Returns a list of maps representing each access control list entry for that file or folder. Each map has three values:

  • user: The user or group name. When the user or group is unknown, the user or group SID is used.

  • permission: A text string with the permissions granted with that ACE. The string contains one or more of these values concatenated:

    • FILE_READ_DATA

    • FILE_WRITE_DATA

    • FILE_APPEND_DATA

    • FILE_EXECUTE

    • FILE_LIST_DIRECTORY

    • FILE_ADD_FILE

    • FILE_ADD_SUBDIRECTORY

    • FILE_TRAVERSE

    • FILE_DELETE_CHILD

    • FILE_READ_ATTRIBUTES

    • FILE_WRITE_ATTRIBUTES

    • FILE_READ_EA

    • FILE_WRITE_EA

    • DELETE

    • READ_CONTROL

    • WRITE_DAC

    • WRITE_OWNER

    • SYNCHRONIZE

    • ACCESS_SYSTEM_SECURITY

    • MAXIMUM_ALLOWED

    • GENERIC_ALL

    • GENERIC_EXECUTE

    • GENERIC_WRITE

    • GENERIC_READ

  • flags: A text string with the inheritance flags for that ACE. The string contains one or more of these values concatenated:

    • CONTAINER_INHERIT_ACE

    • FAILED_ACCESS_ACE_FLAG

    • INHERIT_ONLY_ACE

    • INHERITED_ACE

    • NO_PROPAGATE_INHERIT_ACE

    • OBJECT_INHERIT_ACE

    • SUCCESSFUL_ACCESS_ACE_FLAG

smb:addacl

Shared file

Map with these three values:

  • user

  • permission

  • flags

And optionally, these ones:

  • _auth_user
  • _auth_password
  • _auth_domain

Adds an access control list with the specified permission and flags

smb:removeacl

Shared file

Map with these three values:

  • user
  • permission
  • flags

And optionally, these ones:

  • _auth_user
  • _auth_password
  • _auth_domain

Remove the access control list entry that matches the map. If the permission or flag is missing, the connector will remove any access control list entry for the specified user

smb:setowner

Shared file

Map with the value:

  • user

And optionally, these ones:

  • _auth_user
  • _auth_password
  • _auth_domain

Sets the directory owner to the one specified in the map

By default, actions are performed by the account used to configure the AD connector, but sometimes, another account must be used, mainly when dealing with NAS servers. In order to user custom credentials SMB commands accept three special parameters: _auth_user, _auth_password and _auth_domain. If this parameters are null, the agent user and password is used.


Windows Connector

Active Directory back channel configuration

Introduction

In order to configure the Active Directory back-channel, you must use the eris command line tool.

Being at IAM-Sync installation directory change to eris or eris64 directory (\ProgramFiles\Soffid\eris64) and execute:

eris-ad-service CONFIGURE url-syncserver agent-name | more

Where url-syncserver is the master sync server url (http://master.dom.dom:port) and agent-name is the agent code name configured on Soffid console.

* To see more information when configuring use | more.

In order to test configuration, you must use the eris command line tool.

Being at the IAM-SYNc installation directory change to eris or eris64 directory and execute:

eris-ad-service TEST user pass | more

Where user and pass can be dummy. If you use a real one it will be propagated to the system.

* To see more information during test use | more.


https://github.com/SoffidIAM/syncserver


Windows Connector

AD Integration flows - Update user

Update

Introduction

Soffid provides a workflow to modify and/or delete a user in the final system. In it, we can see each of the steps of which this process is composed. 

Diagram

image-1661426896997.png

Step by Step

In this document, we will explain the process that Soffid performs to modify a user for the AD connector.

1. Initial step

First of all, Soffid checks if the user exists in Soffid and then checks the operation to perform, update or delete. 

1.1. If the user does not exist in Soffid, then Soffid asks to delete the user in the target System. 

❓ Warning message image-1659534714096.png

1.1.1. Yes: If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

1.1.2. No:  If the answer is Yes, the process finishes [10. End]

1.2. If the user exists in Soffid, the process continues through [2. User to remove?]. to check if the 

2. User to remove?

📌 By clicking on the User to remove? step,...

 You can configure all the properties related to the user object for this step

image-1661421084985.png

2.1. If the user is marked for Deletion, Soffid will ask for user consent to continue with the process or to cancel it. If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

❓ Warning message image-1659534714096.png

2.2. If the user is marked for Update, it continues with the flow following through the No branch, [4. Insert or Update branch].

3. Delete branch

📊 Diagram

image-1661440073073.png

3.1. When the operation to perform is to delete a user, first of all, Soffid has to check if the user exists in the target system. 

3.1.1. If the user does not exist, there are no actions to perform in the target system, so the process finishes [10. End].

3.1.2. If the user exists, the flow continues executing the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user delete, and the result (true or false) determines if the main action will be performed or not.

3.1.2.1. False: if the result is false for one or more of these triggers, the process finishes [10. End].

3.1.2.2.True: if the result is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-delete triggers step,...

You can configure all the pre-delete triggers related to the user object for this step.

image-1661427702845.png

3.1.3. Soffid removes the AD user in the Active directory.

3.1.3.  Then Soffid executes the post-delete triggers if any. These triggers can be used to perform a specific action just after performing the remove user operation on the target object.

📌 By clicking on the Post-delete triggers step,...

You can configure the post-delete triggers related to the user object for this step.

image-1661427821300.png

3.1.3.  Then the process finishes [10. End].

4. Insert or Update branch

4.1. When the operation to perform is to update a user, first of all, Soffid generates the AD user.  That is, Soffid calculates the values of the AD user object from the original values of Soffid.

📌 By clicking on the generate AD user step,...

You can configure the attributes related to the user object for this step.

image-1661430867005.png

4.2.Then Soffid asks if the user exists in the target system to decide the action to execute, this action can be an update or an insert. 

4.2.1. If the user does not exist in the target system, the process continues through [5. Insert user branch]

4.2.2. If the user exists in the target system, the process continues through [6. Update user branch].

5. Insert user branch

📊 Diagram  

image-1661440189859.png

5.1. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user creates, and the result (true or false) determines if the main action will be performed or not.

5.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not created in the target system.

5.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

5.2. Soffid creates AD user in the Active directory

5.3. Then Soffid executes post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create user operation on the target object.

📌 By clicking on the Post-insert triggers step,...

You can configure the Post-insert triggers related to the user object for this step.

image-1660290613568.png

5.4. Then the process continues through [7. Groups].

6. Update user branch

📊 Diagram

image-1661440155417.png

 

6.1. Soffid checks if there are any change between the generated object and the values of the object in the target system.

6.1.1. False: if there are no changes,  the process finishes [10. End].

6.1.2. True: if there are changes to update, Soffid continues to the next step.

6.2. Soffid executes the pre-update triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user update, and the result (true or false) determines if the main action will be performed or not.

6.2.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not updated in the target system

6.2.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-update triggers step,...

You can configure the Pre-update triggers related to the user object for this step.

image-1660305125794.png

6.3. Soffid updates the AD user in the Active directory

📌 By clicking on the update user step,...

 You can configure the properties related to the user object for this step.

image-1661431455021.png

6.4. Then Soffid executes the post-update triggers if any. These triggers can be used to perform a specific action just after performing the update user operation on the target object.

📌 By clicking on the Post-update triggers step,...

You can configure the Post-update triggers related to the user object for this step.

image-1661500966301.png

6.6. Then the process continues through [7. Grants].

7. Grants

At this point, Soffid runs the actions relative to the grants. The operations can be to add the user to one or more groups or to remove the user from existing groups.

8. Group to remove

This is a loop while there are groups to remove.

📊 Diagram

image-1661440287892.png

 

8.1. If there are No groups to remove, the process goes to [9. Group to add].

8.2. Yes, there are groups to remove:

8.2.1. Soffid executes the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, a Remove user to group, and the result (true or false) determines if the main action will be performed or not.

8.2.1.1. False: if the response is false for one or more of these triggers, the process goes to [8. Group to remove] and the grant is not created.

8.2.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-delete triggers step,...

 You can configure the Pre-delete triggers related to the grant object for this step.

image-1661497389637.png

8.2.3. If the result of the triggers is true, then Soffid adds the user to a group. 

8.2.4. Then Soffid executes the post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create grant operation on the target object.

📌 By clicking on the Post-delete triggers column values step,...

 You can configure the Post-Update related to the grant object for this step.

image-1661497647604.png

8.2.5.  Then the process continues through  [8. Grant to add].

9. Group to add

📊 Diagram  

image-1661440333930.png

This is a loop while there are grants to remove. This grants list comes from the previous step [7. Grants].

9.1 No: If there are No grants to add, the process goes to [10. End].

9.2. Yes,  there are grants to remove:

9.2.1. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, Add user to group, and the result (true or false) determines if the main action will be performed or not.

9.2.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the grant is not deleted.

9.2.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the pre-delete trigger step,...

 You can configure the Pre-delete triggers related to the grant object for this step.

image-1660651495130.png

9.2.2. If the result of the triggers is true, then Soffid adds the user to the group. This operation can return a true or false result.

9.2.2.1. False: the add action could not be performed and the process check for another grant [9. Group to add].

9.2.2.2. True: the add action could be performed properly. Soffid continues to the next step.

9.2.3. Then Soffid executes the post-insert triggers if any. These triggers can be used to perform a specific action just after performing the add grant operation on the target object.

📌 By clicking on the post-insert trigger step,...

 You can configure the Post-insert triggers related to the grant object for this step.

image-1660661955749.png

9.2.4. Then the process continues through [9. Group to add].

10. End

The process finishes and the log is displayed, and you can download it by clicking the Download button.

📑 Log detail  

image-1661500002798.png

Windows Connector

AD Integration flows - Update account

Update

Introduction

Soffid provides a workflow to modify and/or delete an account in the final system. In it, we can see each of the steps of which this process is composed. 

Diagram

image-1661502094418.png

Step by Step

In this document, we will explain the process that Soffid performs to modify an account for the AD connector.

1. Initial step

First of all, Soffid checks if the account exists in Soffid and then checks the operation to perform, update or delete. 

1.1. If the user does not exist in Soffid, then Soffid asks to delete the user in the target System. 

❓ Warning message image-1659534714096.png

1.1.1. Yes: If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

1.1.2. No:  If the answer is Yes, the process finishes [10. End]

 

1.2. If the user exists in Soffid, the process continues through [2. User to remove?]. to check if the 

2. Account to remove?

📌 By clicking on the Account to remove? step,...

 You can configure all the properties related to the account object for this step

image-1661507222061.png

2.1. If the account is marked for Deletion, Soffid will ask for user consent to continue with the process or to cancel it. If the answer is Yes, the process follows through the Yes branch, [3. Delete branch].

❓ Warning message image-1659534714096.png

2.2. If the account is marked for Update, it continues with the flow following through the No branch, [4. Insert or Update branch].

3. Delete branch

📊 Diagram

image-1661508089980.png

3.1. When the operation to perform is to delete an account, first of all, Soffid has to check if the account exists in the target system. 

3.1.1. If the account does not exist, there are no actions to perform in the target system, so the process finishes [10. End].

3.1.2. If the account exists, the flow continues executing the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, account delete, and the result (true or false) determines if the main action will be performed or not.

3.1.2.1. False: if the result is false for one or more of these triggers, the process finishes [10. End].

3.1.2.2.True: if the result is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-delete triggers step,...

You can configure all the pre-delete triggers related to the user object for this step.

image-1661427702845.png

3.1.3. Soffid removes the AD user in the Active directory.

3.1.3.  Then Soffid executes the post-delete triggers if any. These triggers can be used to perform a specific action just after performing the remove user operation on the target object.

📌 By clicking on the Post-delete triggers step,...

You can configure the post-delete triggers related to the user object for this step.

image-1661427821300.png

3.1.3.  Then the process finishes [10. End].

4. Insert or Update branch

4.1. When the operation to perform is to update a user, first of all, Soffid generates the AD user.  That is, Soffid calculates the values of the AD user object from the original values of Soffid.

📌 By clicking on the generate AD user step,...

You can configure the attributes related to the user object for this step.

image-1661430867005.png

4.2.Then Soffid asks if the user exists in the target system to decide the action to execute, this action can be an update or an insert. 

4.2.1. If the user does not exist in the target system, the process continues through [5. Insert user branch]

4.2.2. If the user exists in the target system, the process continues through [6. Update user branch].

5. Insert user branch

📊 Diagram  

image-1661508113071.png


5.1. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user creates, and the result (true or false) determines if the main action will be performed or not.

5.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not created in the target system.

5.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

5.2. Soffid creates AD user in the Active directory

5.3. Then Soffid executes post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create user operation on the target object.

📌 By clicking on the Post-insert triggers step,...

You can configure the Post-insert triggers related to the user object for this step.

image-1660290613568.png

5.4. Then the process continues through [7. Groups].

6. Update user branch

📊 Diagram


image-1661508149332.png

 

6.1. Soffid checks if there are any change between the generated object and the values of the object in the target system.

6.1.1. False: if there are no changes,  the process finishes [10. End].

6.1.2. True: if there are changes to update, Soffid continues to the next step.

6.2. Soffid executes the pre-update triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, user update, and the result (true or false) determines if the main action will be performed or not.

6.2.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the user is not updated in the target system

6.2.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-update triggers step,...

You can configure the Pre-update triggers related to the user object for this step.

image-1660305125794.png

6.3. Soffid updates the AD user in the Active directory

📌 By clicking on the update user step,...

 You can configure the properties related to the user object for this step.

image-1661431455021.png

6.4. Then Soffid executes the post-update triggers if any. These triggers can be used to perform a specific action just after performing the update user operation on the target object.

📌 By clicking on the Post-update triggers step,...

You can configure the Post-update triggers related to the user object for this step.

image-1661500966301.png

6.6. Then the process continues through [7. Grants].

7. Grants

At this point, Soffid runs the actions relative to the grants. The operations can be to add the user to one or more groups or to remove the user from existing groups.

8. Group to remove

This is a loop while there are groups to remove.

📊 Diagram


 

image-1661508169038.png

8.1. If there are No groups to remove, the process goes to [9. Group to add].

8.2. Yes, there are groups to remove:

8.2.1. Soffid executes the pre-delete triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, a Remove user to group, and the result (true or false) determines if the main action will be performed or not.

8.2.1.1. False: if the response is false for one or more of these triggers, the process goes to [8. Group to remove] and the grant is not created.

8.2.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the Pre-delete triggers step,...

 You can configure the Pre-delete triggers related to the grant object for this step.

image-1661497389637.png

8.2.3. If the result of the triggers is true, then Soffid adds the user to a group. 

8.2.4. Then Soffid executes the post-insert triggers if any. These triggers can be used to perform a specific action just after performing the create grant operation on the target object.

📌 By clicking on the Post-delete triggers column values step,...

 You can configure the Post-Update related to the grant object for this step.

image-1661497647604.png

8.2.5.  Then the process continues through  [8. Grant to add].

9. Group to add

📊 Diagram  

image-1661508179273.png


This is a loop while there are grants to remove. This grants list comes from the previous step [7. Grants].

9.1 No: If there are No grants to add, the process goes to [10. End].

9.2. Yes,  there are grants to remove:

9.2.1. Soffid executes the pre-insert triggers if there is anyone configured. More than one script can be configured. These scripts are executed just before the main action, Add user to group, and the result (true or false) determines if the main action will be performed or not.

9.2.1.1. False: if the response is false for one or more of these triggers, the process finishes [10. End] and the grant is not deleted.

9.2.1.2. True: if the response is true for all of these triggers, Soffid continues to the next step.

📌 By clicking on the pre-delete trigger step,...

 You can configure the Pre-delete triggers related to the grant object for this step.

image-1660651495130.png

9.2.2. If the result of the triggers is true, then Soffid adds the user to the group. This operation can return a true or false result.

9.2.2.1. False: the add action could not be performed and the process check for another grant [9. Group to add].

9.2.2.2. True: the add action could be performed properly. Soffid continues to the next step.

9.2.3. Then Soffid executes the post-insert triggers if any. These triggers can be used to perform a specific action just after performing the add grant operation on the target object.

📌 By clicking on the post-insert trigger step,...

 You can configure the Post-insert triggers related to the grant object for this step.

image-1660661955749.png

9.2.4. Then the process continues through [9. Group to add].

10. End

The process finishes and the log is displayed, and you can download it by clicking the Download button.

📑 Log detail  

image-1661508404245.png

Zarafa Connector

Zarafa Connector

Zarafa Connector

Introduction

Description

Zarafa Connector could manage a Zarafa mail server.

Managed System

This connector is specific for integration with a  Zarafa mail server.

For more information about the Zarafa, please visit the following page: Zarafa

For more information to check if your system may be synchronized with this connector you do not hesitate to contact us through our Contact form

Prerequisites

A Soffid Synchronization Server must be installed on the Zarafa server.

Download and Install

This addon is located in the Connectors section and its name is Zarafa Connector.

For more information about the installation process you can visit the Addons Getting started page.

Agent Configuration

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this Zarafa Connector you could select "Zimbra Agent" or the "Customizable Zimbra Agent" in the attribute "Type" of the generic parameters section in the agent's page configuration.

The difference between both agents is that "Customizable Zimbra Agent" allows "Attribute mapping" and includes "Account metadata".

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

Zimbra admin tool (zmprov)

Zarafa command line tool (this uses to be zarafa-admin)

Zimbra mailbox tool (zmmailxbox)

Existing role in Soffid to be mapped with the Zarafa administrator role. Every user who has this role granted will be created in Zarafa with the administrator flag on

Create alias profile

Values [ true , false ].

Fullname expression (only for Zimbra Agent)


Delete accounts (only for Customizable Zimbra Agent)

Values [ true , false ]. If "true" it allows deleting account in Zarafa when the account is deleted in Soffid.

Attribute mapping

This connector could manage Users, Groups, and Roles.

Users

Groups

Roles

The "Attribute Mapping" tab is only accessible for the "Customizable Zimbra Agent".

Properties

No properties are defined for this agent.

Attributes

You can map users, groups, and role objects. These are some of the attributes to be mapped in those objects:

System attribute

Description

zimbraAccountStatus

accountDisabled ? "closed": "active"

givenName

firstName

displayName

fullName

sn

lastName

zimbraAccount

accountName

For more information about how you may configure attribute mapping, see the following link: Soffid Attribute Mapping Reference

For instance:

Zafara Connector - example.png

Triggers


Load triggers


Account metadata

Accounts are default objects in Soffid. Agents allow you to create additional custom data, on the "Account metadata" tab, to customize the accounts created only for that agent.

The attributes which you define here will be shown when you click on the proper account, on the Accounts Tabs on the users' page.

At this tab, you could add or delete custom attributes. You can visit the Metadata page for more information about the standard attributes.

Operational

Monitoring

After the agent configuration you could check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will something like "Import authoritative data from <AGENT_NAME>".

Reconcile

If you are configured the "Attribute Mapping" tab with some of our objects: "user, account, role, group or grant", an automatic task to synchronize these objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration


SQL Server

SQL Server

SQL Server Connector

Introduction

Description

The SQL Server connector allows an easy way to configure and manage Microsoft SQL Server relational databases.

Managed System

This connector is specific for integration with the Microsoft SQL Server.

 

For more information to check if your system may be synchronized with this connector, do not hesitate to contact us through our Contact form

We can also manage more relational databases, for more information you can check the List of relational databases.

Prerequisites

It is needed a user with access and permissions to the schemes and tables required in the scope of the integration.

Download and Install

This addon is located in the Connectors section and its name is SQLServer.

 

For more information about the installation process, you can visit the Addons Getting started page.

Agent Configuration

This connector could manage User and Role objects.

Basic

Generic parameters

After the installation of the addon, you may create and configure agent instances.

To configure this SQL  Server connector you must select "SQLServer agent" in the attribute "Type" of the generic parameters section in the agent's page configuration.

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

image-1704443217219.png

Custom parameters

Below there are the specific parameters for this agent implementation:

Parameter

Description

User 

Database user name to authenticate

Password

The password of the database user

Connection string to database

URL that identifies the connection properties. Please refer to the specific database vendor documentation to build this URL.


jdbc:sqlserver://<HOST>;databaseName=<DATA_BASE>

Create agents for each database

Select the Yes value if you want to create an agent for each database found by the Reconcile process.
Enable debug

Two options: Yes, and No.

It enables or not more log traces in the Synchronization Server log

image-1704443534381.png

Load triggers

You can define JavaScript or BeanShell scripts that will be triggered when data is loaded into Soffid (incoming triggers). The trigger result will be a boolean value, true to continue or false to stop.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects. 

To view some examples, visit the Incoming triggers examples page.

Access Control

SQL Server connector can establish an access control for SQL Server Users.

If the access control checkbox is enabled, only the users and applications that are listed on the access control page will be allowed to log in. So, you can restrict the IP address,  the user roles, and the applications a user can connect from.

This restriction does not apply to DBA users.

image-1706004218812.png

Check that the user/account is not unmanaged.

When the Enable access control to the database check box is checked, the UpdateAccessControl task will be launched. The following tables will be created on the SQL Server:

When you try to connect to SQL Server, the logon_audit_trigger is launched to check if you have access or not.

You can check the Access Logs page for access controls.

Account metadata

Agents allow you to create additional data, on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings.
The additional data can be used in both mappings and triggers.

The attributes that you define here will be shown when you click on the proper account, on the Accounts Tabs on the user page.

Operational

Monitoring

After the agent configuration you can check on the monitoring page if the service is running in the Synchronization Server, please go to:

Tasks

Authoritative

If you checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available, please go to:

And you will do something like "Import authoritative data from <AGENT_NAME>".

Reconcile

To manage an automatic task to synchronize user objects from the managed system to Soffid is available, please go to:

And you will do something like "Reconcile all accounts from <AGENT_NAME>".

Synchronization

Regarding the synchronization of the objects, there are two possible options:

For more information about how you may configure the generic parameters of the agent, see the following link: Agents configuration

 

Connectors Examples

Connectors Examples

Attribute mappings examples

Attributes

When you are configuring an agent, depending on the connector type, it will be able to define some attributes. The attributes depend on the object that you are configuring, and the objects depend on the connector type.

Get the value of an attribute (a user attribute in that case)

sAMAccountName <= userName
sAMAccountName => userName
sAMAccountName <=> userName

Get the value of a custom attribute

company <= attributes{"company"}
company => attributes{"company"}
company <=> attributes{"company"}

Get the value of an account metadata attribute

office <= accountAttributes{"office"}
office => accountAttributes{"office"}
office <=> accountAttributes{"office"}

Define a constant on the target system

nameConst <= "valueConst"

Assign the result of a script to the soffid attribute

return <SCRIPT> => attribute

Be in mind, it is allowed to use bean Shell expression only in the source when the mapping is one-way.

Assign the result of a script to the target attribute

attribute <= return <SCRIPT>

Be in mind, it is allowed to use bean Shell expression only in the source when the mapping is one-way.


Be in mind

If the attribute name in the final system is hyphenated, you have to use this expression: THIS{"ATTRIBUTENAME"}, for example THIS{"my-name"}


Connectors Examples

Outgoing triggers examples

Attribute mapping triggers

When you are configuring an agent and defining the attribute mappings of connectors, depending on the connector type, it will be able to define BeanShell scripts that will be triggered when data is loaded into the target system, outgoing triggers.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into target objects. 

The trigger result will be a boolean value, true to continue or false to stop.

Use case examples

Example 1

Update or insert a user only when the user is internal (PreInsert User or PreUpdate User)

name = source{"userName"};
user = serviceLocator.getUserService().findUserByUserName(name);
if (user != null) {
  if (user.userType.equals("I")) {
      return true;
  }
}
return false;

Example 2

Update or insert a user only when the company is Soffid. Be in mind that company attribute is a custom attribute.

name = source{"userName"};
company = source{"attributes"}{"company"};
user = serviceLocator.getUserService().findUserByUserName(name);

if (user != null) {
  if (company != null && company.toUpperCase().equals("SOFFID")) {
  	return true; 
  }
}

return false;

Example 3

Recover a response and process it.

if (response != null) {
  for (o : response.getObjects()) {
  	if (o != null && o{"result"} != null) {
	  //TO-DO     
    }
  }
}
return true;

Example 4

Send a HTML mail with the response info.

.....
to = newObject{"identity"};
subject = "LinOTP QR";
body = o{"result"};
serviceLocator.getMailService().sendHtmlMailToActors(new String[] {to}, subject, body);
.......

Example 5

Update a user with the response info

.......
body = o{"result"};
ac = newObject{"user"};
data = new com.soffid.iam.api.UserData();
data.setAccountName(ac);
data.setSystemName("LinOTP");
data.setAttribute("token");
data.setBlobDataValue(body.getBytes());
serviceLocator.getAccountService().updateAccountAttribute(data);
......

Example 6

Call an API and process the response.

.......
userN = accontList.get(0).name;
result = dispatcherService.invoke(
	"GET",
  	"https://" + DOMINIO + "crmRestApi/resources/....?onlyData=true&q=Username=" + userN,
  	null);
if (result != null && !result.isEmpty()) {
  //TO-DO
} 
.......

Example 7

Pre Update: assign a value to an attribute depending on the value of a group attribute. The user can belong to many groups.

userName = source{"userName"};
attributes = serviceLocator.getUserService().findUserAttributes(userName);
dateChange = attributes.get("dateChange");

if (dateChange == null || dateChange == void ) {
	return true;
}

userGroupList = serviceLocator.getGroupService().findUsersGroupByUserName(userName);
contFalse = 0;
contNull  = 0;
isFound = false;
for (ug : userGroupList) {
  group = serviceLocator.getGroupService().findGroupByGroupName(ug.group);
  att = group.attributes.get("indicator");
  if (att != void) {
     if (att == null) contNull++;
     else if (att.equals("0")) contFalse++;
     else if (att.equals("1")) {
       isFound  = true; 
       break;
     } 
  }  
}

if (isFound) {
  newObject{"id-indicator"} = "1";
} else {
  if (contFalse > 0) {
    newObject{"id-indicator"} = "0"; 
  } else if (contNull > 0) {
    newObject{"id-indicator"} =  null;
  } 
} 
    
return true;
Connectors Examples

Incoming triggers examples

Load triggers

When you are configuring an agent, depending on the connector type, it will be able to define BeanShell scripts that will be triggered when data is loaded into Soffid, incoming triggers.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects. 

The trigger result will be a boolean value, true to continue or false to stop.

Use case examples

Example 1

A user can have more than one account on a target system. We want to reconcile only those accounts which have the same name on Soffid and on target system.

name = newObject{"accountName"};
uaList = serviceLocator.getAccountService().findUsersAccounts(name,"agentName");

for(userAccount: uaList) {
  if (userAccount.name.equals(name)) {
    return true;
  } else  {
    return false;
  }
}

return false;

Example 2

Update only users who belong to Soffid company.

name = newObject{"accountName"};
user = serviceLocator.getUserService().findUserByUserName(name);

if (user != null) {
  attributes = serviceLocator.getUserService().findUserAttributes(name);
  company = attributes.get("company");
  if (company != null && company.equals("Soffid")) {
  	return true;
}
return false;
  

Example 3

Discard to create some accounts (PreInsert account).

log.info("************** Pre Insert Account");
cuentas = new java.util.HashMap();
cuentas.put("admin",null);
account = newObject{"accountName"};

if (cuentas.containsKey(account)) {
  log.info("TRIGGER ACCOUNT PREINSERT - Discarded to create the account " + account);
  return false;
}

log.info("TRIGGER ACCOUNT PREINSERT - Correct account " + account);
return true;

Example 4

If does not exist a mail domain, it wil be created.

mailDomain = newObject{"mailDomain"};
if (mailDomain != void && mailDomain != null) {
  existMD = serviceLocator.getMailListsService().findMailDomainByName(mailDomain);
  if (existMD == null) {
    newMailDomain = new com.soffid.iam.api.MailDomain();
    newMailDomain.setName(mailDomain);
    newMailDomain.setDescription(mailDomain);
    serviceLocator.getMailListsService().create(newMailDomain);
  }
}
return true;

Example 5

Avoid deleting users (PreDelete user).

return false;

Example 6

If throw the exception, the return will be is false. True in other cases.

if (....) 
  throw new Exception("Exception message....");
return true;

Example 7

The new group on the target system will have the same id that the old group.

newObject{"idGroup"} = oldObject{"idGroup"};
.....

Example 8

Get the attribute company option 1:

company = source{"attributes"}{"company"};

Get the attribute company option 2

userName = source{"userName"};
attributes = serviceLocator.getUserService().findUserAttributes(userName);
company = attributes.get("company");

Example 9

Update the company attribute:

userName = newObject{"userName"};
// Check if the user exists 
user = serviceLocator.getUserService().findUserByUserName(userName);
if (user == null) {
	return false;
} 
log.info("***************** USER Object: " + user);

attributes = serviceLocator.getUserService().findUserAttributes(userName);
if (attributes == null) {
	attributes = new HashMap();
} 

attributes.put("company", "<COMPANY_NAME>");
serviceLocator.getUserService().updateUserAttributes(userName, attributes);

return true;

Example 10

Check user type

userName = newObject{"userName"};
user = serviceLocator.getUserService().findUserByUserName(userName);

if (user.userType.equals("I")){
  .....
  //TODO
} else {
    .....
  //TODO
}
return true;


Connectors Examples

Triggers: Script Tips

Triggers: Script Tips

Here we will show you some tips about how to use scripts.

For more information you can visit the official documentation of Soffid

Write into a sync-server log

System.out.println("what you want......");

Recover data from a Soffid object when synchronizing

* source only can be used in outgoing triggers. That object will be Soffid format.

* newObject and oldObject can be used in outgoing and incoming triggers. Those objects will be target system format in outgoing triggers and will be Soffid format in incoming triggers.

Recover data from Soffid object to synchronize

Recover user name

name = source{"userName"};
Recover a custom attribute

Recover company (company could be a user custom attribute defined on metadata page)

comp = source{"attributes"}{"company"};
Recover the attribute value that will be sent
no = newObject{"userName"};
gn = newObject{"givenName"};
....
Recover the attribute value from the select

That info comes from the target system. In a synchronization process, the first thing that Soffid does, is to query if the account exists on the target system.

no = oldObject{"userName"};
gn = oldObject{"givenName"};
....

Use  existing services

serviceLocator.getUserService().....
serviceLocator.getAccountService().....
serviceLocator.......

Create a new Soffid object

mailDomain = new com.soffid.iam.api.MailDomain();
newUser = new com.soffid.iam.api.User();
newRol = new com.soffid.iam.api.Role();
............

Loop an object list

for(role : roleList){
  //TO-DO
  out.print(" Role: " + role.roleName + "\n");
}

Recover response

if (response!=null) {
  for (o : response.getObjects()) {
    if (o!=null && o{"result"}!=null) {
      //TO-DO
    }
  }
}

Send a text email 

serviceLocator.getMailService().sendTextMail("mail@soffid.com", "Subject", "Mail message");

Send a HTML mail 

serviceLocator.getMailService().sendHtmlMailToActors(<to>, <subject>, <html-body>);