Wiki source code of Authentication
Version 28.1 by Vincent Massol on 2009/05/18
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 1 User Authentication | ||
| 2 | |||
| 3 | XWiki supports several different authentication mechanisms for authenticating users: | ||
| 4 | #toc("" "" "") | ||
| 5 | |||
| 6 | The form authentication is the default mechanism. | ||
| 7 | |||
| 8 | #info("Note that currently XWiki allows only one method of authentication to be enabled at a time. This will probably be improved in the future.") | ||
| 9 | |||
| 10 | 1.1 Form Authentication | ||
| 11 | |||
| 12 | TODO | ||
| 13 | |||
| 14 | 1.1 LDAP Authentication | ||
| 15 | |||
| 16 | #warning("New LDAP implementation since XWiki Platform 1.3M2, see [previous LDAP authentication service documentation>AuthenticationLdapOld]") | ||
| 17 | |||
| 18 | 1.1.1 Generic LDAP configuration | ||
| 19 | |||
| 20 | In order to enable the LDAP support you have to change the authentication method in ~~WEB-INF/xwiki.cfg~~ as follows: | ||
| 21 | {code} | ||
| 22 | ## Turn LDAP authentication on - otherwise only XWiki authentication | ||
| 23 | ## 0 : disable | ||
| 24 | ## 1 : enable | ||
| 25 | xwiki.authentication.ldap=1 | ||
| 26 | |||
| 27 | ## set LDAP as authentication service | ||
| 28 | xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl | ||
| 29 | |||
| 30 | {code} | ||
| 31 | |||
| 32 | You can setup the LDAP configuration in the ~~xwiki.cfg~~ file by filling the following properties: | ||
| 33 | |||
| 34 | {code:none} | ||
| 35 | ## LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.) | ||
| 36 | xwiki.authentication.ldap.server=156.58.101.204 | ||
| 37 | xwiki.authentication.ldap.port=389 | ||
| 38 | |||
| 39 | ## LDAP login, empty = anonymous access, otherwise specify full dn | ||
| 40 | ## {0} is replaced with the username, {1} with the password | ||
| 41 | xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP | ||
| 42 | xwiki.authentication.ldap.bind_pass={1} | ||
| 43 | |||
| 44 | ## Force to check password after LDAP connection | ||
| 45 | ## 0: disable | ||
| 46 | ## 1: enable | ||
| 47 | xwiki.authentication.ldap.validate_password=0 | ||
| 48 | |||
| 49 | ## only members of the following group will be verified in the LDAP | ||
| 50 | ## otherwise only users that are found after searching starting from the base_DN | ||
| 51 | xwiki.authentication.ldap.user_group=cn=developers,ou=groups,o=MegaNova,c=US | ||
| 52 | |||
| 53 | ## only users not member of the following group can autheticate | ||
| 54 | xwiki.authentication.ldap.exclude_group=cn=admin,ou=groups,o=MegaNova,c=US | ||
| 55 | |||
| 56 | ## base DN for searches | ||
| 57 | xwiki.authentication.ldap.base_DN= | ||
| 58 | department=USER,department=INFORMATIK,department=1230,o=MP | ||
| 59 | |||
| 60 | ## specifies the LDAP attribute containing the identifier to be used as the XWiki name (default=cn) | ||
| 61 | xwiki.authentication.ldap.UID_attr=cn | ||
| 62 | |||
| 63 | ## retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute) | ||
| 64 | xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,fullname=fullName,email=mail | ||
| 65 | |||
| 66 | # on every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki account is created. | ||
| 67 | xwiki.authentication.ldap.update_user=1 | ||
| 68 | |||
| 69 | ## maps XWiki groups to LDAP groups, separator is "|" | ||
| 70 | xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=MegaNova,c=US|\ | ||
| 71 | XWiki.Organisation=cn=testers,ou=groups,o=MegaNova,c=US | ||
| 72 | |||
| 73 | ## time in seconds after which the list of members in a group is refreshed from LDAP (default=3600*6) | ||
| 74 | xwiki.authentication.ldap.groupcache_expiration=21800 | ||
| 75 | |||
| 76 | ## - create : synchronize group membership only when the user is first created | ||
| 77 | ## - always: synchronize on every login | ||
| 78 | xwiki.authentication.ldap.mode_group_sync=always | ||
| 79 | |||
| 80 | ## if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials | ||
| 81 | xwiki.authentication.ldap.trylocal=1 | ||
| 82 | |||
| 83 | ## SSL connection to LDAP server | ||
| 84 | ## 0 : normal | ||
| 85 | ## 1 : SSL | ||
| 86 | xwiki.authentication.ldap.ssl=1 | ||
| 87 | |||
| 88 | ## The keystore file to use in SSL connection | ||
| 89 | xwiki.authentication.ldap.ssl.keystore= | ||
| 90 | {code} | ||
| 91 | |||
| 92 | #info("You can also setup the LDAP configuration in XWiki.XWikiPreferences page by going to the object editor. Simply replace \"xwiki.authentication.ldap.\" by \"ldap_\". For example <tt>xwiki.authentication.ldap.base_DN</tt> become <tt>ldap_base_DN</tt>") | ||
| 93 | |||
| 94 | 1.1.1 LDAP Configuration for Active Directory | ||
| 95 | |||
| 96 | Here are values of the properties you need to set if your LDAP server implementation is Miscrosoft Active Directory: | ||
| 97 | - *ldap_server*: name/IP of AD server machine | ||
| 98 | - *ldap_port*: port ~~(e.g. 389)~~ | ||
| 99 | - *ldap_base_DN*: name of root DN ~~(e.g. dc=ad,dc=company,dc=com)~~ | ||
| 100 | - *ldap_bind_DN*: domain\{0\} ~~(e.g. ad\{0\} where \{0\} will be replaced by username during validation)~~ | ||
| 101 | - *ldap_bind_pass*: \{1\} ~~(where \{1\} will be replaced by password during validation)~~ | ||
| 102 | - *ldap_UID_attr*: sAMAccountName | ||
| 103 | - *ldap_fields_mapping*: name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn | ||
| 104 | |||
| 105 | Example: | ||
| 106 | {code} | ||
| 107 | xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl | ||
| 108 | xwiki.authentication.ldap=1 | ||
| 109 | xwiki.authentication.ldap.server=adserver | ||
| 110 | xwiki.authentication.ldap.port=389 | ||
| 111 | xwiki.authentication.ldap.base_DN=dc=subdomain,dc=domain,dc=suffix | ||
| 112 | xwiki.authentication.ldap.bind_DN=subdomain\\{0} | ||
| 113 | xwiki.authentication.ldap.bind_pass={1} | ||
| 114 | xwiki.authentication.ldap.UID_attr=sAMAccountName | ||
| 115 | xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn | ||
| 116 | {code} | ||
| 117 | |||
| 118 | The bind_DN and bind_pass fields contain the username and password for binding to the LDAP server in order to search, which will not necessarily be the same credentials as the user logging in. | ||
| 119 | |||
| 120 | |||
| 121 | The exact details of this configuration will vary based on your server configuration. It may not be necessary to prefix the username (represented by {0}) with the subdomain. | ||
| 122 | |||
| 123 | For testing purposes, you may wish to omit the "ldap.fields_mapping" field, to test the authentication first, and then add it later to get the mappings right. | ||
| 124 | |||
| 125 | This java client, [LDAP Browser/Editor > http://www-unix.mcs.anl.gov/~gawor/ldap/] is a handy tool for checking your configuration. | ||
| 126 | |||
| 127 | 1.1.1 Detailed use cases | ||
| 128 | |||
| 129 | See [LDAP configuration uses cases>LDAPAuthenticationUseCases] for some detailed use cases. | ||
| 130 | |||
| 131 | 1.1.1 Enable LDAP debug log | ||
| 132 | |||
| 133 | See [AdminGuide.Logging]. The specific targets for LDAP authentication are: | ||
| 134 | {code} | ||
| 135 | log4j.logger.com.xpn.xwiki.plugin.ldap=debug | ||
| 136 | log4j.logger.com.xpn.xwiki.user.impl.LDAP=debug | ||
| 137 | {code} | ||
| 138 | |||
| 139 | 1.1 eXo Authentication | ||
| 140 | |||
| 141 | The eXo authentication is used automatically by adding/editing the ~~xwiki.exo=1~~ property in ~~WEB-INF/xwiki.cfg~~. | ||
| 142 | |||
| 143 | 1.1 Custom Authentication | ||
| 144 | |||
| 145 | This allows plugging to any existing authentication mechanism such as SiteMinder, etc. To configure a custom authentication do the following: | ||
| 146 | # Implement the [XWikiAuthService>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiAuthService.java] interface. | ||
| 147 | # Edit the ~~WEB-INF/xwiki.cfg~~ file and add a ~~xwiki.authentication.authclass~~ property pointing to your class. For example: | ||
| 148 | |||
| 149 | {code} | ||
| 150 | xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService | ||
| 151 | {code} | ||
| 152 | |||
| 153 | Here's a [tutorial on implementing a custom authentication class for authenticating against Oracle's SSO>http://bodez.wordpress.com/2008/10/15/xwiki-user-authentication-with-oracle-sso/]. | ||
| 154 | |||
| 155 | Note, that you also can implement own right management service by implementing [XWikiRightService>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiRightService.java] interface: | ||
| 156 | {code} | ||
| 157 | xwiki.authentication.rightsclass = com.acme.MyCustomRightsService | ||
| 158 | {code} | ||
| 159 | |||
| 160 | and Group Service by implementing [XWikiGroupService>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiGroupService.java]: | ||
| 161 | |||
| 162 | {code} | ||
| 163 | xwiki.authentication.groupclass = com.acme.MyCustomGroupService | ||
| 164 | {code} | ||
| 165 | |||
| 166 | 1.1.1 Custom Authentication using a Groovy script in a wiki page | ||
| 167 | |||
| 168 | Start by specifying you want to use the Groovy Authenticator: | ||
| 169 | |||
| 170 | {code} | ||
| 171 | xwiki.authentication.authclass = com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl | ||
| 172 | {code} | ||
| 173 | |||
| 174 | Then add another configuration parameter to specify in which wiki page the authenticator is: | ||
| 175 | |||
| 176 | {code} | ||
| 177 | xwiki.authentication.groovy.pagename = MySpace.MyPage | ||
| 178 | {code} | ||
| 179 | |||
| 180 | Then in a wiki page put some Groovy code that returns a XWikiAuthService object. | ||
| 181 | |||
| 182 | 1.1 Authentication parameters | ||
| 183 | |||
| 184 | You can set each of these parameters by setting: | ||
| 185 | |||
| 186 | {code} | ||
| 187 | xwiki.authentication.~~param_name~~=~~param_value~~ | ||
| 188 | {code} | ||
| 189 | |||
| 190 | {table} | ||
| 191 | Name | Optional | Allowed values | Default value | Description | ||
| 192 | encryptionKey | No(1) | ? | n/a | Set the Encryption Key used to create a secret key, the secret key is passed to the Cipher object to be used during encryption and decryption of cookie values. | ||
| 193 | validationKey | No(2) | ? | n/a | Set the Validation Key used to generate hash value; the hash value is stored with the cookie and used to verify that the cookie has not been tampered with. | ||
| 194 | cookiedomains | Yes | String | Server host name | Which host(s) should your cookies be sent to; use only if you want to share cookies across domains, otherwise should be commented out | ||
| 195 | cookielife | Yes | Number | 14 | Number of days cookies take to expire | ||
| 196 | cookiepath | Yes | String | / | The webapp path that XWiki cookies should be sent to; if you have anything else running on your web server, this should be set to ~~/xwiki~~ | ||
| 197 | default_page | Yes | String | /bin/view/ Main/WebHome | Page to redirect to if xredirect parameter is not set | ||
| 198 | encryptionalgorithm | Yes | ? | ? | Set the Encryption Algorithm used to encrypt and decrypt cookies | ||
| 199 | encryptionmode | Yes | ? | ? | Set the Encryption Mode used to encrypt and decrypt cookies | ||
| 200 | encryptionpadding | Yes | ? | ? | Set the Encryption Padding used to encrypt and decrypt cookies | ||
| 201 | errorpage | Yes | String | /bin/loginerror/ XWiki/XWikiLogin | Page to redirect to if there is an error logging in | ||
| 202 | loginpage | Yes | String | /bin/login/ XWiki/XWikiLogin | Page to redirect to when not logged in | ||
| 203 | loginsubmitpage | Yes | String | /loginsubmit/ XWiki/XWikiLogin | ? | ||
| 204 | logoutpage | Yes | String | /bin/logout/ XWiki/XWikiLogout | Page to redirect to after logged out | ||
| 205 | realmname | Yes | String | XWiki | Sets the realm name | ||
| 206 | protection | Yes | all, validation, encryption, none | all | Protection level for the "remember me" cookie functionality | ||
| 207 | unauthorized_code | Yes | ? | ? | ? | ||
| 208 | useip | Yes | true / false | true | Specify to use the IP address when encrypting the cookie data; if IP address changes will need to re-login. | ||
| 209 | {table} | ||
| 210 | # Only required if protection = encryption or all (default) | ||
| 211 | # Only required if protection = validation or all (default) | ||
| 212 | |||
| 213 | 1.1 Kerberos SSO Authentication | ||
| 214 | |||
| 215 | #warning("This implementation of SSO is currently under review see: http://jira.xwiki.org/jira/browse/XWIKI-2496 . The class which is described in this segment of documentation, AppServerTrustedKerberosAuthServiceImpl, is not part of the default XWiki distribution!") | ||
| 216 | |||
| 217 | The following is an example of mod_auth_kerb for Apache being used to easily implement Xwiki authentication of users via by HTTP Negotiate on a linux server. This example assumes you already have a working Apache2 HTTPD and Apache Tomcat setup with mod_jk. | ||
| 218 | |||
| 219 | First of all you need to create a principal and keytab for the webserver: | ||
| 220 | {code} | ||
| 221 | # kadmin | ||
| 222 | kadmin> addprinc -randkey HTTP/wiki.example.com | ||
| 223 | kadmin> ktadd -k /etc/apache2/ssl/wiki.keytab HTTP/wiki.example.com | ||
| 224 | kadmin> quit | ||
| 225 | {code} | ||
| 226 | |||
| 227 | Make sure the keytab has the right permissions and ownership: | ||
| 228 | {code} | ||
| 229 | chown www-data:www-data /etc/apache2/ssl/wiki.keytab | ||
| 230 | chmod 400 /etc/apache2/ssl/wiki.keytab | ||
| 231 | {code} | ||
| 232 | |||
| 233 | Install mod_auth_kerb in your linux installation. On Debian or Ubuntu this would be achieved by running: | ||
| 234 | {code} | ||
| 235 | aptitude install libapache2-mod-auth-kerb | ||
| 236 | {code} | ||
| 237 | Of course the installation procedure varies per Linux distribution. | ||
| 238 | |||
| 239 | If your xwiki installation is mounted in Apache HTTPD under /xwiki, add the following to the virtual host configuration: | ||
| 240 | {code} | ||
| 241 | <Location /xwiki/> | ||
| 242 | AuthType Kerberos | ||
| 243 | AuthName "Kerberos Login" | ||
| 244 | KrbAuthRealms EXAMPLE.COM | ||
| 245 | Krb5Keytab "/etc/apache2/ssl/wiki.keytab" | ||
| 246 | KrbMethodK5Passwd off | ||
| 247 | KrbMethodNegotiate on | ||
| 248 | KrbSaveCredentials on | ||
| 249 | require valid-user | ||
| 250 | </Location> | ||
| 251 | {code} | ||
| 252 | |||
| 253 | Make sure Apache Tomcat uses the authentication performed by Apache HTTPD with the "tomcatAuthentication" property in the connector description (which is in the server.xml file of Apache Tomcat): | ||
| 254 | {code} | ||
| 255 | <Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3" /> | ||
| 256 | {code} | ||
| 257 | |||
| 258 | Place the authkerb.jar jar in the WEB-INF/lib directory of Xwiki in Apache Tomcat. | ||
| 259 | |||
| 260 | Have Xwiki use the authentication module by changing the "xwiki.authentication.authclass" property in WEB-INF/lib/xwiki.cfg file. | ||
| 261 | {code} | ||
| 262 | xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl | ||
| 263 | {code} | ||
| 264 | |||
| 265 | If you use Firefox, do not forget to whitelist the xwiki URL for HTTP Negotiate in about:config with the "network.negotiate-auth.trusted-uris" property. possible values for this propperty include (without the quotes): "https://" for all secured connections or "example.com" for all example.com subdomains. |
