[Bps-public-commit] rt-authen-externalauth branch, docs-improvements, created. 0.10_01-8-gf65d432

Ruslan Zakirov ruz at bestpractical.com
Wed Jun 6 06:55:05 EDT 2012


The branch, docs-improvements has been created
        at  f65d4327b2e4c4544406b9a174a2e3ae4f684ecd (commit)

- Log -----------------------------------------------------------------
commit 65de054d182f9fb6eb1ceeb0ead1093c63ec2aa4
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Wed May 18 19:08:22 2011 +0400

    change indents to fit reasonable screen size

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index a080d40..e23cf55 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -11,7 +11,7 @@ Set($ExternalAuthPriority,  [   'My_LDAP',
 # 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. 
+# should be considered disabled.
 #
 # Once user info is found, no more services are checked.
 #
@@ -34,152 +34,158 @@ Set($AutoCreateNonExternalUsers,    0);
 # These are the full settings for each external service as a HashOfHashes
 # Note that you may have as many external services as you wish. They will
 # be checked in the order specified in the Priority directives above.
-# e.g. 
+# e.g.
 #   Set($ExternalAuthPriority,['My_LDAP','My_MySQL','My_Oracle','SecondaryLDAP','Other-DB']);
 #
-Set($ExternalSettings,      {   # AN EXAMPLE DB SERVICE
-                                'My_MySQL'   =>  {      ## GENERIC SECTION
-                                                        # The type of service (db/ldap/cookie) 
-                                                        'type'                      =>  'db',
-                                                        # The server hosting the service
-                                                        'server'                    =>  'server.domain.tld',
-                                                        ## SERVICE-SPECIFIC SECTION
-                                                        # The database name
-                                                        'database'                  =>  'DB_NAME',
-                                                        # The database table
-                                                        'table'                     =>  'USERS_TABLE',
-                                                        # The user to connect to the database as
-                                                        'user'                      =>  'DB_USER',
-                                                        # The password to use to connect with
-                                                        'pass'                      =>  'DB_PASS',
-                                                        # The port to use to connect with (e.g. 3306)
-                                                        'port'                      =>  'DB_PORT',
-                                                        # The name of the Perl DBI driver to use (e.g. mysql)
-                                                        'dbi_driver'                =>  'DBI_DRIVER',
-                                                        # The field in the table that holds usernames
-                                                        'u_field'                   =>  'username',
-                                                        # The field in the table that holds passwords
-                                                        'p_field'                   =>  'password',
-                                                        # 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
-                                                        'p_enc_pkg'                 =>  'Crypt::MySQL',
-                                                        'p_enc_sub'                 =>  'password',
-                                                        # If your p_enc_sub takes a salt as a second parameter, 
-                                                        # uncomment this line to add your salt
-                                                        #'p_salt'                    =>  'SALT',
-                                                        #
-                                                        # The field and values in the table that determines if a user should
-                                                        # be disabled. For example, if the field is 'user_status' and the values
-                                                        # are ['0','1','2','disabled'] then the user will be disabled if their
-                                                        # user_status is set to '0','1','2' or the string 'disabled'.
-                                                        # Otherwise, they will be considered enabled.
-                                                        'd_field'                   =>  'disabled',
-                                                        'd_values'                  =>  ['0'],
-                                                        ## RT ATTRIBUTE MATCHING SECTION
-                                                        # The list of RT attributes that uniquely identify a user
-                                                        'attr_match_list'           =>  [   'Gecos',
-                                                                                            'Name'
-                                                                                        ],
-                                                        # The mapping of RT attributes on to field names
-                                                        'attr_map'                  =>  {   'Name' => 'username',
-                                                                                            'EmailAddress' => 'email',
-                                                                                            'ExternalAuthId' => 'username',
-                                                                                            'Gecos' => 'userID'
-                                                                                        }
-                                                    },
-                                # AN EXAMPLE LDAP SERVICE
-                                'My_LDAP'       =>  {   ## GENERIC SECTION
-                                                        # The type of service (db/ldap/cookie) 
-                                                        'type'                      =>  'ldap',
-                                                        # The server hosting the service
-                                                        'server'                    =>  'server.domain.tld',
-                                                        ## SERVICE-SPECIFIC SECTION
-                                                        # If you can bind to your LDAP server anonymously you should 
-                                                        # remove the user and pass config lines, otherwise specify them here:
-                                                        # 
-                                                        # The username RT should use to connect to the LDAP server 
-                                                        'user'                      =>  'rt_ldap_username',
-                                                        # The password RT should use to connect to the LDAP server
-                                                        'pass'                    =>  'rt_ldap_password',
-                                                        #
-                                                        # The LDAP search base
-                                                        'base'                      =>  'ou=Organisational Unit,dc=domain,dc=TLD',
-                                                        #
-                                                        # ALL FILTERS MUST BE VALID LDAP FILTERS ENCASED IN PARENTHESES!
-                                                        # YOU **MUST** SPECIFY A filter AND A d_filter!!
-                                                        #
-                                                        # The filter to use to match RT-Users
-                                                        'filter'                    =>  '(FILTER_STRING)',
-                                                        # A catch-all example filter: '(objectClass=*)'
-                                                        #
-                                                        # The filter that will only match disabled users
-                                                        'd_filter'                  =>  '(FILTER_STRING)',
-                                                        # A catch-none example d_filter: '(objectClass=FooBarBaz)'
-                                                        #
-                                                        # Should we try to use TLS to encrypt connections?
-                                                        'tls'                       =>  0,
-                                                        # SSL Version to provide to Net::SSLeay *if* using SSL
-                                                        'ssl_version'               =>  3,
-                                                        # What other args should I pass to Net::LDAP->new($host, at args)?
-                                                        'net_ldap_args'             => [    version =>  3   ],
-                                                        # Does authentication depend on group membership? What group name?
-                                                        'group'                     =>  'GROUP_NAME',
-                                                        # What is the attribute for the group object that determines membership?
-                                                        'group_attr'                =>  'GROUP_ATTR',
+Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
+    'My_MySQL'   =>  {
+        ## GENERIC SECTION
+        # The type of service (db/ldap/cookie)
+        'type'                      =>  'db',
+        # The server hosting the service
+        'server'                    =>  'server.domain.tld',
+        ## SERVICE-SPECIFIC SECTION
+        # The database name
+        'database'                  =>  'DB_NAME',
+        # The database table
+        'table'                     =>  'USERS_TABLE',
+        # The user to connect to the database as
+        'user'                      =>  'DB_USER',
+        # The password to use to connect with
+        'pass'                      =>  'DB_PASS',
+        # The port to use to connect with (e.g. 3306)
+        'port'                      =>  'DB_PORT',
+        # The name of the Perl DBI driver to use (e.g. mysql)
+        'dbi_driver'                =>  'DBI_DRIVER',
+        # The field in the table that holds usernames
+        'u_field'                   =>  'username',
+        # The field in the table that holds passwords
+        'p_field'                   =>  'password',
+        # 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
+        'p_enc_pkg'                 =>  'Crypt::MySQL',
+        'p_enc_sub'                 =>  'password',
+        # If your p_enc_sub takes a salt as a second parameter,
+        # uncomment this line to add your salt
+        #'p_salt'                    =>  'SALT',
+        #
+        # The field and values in the table that determines if a user should
+        # be disabled. For example, if the field is 'user_status' and the values
+        # are ['0','1','2','disabled'] then the user will be disabled if their
+        # user_status is set to '0','1','2' or the string 'disabled'.
+        # Otherwise, they will be considered enabled.
+        'd_field'                   =>  'disabled',
+        'd_values'                  =>  ['0'],
+        ## RT ATTRIBUTE MATCHING SECTION
+        # The list of RT attributes that uniquely identify a user
+        'attr_match_list' =>  [
+            'Gecos',
+            'Name',
+        ],
+        # The mapping of RT attributes on to field names
+        'attr_map' => {
+            'Name'           => 'username',
+            'EmailAddress'   => 'email',
+            'ExternalAuthId' => 'username',
+            'Gecos'          => 'userID',
+        },
+    },
+    # AN EXAMPLE LDAP SERVICE
+    'My_LDAP'       =>  {
+        ## GENERIC SECTION
+        # The type of service (db/ldap/cookie)
+        'type'                      =>  'ldap',
+        # The server hosting the service
+        'server'                    =>  'server.domain.tld',
+        ## SERVICE-SPECIFIC SECTION
+        # If you can bind to your LDAP server anonymously you should
+        # remove the user and pass config lines, otherwise specify them here:
+        #
+        # The username RT should use to connect to the LDAP server
+        'user'                      =>  'rt_ldap_username',
+        # The password RT should use to connect to the LDAP server
+        'pass'                    =>  'rt_ldap_password',
+        #
+        # The LDAP search base
+        'base'                      =>  'ou=Organisational Unit,dc=domain,dc=TLD',
+        #
+        # ALL FILTERS MUST BE VALID LDAP FILTERS ENCASED IN PARENTHESES!
+        # YOU **MUST** SPECIFY A filter AND A d_filter!!
+        #
+        # The filter to use to match RT-Users
+        'filter'                    =>  '(FILTER_STRING)',
+        # A catch-all example filter: '(objectClass=*)'
+        #
+        # The filter that will only match disabled users
+        'd_filter'                  =>  '(FILTER_STRING)',
+        # A catch-none example d_filter: '(objectClass=FooBarBaz)'
+        #
+        # Should we try to use TLS to encrypt connections?
+        'tls'                       =>  0,
+        # SSL Version to provide to Net::SSLeay *if* using SSL
+        'ssl_version'               =>  3,
+        # What other args should I pass to Net::LDAP->new($host, at args)?
+        'net_ldap_args'             => [    version =>  3   ],
+        # Does authentication depend on group membership? What group name?
+        'group'                     =>  'GROUP_NAME',
+        # What is the attribute for the group object that determines membership?
+        'group_attr'                =>  'GROUP_ATTR',
                                                         # What is the attribute of the user entry that should be matched against group_attr above? (Optional; defaults to 'dn')
                                                         'group_attr_value'          =>  'GROUP_ATTR_VALUE',
-                                                        ## RT ATTRIBUTE MATCHING SECTION
-                                                        # The list of RT attributes that uniquely identify a user
-							# This example shows what you *can* specify.. I recommend reducing this
-                                                        # to just the Name and EmailAddress to save encountering problems later.
-                                                        'attr_match_list'           => [    'Name',
-                                                                                            'EmailAddress', 
-                                                                                            'RealName',
-                                                                                            'WorkPhone', 
-                                                                                            'Address2'
-                                                                                        ],
-                                                        # The mapping of RT attributes on to LDAP attributes
-                                                        'attr_map'                  =>  {   'Name' => 'sAMAccountName',
-                                                                                            'EmailAddress' => 'mail',
-                                                                                            'Organization' => 'physicalDeliveryOfficeName',
-                                                                                            'RealName' => 'cn',
-                                                                                            'ExternalAuthId' => 'sAMAccountName',
-                                                                                            'Gecos' => 'sAMAccountName',
-                                                                                            'WorkPhone' => 'telephoneNumber',
-                                                                                            'Address1' => 'streetAddress',
-                                                                                            'City' => 'l',
-                                                                                            'State' => 'st',
-                                                                                            'Zip' => 'postalCode',
-                                                                                            'Country' => 'co'
-                                                                                        }
-                                                    },
-                                # An example SSO cookie service
-                                'My_SSO_Cookie'  => {   # # The type of service (db/ldap/cookie)
-                                                        'type'                      =>  'cookie',
-                                                        # The name of the cookie to be used
-                                                        'name'                      =>  'loginCookieValue',
-                                                        # The users table
-                                                        'u_table'                   =>  'users',
-                                                        # The username field in the users table
-                                                        'u_field'                   =>  'username',
-                                                        # The field in the users table that uniquely identifies a user
-                                                        # and also exists in the cookies table
-                                                        'u_match_key'               =>  'userID',
-                                                        # The cookies table
-                                                        'c_table'                   =>  'login_cookie',
-                                                        # The field that stores cookie values
-                                                        'c_field'                   =>  'loginCookieValue',
-                                                        # The field in the cookies table that uniquely identifies a user
-                                                        # and also exists in the users table
-                                                        'c_match_key'               =>  'loginCookieUserID',
-                                                        # The DB service in this configuration to use to lookup the cookie information
-                                                        'db_service_name'           =>  'My_MySQL'
-                                                    }
-                                }
-);
+        ## RT ATTRIBUTE MATCHING SECTION
+        # The list of RT attributes that uniquely identify a user
+        # This example shows what you *can* specify.. I recommend reducing this
+        # to just the Name and EmailAddress to save encountering problems later.
+        'attr_match_list' => [
+            'Name',
+            'EmailAddress',
+            'RealName',
+            'WorkPhone',
+            'Address2'
+        ],
+        # The mapping of RT attributes on to LDAP attributes
+        'attr_map' => {
+            'Name' => 'sAMAccountName',
+            'EmailAddress' => 'mail',
+            'Organization' => 'physicalDeliveryOfficeName',
+            'RealName' => 'cn',
+            'ExternalAuthId' => 'sAMAccountName',
+            'Gecos' => 'sAMAccountName',
+            'WorkPhone' => 'telephoneNumber',
+            'Address1' => 'streetAddress',
+            'City' => 'l',
+            'State' => 'st',
+            'Zip' => 'postalCode',
+            'Country' => 'co'
+        },
+    },
+    # An example SSO cookie service
+    'My_SSO_Cookie'  => {
+        # # The type of service (db/ldap/cookie)
+        'type'                      =>  'cookie',
+        # The name of the cookie to be used
+        'name'                      =>  'loginCookieValue',
+        # The users table
+        'u_table'                   =>  'users',
+        # The username field in the users table
+        'u_field'                   =>  'username',
+        # The field in the users table that uniquely identifies a user
+        # and also exists in the cookies table
+        'u_match_key'               =>  'userID',
+        # The cookies table
+        'c_table'                   =>  'login_cookie',
+        # The field that stores cookie values
+        'c_field'                   =>  'loginCookieValue',
+        # The field in the cookies table that uniquely identifies a user
+        # and also exists in the users table
+        'c_match_key'               =>  'loginCookieUserID',
+        # The DB service in this configuration to use to lookup the cookie information
+        'db_service_name'           =>  'My_MySQL'
+    },
+} );
 
 1;

commit a334d1df7bd0a044c030a000a3c957de26309173
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Wed May 18 19:20:50 2011 +0400

    convert comments into POD

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index e23cf55..74c183f 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -1,42 +1,68 @@
-# The order in which the services defined in ExternalSettings
-# should be used to authenticate users. User is authenticated
-# if successfully confirmed by any service - no more services
-# are checked.
+
+=over 4
+
+=item C<$ExternalAuthPriority>
+
+The order in which the services defined in ExternalSettings
+should be used to authenticate users. User is authenticated
+if successfully confirmed by any service - no more services
+are checked.
+
+=cut
+
 Set($ExternalAuthPriority,  [   'My_LDAP',
                                 'My_MySQL',
                                 'My_SSO_Cookie'
                             ]
 );
 
-# 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 info is found, no more services are checked.
-#
-# You CANNOT use a SSO cookie for authentication.
+=item C<$ExternalInfoPriority>
+
+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.
+
+You CANNOT use a SSO cookie to retrieve information.
+
+=cut
+
 Set($ExternalInfoPriority,  [   'My_MySQL',
                                 'My_LDAP'
                             ]
 );
 
-# If this is set to true, then the relevant packages will
-# be loaded to use SSL/TLS connections. At the moment,
-# this just means "use Net::SSLeay;"
+=item C<$ExternalServiceUsesSSLorTLS>
+
+If this is set to true, then the relevant packages will
+be loaded to use SSL/TLS connections. At the moment,
+this just means L<Net::SSLeay>.
+
+=cut
+
 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.
+=item C<$AutoCreateNonExternalUsers>
+
+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.
+
+=cut
+
 Set($AutoCreateNonExternalUsers,    0);
 
-# These are the full settings for each external service as a HashOfHashes
-# Note that you may have as many external services as you wish. They will
-# be checked in the order specified in the Priority directives above.
-# e.g.
-#   Set($ExternalAuthPriority,['My_LDAP','My_MySQL','My_Oracle','SecondaryLDAP','Other-DB']);
-#
+=item C<$ExternalSettings>
+
+These are the full settings for each external service as a HashOfHashes.
+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.
+
+=cut
+
 Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
     'My_MySQL'   =>  {
         ## GENERIC SECTION
@@ -188,4 +214,8 @@ Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
     },
 } );
 
+=back
+
+=cut
+
 1;

commit 341ffeb36f633e34b221d8f84049469e39f88899
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Thu May 19 01:19:37 2011 +0400

    move config docs into config

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index 74c183f..b5c2b7c 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -1,3 +1,4 @@
+=head1 External Authentication Configuration
 
 =over 4
 
@@ -61,6 +62,100 @@ 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:
+
+    Set($ExternalSettings,
+        MyLDAP => {
+            type => 'ldap',
+            ... other options ...
+        },
+        MyMySQL => {
+            type => 'db',
+            ... other options ...
+        },
+        ... other sources ...
+    );
+
+As showed above each description should have 'type' information,
+the following types are supported:
+
+=over 4
+
+=item ldap
+
+Auth against and information sync 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>
+for details.
+
+=item cookie
+
+Auth by a 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:
+
+=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:
+
+    'attr_match_list' => [
+        'Name',
+        'EmailAddress',
+        'RealName',
+        'WorkPhone',
+    ],
+
+=item attr_map
+
+Mapping of RT attributes on to attributes in the external source.
+Example:
+
+    'attr_map' => {
+        'Name'         => 'sAMAccountName',
+        'EmailAddress' => 'mail',
+        'Organization' => 'physicalDeliveryOfficeName',
+        'RealName'     => 'cn',
+        ...
+    },
+
+Since version 0.10 it's possible to map one RT field to multiple
+external attributes, for example:
+
+    attr_map => {
+        EmailAddress => ['mail', 'alias'],
+        ...
+    },
+
+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:
+
+    attr_match_list => ['Name', 'EmailAddress'],
+    attr_map => {
+        Name         => 'account',
+        EmailAddress => ['mail', 'alias'],
+        ...
+    },
+
+=back
+
 =cut
 
 Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
diff --git a/lib/RT/Authen/ExternalAuth.pm b/lib/RT/Authen/ExternalAuth.pm
index 948939a..d30ac3b 100644
--- a/lib/RT/Authen/ExternalAuth.pm
+++ b/lib/RT/Authen/ExternalAuth.pm
@@ -129,7 +129,7 @@ General Public License. The license is distributed with
 this package in the LICENSE file found in the directory 
 root.
 
-=cut    
+=cut
 
 use RT::Authen::ExternalAuth::LDAP;
 use RT::Authen::ExternalAuth::DBI;

commit f65d4327b2e4c4544406b9a174a2e3ae4f684ecd
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Thu May 19 01:59:52 2011 +0400

    move docs from comments into POD

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index b5c2b7c..f923008 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -158,56 +158,27 @@ attribute is used. Config example:
 
 =cut
 
-Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
+Set($ExternalSettings, {
+    # AN EXAMPLE DB SERVICE
     'My_MySQL'   =>  {
-        ## GENERIC SECTION
-        # The type of service (db/ldap/cookie)
         'type'                      =>  'db',
-        # The server hosting the service
         'server'                    =>  'server.domain.tld',
-        ## SERVICE-SPECIFIC SECTION
-        # The database name
         'database'                  =>  'DB_NAME',
-        # The database table
         'table'                     =>  'USERS_TABLE',
-        # The user to connect to the database as
         'user'                      =>  'DB_USER',
-        # The password to use to connect with
         'pass'                      =>  'DB_PASS',
-        # The port to use to connect with (e.g. 3306)
         'port'                      =>  'DB_PORT',
-        # The name of the Perl DBI driver to use (e.g. mysql)
         'dbi_driver'                =>  'DBI_DRIVER',
-        # The field in the table that holds usernames
         'u_field'                   =>  'username',
-        # The field in the table that holds passwords
         'p_field'                   =>  'password',
-        # 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
         'p_enc_pkg'                 =>  'Crypt::MySQL',
         'p_enc_sub'                 =>  'password',
-        # If your p_enc_sub takes a salt as a second parameter,
-        # uncomment this line to add your salt
-        #'p_salt'                    =>  'SALT',
-        #
-        # The field and values in the table that determines if a user should
-        # be disabled. For example, if the field is 'user_status' and the values
-        # are ['0','1','2','disabled'] then the user will be disabled if their
-        # user_status is set to '0','1','2' or the string 'disabled'.
-        # Otherwise, they will be considered enabled.
         'd_field'                   =>  'disabled',
         'd_values'                  =>  ['0'],
-        ## RT ATTRIBUTE MATCHING SECTION
-        # The list of RT attributes that uniquely identify a user
         'attr_match_list' =>  [
             'Gecos',
             'Name',
         ],
-        # The mapping of RT attributes on to field names
         'attr_map' => {
             'Name'           => 'username',
             'EmailAddress'   => 'email',
@@ -217,50 +188,20 @@ Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
     },
     # AN EXAMPLE LDAP SERVICE
     'My_LDAP'       =>  {
-        ## GENERIC SECTION
-        # The type of service (db/ldap/cookie)
         'type'                      =>  'ldap',
-        # The server hosting the service
         'server'                    =>  'server.domain.tld',
-        ## SERVICE-SPECIFIC SECTION
-        # If you can bind to your LDAP server anonymously you should
-        # remove the user and pass config lines, otherwise specify them here:
-        #
-        # The username RT should use to connect to the LDAP server
         'user'                      =>  'rt_ldap_username',
-        # The password RT should use to connect to the LDAP server
         'pass'                    =>  'rt_ldap_password',
-        #
-        # The LDAP search base
         'base'                      =>  'ou=Organisational Unit,dc=domain,dc=TLD',
-        #
-        # ALL FILTERS MUST BE VALID LDAP FILTERS ENCASED IN PARENTHESES!
-        # YOU **MUST** SPECIFY A filter AND A d_filter!!
-        #
-        # The filter to use to match RT-Users
         'filter'                    =>  '(FILTER_STRING)',
-        # A catch-all example filter: '(objectClass=*)'
-        #
-        # The filter that will only match disabled users
         'd_filter'                  =>  '(FILTER_STRING)',
-        # A catch-none example d_filter: '(objectClass=FooBarBaz)'
-        #
-        # Should we try to use TLS to encrypt connections?
+        'group'                     =>  'GROUP_NAME',
+        'group_attr'                =>  'GROUP_ATTR',
         'tls'                       =>  0,
-        # SSL Version to provide to Net::SSLeay *if* using SSL
         'ssl_version'               =>  3,
-        # What other args should I pass to Net::LDAP->new($host, at args)?
         'net_ldap_args'             => [    version =>  3   ],
-        # Does authentication depend on group membership? What group name?
-        'group'                     =>  'GROUP_NAME',
-        # What is the attribute for the group object that determines membership?
-        'group_attr'                =>  'GROUP_ATTR',
                                                         # What is the attribute of the user entry that should be matched against group_attr above? (Optional; defaults to 'dn')
                                                         'group_attr_value'          =>  'GROUP_ATTR_VALUE',
-        ## RT ATTRIBUTE MATCHING SECTION
-        # The list of RT attributes that uniquely identify a user
-        # This example shows what you *can* specify.. I recommend reducing this
-        # to just the Name and EmailAddress to save encountering problems later.
         'attr_match_list' => [
             'Name',
             'EmailAddress',
@@ -268,7 +209,6 @@ Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
             'WorkPhone',
             'Address2'
         ],
-        # The mapping of RT attributes on to LDAP attributes
         'attr_map' => {
             'Name' => 'sAMAccountName',
             'EmailAddress' => 'mail',
@@ -286,25 +226,14 @@ Set($ExternalSettings, {   # AN EXAMPLE DB SERVICE
     },
     # An example SSO cookie service
     'My_SSO_Cookie'  => {
-        # # The type of service (db/ldap/cookie)
         'type'                      =>  'cookie',
-        # The name of the cookie to be used
         'name'                      =>  'loginCookieValue',
-        # The users table
         'u_table'                   =>  'users',
-        # The username field in the users table
         'u_field'                   =>  'username',
-        # The field in the users table that uniquely identifies a user
-        # and also exists in the cookies table
         'u_match_key'               =>  'userID',
-        # The cookies table
         'c_table'                   =>  'login_cookie',
-        # The field that stores cookie values
         'c_field'                   =>  'loginCookieValue',
-        # The field in the cookies table that uniquely identifies a user
-        # and also exists in the users table
         'c_match_key'               =>  'loginCookieUserID',
-        # The DB service in this configuration to use to lookup the cookie information
         'db_service_name'           =>  'My_MySQL'
     },
 } );
diff --git a/lib/RT/Authen/ExternalAuth/DBI.pm b/lib/RT/Authen/ExternalAuth/DBI.pm
index 7099632..fb941df 100644
--- a/lib/RT/Authen/ExternalAuth/DBI.pm
+++ b/lib/RT/Authen/ExternalAuth/DBI.pm
@@ -5,6 +5,117 @@ use RT::Authen::ExternalAuth::DBI::Cookie;
 
 use strict;
 
+=head1 SYNOPSIS
+
+    Set($ExternalSettings, {
+        'My_MySQL'   =>  {
+            'type'                      =>  'db',
+
+            'dbi_driver'                =>  'DBI_DRIVER',
+
+            'server'                    =>  'server.domain.tld',
+            'port'                      =>  'DB_PORT',
+            'user'                      =>  'DB_USER',
+            'pass'                      =>  'DB_PASS',
+
+            'database'                  =>  'DB_NAME',
+            'table'                     =>  'USERS_TABLE',
+            'u_field'                   =>  'username',
+            'p_field'                   =>  'password',
+
+            'p_enc_pkg'                 =>  'Crypt::MySQL',
+            'p_enc_sub'                 =>  'password',
+            'p_salt'                    =>  'SALT',
+
+            'd_field'                   =>  'disabled',
+            'd_values'                  =>  ['0'],
+
+            'attr_match_list' =>  [
+                'Gecos',
+                'Name',
+            ],
+            'attr_map' => {
+                'Name'           => 'username',
+                'EmailAddress'   => 'email',
+                'ExternalAuthId' => 'username',
+                'Gecos'          => 'userID',
+            },
+        },
+    } );
+
+=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.
+
+The following options are supported:
+
+=over 4
+
+=item dbi_driver
+
+The name of the Perl DBI driver to use (e.g. mysql, Pg, SQLite)
+
+=item server
+
+The server hosting the database
+
+=item port
+
+The port to use to connect with (e.g. 3306)
+
+=item user
+
+The user to connect to the database server as
+
+=item pass
+
+The password to use to connect with
+
+=item database
+
+The database name
+
+=item table
+
+The database table
+
+=item u_field
+
+The field in the table that holds usernames
+
+=item p_field
+
+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.
+
+=item p_salt
+
+If p_enc_sub takes a salt as a second parameter then set it to add
+your salt
+
+=item d_field, d_values
+
+The field and values in the table that determines if a user should
+be disabled. For example, if the field is 'user_status' and the values
+are ['0','1','2','disabled'] then the user will be disabled if their
+user_status is set to '0','1','2' or the string 'disabled'.
+Otherwise, they will be considered enabled.
+
+=back
+
+=cut
+
 sub GetAuth {
 
     my ($service, $username, $password) = @_;
diff --git a/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm b/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
index 3a2b0f3..7700d19 100644
--- a/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
+++ b/lib/RT/Authen/ExternalAuth/DBI/Cookie.pm
@@ -4,6 +4,76 @@ use CGI::Cookie;
 
 use strict;
 
+=head1 SYNOPSIS
+
+Set($ExternalSettings, {
+    # An example SSO cookie service
+    'My_SSO_Cookie'  => {
+        'type'                      =>  'cookie',
+        'name'                      =>  'loginCookieValue',
+        'u_table'                   =>  'users',
+        'u_field'                   =>  'username',
+        'u_match_key'               =>  'userID',
+        'c_table'                   =>  'login_cookie',
+        'c_field'                   =>  'loginCookieValue',
+        'c_match_key'               =>  'loginCookieUserID',
+        'db_service_name'           =>  'My_MySQL'
+    },
+    'My_MySQL' => {
+        ...
+    },
+} );
+
+=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.
+
+The following options are supported:
+
+=over 4
+
+=item name
+
+The name of the cookie to be used
+
+=item u_table
+
+The users table
+
+=item u_field
+
+The username field in the users table
+
+=item u_match_key
+
+The field in the users table that uniquely identifies a user
+and also exists in the cookies table. See c_match_key below.
+
+=item c_table
+
+The cookies table
+
+=item c_field
+
+The field that stores cookie values
+
+=item c_match_key
+
+The field in the cookies table that uniquely identifies a user
+and also exists in the users table. See u_match_key above.
+
+=item db_service_name
+
+The DB service in this configuration to use to lookup the cookie
+information. See L<RT::Authen::ExternalAuth::DBI>.
+
+=back
+
+=cut
+
 # {{{ sub GetCookieVal
 sub GetCookieVal {
 
diff --git a/lib/RT/Authen/ExternalAuth/LDAP.pm b/lib/RT/Authen/ExternalAuth/LDAP.pm
index b228e77..20b8238 100644
--- a/lib/RT/Authen/ExternalAuth/LDAP.pm
+++ b/lib/RT/Authen/ExternalAuth/LDAP.pm
@@ -8,6 +8,121 @@ use strict;
 
 require Net::SSLeay if $RT::ExternalServiceUsesSSLorTLS;
 
+=head1 SYNOPSIS
+
+    Set($ExternalSettings, {
+        # AN EXAMPLE LDAP SERVICE
+        'My_LDAP'       =>  {
+            'type'                      =>  'ldap',
+
+            'server'                    =>  'server.domain.tld',
+            'user'                      =>  'rt_ldap_username',
+            'pass'                    =>  'rt_ldap_password',
+
+            'base'                      =>  'ou=Organisational Unit,dc=domain,dc=TLD',
+            'filter'                    =>  '(FILTER_STRING)',
+            'd_filter'                  =>  '(FILTER_STRING)',
+
+            'group'                     =>  'GROUP_NAME',
+            'group_attr'                =>  'GROUP_ATTR',
+
+            'tls'                       =>  0,
+            'ssl_version'               =>  3,
+
+            'net_ldap_args'             => [    version =>  3   ],
+
+            'attr_match_list' => [
+                'Name',
+                'EmailAddress',
+                'RealName',
+                'WorkPhone',
+                'Address2'
+            ],
+            'attr_map' => {
+                'Name' => 'sAMAccountName',
+                'EmailAddress' => 'mail',
+                'Organization' => 'physicalDeliveryOfficeName',
+                'RealName' => 'cn',
+                'ExternalAuthId' => 'sAMAccountName',
+                'Gecos' => 'sAMAccountName',
+                'WorkPhone' => 'telephoneNumber',
+                'Address1' => 'streetAddress',
+                'City' => 'l',
+                'State' => 'st',
+                'Zip' => 'postalCode',
+                'Country' => 'co'
+            },
+        },
+    } );
+
+=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.
+
+The following options are supported:
+
+=over 4
+
+=item server
+
+The server hosting the service
+
+=item user, pass
+
+The username and password RT should use to connect to the LDAP
+server.
+
+If you can bind to your LDAP server anonymously you shouldn't
+set these options.
+
+=item base
+
+The LDAP search base
+
+=item filter, d_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.
+
+For example:
+
+    filter => '(objectClass=*)',
+
+=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
+in parentheses.
+
+To catch none use
+
+    d_filter => '(objectClass=FooBarBaz)'
+
+=item group
+
+Does authentication depend on group membership? What group name?
+
+=item group_attr
+
+What is the attribute for the group object that determines membership?
+
+=item tls
+
+Should we try to use TLS to encrypt connections?
+
+=item ssl_version
+
+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)?
+
+=cut
+
 sub GetAuth {
     
     my ($service, $username, $password) = @_;

-----------------------------------------------------------------------



More information about the Bps-public-commit mailing list