Skip to content

Commit

Permalink
Documentation: add Custom Authentication Provider Guide
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@guusdk
guusdk committed Jul 14, 2023
1 parent 1e8332a commit dc193f9
Show file tree
Hide file tree
Showing 4 changed files with 214 additions and 31 deletions.
170 changes: 170 additions & 0 deletions documentation/implementing-authprovider-guide.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Openfire: Custom Authentication Provider Guide</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>

<article>

<header>
<img src="images/header_logo.gif" alt="Openfire Logo" />
<h1>Custom Authentication Provider Guide</h1>
</header>

<nav>
<a href="index.html">&laquo; Back to documentation index</a>
</nav>

<section id="intro">

<h2>Introduction</h2>

<p>
This document provides instructions on how to implement an integration between Openfire and an external
system that provides authentication functionality.
</p>
<p>
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.
</p>

<p>Topics that are covered in this document:</p>

<nav>
<ul>
<li><a href="#background">Background</a>
<li><a href="#authprovider">The AuthProvider extension point</a>
<li><a href="#faq">Frequently Asked Questions</a>
</ul>
</nav>

</section>

<section id="background">

<h2>Background</h2>

<p>
Under standard configuration, Openfire maintains authentication data in its own database tables. Various
alternatives to this are offered that allow you to <a href="ldap-guide.html">use Active Directory or LDAP for authentication</a>
or <a href="db-integration-guide.html#authentication-integration">integrating authentication with your custom database tables</a>.
</p>
<p>
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!
</p>
<p>
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).
</p>

</section>

<section id="authprovider">

<h2>The AuthProvider extension point</h2>

<p>
Openfire's API defines the <a href="javadoc/org/jivesoftware/openfire/auth/AuthProvider.html">AuthProvider</a>
interface, which is the extension point to use when implementing custom authentication functionality.
</p>
<p>
The default implementation of this provider is the <code>DefaultAuthProvider</code>, which as the name
suggests is the version of this provider Openfire will use if not overridden. It authenticates against the
<code>ofUser</code> database table and supports plain text and digest authentication.
</p>
<p>
The steps to get Openfire using a custom <code>AuthProvider</code> are described below.
</p>
<ol>
<li>
Write a class that implements <code>AuthProvider</code>, providing your own business logic.
</li>
<li>
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.
</li>
<li>
Set the property <code>provider.auth.className</code> to be the full name of your class, e.g.
<code>org.example.auth.MyAuthProvider</code>. You can easily do this by defining such a property in the
<code>conf/openfire.xml</code> configuration file, as shown below.
<fieldset>
<legend>Example openfire.xml configuration snippet</legend>
<pre><code>&lt;provider&gt;
&lt;auth&gt;
&lt;className&gt;org.example.auth.MyAuthProvider&lt;/className&gt;
&lt;/auth&gt;
&lt;/provider&gt;</code></pre>
</fieldset>
</li>
<li>
Restart Openfire. Your custom class should now be handling authentication.
</li>
</ol>

</section>

<section id="faq">

<h2>Frequently Asked Questions</h2>

<h4>Do I have to compile my custom class into the Openfire jar?</h4>
<p>
No, the class only needs to be visible on the Openfire classpath.
</p>

<h4>How do I ensure my custom class is visible on the Openfire classpath?</h4>
<p>
Just place your new custom library in the Openfire lib directory, this will ensure it is automatically
available at startup.
</p>

<h4>Can I see some examples?</h4>
<p>
Openfire's own authentication mechanism makes use of the <code>AuthProvider</code> 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.
</p>
<ul>
<li><code>org.jivesoftware.openfire.auth.DefaultAuthProvider</code> - used as the default provider.</li>
<li><code>org.jivesoftware.openfire.auth.JDBCAuthProvider</code> - integrates with a custom database.</li>
<li><code>org.jivesoftware.openfire.ldap.LdapAuthProvider</code> - used when Openfire is configured to integrate with Active Directory or LDAP.</li>
</ul>
<p>
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!
</p>

<h4>Will I have a degradation in performance using a custom AuthProvider?</h4>
<p>
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.
</p>

<h4>How can I have my custom class connect to another DB/Web service/NoSQL store etc?</h4>
<p>
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.
</p>

</section>

<footer>
<p>
An active support community for Openfire is available at
<a href="https://discourse.igniterealtime.org">https://discourse.igniterealtime.org</a>.
</p>
</footer>

</article>

</body>
</html>
38 changes: 25 additions & 13 deletions documentation/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,11 @@ <h3>Advanced Server Administration</h3>
<h3>Integration with External Data Sources</h3>

<dl>
<dt><a href="ldap-guide.html">LDAP Guide</a></dt>
<dd>A guide to setting up Openfire to work with LDAP user stores.</dd>
<dt><a href="ldap-guide.html">Active Directory and LDAP Integration Guide</a></dt>
<dd>A guide to setting up Openfire to work with Active Directory or LDAP user stores.</dd>

<dt><a href="db-integration-guide.html">Custom Database Integration Guide</a></dt>
<dd>A guide to integrating Openfire authentication, user, and group data with a custom database.</dd>

<dt><a href="pluggable-roster-support-guide.html">Pluggable Roster Support Guide</a></dt>
<dd>A guide to integrating Openfire rosters with an alternate store.</dd>
</dl>

</section>
Expand All @@ -87,7 +84,7 @@ <h3>Integration with External Data Sources</h3>

<h2>Developer Documentation</h2>

<h3>Basic Development Guides</h3>
<h3>Generic Development Guides</h3>

<dl>
<dt><a href="source-build.html">Building the Source</a></dt>
Expand All @@ -99,25 +96,40 @@ <h3>Basic Development Guides</h3>
<dt><a href="plugin-dev-guide.html">Plugin Developer Guide</a></dt>
<dd>A guide to writing and installing plugins for Openfire.</dd>

<dt><a href="translator-guide.html">Translator Guide</a></dt>
<dd>Information for those interested in translating the admin console of Openfire into other languages.</dd>

<dt><a href="overlay.html">Customization Guide</a></dt>
<dd>Instructions on customization support within the build process for Openfire.</dd>

<dt><a href="working-with-openfire.html">Tips &amp; tricks for working with Openfire</a></dt>
<dd>Some collected tools, tips and useful links.</dd>
</dl>

<h3>Advanced Development Guides</h3>
<h3>Data Provider / IAM Implementation Guides</h3>

<dl>
<dt><a href="translator-guide.html">Translator Guide</a></dt>
<dd>Information for those interested in translating the admin console of Openfire into other languages.</dd>

<dt><a href="overlay.html">Customization Guide</a></dt>
<dd>Instructions on customization support within the build process for Openfire.</dd>
<dt><a href="implementing-authprovider-guide.html">Custom Authentication Provider Guide</a></dt>
<dd>Describes how to integrate Openfire with an external authentication system.</dd>
</dl>
<dl>
<dt><a href="implementing-groupprovider-guide.html">Custom Group Provider Guide</a></dt>
<dd>Describes how to integrate Openfire with an external system that provides Group definitions.</dd>
</dl>
<dl>
<dt><a href="implementing-userprovider-guide.html">Custom User Provider Guide</a></dt>
<dd>Describes how to integrate Openfire with an external system that provides User definitions</dd>
</dl>
<dl>
<dt><a href="pluggable-roster-support-guide.html">Pluggable Roster Support Guide</a></dt>
<dd>A guide to integrating Openfire rosters with an alternate store.</dd>
</dl>

<h3>Reference Documentation</h3>

<dl>
<dt><a href="javadoc/index.html">JavaDocs</a></dt>
<dd>Openfire API documentation.</dt>
<dd>Openfire API documentation.</dd>

<dt><a href="protocol-support.html">Protocol Support</a></dt>
<dd>Provides details on the XMPP support and XEPs that Openfire implements.</dd>
Expand Down
4 changes: 2 additions & 2 deletions documentation/ldap-guide.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Openfire: LDAP Guide</title>
<title>Openfire: Active Directory and LDAP Integration Guide</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
Expand All @@ -10,7 +10,7 @@

<header>
<img src="images/header_logo.gif" alt="Openfire Logo" />
<h1>LDAP Guide</h1>
<h1>Active Directory and LDAP Integration Guide</h1>
</header>

<nav>
Expand Down
33 changes: 17 additions & 16 deletions documentation/pluggable-roster-support-guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,19 +26,10 @@ <h2>Introduction</h2>
with alternate sources of roster data rather than the provided database tables.
</p>
<p>
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.
</p>
<p>
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
<a href="implementing-authprovider-guide.html">custom AuthProvider approach</a> on which it is based.
</p>

<p>Topics that are covered in this document:</p>
Expand All @@ -58,9 +49,19 @@ <h2>Introduction</h2>
<h2>Background</h2>

<p>
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.
</p>
<p>
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.
</p>

</section>
Expand Down

0 comments on commit dc193f9

Please sign in to comment.