You may have noticed that the Oracle Documaker Enterprise Edition (ODEE) Dashboard application does not have any specific Ability Sets like Documaker Interactive. Nor does it limit accessibility to system administrators like the Documaker Administrator application. This is because the Dashboard is meant to be accessed by any users who have rights to the Documaker system. The Dashboard is read-only, so nothing can be changed. However, because the Dashboard can be used to view live transactions within the system, it is important to consider limiting access to the Dashboard, since personally-identifiable information (PII) can accessed here. In this short article I’m going to show how to configure secure access for Documaker Dashboard in two ways.
It’s worth noting that good security practice dictates that one start with the narrowest security scope, and to limit what is transmitted where possible. In short, this means:
- Don’t grant access by default; and
- Don’t put information on a document unless it’s needed.I suspect that most documents have been amended so far to prevent exposure of secure information like full account numbers — when is the last time you saw something that showed an entire credit card number or social security number?
At this point, let’s assume that you already have an existing ODEE implementation that is hooked up to an external user repository (if you need help setting up your system you can refer to my green field guides for more information). Before moving on, let’s discuss some important background information.
- Authentication and Authorization: simply put, the authentication answers the question “who are you”, and authorization answers the question “what are you allowed to do”. Authentication is provided through any number of mechanisms; a common example is a challenge-response (the system challenges you with a password, you respond with what is hopefully correct, and you are now authenticated). The second part of this equation is the authorization — now that the system knows who you are, it can determine what you are allowed to access, or what functions you can perform.
- When ODEE is deployed, a WebLogic domain is created — which is the collection of resources administered in a bundle. The domain has a security realm, which contains all the users and groups and security policies applicable to the domain. When installed, the default configuration is a single user that serves as the Documaker system administrator. You can also install sample users and groups to illustrate how to use the system. These users and groups are all contained within the realm. Most implementations never use the realm to house users and groups, and instead are configured to use an existing user repository like Active Directory. You can read my write-up on how to configure WebLogic and ODEE to use Active Directory here.
- Where ODEE is concerned, all authentication is delegated to WebLogic. That is, ODEE knows nothing about users or their passwords. All of this is handled by WebLogic. What you need to know is that authorization is handled at two levels: the domain, and through a special convention in ODEE, the Ability Set. Each of these aspects are controlled by a user’s group membership — WebLogic considers a user’s group membership for authorization, and ODEE aligns groups to specific functions within its applications (“Abililties”), which are grouped by roles (“Ability Sets”). In this manner, you can map a user group to an ability set commensurate with the groups member’s roles within the application. Put another way, the “Drafter” ability set grants functions within Documaker Interactive that are needed by users to create documents. This ability set is then mapped to user groups.
Did you notice how I mentioned the first authorization handle at the domain and gave no additional details? There’s a reason for that! The bit about ability sets is all part of base product and is already well-documented, but the domain-based authorization isn’t given much attention in the document. This is partly because it’s not specific to the Documaker product, it’s part of a larger Java Security specification that’s implementation by WebLogic, which you can read about here (fair warning: it’s quite dry and technical in nature). Keep in mind that even though this discussion is specific to the Documaker Dashboard, it applies to any application deployed to WebLogic. I am discussing the Dashboard here because it doesn’t have any administrative interface for its authorizations.
There are two models for administering domain-based authorization for the Documaker Dashboard: deployment descriptors or the WebLogic Console. The default model is deployment descriptors, which are a set of files that are contained within the deployable artifacts that are generated and installed when you install ODEE. A deployable artifact is an EAR or WAR file, which is basically a compressed directory structure with the application files in it — a zip file. The other option is the WebLogic Console, which gives you a web-based administrative interface to managing the security. Let’s start with the latter, since it’s somewhat easier.
Note: these instructions assume you’ve already deployed ODEE into a sandbox environment. Because the deployments are done automatically during the installation process, describing how to change these settings during the deployment is beyond the scope of this particular instruction — but it’s possible to do it if you’re rolling your own installation.
Configure for Administration through WebLogic Console
First, undeploy the existing DocumakerDashboard application. This is necessary because the security model is set when the application is deployed.
- Login to your WebLogic console.
- Navigate to Deployments, and tick the box next to DocumakerDashboard and then click Delete. Wait! Make sure you note the Targets for the application. The default is the dmkr_server_al1_1, but your implementation might be different.
Now, deploy the existing Documaker Dashboard application. You should still have the original deployable file in the ODEE_HOME.
- Click Install, and use the path navigator to locate the ODDF_Dashboard.ear file. The default location is <ODEE_HOME>/documaker/j2ee/weblogic/<database>/dashboard. Tick the radio button next to the EAR file, and click Next.
- Accept the default (install as application) and click next.
- On the deployment targets screen, check the appropriate servers for targeting the deployment. Again, the default is the managed server dmkr_server_al1_1. Tick the necessary boxes and click next.
- In the General Section, change the Name to DocumakerDashboard (the default is the name of the deployable, which is ok, but not preferred). In the Security section, notice the default is DD Only. This should be changed to Custom Roles (which leaves policies to be defined in the deployment descriptors) or Custom Roles and Policies (which allows both to be administered in WebLogic) depending on your needs. The most likely selection is Custom Roles and Policies, which is what we’ll demonstrate below. Tick the radio button and click Finish.
Administration through WebLogic Console
Once you’ve set up for administration through WebLogic Console, you can login to the Console and navigate to Deployments > DocumakerDashboard > Security. Here you will see two sub-tabs, Roles and Policies.
On the Roles tab, we want to create a new role, so click New. The only option we need to supply is a role name, and we’ll use valid-users (this happens to mimic the default configuration). The default Authorization Provider XACMLAuthorizer should be selected. Click Save and then switch to the Policies tab.
On the Policies tab, we will define a policy that allows access to the dashboard only by members of a specific group.
- Click Add Conditions
- Select Predicate List: Group, then click Next.
- Enter a Group Argument name and click Add. The name you specify here is a valid group name. If you don’t have a group set up yet, you can put “Documaker Administrators” for now. Click Finish. Click Save.
You can add multiple groups here by repeating this procedure. If you try to login to the Dashboard with the administrative user, you will have access. If you try to login with non-administrative user (e.g. Alan Abrams or other sample users) you will be denied access.
Yes, it was really that simple — so simple in fact you’ll wonder why I’m even going to go into this next part, but in the interest of completeness… Oh, before we go, if you ever want to revert back to the default state of the installation, simply perform the undeploy steps, then deploy again, but this time use the DD Only option on the Security tab. Ok, moving on!
Administration through Deployment Descriptors.
- Follow the undeploy steps in the Configure for Administration through WebLogic Console section above.
- Locate your the original deployable file in the ODEE_HOME. The normal location <ODEE_HOME>/documaker/j2ee/weblogic/<database>/dashboard/ODDF_Dashboard.ear. Make a backup of this file. I feel this should be said twice. Make a backup of this file. I advise you to copy this file to another directory and edit there, rather than backing up somewhere else and editing the original.
- Copy the ODDF_Dashboard.ear file to a new directory, e.g. ~/temp. Unzip the EAR file in this directory. Remove the EAR file.
- Inside the ~/temp directory, unzip Dashboard_ViewController_webapp1.war into a new directory inside ~/temp, e.g. ~/temp/war. Remove the WAR file.
- Inside the ~/temp/war/WEB-INF directory, locate the deployment descriptor weblogic.xml.
- Edit the weblogic.xml file. You’ll see the following bit in this file, which maps the principal name to the role name. That is, the name of group in your repository is mapped to a role name. All you need to do is change the principal name to the name of a group that you want to have access to the application. If you want more than one group, create duplicate <principle-name> elements.
- Save the weblogic.xml file.
- In ~/temp/war, issue the following command to rebuild the WAR file in the ~/temp directory
$ jar -cvf ../Dashboard_Viewcontroller_webapp1.war *
- Change to ~/temp and remove ~/temp/war.
- In ~/temp, issue the following command to rebuild the EAR file in the ~/ directory:
$ jar -cvf ../ODDF_Dashboard.ear *
- Change to ~/ and remove ~/temp.
- Follow the deploy steps in the Configure for Administration through WebLogic console section above.
- Note: some programs will allow you to navigate the contents of zip files and edit them in place. If you associate EAR files and WAR files with such a program, you can simply edit the weblogic.xml and not have to go through the unzip/rezip processes.
That’s it! Hopefully this made sense and will be useful for you. It’s not likely that this configuration will change frequently, but if it something that could be in flux it might be beneficial for you to make this change to use the administration through the WebLogic console, so you won’t have to rebuild the deployable files any time a setting changes. As always, if you need help comment here or over on the Documaker Community.