From 31f35c2d306b0eb8d038ea8674b0acf49eeb286f Mon Sep 17 00:00:00 2001 From: Guus der Kinderen Date: Fri, 14 Jul 2023 21:07:33 +0200 Subject: [PATCH] Documentation: add Custom Group Provider Guide --- .../implementing-groupprovider-guide.html | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 documentation/implementing-groupprovider-guide.html diff --git a/documentation/implementing-groupprovider-guide.html b/documentation/implementing-groupprovider-guide.html new file mode 100644 index 0000000000..cbef834e2d --- /dev/null +++ b/documentation/implementing-groupprovider-guide.html @@ -0,0 +1,176 @@ + + + + Openfire: Custom Group Provider Guide + + + + +
+ +
+ Openfire Logo +

Custom Group Provider Guide

+
+ + + +
+ +

Introduction

+ +

+ This is a guide for developers that wish to integrate Openfire with their own group system. +

+ + + +

+ This integration requires some Java knowledge in order to implement a custom group 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 group data in its own database tables. Various + alternatives to this are offered that allow you to use groups defined in Active Directory or LDAP + or obtaining groups 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 GroupProvider extension point

+ +

+ Openfire's API defines the GroupProvider + interface, which is the extension point to use when implementing custom group functionality. It is noteworthy + that many implementations choose to inherit from + AbstractGroupProvider. This + abstract class provides common functionality typically used by implementations. You are, of course, free to + write your own implementation that does not extend on AbstractGroupProvider! +

+

+ The default implementation of this provider is the DefaultGroupProvider, which as the name + suggests is the version of this provider Openfire will use if not overridden. It uses the + ofGroup, ofGroupUser and ofGroupProp database tables. +

+

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

+
    +
  1. + Write a class that implements GroupProvider, 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.group.className to be the full name of your class, e.g. + org.example.CustomGroupProvider. 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>
+    <group>
+        <className>org.example.CustomGroupProvider</className>
+    </group>
+</provider>
    +
    +
    4. +
  4. + Restart Openfire. Your custom class should now be providing user groups to Openfire. +
    5. +
+ +
+ +
+ +

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 group functionaliy makes use of the GroupProvider 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. +

+
    +
  • org.jivesoftware.openfire.group.DefaultGroupProvider - used as the default provider.
    • +
  • org.jivesoftware.openfire.group.JDBCGroupProvider - integrates with a custom database.
    • +
  • org.jivesoftware.openfire.ldap.LdapGroupProvider - used when Openfire is configured to integrate with Active Directory or LDAP.
    • +
+

+ 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 GroupProvider?

+

+ 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. +

+ +
+ + + +
+ + +