X

Technical info and insight on using Oracle Documaker for customer communication and document automation

Try Oracle Cloud Platform For Free

Configuring Documaker Enterprise in WebLogic with Active Directory Authentication

Andy Little
Technical Director

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.

Configuring WebLogic Security Realm with Active Directory

First, obtain the following information about your Active Directory server:

  • IP Address or Hostname
  • Port
  • Bind DN (user) e.g. cn=weblogic,cn=Users,dc=testcompany,dc=local
  • Bind DN Credential (password)
  • Base DN - this is the top-level grouping where users will be located. This will vary depending on how the organization has configured Active Directory. Recommend using Apache Directory Studio to connect and confirm these settings. Example: "dc=testcompany, dc=local" for the domain "testcompany.local". You may also have additional dc elements if the domain has more dot-separated parts (e.g. test.mycompany.com yields dc=test,dc=mycompany,dc=com)

Armed with this information, let's configure the WebLogic security realm to attach to the Active Directory server.

  • Login to WebLogic Console and navigate to Security Realms > myrealm > Providers
  • Click New, and name your Provider (e.g. AzureAD). Select ActiveDirectoryAuthenticator as the type and click Ok
  • Click your Provider in the list of Providers, then select the Provider Specific tab.
  • Enter the settings for your Active Directory Server
    • Host = IP address or Hostname
    • Port = Port
    • Principal = Bind DN
    • Credential = Bind DN Credential
    • Confirm Credential = Bind DN Credential
    • User Base DN = Base DN
    • User From Name Filter = (&(cn=%u)(objectclass=user))
    • viii.User Search Scope = subtree
    • User Name Attribute = sAMAccountName
    • User Object Class = organizationalPerson
    • Group Base DN = Base DN (note: you may augment the Base DN if the organization has additional tree structure around groups. If the groups are organized separately from users, e.g. in an organizational unit (ou), then you will want to add this to your Base DN, e.g. ou=my-department,dc=test,dc=mycompany,dc=com
    • Group From Name Filter: (&(cn=%g)(objectclass=group))
    • xiii.Group Search Scope = subtree
    • Group Membership Searching = unlimited
    • Max Group Membership Search Level = 0
    • Static Group Name Attribute = cn
    • xvii.Static Group Object Class = group
    • xviii.Static Member DN Attribute = member
    • Static Group DNs from Member DN Filter = (&(member=%M)(objectclass=group))
    • Click Save. WebLogic will validate the connection -- if failure occurs, check your Host, Port, Principal, and Credential settings.
    • Click the Common tab and review the Control Flag setting. It should be set to OPTIONAL at the moment. This will allow WebLogic to query the LDAP repository to get user and group information but does not require a successful authentication of an LDAP user to succeed.
  • Restart the AdminServer. At this point, the chance of failure is minimal since we have configured the ActiveDirectory Provider Control Flag as OPTIONAL, which means it doesn't have to succeed. The DefaultProvider Control Flag should be set to SUFFICIENT. Resolve any startup errors if present.
  • Validate configuration by logging into WebLogic console and navigating to Security Realms > myrealm > Users and Groups.
    • In the Users tab, you should see users listed from DefaultAuthenticator and your provider (e.g. AzureAD).
    • In the Groups tab, you should see groups listed from DefaultAuthenticator and your provider (e.g. AzureAD).
    • This verifies that we are pulling groups and users from Active Directory.

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:

  • Create an Active Directory user that will have the ability to run WebLogic services. In this doc, we will refer to this as the adweblogic user.
  • Create an Active Directory group that contains users with the ability to run WebLogic services. In this doc, we will refer to this as the weblogic admin group.
  • Add the adweblogic user to the weblogic admin group.

 Now that you have this configured, you can continue.

  • Backup your existing configuration in case something breaks. This means to backup your config.xml found in DOMAIN_HOME/config/config.xml.
  • Login to WLS Console and navigate to Security Realms > myrealm > Roles and Policies. Expand Global Roles and click Roles.
  • Click the Admin role, then click Add Conditions. Configure accordingly:
    • Predicate List : Group. Click Next.
    • Group Argument Name: weblogic admin group. Click Add. Click Finish.
    • Click Save.
  • Stop the AdminServer. Update DOMAIN_HOME/servers/AdminServer/security/boot.properties. Enter the adweblogic user and credential in clear text (it will be encrypted after you start the server).
  • Start the AdminServer. Login to WebLogic Console with adweblogic user. If this does not work, check your configuration.
  • Navigate to Security Realms > myrealm > Providers.
  • Click your Active Directory provider
  • Change Control Flag to REQUIRED, then click Save.
  • Use the breadcrumb trail to navigate back to the list of Providers.
  • Click Reorder, then tick the box next to the Active Directory provider, then click the "to top" button so that your provider is listed first.
  • Click Ok.
  • Now, you should:
    • Shutdown the AdminServer.
    • Shutdown any Managed Servers
    • Shutdown NodeManager.
    • Restart NodeManager, connect with WLST, and start the AdminServer.
    • Start any Managed Servers.

 
Configuring ODEE with Active Directory

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

Understanding the configuration

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.

Performing the configuration

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.

 

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.

Recent Content