PowerConnect for SAP Solutions
Auto Light Dark
Auto Light Dark

Adding Authentication to PowerConnect Java for Data Services UI

Applies to the SAP BusinessObjects and SAP Data Services agents.

From version 9.2.1 the agent requires authentication out of the box - the configuration is packaged into the WAR.

Order Do step 1 and step 2 before step 3. If the security rules are added before the user account exists.

Step 1 - Point the PC Java agent at its own user file

Open the context file you created when installing the agent:

$BOBJ_HOME/tomcat/conf/Catalina/localhost/powerconnect-java.xml

Add the Realm line, keeping the existing Environment line exactly as it is:

XML
<Context>
    <Environment name="configurationPath"
                 value="${catalina.home}/conf/powerconnect.properties"
                 type="java.lang.String"/>

    <Realm className="org.apache.catalina.realm.MemoryRealm"
           pathname="${catalina.home}/conf/powerconnect-users.xml"/>
</Context>

Step 2 - Create the user file

Create a new file at:

${catalina.home}/conf/powerconnect-users.xml
XML
<tomcat-users>
    <role rolename="powerconnect"/>
    <user username="pcadmin" password="choose-a-password" roles="powerconnect"/>
</tomcat-users>

Choose a username and password. The role name must be powerconnect

Ensure the file is readable by the operating system account that runs Tomcat, and restrict it from everyone else. It contains a password in plain text, in the same way Tomcat's own tomcat-users.xml does.

Step 3 - Add the security rules to the installed agent

This step is only needed on installations running a version earlier than 9.2.1. Open the deployed descriptor:

$BOBJ_HOME/tomcat/webapps/powerconnect-java/WEB-INF/web.xml

Add the following three blocks immediately before the closing </web-app> tag, leaving everything already in the file unchanged:

XML
    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>PowerConnect</realm-name>
    </login-config>

    <security-constraint>
        <display-name>PowerConnectSecurityConstraint</display-name>
        <web-resource-collection>
            <web-resource-name>PowerConnectResource</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>powerconnect</role-name>
        </auth-constraint>
    </security-constraint>

    <security-role>
        <description>Role required to access the PowerConnect agent UI</description>
        <role-name>powerconnect</role-name>
    </security-role>

Step 4 - Restart Tomcat

All three files are read when Tomcat starts, so a restart is required.

Step 5 - Confirm it is working

Browse to:

http://<host>:<port>/powerconnect-java/index.html

Your browser will ask for a username and password. Enter the account from step 2 and the administration pages will load as before. If you are not prompted, clear your browser cache and try again in a private window.

What happens at the next upgrade

When you deploy version 9.2.1 or later, the new WAR replaces the agent's WEB-INF/web.xml, so the edit from step 3 is discarded and replaced by the same rules shipped in the WAR. No cleanup is needed and nothing has to be re-applied.

The files from steps 1 and 2 live outside the agent's own directory and are not touched by a deployment, so your account continues to work unchanged. This is the same reason your configurationPath setting survives upgrades today.


Survives Tomcat restart

Survives agent upgrade

conf/Catalina/localhost/powerconnect-java.xml (step 1)

Yes

Yes

conf/powerconnect-users.xml (step 2)

Yes

Yes

webapps/powerconnect-java/WEB-INF/web.xml (step 3)

Yes

No - replaced by the WAR

A plain Tomcat restart does not affect the step 3 edit. It is replaced only when a new or updated WAR is deployed, including by WDeploy.

Troubleshooting

The agent UI does not appear after restarting Tomcat. The user file is missing or cannot be read. Check that conf/powerconnect-users.xml exists at the location given by pathname, and that the Tomcat account can read it. Tomcat records the reason in logs/catalina.out.

The sign-in prompt reappears after entering correct details. The username or password does not match the user file, or Tomcat has not been restarted since the file was created.

Sign-in succeeds but every page returns "403 Forbidden". The roles attribute does not read exactly powerconnect. It is case-sensitive and must match the name the agent expects.

Every page returns "401 Unauthorized" and no password works. Step 3 was applied before steps 1 and 2. Complete those, then restart Tomcat.

Optional: storing the password as a hash

Tomcat can store the password as a one-way hash rather than plain text. Add a credential handler inside the same Realm element:

XML
<Realm className="org.apache.catalina.realm.MemoryRealm"
       pathname="${catalina.home}/conf/powerconnect-users.xml">
    <CredentialHandler
        className="org.apache.catalina.realm.MessageDigestCredentialHandler"
        algorithm="SHA-256"
        iterations="100000"/>
</Realm>

Generate the hashed value with the utility included in your Tomcat installation and put the result in the password attribute in place of the plain text:

Linux

$BOBJ_HOME/tomcat/bin/digest.sh -a sha-256 -i 100000 your-password

On Windows, use digest.bat. Verify sign-in works before discarding your record of the original password.

Note on authentication scope

The rules above apply only to the PowerConnect agent's own context. Your existing Tomcat users, and the configuration behind the Central Management Console, are not read, modified, or affected.

If your Tomcat already has a populated tomcat-users.xml and you would rather reuse an existing account, you can skip steps 1 and 2 entirely and instead add powerconnect to that user's roles attribute. Do not do both - a Realm declared in the context file replaces the inherited one for this context, so the agent would then read only powerconnect-users.xml and ignore tomcat-users.xml.