com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring Secondary User Stores

Owned by Former user (Deleted)
Last updated: Dec 12, 2014
3 min read

The default configurations of WSO2 products have a single, embedded user store. If required, you can configure WSO2 products to connect to several secondary user stores as well. After configuration, users from different stores can log in and perform operations depending on their roles/permissions. You can also configure your own customized user stores and connect them with the products as secondary stores.

The topics below explain how to configure secondary user stores manually or using the management console: 

Tip: If you set up a database other than the default H2 that comes with the product to store user information, select the script relevant to your database type from the <APIM_HOME>/dbscripts folder and run it on your database. It creates the necessary tables.

Tip: If your setup has multiple product clusters such as the API Manager cluster, WSO2 ESB cluster etc, when you add a secondary user store in one cluster, it will be unknown to the other product clusters. This is because the WSO2 deployment synchroniser does not facilitate cross product synchronisation of artefacts. Therefore, you need to create the same user store in one node of each product cluster.

Fox example, if your setup has a WSO2 Identity Server instance serving an APIM cluster and an ESB cluster, the user store needs to be created in one APIM node and one ESB node.

Configuring using the management console

  1. Log in to the management console and click User Store Management sub menu under Configure menu.

  2. The User Store Management page opens. Initially, there are no secondary user stores.

    Note: You cannot update the PRIMARY user store at run time, so it is not visible on this page.

  3. Click Add Secondary User Store.

  4. The User Store Manager page opens. Enter a unique domain name and fill in the rest of the data.

    Domain names must be unique and must not include underscore character (_).

    For details on each property, see the respective property description that is provided. Also, select the required implementation of user store manager from the User Store Manager Class drop-down list. The displayed property list varies depending on the selected user store manager implementation. By default, all WSO2 products come with four user store manager implementations as follows:

    • ReadWriteLDAPUserStoreManager
    • ReadOnlyLDAPUserStoreManager
    • ActiveDirectoryUserStoreManager
    • JDBCUserStoreManager

    You can also populate this drop-down list with custom user store manager implementations by adding them to the server. A sample custom user store manager can be found in the repository.

     

  5. Ensure that all the mandatory fields are filled and a valid domain name is given and click Add. 

  6. A message appears saying that the user stores are being added. 

    Note: The above message does not imply that the user store is added successfully. It simply means that the server is attempting to add the new user store to the end of the available chain of stores.

  7. Refresh the page after a few seconds to check the status. 

  8. If the new user store is successfully added, it will appear in the User Store Management page.

  9. After adding to the server, you can edit the properties of the new secondary user store and enable/disable it in a dynamic manner.

Configuring manually

By default, the configuration of the primary user store is saved in the user-mgt.xml file. When you create a secondary user store using the management console as explained above, its configuration is saved to an XML file with the same name as the domain name you specify. Alternatively, you can create this XML file manually and save it as follows:

    • When you configure multiple user stores, you must give a unique domain name to each user store in the <DomainName> element. If you configure a user store without specifying a domain name, the server throws an exception at start up.
    • If it is the configuration of a super tenant, save the secondary user store definitions in <PRODUCT_HOME>/repository/deployment/server/userstores directory.
    • If it is a general tenant, save the configuration in <PRODUCT_HOME>/repository/tenants/<tenantid>/userstores directory.
    • The the secondary user store configuration file must have the same name as the domain with an underscore (_) in place of the period. For example, if the domain is wso2.com, name the file as wso2_com.xml.
    • One file only contains the definition for one user store domain.
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.