diff --git a/documentation/implementing-userprovider-guide.html b/documentation/implementing-userprovider-guide.html new file mode 100644 index 0000000000..f10546f59e --- /dev/null +++ b/documentation/implementing-userprovider-guide.html @@ -0,0 +1,184 @@ + + + + Openfire: Custom User Provider Guide + + + + +
+ +
+ Openfire Logo +

Custom User Provider Guide

+
+ + + +
+ +

Introduction

+ +

+ This is a guide for developers that wish to integrate Openfire with an external system that provides user + definitions. +

+

+ Beware that this integration can be used to provision Openfire with user data, but critically, does not + implement authentication. For that, please refer to the + Custom Authentication Provider Guide. +

+

+ This integration requires some Java knowledge in order to implement a custom user provider + for Openfire. The skill needed will vary depending on what you are trying to achieve. +

+ +

Topics that are covered in this document:

+ + + +
+ +
+ +

Background

+ +

+ Under standard configuration, Openfire maintains user data in its own database tables. Various + alternatives to this are offered that allow you to use users defined in Active Directory or LDAP + or obtaining users from custom database tables. +

+

+ If you're interested in integrating with a system that is not compatible with the standard integration + options that are provided by Openfire, then you can implement a custom integration. This guide will help you + get started! +

+ +
+ +
+ +

The UserProvider extension point

+ +

+ Openfire's API defines the UserProvider + interface, which is the extension point to use when implementing custom user functionality. +

+

+ The default implementation of this provider is the DefaultUserProvider, which as the name + suggests is the version of this provider Openfire will use if not overridden. It uses the + ofUser, ofUserFlag and ofUserProp database tables. +

+

+ The steps to get Openfire using a custom UserProvider are described below. +

+
    +
  1. + Write a class that implements UserProvider, providing your own business logic. +
    2. +
  2. + Make the class available in a jar and make this available to Openfire by placing it in the lib directory. + There are numerous ways to package a jar with this class inside it, popular build systems such as Gradle and Maven + can make your life easier. +
    3. +
  3. + Set the property provider.user.className to be the full name of your class, e.g. + org.example.user.FooUserProvider. You can easily do this by defining such a property in the + conf/openfire.xml configuration file, as shown below. +
    + Example openfire.xml configuration snippet + 
    <provider>
+    <user>
+        <className>org.example.user.FooUserProvider</className>
+    </user>
+</provider>
    +
    +
    4. +
  4. + Restart Openfire. Your custom class should now be providing users to Openfire. +
    5. +
+

+ It is worth noting that the UserProvider interface defines an interface that can be used to + both read data from, but also write data back to the system that is being integrated with. If the system + that you're integrating with can not or must not have its user definitions changed, you can implement your + provider as being 'read-only'. +

+

+ To mark your provider as being read-only, implement the isReadOnly() method to return the value + true. All methods that would cause a change of data won't be invoked by Openfire if you do so. + These methods should receive an implementation that throws java.lang.UnsupportedOperationException. +

+

+ A similar approach (throwing java.lang.UnsupportedOperationException) can be used to prevent + implementing optional functionality, such as the support for search functionality. +

+ +
+ +
+ +

Frequently Asked Questions

+ +

Do I have to compile my custom class into the Openfire jar?

+

+ No, the class only needs to be visible on the Openfire classpath. +

+ +

How do I ensure my custom class is visible on the Openfire classpath?

+

+ Just place your new custom library in the Openfire lib directory, this will ensure it is automatically + available at startup. +

+ +

Can I see some examples?

+

+ Openfire's own user functionality makes use of the UserProvider API! If you want to get + some inspiration, you can have a look at the implementations of this interface that are part of Openfire, + such as the ones below. +

+ +

+ Note that these providers are but a sample of the available providers. Discover more providers by using your + IDE to find implementations of the interface! +

+ +

Will I have a degradation in performance using a custom UserProvider?

+

+ It completely depends on your implementation. As with any Openfire customisation or plugin, badly written + code has the potential to cause Openfire to perform slower. Use performance testing tools such as Tsung to + ensure issues haven't been introduced. +

+ +

How can I have my custom class connect to another DB/Web service/NoSQL store etc?

+

+ This is out of the scope of this documentation and is your choice as a developer. If you are looking to + externalize properties like connection details, the Openfire properties mechanism and the JiveGlobals class + are good places to start investigating. +

+ +
+ + + +
+ + +