From dc193f97b78d3040e20c851e1df9bc5e54eace0e 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 | 170 ++++++++++++++++++ documentation/index.html | 38 ++-- documentation/ldap-guide.html | 4 +- .../pluggable-roster-support-guide.html | 33 ++-- 4 files changed, 214 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..bdcc78a715 --- /dev/null +++ b/documentation/implementing-authprovider-guide.html @@ -0,0 +1,170 @@ + + + + Openfire: Custom Authentication Provider Guide + + + + +
+ +
+ Openfire Logo +

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

+ +

Topics that are covered in this document:

+ + + +
+ +
+ +

Background

+ +

+ Under standard configuration, Openfire maintains authentication data in its own database tables. Various + alternatives to this are offered that allow you to use Active Directory or LDAP for authentication + or integrating authentication with your 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! +

+

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

+
    +
  1. + Write a class that implements AuthProvider, 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.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. +
    + Example openfire.xml configuration snippet + 
    <provider>
+    <auth>
+        <className>org.example.auth.MyAuthProvider</className>
+    </auth>
+</provider>
    +
    +
    4. +
  4. + Restart Openfire. Your custom class should now be handling authentication. +
    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 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. +

+ +
+ + + +
+ + + diff --git a/documentation/index.html b/documentation/index.html index 513aa2c86d..1d03bd3a94 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -71,14 +71,11 @@

Advanced Server Administration

Integration with External Data Sources

-
LDAP Guide
-
A guide to setting up Openfire to work with LDAP user stores.
+
Active Directory and LDAP Integration Guide
+
A guide to setting up Openfire to work with Active Directory or LDAP user stores.
Custom Database Integration Guide
A guide to integrating Openfire authentication, user, and group data with a custom database.
- -
Pluggable Roster Support Guide
-
A guide to integrating Openfire rosters with an alternate store.
@@ -87,7 +84,7 @@

Integration with External Data Sources

Developer Documentation

-

Basic Development Guides

+

Generic Development Guides

Building the Source
@@ -99,25 +96,40 @@

Basic Development Guides

Plugin Developer Guide
A guide to writing and installing plugins for Openfire.
+
Translator Guide
+
Information for those interested in translating the admin console of Openfire into other languages.
+ +
Customization Guide
+
Instructions on customization support within the build process for Openfire.
+
Tips & tricks for working with Openfire
Some collected tools, tips and useful links.
-

Advanced Development Guides

+

Data Provider / IAM Implementation Guides

-
Translator Guide
-
Information for those interested in translating the admin console of Openfire into other languages.
- -
Customization Guide
-
Instructions on customization support within the build process for Openfire.
+
Custom Authentication Provider Guide
+
Describes how to integrate Openfire with an external authentication system.
+
+
+
Custom Group Provider Guide
+
Describes how to integrate Openfire with an external system that provides Group definitions.
+
+
+
Custom User Provider Guide
+
Describes how to integrate Openfire with an external system that provides User definitions
+
+
+
Pluggable Roster Support Guide
+
A guide to integrating Openfire rosters with an alternate store.

Reference Documentation

JavaDocs
-
Openfire API documentation. +
Openfire API documentation.
Protocol Support
Provides details on the XMPP support and XEPs that Openfire implements.
diff --git a/documentation/ldap-guide.html b/documentation/ldap-guide.html index 7615ffd93c..a842c1929d 100644 --- a/documentation/ldap-guide.html +++ b/documentation/ldap-guide.html @@ -1,7 +1,7 @@ - Openfire: LDAP Guide + Openfire: Active Directory and LDAP Integration Guide @@ -10,7 +10,7 @@
Openfire Logo -

LDAP Guide

+

Active Directory and LDAP Integration Guide