Integrating with more than one External Data Source

Introduction

Openfire can be configured to use a variety of external sources for authentication, users and groups. This is useful when your users already have accounts in an external system, and you do not wish to duplicate those accounts. More information on this subject is available in the Custom Database Integration Guide, as well as the LDAP guide. You can even develop your own, custom connectivity to external data sources, as described in the Custom User Provider Guide, Custom Authentication Provider Guide and Custom Group Provider Guide.

This document takes the concept one step further, and provides instructions on how to configure Openfire to obtain its users from multiple backend systems.

Topics that are covered in this document:

Mapped Providers

A Mapped Provider is a provider that based on a particular characteristic of a user, uses a different provider to perform the actual operations.

Openfire provides mapped providers for the following types of data:

Authentication

org.jivesoftware.openfire.auth.MappedAuthProvider

Users

org.jivesoftware.openfire.user.MappedUserProvider

Groups

org.jivesoftware.openfire.group.MappedGroupProvider

User Properties

org.jivesoftware.openfire.user.property.MappedUserPropertyProvider

A Mapped Provider is configured with a Mapper. The Mapper will determine which secondary provider to use for a particular user. Openfire provides the following types of Mappers:

• Authorization Based Mapper -- to draw administrative users from another source than the regular, non-administrative users.
• Property Based Mapper -- uses Openfire system properties (that hold a list of usernames) to relate specific users to specific providers.

For each type of data, these Mappers are available

Example Configuration

An elaborate example, including configuration examples, of how Mapped Providers can be used is provided in the Separating Administrative Users Guide. This is a guide to setting up Openfire to work with different user stores for admins and non-administrative users, by utilizing Mapped Providers.

Hybrid Providers

The Hybrid variant of the providers iterates over its backing providers, operating on the first applicable instance.

Openfire provides hybrid providers for the following types of data:

Authentication

org.jivesoftware.openfire.auth.HybridAuthProvider

Users

org.jivesoftware.openfire.user.HybridUserProvider

Groups

org.jivesoftware.openfire.group.HybridGroupProvider

User Properties

org.jivesoftware.openfire.user.property.HybridUserPropertyProvider

Each Hybrid provider is configured to use up to three backing providers. These are configured through properties like these for the HybridAuthProvider:

• hybridAuthProvider.primaryProvider.className
• hybridAuthProvider.secondaryProvider.className
• hybridAuthProvider.tertiaryProvider.className

The property value for each of these will be the canoncial class name of the desired backing provider. Please refer to the documentation of each Hybrid provider for the names of the properties used by that provider.

Example Configuration

Below is a sample config file section that illustrates the usage of Hybrid providers. For brevity, this example is limited to User and Auth providers (note: the "..." sections in the examples indicate areas where the rest of the config file would exist).

First, Openfire is configured to use the Hybrid providers:

<jive>
    ...
    <provider>
        <auth>
            <className>org.jivesoftware.openfire.auth.HybridAuthProvider</className>
        </auth>
        <user>
            <className>org.jivesoftware.openfire.user.HybridUserProvider</className>
        </user>
    </provider>
    ...
</jive>

Next, each Hybrid provider is configured with a set of providers to use to interact with data stores. In the example below, both an LDAP store and the default Openfire data stores are used.

<jive>
    ...
    <hybridAuthProvider>
        <primaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapAuthProvider</className>
        </primaryProvider>
        <secondaryProvider>
            <className>org.jivesoftware.openfire.auth.DefaultAuthProvider</className>
        </secondaryProvider>
    </hybridAuthProvider>

    <hybridUserProvider>
        <primaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapUserProvider</className>
        </primaryProvider>
        <secondaryProvider>
            <className>org.jivesoftware.openfire.user.DefaultUserProvider</className>
        </secondaryProvider>
    </hybridUserProvider>
    ...
</jive>

The above completes the configuration of the Hybrid providers. When backing providers require additional configuration, that should be added too. Shown below is the LDAP connection configuration which will be used by the LDAP user and auth Provider. For good measure, a commonly-used property is used that defines what usernames are considered to be administrators.

<jive>
    ...
    <ldap>
        <host>localhost</host>
        <port>389</port>
        <baseDN>ou=people,dc=springfield,dc=com</baseDN>
        <adminDN>cn=admin,dc=springfield,dc=com</adminDN>
        <adminPassword>Anytown</adminPassword>
        <startTlsEnabled>false</startTlsEnabled>
        <sslEnabled>false</sslEnabled>
    </ldap>

    <admin>
        <authorizedUsernames>bart</authorizedUsernames>
    </admin>
    ...
</jive>

Using more than one provider of the same type

The example above shows how a Hybrid provider is used to delegate access to two data stores of different types: an LDAP store, and Openfire's own store. What if you'd like to use two LDAP services, each on a separate host?

In the configuration example above, both the LdapAuthProvider and LdapUserProvider use the same LDAP connectivity configuration. All LDAP providers by default will use LDAP connectivity configuration as defined in the ldap properties. How can you configure multiple LDAP providers that each connect to a different LDAP host?

The configuration of each backing provider configured in a Hybrid provider can include an optional config element. This element is used to point at the property that holds the connection configuration for the provider.

In the example below, Hybrid providers are configured for both Auth and Users. Each Hybrid provider is configured to use two backing providers, that are both LDAP-based. Note how for each provider, a config value is provided that refers to another property, in which the LDAP connection information that's applicable to that provider is defined.

<jive>
    ...
    <provider>
        <auth>
            <className>org.jivesoftware.openfire.auth.HybridAuthProvider</className>
        </auth>
        <user>
            <className>org.jivesoftware.openfire.user.HybridUserProvider</className>
        </user>
    </provider>

    <hybridAuthProvider>
        <primaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapAuthProvider</className>
            <config>ldapPrimary</config>
        </primaryProvider>
        <secondaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapAuthProvider</className>
            <config>ldapSecondary</config>
        </secondaryProvider>
    </hybridAuthProvider>

    <hybridUserProvider>
        <primaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapUserProvider</className>
            <config>ldapPrimary</config>
        </primaryProvider>
        <secondaryProvider>
            <className>org.jivesoftware.openfire.ldap.LdapUserProvider</className>
            <config>ldapSecondary</config>
        </secondaryProvider>
    </hybridUserProvider>

    <ldapPrimary>
        <host>dc.springfield.com</host>
        <port>10389</port>
        <baseDN>dc=springfield,dc=com</baseDN>
        <adminDN>cn=admin,dc=springfield,dc=com</adminDN>
        <adminPassword>Anytown</adminPassword>
        <startTlsEnabled>false</startTlsEnabled>
        <sslEnabled>false</sslEnabled>
    </ldapPrimary>

    <ldapSecondary>
        <host>ldap.planetexpress.com</host>
        <port>389</port>
        <baseDN>ou=people,dc=planetexpress,dc=com</baseDN>
        <adminDN>cn=admin,dc=planetexpress,dc=com</adminDN>
        <adminPassword>GoodNewsEveryone</adminPassword>
        <startTlsEnabled>false</startTlsEnabled>
        <sslEnabled>false</sslEnabled>
        <groupSearchFilter>(objectClass=Group)</groupSearchFilter>
    </ldapSecondary>
    ...
</jive>

Frequently Asked Questions

Can I add my own Mapper?

Absolutely. You can implement your custom implementation and place the new custom library in the Openfire lib directory. This will ensure it is automatically available at startup. You can then reference it in Openfire's configuration by its canonical class name.

Can I use my custom auth/user/group provider in a Mapped or Hybrid provider?

Yes! If you've implemented custom code (as described in the Custom User Provider Guide, Custom Authentication Provider Guide and Custom Group Provider Guide) then you can use reference these implementations by their canonical class name in Openfire's configuration.