External Authentication Reference

Modern approach (recommended)

Introduction

We recommend using this approach when implementing new AD/LDAP integrations.

Existing AD/LDAP integrations should consider migrating from the legacy approach to the modern approach.

Modern approach involves running the native LDAP client from the authentication module and passing the appropriate parameters to it.

Using a DNS name for AD/LDAP servers and enabling SSL is strongly recommended, you can do this by passing the SSL parameter with the value 1.

Using the encoded bind password instead of a plain-text bind password is strongly recommended. You can use the password tool mode of ISL Conference Proxy from command prompt/terminal to encode your bind password (e.g. topsecret).

Linux example:

./confproxy_server --password-tool encode islstatic1 'topsecret'

Windows example:

confproxy_server.exe --password-tool encode islstatic1 "topsecret"

If the arguments are correct, you should get the encoded password in the chosen format, looking like this:

[^|islstatic1|^]xnrRLHGFSpR51DLLsYwmQAwYuSkqxSJF

We strongly suggest testing from command prompt/terminal first, checking the output and making sure it works as expected before applying the external authenticator setting to your ISL Conference Proxy. You can refer to the following two manual topics for sample steps:

• Active Directory Authentication
• OpenLDAP Authentication

Sample external authenticator setting for linux:

authenticator/ldap;-;HOST;example.com;SSL;1;SSLCACERTFILE;objects/example-com-ca.pem;BINDDN;cn=icp,ou=Users,dc=example,dc=com;BINDPASSWORD;[^|islstatic1|^]xnrRLHGFSpR51DLLsYwmQAwYuSkqxSJF;SEARCHBASE;ou=Users,dc=example,dc=com;SEARCHFILTER;uid=@USERNAME@;REMAP;\\default\@uid@;

Sample external authenticator setting for Windows:

authenticator\ldap.exe;-;HOST;example.com;SSL;1;BINDDN;cn=icp,cn=Users,dc=example,dc=com;BINDPASSWORD;[^|islstatic1|^]xnrRLHGFSpR51DLLsYwmQAwYuSkqxSJF;SEARCHBASE;cn=Users,dc=example,dc=com;SEARCHFILTER;sAMAccountName=@USERNAME@;REMAP;\\default\@samaccountname@;

Detailed reference

Microsoft Active Directory example

Parameters and sample values:

• ISL Conference Proxy domain: default
• AD servers: ad1.example.com, ad2.example.com
• AD domain: example.com
• AD authenticator account: auth
• AD group: ISL
• map AD account attributes: name, mail
• AD group attributes in list: cn

Windows: standard approach using negotiate authentication method:

authenticator\ldap.exe;-;HOST;ad1.example.com,ad2.example.com;BINDAUTHTYPE;negotiate;BINDUSERNAME;auth@example.com;BINDPASSWORD;Aab1234;SEARCHBASE;CN=Users,DC=example,DC=com;SEARCHFILTER;sAMAccountName=@USERNAME@;GROUPSCOPE;base;GROUPBASE;CN=ISL,CN=Users,DC=example,DC=com;GROUPFILTER;member=@USERDN@;AUTHTYPE;negotiate;AUTHUSERNAME;@samaccountname@@example.com;REMAP;\\default\@samaccountname@;SETTINGS;realname=name#email=mail;GROUPLIST_allgroups_SCOPE;onelevel;GROUPLIST_allgroups_BASE;CN=Users,DC=example,DC=com;GROUPLIST_allgroups_FILTER;member=@USERDN@;GROUPLIST_allgroups_ATTRS;cn;

Windows: alternative approach using simple authentication method with STARTTLS:

authenticator\ldap.exe;-;HOST;ad1.example.com,ad2.example.com;STARTTLS;1;BINDDN;CN=auth,CN=Users,DC=example,DC=com;BINDPASSWORD;Aab1234;SEARCHBASE;CN=Users,DC=example,DC=com;SEARCHFILTER;sAMAccountName=@USERNAME@;GROUPSCOPE;base;GROUPBASE;CN=ISL,CN=Users,DC=example,DC=com;GROUPFILTER;member=@USERDN@;REMAP;\\default\@samaccountname@;SETTINGS;realname=name#email=mail;GROUPLIST_allgroups_SCOPE;onelevel;GROUPLIST_allgroups_BASE;CN=Users,DC=example,DC=com;GROUPLIST_allgroups_FILTER;member=@USERDN@;GROUPLIST_allgroups_ATTRS;cn;

Linux: standard approach using simple authentication method with STARTTLS:

authenticator/ldap;-;HOST;ad1.example.com,ad2.example.com;STARTTLS;1;SSLCACERTFILE;ca.pem;BINDDN;CN=auth,CN=Users,DC=example,DC=com;BINDPASSWORD;Aab1234;SEARCHBASE;CN=Users,DC=example,DC=com;SEARCHFILTER;sAMAccountName=@USERNAME@;GROUPSCOPE;base;GROUPBASE;CN=ISL,CN=Users,DC=example,DC=com;GROUPFILTER;member=@USERDN@;REMAP;\\default\@samaccountname@;SETTINGS;realname=name#email=mail;GROUPLIST_allgroups_SCOPE;onelevel;GROUPLIST_allgroups_BASE;CN=Users,DC=example,DC=com;GROUPLIST_allgroups_FILTER;member=@USERDN@;GROUPLIST_allgroups_ATTRS;cn;

To check group membership recursively instead of just immediate group, replace:

GROUPSCOPE;base;GROUPBASE;CN=ISL,CN=Users,DC=example,DC=com;GROUPFILTER;member=@USERDN@;

with:

GROUPSCOPE;onelevel;GROUPBASE;CN=Users,DC=example,DC=com;GROUPFILTER;(&(distinguishedName=CN=ISL,CN=Users,DC=example,DC=com)(member:1.2.840.113556.1.4.1941:=@MS$USERDN@))

In case the groups are nested, use:

GROUPSCOPE;subtree;

To return all recursive groups instead of just immediate groups, replace:

GROUPLIST_allgroups_FILTER;member=@USERDN@;

with:

GROUPLIST_allgroups_FILTER;member:1.2.840.113556.1.4.1941:=@MS$USERDN@;

In case the groups are nested, use:

GROUPLIST_allgroups_SCOPE;subtree;

General settings

• -; (pass process arguments on stdin)
• HOST;10.0.20.1,10.0.20.2; (LDAP servers)
• PORT;636; (LDAPS TCP port)
• SSL;1; (enable SSL)
• STARTTLS;1; (enable SSL)
• SSLCACERTFILE;ca.pem; (linux: path to CA certificate file)
• TIMEOUT;30; (LDAP operation timeout in seconds)
• STDERRFILE;ldap.log; (log file)
• ALLERRORS;1; (treat non-critical errors like wrong password as fatal, backward compatibility)
• DEBUG;1; (linux: print extra debugging information)
• DEBUGSECURE;1; (print secure data like passwords as plaintext)
• DISABLEIEAUTODETECT;1; (windows: disable Internet explorer connection auto-detection in registry)
• DISABLEREFERRALS;1; (stop LDAP from chasing referrals - you can try this setting in case you encounter speed issues, random failures, timeouts and similar inconsistent behaviour)

Search method settings

• BINDAUTHTYPE;negotiate; (windows: authentication method for authenticator account)
• BINDDN;CN=auth,CN=Users,DC=example,DC=com; (dn for authenticator account, simple authentication)
• BINDUSERNAME;auth@example.com; (windows: username for authenticator account, non-simple authentication)
• BINDDOMAIN;example.com; (windows: domain for authenticator account, non-simple authentication)
• BINDPASSWORD;Aab1234; (password for authenticator account)
• SEARCHSCOPE;subtree; (LDAP search scope for user)
• SEARCHBASE;CN=Users,DC=example,DC=com; (LDAP search base for user)
• SEARCHFILTER;sAMAccountName=@USERNAME@; (LDAP search filter for user)
• USERATTRS;1; (always retrieve all attributes for user)
• GROUPSCOPE;base; (LDAP search scope for group)
• GROUPBASE;CN=ISL,CN=Users,DC=example,DC=com; (LDAP search base for group)
• GROUPFILTER;member=@USERDN@; (LDAP search filter for group)
• GROUPATTRS;1; (retrieve all attributes for group)
• GROUPLIST_tag_SCOPE;onelevel; (LDAP search scope for group list "tag")
• GROUPLIST_tag_BASE;CN=Users,DC=example,DC=com; (LDAP search base for group list "tag")
• GROUPLIST_tag_FILTER;member=@USERDN@; (LDAP search filter for group list "tag")
• GROUPLIST_tag_ATTRS;cn,objectguid; (list of attributes to retrieve for group list "tag", use * for everything when debugging)
• AUTHTYPE;negotiate; (windows: authentication method for user account)
• AUTHUSERNAME;@samaccountname@@example.com; (windows: username mapping for user account, non-simple authentication)
• AUTHDOMAIN;example.com; (windows: domain mapping for user account, non-simple authentication)
• SSO_LDAP_SCOPE;base; (LDAP search scope for password-less authentication)
• SSO_LDAP_BASE;CN=User,CN=Users,DC=example,DC=com; (LDAP search base for password-less authentication)
• SSO_LDAP_FILTER;objectCategory=*; (LDAP search filter for password-less authentication)

Map method settings (not recommended)

• MAPUSER;@USERNAME@@example.com; (dn or username mapping for user account)
• MAPAUTHTYPE;negotiate; (authentication method for user account)
• MAPAUTHDOMAIN;example.com; (windows: domain mapping for user account, non-simple authentication)

LDAP search scopes

• base
• onelevel
• subtree

Authentication methods

• Windows: digest, dpa, msn, negotiate, ntlm, sicily, sspi, simple
• Linux: simple

Troubleshooting SSL certificate verification

• Windows: Open Event Viewer > Windows Logs > System, look for errors by Schannel
• Linux: Use "DEBUG 1" to get SSL handshake log in console

Perl / .NET approach (legacy)

Available ways of using external authentication depend on the operating system used on the server that is running ISL Conference Proxy. Please refer to the appropriate section below.

Important: Please replace 1.2.3.4 and 1.2.3.5 with the appropriate authenticator server address(es) for your situation.

Important: Please note that all external authentication strings must end with a semicolon.

Linux

Please choose the appropriate section based on the external authenticator you are using:

• FreeRADIUS (requires FreeRADIUS)

/usr/bin/perl;authenticator/FreeRADIUS.pl;HOST;1.2.3.4,1.2.3.5;SECRET;abc;

• Radius (requires CPAN module RadiusPerl - use libauthen-radius-perl on debian)

/usr/bin/perl;authenticator/RadiusPerl.pl;HOST;1.2.3.4,1.2.3.5;SECRET;abc;

• LDAP (requires CPAN modules perl-ldap and IO-Socket-SSL - use libnet-ldap-perl and libio-socket-ssl-perl on debian)

1. direct bind approach (for Microsoft Active Directory) - replace MAPUSER to match your environment:

/usr/bin/perl;authenticator/perl-ldap.pl;HOST;ldap://1.2.3.4,ldap://1.2.3.5;MAPUSER;@USERNAME@@example.com;

2. search approach (for Novell eDirectory and OpenLDAP) - replace SEARCHBASE and SEARCHFILTER to match your environment:

/usr/bin/perl;authenticator/perl-ldap.pl;HOST;ldap://1.2.3.4,ldap://1.2.3.5;SEARCHBASE;ou=People,dc=Company;SEARCHFILTER;uid=@USERNAME@;

Note: If you use SSL, please replace ldap:// with ldaps://

Note: If you require a special username and password to connect (i.e. anonymous bind not allowed or it does not have enough privileges), then specify this username and password using BINDDN and BINDPASSWORD (please note that you need to properly escape certain special characters if you have them in the password, e.g. % to %25, ; to %3B etc.).

Note: If you wish to add a group membership check, you can do it like this:

(&(uid=@USERNAME@)(groupMembership=cn=somegroup,ou=Groups,dc=Company))

If you are using AD and wish to use subgroups (e.g. you have a top group Top_ISL_Group and its members are groups like local1_ISL_Group, local2_ISL_Group etc., but you assign users to subgroups, not to the top group directly), then you would do it like this in order to instruct AD to walk the group chain:

(&(sAMAccountName=@USERNAME@)(memberOf:1.2.840.113556.1.4.1941:=cn=Top_ISL_Group,ou=Groups,dc=Company))

Note: If you are using AD, please note that users on ISL Conference Proxy are case-sensitive while your AD most likely is not. This means that if you login with e.g. User1, user1 or USeR1, three users will be created on ISL Conference Proxy even though they match the same user on AD. In order to avoid this and always create just the user using the exact same casing from your AD, please use the REMAP parameter (important: the string between two @ should be lowercased!), e.g. REMAP;\\default\@samaccountname@;

Windows

You can use either perl or .NET for external authentication.

Important: If using perl, the following examples assume that it is installed in c:\perl.

Please choose the appropriate section based on the external authenticator you are using:

• Radius (requires CPAN module RadiusPerl)

c:\perl\bin\perl.exe;authenticator\RadiusPerl.pl;HOST;1.2.3.4,1.2.3.5;SECRET;abc;

• LDAP

3. direct bind approach (for Microsoft Active Directory) - replace MAPUSER to match your environment:

perl (requires CPAN modules perl-ldap and IO-Socket-SSL):

c:\perl\bin\perl.exe;authenticator\perl-ldap.pl;HOST;ldap://1.2.3.4,ldap://1.2.3.5;MAPUSER;@USERNAME@@example.com;

.NET (requires .NET Framework 2.0 or newer):

authenticator\WinLdap.exe;HOST;1.2.3.4,1.2.3.5;MAPUSER;@USERNAME@@example.com;

4. search approach (for Novell eDirectory and OpenLDAP) - replace SEARCHBASE and SEARCHFILTER to match your environment:

perl (requires CPAN modules perl-ldap and IO-Socket-SSL):

c:\perl\bin\perl.exe;authenticator\perl-ldap.pl;HOST;ldap://1.2.3.4,ldap://1.2.3.5;SEARCHBASE;ou=People,dc=Company;SEARCHFILTER;uid=@USERNAME@;

.NET (requires .NET Framework 2.0 or newer):

authenticator\WinLdap.exe;HOST;1.2.3.4,1.2.3.5;SEARCHBASE;ou=People,dc=Company;SEARCHFILTER;uid=@USERNAME@;

Note: If you use SSL, please replace ldap:// with ldaps://

Note: If you require a special username and password to connect (i.e. anonymous bind not allowed or it does not have enough privileges), then specify this username and password using BINDDN and BINDPASSWORD (please note that you need to properly escape certain special characters if you have them in the password, e.g. % to %25, ; to %3B etc.).

Note: If you wish to add a group membership check, you can do it like this:

(&(uid=@USERNAME@)(groupMembership=cn=somegroup,ou=Groups,dc=Company))

If you are using AD and wish to use subgroups (e.g. you have a top group Top_ISL_Group and its members are groups like local1_ISL_Group, local2_ISL_Group etc., but you assign users to subgroups, not to the top group directly), then you would do it like this in order to instruct AD to walk the group chain:

(&(sAMAccountName=@USERNAME@)(memberOf:1.2.840.113556.1.4.1941:=cn=Top_ISL_Group,ou=Groups,dc=Company))

Note: If you are using AD, please note that users on ISL Conference Proxy are case-sensitive while your AD most likely is not. This means that if you login with e.g. User1, user1 or USeR1, three users will be created on ISL Conference Proxy even though they match the same user on AD. In order to avoid this and always create just the user using the exact same casing from your AD, please use the REMAP parameter (important: the string between two @ should be lowercased!), e.g. REMAP;\\default\@samaccountname@;

Having chosen the desired external authentication method, you should first test it from the command line - please check the samples below and modify accordingly.

Linux

In the ISL Conference Proxy's authenticator subdirectory, use the perl-ldap.pl like this (use ' for escaping):

perl perl-ldap.pl HOST ldap://1.2.3.4 SEARCHBASE 'ou=People,dc=Company,dc=local' SEARCHFILTER 'uid=@USERNAME@' USERNAME 'testuser' PASSWORD ***

With the appropriate username and password combination you will get the OK reply, otherwise you  will get an error message informing you that the supplied credential is invalid.

Windows

In the ISL Conference Proxy's authenticator subdirectory, use the WinLdap.exe like this (please note that on Windows you need to use " for escaping instead of ' and if the username contains a space, put " around it):

WinLdap.exe HOST 1.2.3.4 SEARCHBASE "ou=People,dc=Company,dc=local" SEARCHFILTER "uid=@USERNAME@" USERNAME "testuser" PASSWORD ***

With the appropriate username and password combination you will get the OK reply, otherwise you  will get an error message informing you that the supplied credential is invalid.

Now that you know that those settings work fine, please follow these steps to set the external authenticator in ISL Conference Proxy:

1. Login to your ISL Conference Proxy administration (http://localhost:7615/conf).
2. Go to User management, click on the Domains tab.
3. Select the desired domain that will use external authentication (e.g. ldapusers).
4. Click on the Security tab.
5. Uncheck the External authenticator option and paste the appropriate modified line from the top part of this topic (with ; as the delimiter - e.g. .NET LDAP direct bind approach example with modified HOST address(es) and MAPUSER).
6. Click Save.

This concludes the external authentication configuration. Time to test it - you can go to http://localhost:7615/ and click Product Login in the top right corner. Use the appropriate domain prefix (in the example above it would be \\ldapusers\testuser), add the LDAP username and password and you should be able to login.

Note: If you have a private cloud with a mix of platforms (windows and linux servers) or would simply like to create a combined external authentication string which covers both platforms, please use the following syntax:

{platform=windows} c:\perl\bin\perl.exe;...;

{platform=linux} /usr/bin/perl;...;

You can check our one time password example for a simple test illustration of external authentication.

You are also welcome to check our blog post for more information and an example.