From b2f6fee77dc01e31aa46fc6cfc77d9ae86089ce4 Mon Sep 17 00:00:00 2001
From: Guus der Kinderen
Date: Fri, 14 Jul 2023 20:31:19 +0200
Subject: [PATCH] Documentation: add Custom Authentication Provider Guide
This commit also refactors the existing documentation a bit, renaming the LDAP guide to more explicitly mention Active Directory, and re-order the index page.
---
.../implementing-authprovider-guide.html | 185 ++++++++++++++++++
documentation/index.html | 38 ++--
documentation/ldap-guide.html | 4 +-
.../pluggable-roster-support-guide.html | 33 ++--
4 files changed, 229 insertions(+), 31 deletions(-)
create mode 100644 documentation/implementing-authprovider-guide.html
diff --git a/documentation/implementing-authprovider-guide.html b/documentation/implementing-authprovider-guide.html
new file mode 100644
index 0000000000..9e3ffbfa39
--- /dev/null
+++ b/documentation/implementing-authprovider-guide.html
@@ -0,0 +1,185 @@
+
+
+
+ Openfire: Custom Authentication Provider Guide
+
+
+
+
+
+
+
+
+
Custom Authentication Provider Guide
+
+
+
+
+
+
+
Introduction
+
+
+ This document provides instructions on how to implement an integration between Openfire and an external
+ system that provides authentication functionality.
+
+
+ This integration requires some Java knowledge in order to implement a custom authentication provider
+ for Openfire. The skill needed will vary depending on what you are trying to achieve.
+
+ 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!
+
+
+ It is good to realize that the provider architecture that is used in this guide is never used by end-user
+ clients directly. Instead, the implementation that you will create based on this guide is used by the
+ Openfire service itself. This service will use it to process client authentication requests (which typically
+ use a SASL mechanism). The implementation of custom SASL mechanisms is out of scope of for this guide).
+
+
+
+
+
+
+
The AuthProvider extension point
+
+
+ Openfire's API defines the AuthProvider
+ interface, which is the extension point to use when implementing custom authentication functionality.
+
+
+ The default implementation of this provider is the DefaultAuthProvider, which as the name
+ suggests is the version of this provider Openfire will use if not overridden. It authenticates against the
+ ofUser database table and supports plain text and digest authentication.
+
+
+ The steps to get Openfire using a custom AuthProvider are described below.
+
+
+
+ Write a class that implements AuthProvider, providing your own business logic.
+
+
+ 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.
+
+
+ Set the property provider.auth.className to be the full name of your class, e.g.
+ org.example.auth.MyAuthProvider. You can easily do this by defining such a property in the
+ conf/openfire.xml configuration file, as shown below.
+
+
+
+ Restart Openfire. Your custom class should now be handling authentication.
+
+
+
+ It is worth noting that the AuthProvider 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 hash/digest-based credentials.
+
+
+
+
+
+
+
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 authentication mechanism makes use of the AuthProvider 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.auth.DefaultAuthProvider - used as the default provider.
+
org.jivesoftware.openfire.auth.JDBCAuthProvider - integrates with a custom database.
+
org.jivesoftware.openfire.ldap.LdapAuthProvider - 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 AuthProvider?
+
+ 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.
+
- Consider the scenario where Openfire is integrated as the chat server solution for an existing
- 'social' application. In this application a user is linked to other users via a relationship
- of sorts, and the system of record for the relationship data is NOT the Openfire system.
- Using an XMPP server such as Openfire the applications benefit from the real-time nature of
- XMPP rosters and other subscription based features such as PEP, but with the caveat that
- the existing relationship information has to be duplicated in Openfire and could potentially
- become out of sync.
-
-
- With the introduction of pluggable roster providers, Openfire can be instructed to retrieve and
- modify roster data that lives in alternative locations to the standard database tables. The options
- are limitless as to what this could be, e.g. an alternative database table(s), a web service, a NoSQL
- database etc.
+ This integration requires some Java knowledge in order to implement a custom roster provider
+ for Openfire. The skill needed will vary depending on what you are trying to achieve.
+ The extension approach is similar to the
+ custom AuthProvider approach on which it is based.
Topics that are covered in this document:
@@ -58,9 +49,19 @@
Introduction
Background
- This integration requires some Java knowledge in order to implement a custom roster provider
- for Openfire. The skill needed will vary depending on what you are trying to achieve.
- The extension approach is similar to the custom AuthProvider approach on which it is based.
+ Consider the scenario where Openfire is integrated as the chat server solution for an existing
+ 'social' application. In this application a user is linked to other users via a relationship
+ of sorts, and the system of record for the relationship data is NOT the Openfire system.
+ Using an XMPP server such as Openfire the applications benefit from the real-time nature of
+ XMPP rosters and other subscription based features such as PEP, but with the caveat that
+ the existing relationship information has to be duplicated in Openfire and could potentially
+ become out of sync.
+
+
+ With the introduction of pluggable roster providers, Openfire can be instructed to retrieve and
+ modify roster data that lives in alternative locations to the standard database tables. The options
+ are limitless as to what this could be, e.g. an alternative database table(s), a web service, a NoSQL
+ database etc.