Extension:LDAP Authentication/Smartcard Configuration Examples

Back to the LDAP Authentication Documentation

Many organizations are moving towards using smartcards and LDAP as a Single Sign On solution. As organizations move to smartcard authentication, one stumbling block seems to be web applications.

The LdapAuthentication plugin 1.1+ supports smartcard authentication in MediaWiki 1.6+. For those in a transitionary 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 plugin.

If you do not need LDAP support, and only need Smartcard/SSL authentication support, this is not the plugin for you; please see the See also section instead.

This plugin is based upon the work of the SSL Authentication plugin and the Shibboleth Authentication plugin. Links to those plugins are in the See also section.

What the plugin does
The LDAP Authentication plugin 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 plugin gets the information about the card from Apache
 * 3) The LDAP plugin then takes information from the card and searches the LDAP directory for the user, using proxy or anonymous credentials
 * 4) The LDAP plugin gets the user entry, and uses an attribute from the entry to use as a MediaWiki username
 * 5) The plugin 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 setup
The Apache setup will require mod_ssl. The wiki setup 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 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 is out of the scope of this document, and will be considered a prerequisite. Only directives that are smartcard specific will be discussed.

Apache setup
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 setup for smartcard protecting the entire server or virtual host
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 setup for smartcard protecting a wiki by directory
This will most likely be *very* slow, as apache will check the user's smartcard every time the user accesses any wiki page. The following can be placed at the global, or virtual host level:

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

 Options None AllowOverride None Order allow,deny Allow from all SSLRequireSSL SSLVerifyClient require SSLVerifyDepth 1 

Apache setup for allowing smartcard login without protecting an entire server, virtual host or wiki
The following setup will only log a user in automatically when a user visits a wiki article called "Smartcard Login". This can allow you to mix password authentication domains and a smartcard authentication domain.

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

 SSLRequireSSL SSLVerifyClient require SSLVerifyDepth 10 

General MediaWiki configuration
The following example uses Active Directory.

require_once( 'extensions/LdapAuthentication.php' );

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

$wgLDAPUseSmartcardAuth = true; $wgLDAPSmartcardDomain = "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)");

//Munge this however needed. if (isset($_SERVER['SSL_CLIENT_S_DN_CN'])) { $wgLDAPSSLUsername = $_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 get the username from LDAP however you need to do it. function SetUsernameAttribute(&$LDAPUsername, $info) { //$info is the user's full entry, you can use any attribute or combination of attributes you like. //This is specifically what the wiki uses 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 SSLAuthSetup;

Advanced Mediawiki configuration
The following will set up 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( '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");

$wgLDAPUseSmartcardAuth = true; $wgLDAPSmartcardDomain = "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)");

//Munge this however needed. if (isset($_SERVER['SSL_CLIENT_S_DN_CN'])) { $wgLDAPSSLUsername = $_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 get the username from LDAP however you need to do it. function SetUsernameAttribute(&$LDAPUsername, $info) { //$info is the user's full entry, you can use any attribute or combination of attributes you like. //This is specifically what the wiki uses 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 SSLAuthSetup;

Configuration steps for article based smartcard login

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