[Bps-public-commit] rt-authen-externalauth branch, docs-improvements, created. 0.13-4-g0983a4b
Ruslan Zakirov
ruz at bestpractical.com
Thu Apr 25 10:38:24 EDT 2013
The branch, docs-improvements has been created
at 0983a4b31711e508203c32c7bc274fec2aea68e6 (commit)
- Log -----------------------------------------------------------------
commit 8991389d07c5f6e063cfa050db17717596cfe1f8
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 687c989..f5afc9d 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,155 +34,163 @@ 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 scope of the group search? (base, one, sub)
- # Optional; defaults to 'base', which is good enough for most cases. 'sub' is appropriate when you have nested groups
- 'group_scope' => 'base',
- # 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'
- }
- }
-);
+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 scope of the group search? (base, one, sub)
+ # Optional; defaults to 'base', which is good enough for most cases.
+ # 'sub' is appropriate when you have nested groups
+ 'group_scope' => 'base',
+ # 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'
+ },
+} );
1;
commit 6515c048d4ef49db6b13be74e580364a0008f1d2
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 f5afc9d..74a273c 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
@@ -193,4 +219,8 @@ Set($ExternalSettings, { # AN EXAMPLE DB SERVICE
},
} );
+=back
+
+=cut
+
1;
commit 209803365b6da51ad014f43119d1efb3bcf15ae9
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 74a273c..415b66e 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 36f68a0..30b685c 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 0983a4b31711e508203c32c7bc274fec2aea68e6
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 415b66e..504b28f 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,55 +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 scope of the group search? (base, one, sub)
- # Optional; defaults to 'base', which is good enough for most cases.
- # 'sub' is appropriate when you have nested groups
'group_scope' => 'base',
- # 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',
@@ -273,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',
@@ -291,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 e73198c..21905b1 100644
--- a/lib/RT/Authen/ExternalAuth/LDAP.pm
+++ b/lib/RT/Authen/ExternalAuth/LDAP.pm
@@ -8,6 +8,132 @@ 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 group_scope
+
+What is the scope of the group search? C<base>, C<one> or C<sub>.
+Optional; defaults to C<base>, which is good enough for most cases.
+C<sub> is appropriate when you have nested groups.
+
+=item group_attr_value
+
+What is the attribute of the user entry that should be matched against
+group_attr above? Optional; defaults to C<dn>.
+
+=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