[Bps-public-commit] rt-authen-externalauth branch, docs-improvements, updated. 0.13-5-gbe1de67
Jim Brandt
jbrandt at bestpractical.com
Mon May 6 11:05:25 EDT 2013
The branch, docs-improvements has been updated
via be1de678940b2b64b3425c5c43740975b8bd9920 (commit)
from 0983a4b31711e508203c32c7bc274fec2aea68e6 (commit)
Summary of changes:
etc/RT_SiteConfig.pm | 112 +++++++++++++++++++++----------
lib/RT/Authen/ExternalAuth/DBI.pm | 45 +++++++------
lib/RT/Authen/ExternalAuth/DBI/Cookie.pm | 24 ++++---
lib/RT/Authen/ExternalAuth/LDAP.pm | 36 ++++++----
4 files changed, 137 insertions(+), 80 deletions(-)
- Log -----------------------------------------------------------------
commit be1de678940b2b64b3425c5c43740975b8bd9920
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Mon May 6 11:05:06 2013 -0400
Additional updates to docs
diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index 504b28f..68102e7 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -1,5 +1,11 @@
=head1 External Authentication Configuration
+L<RT::Authen::ExternalAuth> provides a lot of flexibility
+with many configuration options. This file describes these
+configuration options and is itself a sample configuration
+suitable for dropping into your C<etc/RT_SiteConfig.pm>
+file and modifying.
+
=over 4
=item C<$ExternalAuthPriority>
@@ -9,29 +15,36 @@ should be used to authenticate users. User is authenticated
if successfully confirmed by any service - no more services
are checked.
+You should remove services you don't use. For example,
+if you're only using My_LDAP, remove My_MySQL and My_SSO_Cookie.
+
=cut
-Set($ExternalAuthPriority, [ 'My_LDAP',
- 'My_MySQL',
- 'My_SSO_Cookie'
+Set($ExternalAuthPriority, [ 'My_LDAP',
+ 'My_MySQL',
+ 'My_SSO_Cookie'
]
);
=item C<$ExternalInfoPriority>
-The order in which the services defined in ExternalSettings
+When multiple auth services are available, this value eefines
+the order in which the services defined in ExternalSettings
should be used to get information about users. This includes
RealName, Tel numbers etc, but also whether or not the user
should be considered disabled.
-Once user record is found, no more services are checked.
+Once a user record is found, no more services are checked.
You CANNOT use a SSO cookie to retrieve information.
+You should remove services you don't use, but you must define
+at least one service.
+
=cut
-Set($ExternalInfoPriority, [ 'My_MySQL',
- 'My_LDAP'
+Set($ExternalInfoPriority, [ 'My_LDAP',
+ 'My_MySQL',
]
);
@@ -49,7 +62,9 @@ Set($ExternalServiceUsesSSLorTLS, 0);
If this is set to 1, then users should be autocreated by RT
as internal users if they fail to authenticate from an
-external service.
+external service. This is useful if you have users outside
+your organization who might interface with RT, perhaps by sending
+email to a support email address.
=cut
@@ -62,8 +77,9 @@ Note that you may have as many external services as you wish. They will
be checked in the order specified in $ExternalAuthPriority and
$ExternalInfoPriority directives above.
-Option is a hash with (name of external source, hash reference with
-description) pairs, for example:
+The outer structure is a key with the authentication option (name of external
+source). The value is a hash reference with configuration keys and values,
+for example:
Set($ExternalSettings,
MyLDAP => {
@@ -77,53 +93,56 @@ description) pairs, for example:
... other sources ...
);
-As showed above each description should have 'type' information,
-the following types are supported:
+As shown above, each description should have 'type' defined.
+The following types are supported:
=over 4
=item ldap
-Auth against and information sync with LDAP servers.
+Authenticate against and sync information with LDAP servers.
See L<RT::Authen::ExternalAuth::LDAP> for details.
=item db
-Auth against and information sync with external RDBMS supported
-by perl's L<DBI> interface. See L<RT::Authen::ExternalAuth::DBI>
+Authenticate against and sync information with external RDBMS,
+supported by Perl's L<DBI> interface. See L<RT::Authen::ExternalAuth::DBI>
for details.
=item cookie
-Auth by a cookie. See L<RT::Authen::ExternalAuth::DBI::Cookie>
+Authenticate by cookie. See L<RT::Authen::ExternalAuth::DBI::Cookie>
for details.
=back
-See documentation of referenced modules for information on config
-options.
-
-Generic options for services providing users' information:
+See the modules noted above for configuration options specific to each type.
+The following apply to all types.
=over 4
=item attr_match_list
-The list of RT attributes that uniquely identify a user. It's
-recommended to use 'Name' and 'EmailAddress' to save
-encountering problems later. Example:
+The list of RT attributes that uniquely identify a user. These values
+are used, in order, to find users in the selected authentication
+source. Each value specified here must have a mapping in the
+L</"attr_map"> section below. You can remove values you don't
+expect to match, but it's recommended to use 'Name' and 'EmailAddress'
+at minimum. For example:
'attr_match_list' => [
'Name',
'EmailAddress',
'RealName',
- 'WorkPhone',
],
=item attr_map
Mapping of RT attributes on to attributes in the external source.
-Example:
+Valid keys are attributes of an
+L<RT::User|http://bestpractical.com/rt/docs/latest/RT/User.html>.
+The values are attributes from your authentication source.
+For example, an LDAP mapping might look like:
'attr_map' => {
'Name' => 'sAMAccountName',
@@ -141,11 +160,17 @@ external attributes, for example:
...
},
-Note that only one value storred in RT. However, search goes by
-all external attributes if such RT field list in 'attr_match_list'.
-On create or update entered value is used as long as it's valid.
-If user didn't enter value then value stored in the first external
-attribute is used. Config example:
+Note that only one value is stored in RT, so this doesn't enable RT
+users to have multiple email addresses defined. However, the search
+will use all of the attributes to try to match a user if the field is
+defined in the C<attr_match_list>.
+
+On create or update, the original value input by the user, from an email
+or login attempt, is used as long as it's valid. If user didn't enter a
+value for that attribute, then the value retrieved from the first external
+attribute is used.
+
+For example, for the following configuration:
attr_match_list => ['Name', 'EmailAddress'],
attr_map => {
@@ -154,6 +179,27 @@ attribute is used. Config example:
...
},
+If a new user sent an email to RT from an email alias, the search
+would match on the alias and that alias would be set as the user's
+EmailAddress in RT when the new account is created.
+
+However, if a user with an existing RT account, with EmailAddress set
+to the C<mail> address, sent mail from C<alias>, it would
+still match. However, the user's EmailAddress in RT would
+remain the primary C<mail> address.
+
+This feature is useful for LDAP configurations where users have
+a primary institutional email address, but might also use aliases from
+subdomains or other email services. This prevents RT from creating
+multiple accounts for the same person.
+
+If you want the RT user accounts to always have the primary C<mail>
+address for EmailAddress, you likely want to run
+L<RT::Extension::LDAPImport> to make sure the user accounts are
+created with the desired email address set.
+
+=back
+
=back
=cut
@@ -206,8 +252,6 @@ Set($ExternalSettings, {
'Name',
'EmailAddress',
'RealName',
- 'WorkPhone',
- 'Address2'
],
'attr_map' => {
'Name' => 'sAMAccountName',
@@ -238,8 +282,4 @@ Set($ExternalSettings, {
},
} );
-=back
-
-=cut
-
1;
diff --git a/lib/RT/Authen/ExternalAuth/DBI.pm b/lib/RT/Authen/ExternalAuth/DBI.pm
index fb941df..112b877 100644
--- a/lib/RT/Authen/ExternalAuth/DBI.pm
+++ b/lib/RT/Authen/ExternalAuth/DBI.pm
@@ -5,6 +5,10 @@ use RT::Authen::ExternalAuth::DBI::Cookie;
use strict;
+=head1 DESCRIPTION
+
+Provides the database implementation for L<RT::Authen::ExternalAuth>.
+
=head1 SYNOPSIS
Set($ExternalSettings, {
@@ -45,42 +49,43 @@ use strict;
=head1 CONFIGURATION
-Generic options described in F<etc/RT_SiteConfig.pm> file shipped with
-tarball.
-
-Above in L</SYNOPSIS> you can find example that lists all options.
+DBI-specific options are described here. Shared options
+are described in the F<etc/RT_SiteConfig.pm> file included
+in this distribution.
-The following options are supported:
+The example in the L</SYNOPSIS> lists all available options
+and they are described below. See the L<DBI> module for details
+on debugging connection issues.
=over 4
=item dbi_driver
-The name of the Perl DBI driver to use (e.g. mysql, Pg, SQLite)
+The name of the Perl DBI driver to use (e.g. mysql, Pg, SQLite).
=item server
-The server hosting the database
+The server hosting the database.
=item port
-The port to use to connect with (e.g. 3306)
+The port to use to connect on (e.g. 3306).
=item user
-The user to connect to the database server as
+The database user for the connection.
=item pass
-The password to use to connect with
+The password for the database user.
=item database
-The database name
+The database name.
=item table
-The database table
+The database table containing the user information to check against.
=item u_field
@@ -92,17 +97,17 @@ The field in the table that holds passwords
=item p_enc_pkg, p_enc_sub
-The Perl package & subroutine used to encrypt passwords
-e.g. if the passwords are stored using the MySQL v3.23 "PASSWORD"
-function, then you will need Crypt::MySQL::password, but for the
-MySQL4+ password function you will need Crypt::MySQL::password41
-Alternatively, you could use Digest::MD5::md5_hex or any other
-encryption subroutine you can load in your perl installation.
+The Perl package and subroutine used to encrypt passwords from the
+database. For example, if the passwords are stored using the MySQL
+v3.23 "PASSWORD" function, then you will need the L<Crypt::MySQL>
+C<password> function, but for the MySQL4+ password you will need
+L<Crypt::MySQL>'s C<password41>. Alternatively, you could use
+L<Digest::MD5> C<md5_hex> or any other encryption subroutine you can
+load in your Perl installation.
=item p_salt
-If p_enc_sub takes a salt as a second parameter then set it to add
-your salt
+If p_enc_sub takes a salt as a second parameter then set it here.
=item d_field, d_values
diff --git a/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm b/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
index 7700d19..2d48d90 100644
--- a/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
+++ b/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
@@ -4,6 +4,10 @@ use CGI::Cookie;
use strict;
+=head1 DESCRIPTION
+
+Provides the Cookie implementation for L<RT::Authen::ExternalAuth>.
+
=head1 SYNOPSIS
Set($ExternalSettings, {
@@ -26,26 +30,26 @@ Set($ExternalSettings, {
=head1 CONFIGURATION
-Generic options described in F<etc/RT_SiteConfig.pm> file shipped with
-tarball.
-
-Above in L</SYNOPSIS> you can find example that lists all options.
+Cookie-specific options are described here. Shared options
+are described in the F<etc/RT_SiteConfig.pm> file included
+in this distribution.
-The following options are supported:
+The example in the L</SYNOPSIS> lists all available options
+and they are described below.
=over 4
=item name
-The name of the cookie to be used
+The name of the cookie to be used.
=item u_table
-The users table
+The users table.
=item u_field
-The username field in the users table
+The username field in the users table.
=item u_match_key
@@ -54,11 +58,11 @@ and also exists in the cookies table. See c_match_key below.
=item c_table
-The cookies table
+The cookies table.
=item c_field
-The field that stores cookie values
+The field that stores cookie values.
=item c_match_key
diff --git a/lib/RT/Authen/ExternalAuth/LDAP.pm b/lib/RT/Authen/ExternalAuth/LDAP.pm
index 21905b1..79dc8d2 100644
--- a/lib/RT/Authen/ExternalAuth/LDAP.pm
+++ b/lib/RT/Authen/ExternalAuth/LDAP.pm
@@ -8,6 +8,10 @@ use strict;
require Net::SSLeay if $RT::ExternalServiceUsesSSLorTLS;
+=head1 DESCRIPTION
+
+Provides the LDAP implementation for L<RT::Authen::ExternalAuth>.
+
=head1 SYNOPSIS
Set($ExternalSettings, {
@@ -17,7 +21,7 @@ require Net::SSLeay if $RT::ExternalServiceUsesSSLorTLS;
'server' => 'server.domain.tld',
'user' => 'rt_ldap_username',
- 'pass' => 'rt_ldap_password',
+ 'pass' => 'rt_ldap_password',
'base' => 'ou=Organisational Unit,dc=domain,dc=TLD',
'filter' => '(FILTER_STRING)',
@@ -57,18 +61,20 @@ require Net::SSLeay if $RT::ExternalServiceUsesSSLorTLS;
=head1 CONFIGURATION
-Generic options described in F<etc/RT_SiteConfig.pm> file shipped with
-tarball.
+LDAP-specific options are described here. Shared options
+are described in the F<etc/RT_SiteConfig.pm> file included
+in this distribution.
-Above in L</SYNOPSIS> you can find example that lists all options.
-
-The following options are supported:
+The example in the L</SYNOPSIS> lists all available options
+and they are described below. Note that many of these values
+are specific to LDAP, so you should consult your LDAP
+documentation for details.
=over 4
=item server
-The server hosting the service
+The server hosting the LDAP or AD service.
=item user, pass
@@ -80,12 +86,12 @@ set these options.
=item base
-The LDAP search base
+The LDAP search base.
-=item filter, d_filter
+=item filter
-The filter to use to match RT-Users. You B<MUST> specify it
-and it B<MUST> be a valid LDAP filter encased in parentheses.
+The filter to use to match RT users. You B<must> specify it
+and it B<must> be a valid LDAP filter encased in parentheses.
For example:
@@ -93,8 +99,8 @@ For example:
=item d_filter
-The filter that will only match disabled users. You B<MUST>
-specify it and it B<MUST> be a valid LDAP filter encased
+The filter that will only match disabled users. You B<must>
+specify it and it B<must> be a valid LDAP filter encased
in parentheses.
To catch none use
@@ -126,12 +132,14 @@ Should we try to use TLS to encrypt connections?
=item ssl_version
-SSL Version to provide to Net::SSLeay *if* using SSL
+SSL Version to provide to Net::SSLeay *if* using SSL.
=item net_ldap_args
What other args should be passed to Net::LDAP->new($host, at args)?
+=back
+
=cut
sub GetAuth {
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list