.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RT::Authen::ExternalAuth::LDAP 3pm"
.TH RT::Authen::ExternalAuth::LDAP 3pm "2016-09-06" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RT::Authen::ExternalAuth::LDAP \- LDAP source for RT authentication
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides the \s-1LDAP\s0 implementation for RT::Authen::ExternalAuth.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    Set($ExternalSettings, {
\&        # AN EXAMPLE LDAP SERVICE
\&        \*(AqMy_LDAP\*(Aq       =>  {
\&            \*(Aqtype\*(Aq                      =>  \*(Aqldap\*(Aq,
\&
\&            \*(Aqserver\*(Aq                    =>  \*(Aqserver.domain.tld\*(Aq,
\&            \*(Aquser\*(Aq                      =>  \*(Aqrt_ldap_username\*(Aq,
\&            \*(Aqpass\*(Aq                      =>  \*(Aqrt_ldap_password\*(Aq,
\&
\&            \*(Aqbase\*(Aq                      =>  \*(Aqou=Organisational Unit,dc=domain,dc=TLD\*(Aq,
\&            \*(Aqfilter\*(Aq                    =>  \*(Aq(FILTER_STRING)\*(Aq,
\&            \*(Aqd_filter\*(Aq                  =>  \*(Aq(FILTER_STRING)\*(Aq,
\&
\&            \*(Aqgroup\*(Aq                     =>  \*(AqGROUP_NAME\*(Aq,
\&            \*(Aqgroup_attr\*(Aq                =>  \*(AqGROUP_ATTR\*(Aq,
\&
\&            \*(Aqtls\*(Aq                       =>  { verify => "require", capath => "/path/to/ca.pem" },
\&
\&            \*(Aqnet_ldap_args\*(Aq             => [    version =>  3   ],
\&
\&            \*(Aqattr_match_list\*(Aq => [
\&                \*(AqName\*(Aq,
\&                \*(AqEmailAddress\*(Aq,
\&            ],
\&            \*(Aqattr_map\*(Aq => {
\&                \*(AqName\*(Aq => \*(AqsAMAccountName\*(Aq,
\&                \*(AqEmailAddress\*(Aq => \*(Aqmail\*(Aq,
\&                \*(AqOrganization\*(Aq => \*(AqphysicalDeliveryOfficeName\*(Aq,
\&                \*(AqRealName\*(Aq => \*(Aqcn\*(Aq,
\&                \*(AqExternalAuthId\*(Aq => \*(AqsAMAccountName\*(Aq,
\&                \*(AqGecos\*(Aq => \*(AqsAMAccountName\*(Aq,
\&                \*(AqWorkPhone\*(Aq => \*(AqtelephoneNumber\*(Aq,
\&                \*(AqAddress1\*(Aq => \*(AqstreetAddress\*(Aq,
\&                \*(AqCity\*(Aq => \*(Aql\*(Aq,
\&                \*(AqState\*(Aq => \*(Aqst\*(Aq,
\&                \*(AqZip\*(Aq => \*(AqpostalCode\*(Aq,
\&                \*(AqCountry\*(Aq => \*(Aqco\*(Aq
\&            },
\&        },
\&    } );
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
LDAP-specific options are described here. Shared options
are described in the \fIetc/RT_SiteConfig.pm\fR file included
in this distribution.
.PP
The example in the \*(L"\s-1SYNOPSIS\*(R"\s0 lists all available options
and they are described below. Note that many of these values
are specific to \s-1LDAP,\s0 so you should consult your \s-1LDAP\s0
documentation for details.
.IP "server" 4
.IX Item "server"
The server hosting the \s-1LDAP\s0 or \s-1AD\s0 service.
.IP "user, pass" 4
.IX Item "user, pass"
The username and password \s-1RT\s0 should use to connect to the \s-1LDAP\s0
server.
.Sp
If you can bind to your \s-1LDAP\s0 server anonymously you may be able to omit these
options.  Many servers do not allow anonymous binds, or restrict what information
they can see or how much information they can retrieve.  If your server does not
allow anonymous binds then you must have a service account created for this
extension to function.
.IP "base" 4
.IX Item "base"
The \s-1LDAP\s0 search base.
.IP "filter" 4
.IX Item "filter"
The filter to use to match \s-1RT\s0 users. You \fBmust\fR specify it
and it \fBmust\fR be a valid \s-1LDAP\s0 filter encased in parentheses.
.Sp
For example:
.Sp
.Vb 1
\&    filter => \*(Aq(objectClass=*)\*(Aq,
.Ve
.IP "d_filter" 4
.IX Item "d_filter"
The filter that will only match disabled users. Optional.
\&\fBMust\fR be a valid \s-1LDAP\s0 filter encased in parentheses.
.Sp
For example with Active Directory the following can be used:
.Sp
.Vb 1
\&    d_filter => \*(Aq(userAccountControl:1.2.840.113556.1.4.803:=2)\*(Aq
.Ve
.IP "group" 4
.IX Item "group"
Does authentication depend on group membership? What group name?
.IP "group_attr" 4
.IX Item "group_attr"
What is the attribute for the group object that determines membership?
.IP "group_scope" 4
.IX Item "group_scope"
What is the scope of the group search? \f(CW\*(C`base\*(C'\fR, \f(CW\*(C`one\*(C'\fR or \f(CW\*(C`sub\*(C'\fR.
Optional; defaults to \f(CW\*(C`base\*(C'\fR, which is good enough for most cases.
\&\f(CW\*(C`sub\*(C'\fR is appropriate when you have nested groups.
.IP "group_attr_value" 4
.IX Item "group_attr_value"
What is the attribute of the user entry that should be matched against
group_attr above? Optional; defaults to \f(CW\*(C`dn\*(C'\fR.
.IP "tls" 4
.IX Item "tls"
Should we try to use \s-1TLS\s0 to encrypt connections?  Either a scalar, for
simple enabling, or a hash of values to pass to \*(L"start_tls\*(R" in Net::LDAP.
By default, Net::LDAP does \fBno\fR certificate validation!  To validate
certificates, pass:
.Sp
.Vb 3
\&    tls => { verify => \*(Aqrequire\*(Aq,
\&             cafile => "/etc/ssl/certs/ca.pem",  # Path CA file
\&           },
.Ve
.IP "net_ldap_args" 4
.IX Item "net_ldap_args"
What other args should be passed to Net::LDAP\->new($host,@args)?