Wiki source code of Create a Custom Authenticator
Version 9.1 by Mohammad Humayun Khan on 2021/08/16
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | It is possible to plug to any existing authentication mechanism by providing a bridge for it. | ||
| 2 | |||
| 3 | To create a custom authentication do the following: | ||
| 4 | |||
| 5 | 1. Implement the {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/user/api/XWikiAuthService.java"}}XWikiAuthService{{/scm}} interface. It's recommended to extend the {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/user/impl/xwiki/XWikiAuthServiceImpl.java"}}XWikiAuthServiceImpl{{/scm}} class which is the default implementation(this is very useful if you want to reuse the standard login form, for example). | ||
| 6 | 1. Edit the //WEB-INF/xwiki.cfg// file and add a //xwiki.authentication.authclass// property pointing to your class. For example: | ||
| 7 | |||
| 8 | {{code language="properties"}} | ||
| 9 | xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService | ||
| 10 | {{/code}} | ||
| 11 | |||
| 12 | {{info}} | ||
| 13 | {{version since="13.3RC1"}} | ||
| 14 | To comply with the latest best practices, your custom authentication should trigger a {{scm path="xwiki-platform-core/xwiki-platform-security/xwiki-platform-security-authentication/xwiki-platform-security-authentication-api/src/main/java/org/xwiki/security/authentication/UserAuthenticatedEvent.java"}}UserAuthenticatedEvent{{/scm}} when it implements itself ##checkAuth(XWikiContext context)## (if your authenticator is reusing the standard login form this part is handled by XWiki). You can find implementation examples in {{code}}xwiki-platform-oldcore{{/code}} as {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/user/impl/xwiki/MyFormAuthenticator.java"}}MyFormAuthenticator{{/scm}} and {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/user/impl/xwiki/MyBasicAuthenticator.java"}}MyBasicAuthenticator{{/scm}}. Note that a {{scm path="xwiki-platform-core/xwiki-platform-security/xwiki-platform-security-authentication/xwiki-platform-security-authentication-api/src/main/java/org/xwiki/security/authentication/UserAuthenticatedEvent.java"}}UserAuthenticatedEvent{{/scm}} should be created with a {{scm path="xwiki-platform-core/xwiki-platform-user/xwiki-platform-user-api/src/main/java/org/xwiki/user/UserReference.java"}}UserReference{{/scm}}. | ||
| 15 | {{/version}} | ||
| 16 | {{/info}} | ||
| 17 | |||
| 18 | Here is an example code for a custom authenticator: | ||
| 19 | |||
| 20 | {{code language="java"}} | ||
| 21 | public class MyCustomAuthenticationService extends XWikiAuthServiceImpl | ||
| 22 | { | ||
| 23 | // We cannot use "real" component injection here because authenticators are not components currently | ||
| 24 | // But it's recommended to put most of your authenticator's actual code in a component (or several components) and use this component, | ||
| 25 | // it will make it a lot easier to reuse various XWiki tools and APIs | ||
| 26 | private MyCustomAuthentor authenticator; | ||
| 27 | |||
| 28 | // If you don't plan to reuse the standard XWiki login you should implement this method which is usually in charge of gathering the user credentials | ||
| 29 | // or other means of indicating what is the current user (HTTP headers, etc.) | ||
| 30 | @Override | ||
| 31 | public XWikiUser checkAuth(XWikiContext context) | ||
| 32 | { | ||
| 33 | // Call the actual authenticator | ||
| 34 | return this.authenticator.checkAuth(context); | ||
| 35 | } | ||
| 36 | |||
| 37 | // This is the method which will be called if you reuse the standard means of gathering the credentials (login page, BASIC auth) | ||
| 38 | // What's left on your side is to validate the credential and create/update the XWiki user profile (and eventually synchronize other user-related info like the groups, etc.) | ||
| 39 | @Override | ||
| 40 | public Principal authenticate(String username, String password, XWikiContext context) throws XWikiException | ||
| 41 | { | ||
| 42 | // Call the actual authenticator | ||
| 43 | return this.authenticator.checkAuth(context); | ||
| 44 | } | ||
| 45 | } | ||
| 46 | |||
| 47 | @Component(roles = MyCustomAuthenticator.class) | ||
| 48 | @Singleton | ||
| 49 | public MyCustomAuthenticator | ||
| 50 | { | ||
| 51 | @Inject | ||
| 52 | private ObservationManager observation; | ||
| 53 | |||
| 54 | public XWikiUser checkAuth(XWikiContext context) | ||
| 55 | { | ||
| 56 | // You authenticate a user somehow | ||
| 57 | ... | ||
| 58 | |||
| 59 | // Since 13.3, if this is a new authentication (the user was not already authenticated in this session) you should send a notification about that | ||
| 60 | if (newAuth) { | ||
| 61 | // You have to retrieve its UserReference | ||
| 62 | // You should be able to use a UserReferenceResolver if needed | ||
| 63 | UserReference userReference = ...; | ||
| 64 | |||
| 65 | // Then, trigger a UserAuthenticatedEvent by passing previously retrieved user reference to UserAuthenticatedEvent constructor | ||
| 66 | this.observationManager.notify(new UserAuthenticatedEvent(userReference), null); | ||
| 67 | } | ||
| 68 | } | ||
| 69 | |||
| 70 | public Principal authenticate(String username, String password, XWikiContext context) throws XWikiException | ||
| 71 | { | ||
| 72 | ... | ||
| 73 | } | ||
| 74 | } | ||
| 75 | {{/code}} | ||
| 76 | |||
| 77 | You can find various authenticators examples in [[extensions>>http://extensions.xwiki.org/xwiki/bin/view/Main/WebHome#|t=extensions&p=1&l=30&s=doc.creationDate&d=desc&name=authenticator]] or [[sandbox>>https://github.com/xwiki-contrib/sandbox/tree/master/authenticators]]. | ||
| 78 | |||
| 79 | 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/]]. |
