A common implementation task is to tie in the authentication of users into an established user repository. Documaker is no different in this aspect of implementation, and in this article, I'm going to give you a short primer on how to configure an external LDAP repository for use with Documaker Enterprise Edition. First, a review. LDAP is an acronym for Lightweight Directory Access Protocol, and is a terse language used to query a server for information. In plain terms, the directory is like a phone book of information that could be users, machines, printers, or just about anything. In terms of this example, our directory service will be used to lookup users and their group membership(s). A directory is a hierarchical structure of related nodes, and each node has attributes that describe it. Some nodes and attributes are specified by the X.500 data model, others can be specific to your organization. The image above is an example directory structure.
In the above image we can see a few abbreviations: dc is domain component, cn is common name, ou = organizational unit, o = organization. Each of these levels is called a relative distinguished name, or RDN. When we reference a specific element in our directory, the sum of all the RDNs to locate that element gives us the distinguished name, or DN.
Documaker Enterprise features the Administrator, Dashboard, and Interactive applications. These applications require all users to be authenticated - that is, users must present a credential from a trusted system so Documaker (or more specifically, the application server hosting the Documaker applications) is assured that the user is actually "Jane Doe". From there, the Documaker applications can apply authorization: what Jane Doe is allowed to do inside various applications. Where Documaker is concerned, these authorizations are represented by collectively represented by Ability Sets, which are tied to Entities. An Entity is a group, or role. So, when Jane Doe logs into Documaker Interactive, the application authenticates Jane (usually through a challenge/response, e.g. Jane must input her user ID and password), and then the application will learn Jane's group memberships, and will look up these groups in its configured Entities. These Entities are correlated to Ability Sets, and thus the application now knows which functions are available to Jane when displaying the user interface.
When Oracle Documaker Enterprise Edition (ODEE) is first installed, a default security realm is created and populated with sample users. The security realm is the source for user authentication and authorization for applications and components deployed in a WebLogic domain. The installation process also creates a set of default users and authorizations, both for administration (e.g. the " documaker " user) and for reference implementation (e.g. users such as "Alan Abrams" and "Linda Lamas"). This is great for establishing a sandbox environment, but unless you have a very small user base you're not likely to import your users into this security realm. Luckily, WebLogic's security framework provides the ability to define multiple authentication sources.This short instruction set will illustrate the necessary configurations and settings to link an Active Directory server to a WebLogic security realm, and then to configure the system so that ODEE's applications will function, and domain users will be able to login . If you have any questions, you can comment below, or over at the Documaker Community. As always, if you need to set up an ODEE sandbox, you can review my instructions here or here. Keep in mind that if you decide to try this in your environment with an existing Active Directory configuration, you'll want to review the settings for locating groups and users with your Active Directory system administrator to make sure they are correct for your environment.
First, obtain the following information about your Active Directory server:
Armed with this information, let's configure the WebLogic security realm to attach to the Active Directory server.
Now that we have configured our WebLogic domain for Active Directory, we have to configure the Providers in order and with specific Control Flags. The reason for this is two-fold: one, ODEE web applications only have visibility into the first Provider in the list, and two, most organizations will want to limit the user/group containers only to Active Directory. That is, they do not want to have users/groups coming from multiple sources, especially one that is not enterprise-wide, like the DefaultAuthenticator. The key difficulty in this configuration, which will specifically limit WebLogic user/group validation to Active Directory, means that the users needed to run WebLogic services and login to the console must be defined in WebLogic before the services will run, and any failure to connect to Active Directory will mean the services will not start. Before proceeding, make sure that your Active Directory has a user with sufficient rights to run services in your domain. What does this mean? You must:
Now that you have this configured, you can continue.
In order to use ODEE Applications with Active Directory, some additional configuration is required. You will need a SQL tool (SQLDeveloper, MSSQLStudio, or any tool where you can perform SQL statements).
ODEE apps use several tables in the DMKR_ADMIN schema to determine what applications and functions users can access. The tables are populated during the initial installation, and the JPSQUERY tool is used to correlate entries in the DMKR_ENTITIES table to users in the default Security Realm. However, when migrating to Active Directory, we have no such users (in fact, if you attempt to login to the applications with the documaker user, you will find that you cannot. It is important to understand the relationship between the tables:
DMKR_ENTITIES
|
This table lists the groups that have been associated to one or more ability sets using Documaker Administrator. This table also lists any users that have successfully accessed the system — note that ability sets are mapped only to groups, not users. |
DMKR_ENTITY_TO_ENTITY |
This table defines the relationship between users who have logged into the system and any groups with mapped ability sets. So, when a user logs in, |
DMKR_ENTITY_ABILITYSET |
This table defines the relationship between a group and its mapped ability set(s). |
So, when a user attempts to log into web applications deployed to WebLogic, the security provider is queried to authenticate the user credential, and then obtain the user’s group membership. The web application, e.g. Documaker Administrator, will determine if the user is a member of any group that has been given the appropriate ability set for that application. If the user has membership in a group with a mapped ability set, those entries are created in the DMKR_ENTITIES and DMKR_ENTITY_to_ENTITY table, and then the user is granted access to the application.
Use your SQL tool to connect to the DMKR_ADMIN schema, and run the following queries. You may need to modify them slightly for your target database - these examples were done with Microsoft SQL Server, using the default schema DMKR_ADMIN. Note: Replace <Your_AD_Documaker_Admin_Group_Name> with the name of a group in Active Directory that contains administrators of the Documaker system. Replace <Your_AD_Documaker_Admin_User_Name> with the name of a user in Active Directory that is a member of your Documaker admin group.
UPDATE DMKR_ADMIN.DMKR_ENTITIES SET NAME=“<Your_AD_Documaker_Admin_Group_Name>” WHERE NAME = “Documaker Administrators” COMMIT UPDATE DMKR_ADMIN.DMKR_ENTITIES SET NAME=“<Your_AD_Documaker_Admin_User_Name>” WHERE NAME = “documaker” COMMIT DELETE FROM DMKR_ADMIN.DMKR_APPRLEVELSENTITIES COMMIT DELETE FROM DMKR_ADMIN.DMKR_ENTITIES WHERE NAME NOT IN ( <Your_AD_Documaker_Admin_User_Name>,<Your_AD_Documaker_Admin_Group_Name>) COMMIT
After running these queries, you should be able to run JPSQuery* and see output as follows (note: it may differ slightly, as you might see more Users if you have multiple users in the Documaker Administrator group. Also if you have run JPSQuery multiple times it may say “updated” the first time you run this after the SQL queries and "found" in subsequent runs.Restart the managed server(s) running the Documaker applications and you should now be able to login to the Documaker Administrator with your Active Directory user that is a member of the Documaker Administrators group in Active Directory. You can then proceed to link up "Enterprise Groups" (groups from Active Directory) with "Ability Sets", which are preconfigured roles within Documaker applications. Well done!
*The JPSQuery application is installed by default to the AdminServer in the WebLogic domain, which runs on port 7001, so you would access it via a browser to https://<admin-server-host>:7001/jpsquery. Your installation may be different.