LISTSERVLDAPDocumentation

L‐SoftSwedenAB200728November2007OverviewLISTSERVversion15.
5caninterfacetoLDAPserverstoauthenticateuserlogins,toinsertLDAPattributesinmail‐mergedistributionsaswellastoimplementDynamicQueries,anewfeaturedescribedinaseparatedocument.
ThefollowingdiagramshowstheLISTSERV15.
5LDAParchitecture,inrelationtoothercomponents:Forclarity,DynamicQueryfunctionshavebeenomittedfromthediagram,buttheyalsointerfacewiththenewLDAPfunctionality.
TheLDAPinterfaceisatthesamelevelastheDBMSinterface–notatthelevelofthevendor‐specificSQLdrivers.
Quitesimply,LDAPserversdonot"speak"SQL.
TosupportLDAP,wehadtoteachthemail‐mergeandauthenticationmodulesto"speak"LDAP.
ThisiswhythereisanewsyntaxforeveryLDAP‐relatedfunction.
Atthispoint,LISTSERVonlyqueriesLDAPdirectories.
Itwillnevertrytomakeanychanges,soitshouldnotbegivenwriteaccesstothedirectory.
LDAPDBMS(SQL)FlatFileListStorageLayerMail‐Merge(DISTRIBUTE)ListManagementAuthenticationInternalPasswords.
.
.
ODBCOCICLI1ConfiguringLDAPinLISTSERVThefirststepinusingLDAPwithLISTSERVistoaddoneormoreLDAPserversintheLISTSERVsiteconfiguration.
ThiscanbedoneviatheLISTSERVwebadministrationinterface(thepreferredmethod),oralternatelybyaddingtheentriesmanuallytoSITE.
CFGor'go'.
EachLDAPserverisgivenanicknameintheLISTSERVconfiguration,similarlytoDBMSdatasources.
YoucanalsoconfigureoneunnamedLDAPserver,againlikewithDBMSdatasources,butitisprobablylessconfusingtoassignanicknametoeveryLDAPserver.
ThreeconfigurationvariablesmustbedefinedforeveryLDAPserver:LDAP_SERVER_nickname=hostname[:port]ThehostnameandoptionalportoftheLDAPserver.
TheexactformatdependsonyouroperatingsystemandLDAPlibrary;LISTSERVpassesthisstringtotheLDAPlibraryasitis.
Onunix,SSLencryptionisrequestedbyprepending'ldaps://'tothehostname.
OnWindows,the'ldaps://'prefixisnotavailable,butsettingtheportto636automaticallyrequestsSSL.
LDAP_UID_nickname=useridLDAP_AUTH_nickname=passwordTheuseridandpasswordthatLISTSERVshoulduseinordertologintotheLDAPserver.
TheexactformatoftheuseriddependsonyourLDAPserver.
LISTSERVdoesnotattempttoparseorreformatthesevariables.
Ifthepasswordistheemptystring,mostLDAPserverswillperformananonymouslogin.
Ifbothuseridandpasswordaretheemptystring,LISTSERVwillattemptadefaultlogin,asdefinedbytheLDAPlibraryforyouroperatingsystem.
UnderWindows,LISTSERVwillbeloggedinwithitscurrentdomaincredentials(assumingitisconnectingtoanActiveDirectoryserver),andthisusuallyprovidessufficientaccess–tryitbeforeconfiguringauseridandpassword.
IftheLDAPserveristobeusedtoauthenticateLISTSERVusers,thefollowingvariablesmustalsobedefined:LDAP_PW_BASE_nickname=DNThe'distinguishedname'thatshouldbethe'base'forsearcheswhenLISTSERVlooksforauseraccount(seebelowforanexplanationoftheauthenticationprocess).
ThiscanbeusedtorestrictLISTSERVaccesstoaparticularorganizationalunitwithintheenterprise.
Ifomitted,LISTSERVtriestoguesstheDNthatwilladmitanyActiveDirectoryWindowsaccount,butthisisadifficultguesstomake,andofcourseyoumaynotevenbeconnectingtoActiveDirectory.
LDAP_PW_FILTER_nickname=filterTheLDAP'filter'thatshouldbeusedwhenlookingupuseraccounts(ifthisfilterreturnsatleastoneentry,LISTSERVallowstheusertotryandlogin;otherwise,theloginisrejected,eveniftheuserwouldotherwisebeabletologintotheLDAPserverwiththesuppliedcredentials).
Anyoccurrencesof'%s'arereplacedwiththeuser'sfulle‐mailaddress,while'%u'expandstojusttheuseridand'%h'expandstothehostname.
Ifomitted,LISTSERVusesafilterthatissuitableformostActiveDirectoryinstallations.
2Inaddition,thefollowingoptionalvariablescanbedefined:LDAP_DEFAULT_EMAIL_nickname=attributeThenameoftheattributethatordinarilyspecifiesauser'se‐mailaddressinthisdirectory.
Thisisusedasadefaultvalueinsearchesandcanbeoverridden.
Ifomitted,itdefaultsto'mail'(suitableforActiveDirectory).
LDAP_DEFAULT_NAME_nickname=attributeThenameoftheattributethatordinarilycontainstheuser'sfullname.
Defaultsto'name'.
UsingLDAPformailmergeBecauseofitscomplex,machine‐friendlysyntax,LDAPisprimarilysuitedforscripting.
Whileitisrelativelyeasyforaprogrammertowriteascriptthatsendsaweeklynoticetoeverymemberofaparticulardepartment,itisnotrealistictoexpectordinarylistownersorend‐userstounderstandtheintricaciesofLDAPanddeviseworkingsearchfilters.
Forinstance,toselectallusersinanExchangedatabase,onewouldhavetousethefollowingfilter:(&(!
(Alias=$null))(|(&(ObjectCategory=person)(ObjectClass=user)(Database=$null)(ServerLegacyDN=$null))(&(ObjectCategory=person)(ObjectClass=user)(!
(Database=$null))(!
(ServerLegacyDN=$null)))))))L‐SoftexpectsthatLDAP‐baseddistributionswillbecreatedbycustomer‐developedscripts–eitherintranetwebscriptsortraditional'cron'jobsorscheduledtasks.
Atthispoint,therearenoplanstoprovideawebinterfacepageintowhichrawLDAPsearchfilterscouldbeentered.
TocreateanLDAP‐baseddistribution,ascriptusestheDISTRIBUTEcommandandspecifiesanLDAPkeywordasfollows:DISTRIBUTE…LDAP=YES(SERVER=nickname,E‐MAIL=attribute,PARTS=attribute)ThesyntaxofthiskeywordisessentiallythesameasforSQL‐baseddistributions("DBMS="):SERVER=nicknameidentifiestheLDAPservertobequeried.
Ifomitted,thedefault(unnamed)LDAPserverisused.
E‐MAIL=attributeidentifiesthenameofthedirectoryattributecontainingtherecipient'se‐mailaddress.
Ifomitted,thevalueofLDAP_DEFAULT_EMAIL_nicknameisused.
PARTS=attributeisthenameofanoptionaldirectoryattributecontainingalistofmessagepartsthattherecipientsubscribesto.
Althoughthismail‐mergefeatureisunlikelytobeusedwithLDAP,itisavailableifdesired.
SimilarlytoSQL‐baseddistributions,the'TO'DDcontainsalistofLDAPsearchstatements,ratherthanalistofactualrecipients.
Eachlineinthe'TO'DDcanbeoneofthefollowingstatements:BASEDNThe'distinguishedname'ofthe'base'oftheLDAPsearch.
Mandatory.
3FILTERsearch_filterTheLDAPsearchfilterforthesearch.
Mandatory.
ATTRSattr1[attr2[…]]Alistofdirectoryattributesofinterest(usedinthemail‐merge).
Ifomitted,alldirectoryattributesaremadeavailable.
Attributenamesarenotcase‐sensitive.
Themainpurposeofthisstatementistoimprovesearchperformanceiftherearemanyirrelevantattributesinthedirectory.
NotethattheE‐MAILand(ifenabled)PARTSattributesmustbespecifiedorthedistributionwillfail.
SCOPEBASE|ONELEVEL|SUBTREEOptionallychangesthescopeofthesearchfromthedefault(SUBTREE).
SEARCHStartsthesearch.
ThiscommandallowsmultipleLDAPsearchestobeperformedinthesamedistribution.
Ifthereisonlyonesearch,thiscommandisoptional–LISTSERVautomaticallystartsthesearchwhenitreachestheendofthe'TO'DD.
Forinstance,thissearchwillselectallWindowsusersintheEXAMPLE.
COMdomainwithavalide‐mailaddress:BASECN=Users,DC=EXAMPLE,DC=COMFILTER(&(objectcategory=person)(objectclass=user))ATTRSNameMailPhoneSEARCHUsingLDAPforauthenticationLISTSERVcanbeconfiguredtouseoneorseveralLDAPserversforauthentication(userlogin).
YoucanchoosetoallowuserswithoutanLDAPaccounttologinwithaninternalLISTSERVpassword,ortorestrictaccesstouserswithanLDAPaccount.
LDAPauthenticationisenabledbydefiningthefollowingconfigurationvariables:LDAP_PW_SERVERS=nickname1[nickname2[…]]ThelistofLDAPserverstobequeried(inthespecifiedorder)foruseraccounts.
Besuretoenterservernicknames,nothostnames.
LDAP_PW_ONLY=0or1(default:0)Ifsetto1,onlyuserswithanLDAPaccountareallowedtologintoLISTSERV;otheruserswillonlybeabletoaccessLISTSERVanonymously.
MakesuretotestyourLDAPsettingsbeforeenablingthisoption,oryouwillnotbeabletoundoitfromthewebinterface!
Enablingthisoptiononaserverthatpreviouslyhadexternalusersislikelytoresultinsignificantconfusionfortheexternalusers,whosepasswordswillnolongerwork.
LDAP_PW_REQUIRE_SSL=0or1(default:1)WhetherornotLISTSERVshouldacceptLDAPpasswordstransmittedtothewebinterfaceinplaintext.
Bydefault,LISTSERVwillonlyattempttoverifypasswordstransmittedoverSSL.
Note4thatthisoptiondoesnotcontrolLISTSERV'sownuseofSSLwhencommunicatingwiththeLDAPserver.
SeetheLDAP_SERVER_nicknamevariable.
SIGNUP_REQUIRE_SSL=0or1(default:0)Similartotheabove,butaffectsallLISTSERVpasswords,whetherLDAPorinternal.
CanbeusedwithoutenablingLDAPauthentication.
TheLDAPauthenticationprocessWhenLDAPisenabled,LISTSERVgoesthroughthefollowingstepstologinauser:1.
TheserverslistedinLDAP_PW_SERVERSareexaminedinturn,intheorderinwhichtheywerelisted.
Foreachserver,LISTSERVexecutesthesearchconfiguredwiththeLDAP_PW_BASE_nicknameandLDAP_PW_FILTER_nicknamevariables.
LISTSERVstopsatthefirstsuccessfulsearch,orwhentherearenomoreLDAPserverstoquery.
2.
Ifnoneofthesearchesweresuccessful(noLDAPaccountexistsforthisuser),LISTSERV:a.
RejectstheloginifLDAP_PW_ONLY=1.
b.
Switchestointernal(non‐LDAP)loginifLDAP_PW_ONLY=0.
Theloginwillbevalidatedagainsttheuser'sinternalLISTSERVpassword,ifany,ortheuserwillbepromptedtocreateaLISTSERVpassword.
3.
IfanLDAPaccountwasfoundforthisuser,LISTSERV:a.
RejectstheloginifLDAP_PW_REQUIRE_SSL=1andtheloginrequestdidnotcomeoveranSSLsession.
Inthiscase,LISTSERVdoesnoteventrytoverifythepassword.
b.
VerifiesthepasswordagainsttheLDAPserverwheretheaccountwasfound,andacceptsorrejectstheloginasappropriate.
Anoteonthe"requireSSL"optionThepurposeofthe"requireSSL"optionistopreventordinary,non‐malicioususersfromjeopardizingtheirlogincredentialsfortheirpersonalconvenience,forinstancebytypingclear‐textpasswordsine‐mailrequestsbecauseitisfasterthanwaitingforaconfirmation'cookie'attheparticularInternetcaféwheretheyarereadingtheirmail.
The"requireSSL"optioneffectivelydisablestheseloginattemptsandforcesuserstologinusingthewebinterfaceandSSL.
AsLISTSERVdoesnotdirectlyprocessSSLsessions,ithasnofirst‐handknowledgeastowhetherSSLwasusedtoencrypttheloginsessionornot.
ItisthewebserverthathandlestheSSLsessionwiththeuser'sbrowser,notifiestheLISTSERVwebinterfacethatSSLwasused,andthewebinterfacescriptinturnnotifiesLISTSERVthatthepasswordwasnotsentincleartext.
LISTSERVhasnowaytoverifythisrepresentationorguaranteethatSSLwasinfactusedtotransmitthepassword.
Thisbeingsaid,thereisnoadvantageforamalicioususerinloggingintoLISTSERVwithhisowncredentialsoveranunencryptedconnection.
Themalicioususer'sinterestisforother,non‐malicioususerstoexposetheirpasswordsbysendingthemincleartext,sothatthemalicioususermaygatherthem.
5DynamicQueryfeatureAlthoughDynamicQueriesareprimarilybasedontheLDAPinterface,theyaredescribedinaseparatedocumentastheysupportbothLDAPandDBMSdatastores.
KnownissuesandrestrictionsThefollowingknownissuesandrestrictionsexist:Someunixsystemsnotsupported.
Atthispoint,LDAPfunctionalityisnotavailableforTru64orHP‐UX.
OpenLDAPlibraryrequiredtore‐linkonunix.
Customerswishingtore‐link'lsv'onunixwillhavetoinstalltheOPENLDAPlibrary(exceptonTru64andHP‐UX),eveniftheydonotwanttouseLDAP.
Staticlibrarysupportnottestedonallunixbrands.
OurgoalisforunixbuildswithLDAPfunctionalitytoworkontargetsystemsthatdonothavethedynamicLDAPlibrary,butwehavenottestedthisoneverysystem.
6