Extension:LDAP Authentication/Smartcard Configuration Examples

From MediaWiki.org
Jump to navigation Jump to search

About - Requirements - Examples - Configuration Options - Changelog - Roadmap - Suggestions - User provided info - FAQ - Support

Group and Preferences Examples - Generic LDAP Examples - Active Directory Examples - Smartcard Examples - Kerberos Examples


MediaWiki extensions manual
OOjs UI icon advanced.svg
LDAP Authentication
Release status: stable
Implementation User identity
Description Provides LDAP authentication, and some authorization functionality for MediaWiki
Author(s) Ryan Lane (Ryan lanetalk)
Latest version 2.1.0 (2018-10-11)
Compatibility policy master
MediaWiki 1.19+
Database changes Yes
License GNU General Public License 2.0 or later
Download
Hooks used
LoadExtensionSchemaUpdates
Translate the LDAP Authentication extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

The LdapAuthentication extension 1.1+ supports smartcard (SSL client) authentication in MediaWiki 1.6+. For those in a transitional period, the plugin supports a mixture of smartcard and password authentication if needed. This article will describe a few different ways to configure Apache, and a few different ways to configure the extension.

If you do not need LDAP support, and only need Smartcard/SSL authentication support, this is not the extension for you; please see the SSL Authentication extension.

Parts of this extension are based upon the work of the SSL Authentication extension and the Shibboleth Authentication extension.

What the extension does[edit]

The LDAP Authentication extension will do the following steps when using smartcard login:

  1. Apache verifies the smartcard is signed by a trusted CA, and pulls information from the card
  2. The LDAP extension gets the information about the card from Apache
  3. The LDAP extension then takes information from the card and searches the LDAP directory for the user, using proxy or anonymous credentials
  4. The LDAP extension gets the user entry, and uses an attribute from the entry to use as a MediaWiki username
  5. The extension then either pulls the user from the database and logs him/her in, or creates the user

When searching for the user, it is possible to add extra search string/attributes to ensure the user isn't disabled, or has any roles/attributes you require for the user to be logged in. It is also possible to check for group membership.

After the user is authenticated, it is possible to pull preference and other user/group information from LDAP. All features supported by password authentication should work for smartcard authentication.

General configuration[edit]

The Apache configuration will require mod_ssl or mod_nss. The LDAP extension configuration will require that you use a proxyagent and proxyagent password (anonymous searching is also supported). You cannot rely on user's credentials as the user never actually binds to the LDAP server.

For smartcard authentication to work at all, Apache must be setup to trust certain Certificate Authorities (CAs) for client authentication using the "SSLCACertificateFile" and "SSLCARevocationFile" directives. This may be a limiting factor if you are in a hosted environment as this can only be defined at the server or VirtualHost level.

Knowledge of how to setup https using mod_ssl/mod_nss is out of the scope of this document, and will be considered a prerequisite. Only directives that are smartcard specific will be discussed.

Apache configuration[edit]

In the below two Apache configurations, when a user accesses your wiki, they will automatically be logged in. With these configurations, you cannot mix password and smartcard authentication. The user will be required to have a smartcard.

Apache configuration for smartcard-protecting the entire server or virtual host[edit]

If your mod_ssl configuration is at the global or virtual host level, add the following directives after your other mod_ssl directives:

SSLVerifyClient require
SSLVerifyDepth 1

SSLRequireSSL
SSLCACertificateFile /path/to/CA.crt
SSLCARevocationFile  /path/to/CRLs.crl

Apache configuration for smartcard-protecting a wiki by directory[edit]

This will be *very* slow, as Apache will check the user's smartcard every time the user accesses any page below this location/directory. The following can be placed at the global, or virtual host level:

SSLCACertificateFile /path/to/CA.crt
SSLCARevocationFile  /path/to/CRLs.crl

<Directory "/path/to/wiki/">
    Options None
    AllowOverride None
    Order allow,deny
    Allow from all
    SSLRequireSSL
    SSLVerifyClient require
    SSLVerifyDepth 1
</Directory>

Apache configuration for allowing smartcard login without protecting an entire server, virtual host or wiki[edit]

The following configuration will only log a user in automatically when a user visits a wiki article called "Smartcard Login". This allows you to mix password authentication domains and a smartcard authentication domain, or allows you to allow smart card login to a specific wiki without the overhead of the Location/Directory approach above.

SSLCACertificateFile /path/to/CA.crt
SSLCARevocationFile  /path/to/CRLs.crl

<Location "/wiki/index.php/Smartcard_Login">
    SSLRequireSSL
    SSLVerifyClient require
    SSLVerifyDepth 10
</Location>

Basic LDAP extension configuration[edit]

The following example uses Active Directory.

require_once( "$IP/extensions/LdapAutoAuthentication.php" );
require_once( "$IP/extensions/LdapAuthentication.php" );

$wgLDAPDomainNames = array("exampleADDomain");
$wgLDAPServerNames = array("exampleADDomain"=>"example.adserver.com");

$wgLDAPAutoAuthDomain = "exampleADDomain";

$wgLDAPProxyAgent = array("exampleADDomain"=>"CN=proxy agent,OU=Domain_Users,DC=example,DC=com");
$wgLDAPProxyAgentPassword = array("exampleADDomain"=>"password");
$wgLDAPBaseDNs = array("exampleADDomain"=>"DC=example,DC=com");

$wgLDAPSearchAttributes = array("exampleADDomain"=>"userPrincipalName");

// We want to check to make sure the user isn't disabled.
$wgLDAPRequireAuthAttribute = array("exampleADDomain"=>true);

// The userAccountControl attribute has hex flags that specify information about a user's account
// a hex flag of 2 specifies the user's account is disabled.
$wgLDAPAuthAttribute = array("exampleADDomain"=>"!(userAccountControl:1.2.840.113556.1.4.803:=2)");

// This tells the plugin to use the CN field from the user's smartcard
// Munge this however needed to fit your situation; see:
//   http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#envvars
// For a list of environment variables to use
if (isset($_SERVER['SSL_CLIENT_S_DN_CN'])) {
        $wgLDAPAutoAuthUsername = $_SERVER['SSL_CLIENT_S_DN_CN'];
}

// This hook is called by the LdapAuthentication extension. It is a configuration hook. Here we
// are specifying what attribute we want to use for a username in the wiki.
// The hook calls the function defined below.
$wgHooks['SetUsernameAttributeFromLDAP'][] = 'SetUsernameAttribute';

// This function allows you to use another attribute from LDAP as the username.
function SetUsernameAttribute(&$LDAPUsername, $info) {
        //$info is the user's full entry, you can use any attribute or combination of attributes you like.
        //This is what the wiki will use as a username.
        $LDAPUsername = $info[0]['samaccountname'][0];
}

// After we set all configuration options, we want to tell the extension to use
// auto-authentication. This will create an instance of LdapAuthentication as $wgAuth
AutoAuthSetup();

Advanced LDAP extension configuration[edit]

The following will configure three domains: one domain pointing to openldap, another pointing to Active Directory, and a third using smartcard authentication pointing to the same Active directory.

The openldap domain will use straight binds, and the Active Directory domain will use proxy authentication.

This configuration requires SSLVerifyClient to be set in a location directive (the third apache setup above).

require_once( "$IP/extensions/LdapAutoAuthentication.php" );
require_once( "$IP/extensions/LdapAuthentication.php" );

$wgLDAPDomainNames = array("exampleOLDomain","exampleADDomain", "exampleADDomain-smartcard");
$wgLDAPServerNames = array("exampleOLDomain"=>"example.olserver.com", "exampleADDomain"=>"example.adserver.com", "exampleADDomain-smartcard"=>"example.adserver.com");

$wgLDAPSearchStrings = array("exampleOLDomain"=>"uid=USER-NAME,ou=people,dc=example,dc=oldomain,dc=com");

$wgLDAPAutoAuthDomain = "exampleADDomain-smartcard";

$wgLDAPProxyAgent = array("exampleADDomain"=>"CN=proxy agent,OU=Domain_Users,DC=example,DC=addomain,DC=com", "exampleADDomain-smartcard"=>"CN=proxy agent,OU=Domain_Users,DC=example,DC=addomain,DC=com");
$wgLDAPProxyAgentPassword = array("exampleADDomain"=>"password", "exampleADDomain-smartcard"=>"password");
$wgLDAPBaseDNs = array("exampleADDomain"=>"DC=example,DC=addomain,DC=com", "exampleADDomain-smartcard"=>"DC=example,DC=addomain,DC=com");

$wgLDAPSearchAttributes = array("exampleADDomain"=>"samaccountname", "exampleADDomain-smartcard"=>"userPrincipalName");

// We want to check to make sure the user isn't disabled when using
// smartcard authentication.
$wgLDAPRequireAuthAttribute = array("exampleADDomain-smartcard"=>true);

// The userAccountControl attribute has hex flags that specify information about a user's account
// a hex flag of 2 specifies the user's account is disabled.
$wgLDAPAuthAttribute = array("exampleADDomain-smartcard"=>"!(userAccountControl:1.2.840.113556.1.4.803:=2)");

// This tells the plugin to use the CN field from the user's smartcard
// Munge this however needed to fit your situation; see:
//   http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#envvars
// For a list of environment variables to use
if (isset($_SERVER['SSL_CLIENT_S_DN_CN'])) {
        $wgLDAPAutoAuthUsername = $_SERVER['SSL_CLIENT_S_DN_CN'];
}

// This hook is called by the LdapAuthentication plugin. It is a configuration hook. Here we
// are specifying what attibute we want to use for a username in the wiki.
// The hook calls the function defined below.
$wgHooks['SetUsernameAttributeFromLDAP'][] = 'SetUsernameAttribute';

// This function allows you to use another attribute from LDAP as the username.
function SetUsernameAttribute(&$LDAPUsername, $info) {
        //$info is the user's full entry, you can use any attribute or combination of attributes you like.
        //This is what the wiki will use as a username.
        $LDAPUsername = $info[0]['samaccountname'][0];
}

// After we set all configuration options, we want to setup the SSL plugin. This will
// create an instance of LdapAuthentication as $wgAuth
AutoAuthSetup();

Configuration steps for article based smartcard login[edit]

  1. Create an article called "Smartcard Login"
    1. Add "#REDIRECT [[Main Page]]"
    2. Protect the article
  2. Edit loginprompt in Special:Allmessages and add:
    [[Smartcard Login|Click here to log in with your smartcard.]]