How to work with VISULOX Datasources

Overview

VISULOX handles users, groups and applications. These are the so called datasources and they are imported by the VISULOX Importer Service.

Applications and VISULOX PORTAL user profiles are defined in the VISULOX PORTAL Datastore and are imported by default.

Usage datasource

The VISULOX PORTAL authentication system can use different user repositories (UR). The URs are configured under services and with the tarantella service command.

To allow VISULOX policies on users and groups from different URs, these URs can be configured.

CODE

visulox datasource add | list | edit | delete | copy | check | clean | query | stat <parameters>

Nested groups

VISULOX does not support nested groups! (Using nesting, a group can be added as a member of another group).

Parameter list

Paramater	Value / example	Comment
-name	myDomain myDomain:1 myDomain:2	The name of the datasource. Without a fallback postion it is the primary datasource. :1 will be the first fallback entry.
-location	<any string>	String to identify the datastource in the GUI. Recommendation is to use a short string.
-pwdprotocol	<oud>, <ipa>, <ad>, <none>	Password protocol has to be set for password change. If visulox datasource edit -name <> -pwdprotocol is set to none and the password has to be changed, the user cannot log in and a message is displayed in the login mask, that he has to change his password.
-base		Searchbase in the LDAP tree.
-host	host/IP of the datasource
-port	389 is the default LDAP port	363 is the secure LDAP port
-secure	true/false/verify	Defines unsecure (LDAP) or secure connection (LDAPS). For LDAPS also have a look at: Troubleshooting: LDAPS
-type	LDAP	Currently only LDAP connections are supported. LDAPS is controlled via -port and -secure.
-cafile	<path to cafile>
-username	<username>	User is allowed to read the LDAP server. The username depends on the configuration entries on the AD servers. The following fields can be used for the connection, if set: distinguishedName cn userPrincipalName If a field is not set in AD, it can not be used for the connection.
-password	<passcode>	Password of the user who can access the LDAP server. STDIN input via CLI is possible as well.
-mapping		Mapping schema in VISULOX to map the attributes to the internal values. Two mappings are available MSAD, LDAP. See: How to configure alternate mappings for datasources
-paging	true \| false	The AD default search result is limited to 1000 objects. It can be extended, but it is a change on the AD and so this is not the best solution. This setting allows to disable the paging feature, even if the LDAP Server provides this feature.
-searchadmin	LDAP search string to get users, which are related to be admins.	The searchstring can include a place holder "%SEARCH_STRING%" to use the -filter option of the ldap.tcl test command. Internally this placeholder is not used in VISULOX. Currently there is no usecase for that!
-searchgroup	LDAP search string to get the groups	The searchstring can include a place holder "%SEARCH_STRING%" to use the -filter option of the ldap.tcl test command. Internally this placeholder is not used in VISULOX. If (distinguishedName=%SEARCH_STRING%) is in the "searchgroup", it is possible to use ldap.tcl with -filter <dn of group) to get additional data from the LDAP server in a script. Currently there is no usecase for that!
-searchuser	LDAP search string to get users, which can log into VISULOX PORTAL.	The searchstring can include a place holder "%SEARCH_STRING%" to use the -filter option of the ldap.tcl test command. Internally this placeholder is not used in VISULOX. If (distinguishedName=%SEARCH_STRING%) is in "searchuser", it is possible to use ldap.tcl with -filter $VLXOWNER to get additional data from the LDAP server in a script.
-groupfilter	<regexp on groups>	The AD provides all the groups assigned to a user and all the groups itself. This parameter allows to reduce the data from the user repository to the relevant information, i.e -groupfilter "CN=VLX" imports only groups beginning wth cn=VLX. The value is a regexp (http://www.tcl.tk/man/tcl8.6/TclCmd/re_syntax.htm). So -groupfilter "CN=VLX\|CN=portal" will import two groups.
-dse	Disable search extensions	Disable built search extensions for searchuser / searchadmin / searchgroup. (e.g. useful for OUD) Auto-adjust will be disabled. Important is that searchuser / searchadmin / searchgroup contain "%SEARCH_STRING%", otherwise ./ldap.tcl -filter does not work.

A search query on an AD is limited to 1000. If this is the case, the MaxPageSize must be configured by the AD Administrator on the AD site (http://support.microsoft.com/kb/315071/en).

Better: Enable/disable the paging feature with the visulox datasource -paging command.

If too many irrelevant users or groups are imported the searchuser or searchgroup query must have an additional criteria.

Import only users within the LOGINGROUP

CODE

-searchuser "(&(objectClass=person)(memberOf=$LOGINGROUP)(|(distinguishedName=%SEARCH_STRING%)(cn=%SEARCH_STRING%)(givenName=%SEARCH_STRING%)(uid=%SEARCH_STRING%)    (mail=%SEARCH_STRING%)(sAMAccountName=%SEARCH_STRING%)))"

Import only users within the LOGINGROUP - No computer objects / only persons

CODE

-searchuser "(&(objectClass=person)(!(objectclass=computer))(memberOf=$LOGINGROUP)(|(distinguishedName=%SEARCH_STRING%)(cn=%SEARCH_STRING%)(givenName=%SEARCH_STRING%)(uid=%SEARCH_STRING%)    (mail=%SEARCH_STRING%)(sAMAccountName=%SEARCH_STRING%)))"

Import only groups with VLX_ or POC-Groups in the name

CODE

-searchgroup "(&(objectClass=group)(|(cn=VLX_*)(cn=POC-GROUPS*))(|(distinguishedName=%SEARCH_STRING%)(cn=%SEARCH_STRING%)(gidNumber=%SEARCH_STRING%)))"

Make sure that distinguished names are always used for the fields in the search string.

Additional placeholders

The default setting for the parameter -type is "ldap". LDAPS is controlled via -port and -secure.

Two placeholders are available %isUser% and %isGroup%:

CODE

::isUser {&(|(objectClass=user)(objectClass=person))(!(objectClass=computer))(!(userAccountControl:1.2.840.113556.1.4.803:=2))}
::isGroup {|(objectClass=group)(objectClass=posixGroup)}

With these placeholders a default LDAP query string is available for searchuser and searchgroup, that should work in most cases and only has to be set, if a subset of users / groups should be read out.

searchadmin is set with:

CODE

'(&(%isUser%)(memberOf=CN=VLX_ADMINS,DC=myDomain,DC=de))'

A bracket check is implemented for the LDAP strings. The number of opened brackets must match the number of closed brackets.

Configuration

List datasources

CODE

visulox datasource list
Datasources
    --------------------------------------------------------------
    |         name |  location |                 host | disabled |
    --------------------------------------------------------------
    |    company:0 |  EMPLOYEE |      srv1.company.de |    false |
    |   myDomain:0 | Stuttgart | ur1.stgt.mydomain.de |    false |
    |   myDomain:1 |   Hamburg |  ur2.hmb.mydomain.de |    false |
    | remoteuser:0 | EXTERNALS |      srv2.company.de |    false |
    --------------------------------------------------------------

Detailed list as CSV list

CODE

visulox datasource list -name  myDomain -info -format csv

name;parameter;value
myDomain,0;location;Stuttgart
myDomain,0;host;ur1.stgt.mydomain.de
myDomain,0;type;ldap
myDomain,0;username;CN=Logon,OU=Admins,DC=myDomain,DC=de
myDomain,0;port;389
myDomain,0;password;<hidden>
myDomain,0;attributes;objectclass dn mail uid cn surname mobile member memberOf c countryCode
myDomain,0;base;OU=Users,DC=myDomain,DC=de
myDomain,0;disabled;false
myDomain,0;groupfilter;cn=
myDomain,0;mapping;MSAD
myDomain,0;searchadmin;(&(objectClass=person)(memberOf=CN=portaladmin,CN=Users,DC=test,DC=de))
myDomain,0;searchgroup;(&(objectclass=posixGroup)(|(cn=%SEARCH_STRING%)(gidNumber=%SEARCH_STRING%)))
myDomain,0;searchuser;(&(objectclass=person)(|(distinguishedName=%SEARCH_STRING%)(cn=%SEARCH_STRING%)(givenName=%SEARCH_STRING%)(uid=%SEARCH_STRING%)(mail=%SEARCH_STRING%)(sAMAccountName=%SEARCH_STRING%)))
myDomain,0;vlx_source;vTABOL6U4SGD1510
myDomain,1;location;Hamburg
myDomain,1;host;ur2.hmb.mydomain.de
myDomain,1;type;ldap
myDomain,1;username;CN=Logon,OU=Admins,DC=myDomain,DC=de
myDomain,1;port;389
myDomain,1;password;<hidden>
myDomain,1;attributes;objectclass dn mail uid cn surname mobile member memberOf c countryCode
myDomain,1;base;OU=Users,DC=myDomain,DC=de
myDomain,1;disabled;false
myDomain,1;groupfilter;cn=
myDomain,1;mapping;MSAD
myDomain,1;searchadmin;(&(objectClass=person)(memberOf=CN=portaladmin,CN=Users,DC=test,DC=de))
myDomain,1;searchgroup;(&(objectclass=group)(|(cn=%SEARCH_STRING%)(gidNumber=%SEARCH_STRING%)))
myDomain,1;searchuser;(&(objectclass=person)(|(distinguishedName=%SEARCH_STRING%)(cn=%SEARCH_STRING%)(givenName=%SEARCH_STRING%)(uid=%SEARCH_STRING%)(mail=%SEARCH_STRING%)(sAMAccountName=%SEARCH_STRING%)))

The command dumps the current configured datasources with all their values.

Edit a datasource

CODE

visulox datasource edit -name myDomain               \
  -location   Stuttgart                              \
  -type       ldap                                   \
  -host       ur1.stgt.mydomain.de                   \
  -port       389                                    \
.....

VISULOX supports the configuration of fallback or backup datasources. This can be done by adding additional datasources with the same name followed by the fallback position (<name>:<position>) and different physical parameters.

Example of a fallback datasource

CODE

visulox datasource list -name MyDomain

Datasources
    -----------------------------------------------------------------
    |       name | parameter |                                value |
    -----------------------------------------------------------------
    | myDomain,0 |  location |                            Stuttgart |
    | myDomain,0 |      host |                 ur1.stgt.mydomain.de |
    | myDomain,0 |      type |                                 ldap |
    | myDomain,0 |  username | CN=Logon,OU=Admins,DC=myDomain,DC=de |
    | myDomain,0 |      port |                                  389 |
    | myDomain,0 |    secure |                                false |
    | myDomain,0 |  password |                             <hidden> |
    | myDomain,1 |  location |                              Hamburg |
    | myDomain,1 |      host |                  ur2.hmb.mydomain.de |
    | myDomain,1 |      type |                                 ldap |
    | myDomain,1 |  username | CN=Logon,OU=Admins,DC=myDomain,DC=de |
    | myDomain,1 |      port |                                  389 |
    | myDomain,1 |  password |                             <hidden> |
    -----------------------------------------------------------------

Temporarily disabling a datasource

CODE

visulox datasource edit -name  myDomain:1 -disabled true

Dataobjects import statistic

CODE

visulox datasource stat
Dataobjects import statistics
    ------------------------------------------------------------
    | datasource |            class | duration | objects | rtn |
    ------------------------------------------------------------
    |  DATASTORE |      application |    1.211 |       5 |  OK |
    |  DATASTORE | applicationgroup |    0.622 |       1 |  OK |
    |  DATASTORE |             host |    0.553 |       0 |  OK |
    |  DATASTORE |             user |    1.803 |       1 |  OK |
    |      TOTAL |                  |    4.189 |       7 |     |
    ------------------------------------------------------------

Datasource template

A datasource template can be found in /opt/visulox/setup/examples

Usage importer

The service/importer.tcl imports the datasources on each VISULOX Access Node. The command is run as a service, but can be called manually as well to see how the import works:

./lib/service/importer.tcl

CODE

/opt/visulox/lib/service/importer.tcl 
Dataobjects import statistic
    -------------------------------------------------
    | datasource |       class | duration | objects |
    -------------------------------------------------
    |  DATASTORE | application |    0.386 |      23 |
    |  DATASTORE |        user |    0.314 |       1 |
    |        POC |       group |    0.222 |       5 |
    |        POC |        user |    0.218 |       1 |
    |     TESTAD |       group |    0.318 |       2 |
    |     TESTAD |        user |    0.398 |     114 |
    | TESTMASTER |       group |    0.281 |       7 |
    | TESTMASTER |        user |    1.457 |    1269 |
    |      TOTAL |             |    3.594 |    1422 |
    -------------------------------------------------

If the cluster key has been changed (attaching new nodes) all datasources have to be re-registered.

On all Filter Object pages a "Reload Objects" button is displayed. With this button the reload of LDAP import can be triggered by the user.

LDAP pagesize

If necessary, the LDAP pagesize can be adjusted. The default value is 250.

CODE

visulox config -name importer.ldap.pagesize   
	--------------------------------------------
    | changed | key                    | value |
    --------------------------------------------
    |         | importer.ldap.pagesize | 250   |
    --------------------------------------------

Known issues and comments

Import of nested groups is not supported.

Connecting to AD via LDAP or LDAPS is supported.

Related information

General command line configuration

How to configure alternate mappings for datasources

Creating VISULOX user groups based on an AD/LDAP attribute

How to use Unix user profiles

How to test and check an LDAP datasource in VISULOX

Troubleshooting: LDAPS