Wiki source code of Authentication
Version 14.1 by Thomas Mortagne on 2008/03/07
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 which. This will probably be improved in the future.") | ||
| 9 | |||
| 10 | 1.1 Form Authentication | ||
| 11 | |||
| 12 | TODO | ||
| 13 | |||
| 14 | 1.1 LDAP Authentication | ||
| 15 | #warning("New experimental service since XWiki Platform 1.3M2, see [previous LDAP authentication service documentation>AuthenticationLdapOld]") | ||
| 16 | |||
| 17 | 1.1.1 Generic LDAP configuration | ||
| 18 | |||
| 19 | In order to enable the LDAP support you have to change the authentication method in ~~WEB-INF/xwiki.cfg~~ as follows: | ||
| 20 | {code} | ||
| 21 | ## Turn LDAP authentication on - otherwise only XWiki authentication | ||
| 22 | ## 0 : disable | ||
| 23 | ## 1 : enable | ||
| 24 | xwiki.authentication.ldap=1 | ||
| 25 | |||
| 26 | ## set LDAP as authentication service | ||
| 27 | xwiki.authentication.ldap.authclass=com.xpn.xwiki.ldap.authentication.XWikiLDAPAuthServiceImpl | ||
| 28 | {code} | ||
| 29 | |||
| 30 | You can setup the LDAP configuration in the ~~xwiki.cfg~~ file by filling the following properties: | ||
| 31 | |||
| 32 | {code:none} | ||
| 33 | ## LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.) | ||
| 34 | xwiki.authentication.ldap.server=156.58.101.204 | ||
| 35 | xwiki.authentication.ldap.port=389 | ||
| 36 | |||
| 37 | ## LDAP login, empty = anonymous access, otherwise specify full dn | ||
| 38 | ## {0} is replaced with the username, {1} with the password | ||
| 39 | xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP | ||
| 40 | xwiki.authentication.ldap.bind_pass={1} | ||
| 41 | |||
| 42 | #-# Force to check password after LDAP connection | ||
| 43 | #-# 0: disable | ||
| 44 | #-# 1: enable | ||
| 45 | xwiki.authentication.ldap.validate_password=0 | ||
| 46 | |||
| 47 | ## only members of the following group will be verified in the LDAP | ||
| 48 | ## otherwise only users that are found after searching starting from the base_DN | ||
| 49 | xwiki.authentication.ldap.user_group=cn=developers,ou=groups,o=MegaNova,c=US | ||
| 50 | |||
| 51 | ## base DN for searches | ||
| 52 | xwiki.authentication.ldap.base_DN= | ||
| 53 | department=USER,department=INFORMATIK,department=1230,o=MP | ||
| 54 | |||
| 55 | ## specifies the LDAP attribute containing the identifier to be used as the XWiki name (default=cn) | ||
| 56 | xwiki.authentication.ldap.UID_attr=cn | ||
| 57 | |||
| 58 | ## retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute) | ||
| 59 | xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,fullname=fullName,email=mail,ldap_dn=dn | ||
| 60 | |||
| 61 | # on every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki account is created. | ||
| 62 | xwiki.authentication.ldap.update_user=1 | ||
| 63 | |||
| 64 | ## maps XWiki groups to LDAP groups, separator is "|" | ||
| 65 | xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=MegaNova,c=US|\ | ||
| 66 | XWiki.Organisation=cn=testers,ou=groups,o=MegaNova,c=US | ||
| 67 | |||
| 68 | ## time in seconds after which the list of members in a group is refreshed from LDAP (default=3600*6) | ||
| 69 | xwiki.authentication.ldap.groupcache_expiration=21800 | ||
| 70 | |||
| 71 | ## - create : synchronize group membership only when the user is first created | ||
| 72 | ## - always: synchronize on every login | ||
| 73 | xwiki.authentication.ldap.mode_group_sync=always | ||
| 74 | |||
| 75 | ## if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials | ||
| 76 | xwiki.authentication.ldap.trylocal=1 | ||
| 77 | |||
| 78 | ## SSL connection to LDAP server | ||
| 79 | ## 0 : normal | ||
| 80 | ## 1 : SSL | ||
| 81 | xwiki.authentication.ldap.ssl=1 | ||
| 82 | |||
| 83 | ## The keystore file to use in SSL connection | ||
| 84 | xwiki.authentication.ldap.ssl.keystore= | ||
| 85 | {code} | ||
| 86 | |||
| 87 | #info("You can also setup the LDAP configuration in XWiki.XWikiPreferences page by going to the class editor and adding the following fields: | ||
| 88 | * ldap | ||
| 89 | * ldap_server | ||
| 90 | * ldap_port | ||
| 91 | * ldap_check_level | ||
| 92 | * ldap_base_DN | ||
| 93 | * ldap_bind_DN | ||
| 94 | * ldap_bind_pass | ||
| 95 | * ldap_validate_password | ||
| 96 | * ldap_UID_attr | ||
| 97 | * ldap_fields_mapping | ||
| 98 | * ldap_update_user | ||
| 99 | * ldap_group_mapping | ||
| 100 | * ldap_groupcache_expiration | ||
| 101 | * ldap_mode_group_sync | ||
| 102 | * ldap_trylocal | ||
| 103 | * ldap_ssl | ||
| 104 | * ldap_ssl.keystore") | ||
| 105 | |||
| 106 | 1.1.1 LDAP Configuration for Active Directory | ||
| 107 | |||
| 108 | Here are values of the properties you need to set if your LDAP server implementation is Miscrosoft Active Directory: | ||
| 109 | - *ldap_server*: name/IP of AD server machine | ||
| 110 | - *ldap_port*: port ~~(e.g. 389)~~ | ||
| 111 | - *ldap_check_level*: 1 | ||
| 112 | - *ldap_base_DN*: name of root DN ~~(e.g. dc=ad,dc=company,dc=com)~~ | ||
| 113 | - *ldap_bind_DN*: domain\{0\} ~~(e.g. ad\{0\} where \{0\} will be replaced by username during validation)~~ | ||
| 114 | - *ldap_bind_pass*: \{1\} ~~(where \{1\} will be replaced by password during validation)~~ | ||
| 115 | - *ldap_UID_attr*: sAMAccountName | ||
| 116 | - *ldap_fields_mapping*: name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn | ||
| 117 | |||
| 118 | Example: | ||
| 119 | {code} | ||
| 120 | xwiki.authentication.ldap=1 | ||
| 121 | xwiki.authentication.ldap.authclass=com.xpn.xwiki.user.impl.LDAP.LDAPAuthServiceImpl | ||
| 122 | xwiki.authentication.ldap.server=adserver | ||
| 123 | xwiki.authentication.ldap.check_level=1 | ||
| 124 | xwiki.authentication.ldap.port=389 | ||
| 125 | xwiki.authentication.ldap.base_DN=dc=subdomain,dc=domain,dc=suffix | ||
| 126 | xwiki.authentication.ldap.bind_DN=subdomain\\{0} | ||
| 127 | xwiki.authentication.ldap.bind_pass={1} | ||
| 128 | xwiki.authentication.ldap.UID_attr=sAMAccountName | ||
| 129 | xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn | ||
| 130 | {code} | ||
| 131 | |||
| 132 | 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. | ||
| 133 | |||
| 134 | |||
| 135 | 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. | ||
| 136 | |||
| 137 | 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. | ||
| 138 | |||
| 139 | This java client, [LDAP Browser/Editor > http://www-unix.mcs.anl.gov/~gawor/ldap/] is a handy tool for checking your configuration. | ||
| 140 | |||
| 141 | |||
| 142 | |||
| 143 | |||
| 144 | 1.1 eXo Authentication | ||
| 145 | |||
| 146 | The eXo authentication is used automatically by adding/editing the ~~xwiki.exo=1~~ property in ~~WEB-INF/xwiki.cfg~~. | ||
| 147 | |||
| 148 | 1.1 Custom Authentication | ||
| 149 | |||
| 150 | This allows plugging to any existing authentication mechanism such as SiteMinder, etc. To configure a custom authentication do the following: | ||
| 151 | # Implement the XWikiAuthService interface. | ||
| 152 | # Edit the ~~WEB-INF/xwiki.cfg~~ file and add a ~~xwiki.authentication.authclass~~ property pointing to your class. For example: | ||
| 153 | |||
| 154 | {code} | ||
| 155 | xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService | ||
| 156 | {code} | ||
| 157 | |||
| 158 | Note, that you also can implement own right management service by implementing XWikiRightService interface: | ||
| 159 | {code} | ||
| 160 | xwiki.authentication.rightsclass = com.acme.MyCustomRightsService | ||
| 161 | {code} | ||
| 162 | |||
| 163 | and group service by implementing XWikiGroupService and setting ~~xwiki.authentication.groupclass~~ property. | ||
| 164 | |||
| 165 | |||
| 166 | |||
| 167 | |||
| 168 | |||
| 169 | 1.1 Authentication parameters | ||
| 170 | |||
| 171 | You can set each of these parameters by setting: | ||
| 172 | |||
| 173 | {code} | ||
| 174 | xwiki.authentication.~~param_name~~=~~param_value~~ | ||
| 175 | {code} | ||
| 176 | |||
| 177 | {table} | ||
| 178 | Name | Optional | Allowed values | Default value | Description | ||
| 179 | 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. | ||
| 180 | 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. | ||
| 181 | 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 | ||
| 182 | cookielife | Yes | Number | 14 | Number of days cookies take to expire | ||
| 183 | 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~~ | ||
| 184 | default_page | Yes | String | /bin/view/ Main/WebHome | Page to redirect to if xredirect parameter is not set | ||
| 185 | encryptionalgorithm | Yes | ? | ? | Set the Encryption Algorithm used to encrypt and decrypt cookies | ||
| 186 | encryptionmode | Yes | ? | ? | Set the Encryption Mode used to encrypt and decrypt cookies | ||
| 187 | encryptionpadding | Yes | ? | ? | Set the Encryption Padding used to encrypt and decrypt cookies | ||
| 188 | errorpage | Yes | String | /bin/loginerror/ XWiki/XWikiLogin | Page to redirect to if there is an error logging in | ||
| 189 | loginpage | Yes | String | /bin/login/ XWiki/XWikiLogin | Page to redirect to when not logged in | ||
| 190 | loginsubmitpage | Yes | String | /loginsubmit/ XWiki/XWikiLogin | ? | ||
| 191 | logoutpage | Yes | String | /bin/logout/ XWiki/XWikiLogout | Page to redirect to after logged out | ||
| 192 | realname | Yes | String | XWiki | Sets the realm name (should be ~~realmname~~???) | ||
| 193 | protection | Yes | all, validation, encryption, none | all | Protection level for the "remember me" cookie functionality | ||
| 194 | unauthorized_code | Yes | ? | ? | ? | ||
| 195 | 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. | ||
| 196 | {table} | ||
| 197 | # Only required if protection = encryption or all (default) | ||
| 198 | # Only required if protection = validation or all (default) |
