JBoss.orgCommunity Documentation

Chapter 4. Administration

Table of Contents

4.1. Changing the Web Server Listen Port
4.2. Administering Users and Access Control
4.2.1. Administrative Users
4.2.2. End Users
4.3. Configuration Database Connections
4.3.1. Derby Out-of-the-Box
4.3.2. Switching to another Database
4.3.3. Switch to MySQL on Tomcat using OpenJPA
4.3.4. Switch to Postgres on Tomcat using OpenJPA
4.3.5. Switch to Postgres on JBoss using Hibernate
4.3.6. Switch to Oracle on Tomcat using Hibernate
4.3.7. Switch to HSQL on Tomcat using Hibernate
4.3.8. Switch to other db
4.3.9. Override persistence properties in the juddiv3.xml
4.4. Logging
4.5. Administering the GUI (juddi-gui.war)
4.6. Task: Signing the Digital Signature Applet jar file
4.7. Administrating your jUDDI Instance using the Administrative Console
4.8. Configure jUDDI
4.8.1. Enabling Remote Access
4.9. Monitoring the Status and Statistics
4.9.1. Statistics
4.9.2. Status
4.10. Accessing the jUDDIv3 API
4.11. Security Guidance
4.11.1. jUDDI Server
4.11.2. jUDDI Client (and developers)
4.11.3. jUDDI GUI (Web user interface)
4.12. Backups, Upgrading and Data Migration
4.12.1. Database Backups
4.12.2. Config Backup
4.13. Upgrading jUDDI
4.14. Scaling jUDDI and Federation
4.14.1. Scaling the jUDDI Services (multiple servers)
4.14.2. Limitations of jUDDI

If you want to change the port Tomcat listens on to something non-standard (something other than 8080), use the following guidance.

jUDDI Server (Tomcat) - This assumes you are using the jUDDI server bundled with Apache Tomcat. For other application servers, consult their documentation, however the juddiv3.xml must still be altered.

  • Edit conf/server.xml and change the port within the <Connector> element.
  • Edit webapps/juddiv3/WEB-INF/classes/juddiv3.xml and change the port number jUDDI Server Baseurl.
  • Edit webapps/juddiv3/WEB-INF/config.properties and change the port numbers for "securityurl" and "juddipapi".
  • Edit webapps/juddi-gui/META-INF/config.properties and change the port numbers for all of the URLs listed.

As of version 3.2, jUDDI Authentication is handled from two perspectives, administrator and end user access.

Administrative users have special access to juddi-gui’s remote configuration page at http://localhost:8080/juddi-gui/settings.jsp and to the Administrative Console at http://localhost:8080/juddiv3/admin. Access to both of these is configured at the container level (i.e. Jboss, Tomcat, etc). By default, users that need to access these pages need to have the "uddiadmin" role (which is defined in the WEB-INF/web.xml of both web application archives). When you are running on tomcat this configuration can be found in the <tomcat>/conf/tomcat-users.conf file.

End users typically will either access jUDDI’s services directly at http://localhost:8080/juddiv3/ or via the user interfaces http://localhost:8080/juddi-gui. In both cases, authentication is handled via jUDDI’s Authentication providers which is configured in juddiv3.war/WEB-INF/classes/juddiv3.xml.

In order to enforce proper write access to jUDDI, each request to jUDDI needs a valid authToken. Note that read access is not restricted (by default, but can be enabled) and therefore queries into the registries are not restricted.

To obtain a valid authToken a getAuthToken() request must be made, where a GetAuthToken object is passed. On the GetAuthToken object a userid and credential (password) needs to be set.

org.uddi.api_v3.GetAuthToken ga = new org.uddi.api_v3.GetAuthToken();
org.uddi.api_v3.AuthToken token = securityService.getAuthToken(ga);

The property juddi/auth/* in the juddiv3.xml configuration file can be used to configure how jUDDI is going to check the credentials passed in on the GetAuthToken request. By default jUDDI uses the JUDDIAuthenticator implementation. You can provide your own authentication implementation or use any of the ones mention below. The implementation needs to implement the org.apache.juddi.auth.Authenticator interface, and juddi/auth/authenticator/class property should refer to the implementation class.

There are two phases involved in Authentication. The authenticate phase and the identify phase. Both of these phases are represented by a method in the Authenticator interface.

The authenticate phase occurs during the GetAuthToken request as described above. The goal of this phase is to turn a user id and credentials into a valid publisher id. The publisher id (referred to as the "authorized name" in UDDI terminology) is the value that assigns ownership within UDDI. Whenever a new entity is created, it must be tagged with ownership by the authorized name of the publisher. The value of the publisher id can be completely transparent to jUDDI - the only requirement is that one exists to assign to new entities. Thus, the authenticate phase must return a non-null publisher id. Upon completion of the GetAuthToken request, an authentication token is issued to the caller.

In subsequent calls to the UDDI API that require authentication, the token issued from the GetAuthToken request must be provided. This leads to the next phase of jUDDI authentication - the identify phase.

The identify phase is responsible for turning the authentication token (or the publisher id associated with that authentication token) into a valid UddiEntityPublisher object. The UddiEntityPublisher object contains all the properties necessary to handle ownership of UDDI entities. Thus, the token (or publisher id) is used to "identify" the publisher.

The two phases provide compliance with the UDDI authentication structure and grant flexibility for users that wish to provide their own authentication mechanism. Handling of credentials and publisher properties can be done entirely outside of jUDDI. However, jUDDI provides the Publisher entity, which is a sub-class of UddiEntityPublisher, to persist publisher properties within jUDDI. This is used in the default authentication and is the subject of the next section.

Finally is it possible to hook up to third party credential stores. If for example jUDDI is deployed to the JBoss Application server it is possible to hook up to it’s authentication machinery. The JBossAuthenticator class is provided in the docs/examples/auth directory. This class enables jUDDI deployments on JBoss use a server security domain to authenticate users.

To use this class you must add the following properties to the juddiv3.xml file:


The juddi/auth/authenticator/class property plugs the JbossAuthenticator class into the jUDDI the Authenticator framework. The juddi/sercuityDomain, configures the JBossAuthenticator class where it can lookup the application server’s security domain, which it will use to perform the authentication. Note that JBoss creates one security domain for each application policy element on the $JBOSS_HOME/server/default/conf/login-config.xml file, which gets bound to the server JNDI tree with name java:/jaas/<application-policy-name></application-policy-name>. If a lookup refers to a non existent application policy it defaults to a policy named other.

By default jUDDI uses an embedded Derby database. This allows us to build a downloadable distribution that works out-of-the-box, without having to do any database setup work. We recommend switching to an enterprise-level database before going to production. JUDDI uses the Java Persistence API (JPA) in the back end and we’ve tested with both OpenJPA and Hibernate. To configure which JPA provider you want to use, you will need to edit the configuration in the juddiv3.war/WEB-INF/classes/META-INF/persistence.xml. The content of this file is pretty standard between JPA implementations, however there can be slight differences. To make it easy we created different versions for different JPA implementations and target platforms. All JPA implementation have an enhancement phase, where the persistence model classes are enhanced. Hibernate does this at runtime, OpenJPA prefers doing this at compile time. This is the reason we ship two versions of juddi-core, where the juddi-core-openjpa.jar contains classes (byte-code) enhanced by OpenJPA. This is the reason this jar is larger then the juddi-core.jar.

For Hibernate, for testing the content of this file looks like

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    <persistence-unit name="juddiDatabase" transaction-type="RESOURCE_LOCAL">
        <!-- entity classes -->

            <property name="hibernate.archive.autodetection" value="class"/>
            <property name="hibernate.hbm2ddl.auto" value="update"/>
            <property name="hibernate.show_sql" value="false"/>
            <property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect"/>

For OpenJPA the persistence.xml looks like

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
  <persistence-unit name="juddiDatabase" transaction-type="RESOURCE_LOCAL">
    <!-- entity classes -->
      <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(SchemaAction='add')"/>
      <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/>
      <property name="openjpa.jdbc.UpdateManager" value="operation-order"/>
      <property name="openjpa.jdbc.DBDictionary" value="derby"/>
      <!-- dialects: derby, postgres, mysql, oracle, sybase, sqlserver
           for a complete list check the OpenJPA documentation -->
      <property name="openjpa.RuntimeUnenhancedClasses" value="warn"/>
      <property name="openjpa.Compatibility" value="CheckDatabaseForCascadePersistToDetachedEntity=true"/>

In this case we reference a jta-data-source called java:comp/env/jdbc/JuddiDS. Datasource deployment is Application Server specific. If you are using Tomcat, then the datasource is defined in juddi/META-INF/context.xml which by default looks like

<?xml version="1.0" encoding="UTF-8"?>
    <Resource name="jdbc/JuddiDS" auth="Container"
        type="javax.sql.DataSource" username="" password=""

By default the juddiv3.war is configured to be used on Tomcat using OpenJPA. However the download bundle lets you specify different target platforms resulting in a different setup. In all cases it will point to the embedded Derby database.

This was written from a JBoss - jUDDI perspective. Non-JBoss-users may have to tweak this a little bit, but for the most part, the files and information needed is here. Logged in as postgres user, access psql:

postgres= CREATE USER juddi with PASSWORD 'password';
postgres= CREATE DATABASE juddi;
postgres= GRANT ALL PRIVILEGES ON DATABASE juddi to juddi;

Note, for this example, my database is called juddi, as is the user who has full privileges to the database. The user juddi has a password set to password. Next edit the juddi-ds.xml datasource file with the settings for the postgres connection info:

        <!-- sql to call when connection is created.  Can be anything,
        select 1 is valid for PostgreSQL
        <new-connection-sql>select 1</new-connection-sql>
        <!-- sql to call on an existing pooled connection when it is obtained
        from pool.  Can be anything, select 1 is valid for PostgreSQL
        <check-valid-connection-sql>select 1</check-valid-connection-sql>
        <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml -->
            <type-mapping>PostgreSQL 8.0</type-mapping>

In persistence.xml, reference the correct JNDI name of the datasource and remove the derby Dialect and add in the postgresql Dialect, for Hibernate on JBoss use:

<property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>

Be sure to have postgresql-8.3-604.jdbc4.jar in the lib folder.

The jUDDI codebase uses the commons-logging-api, and log4j as the default logging implementation. The juddiv3/WEB-INF/classes/commons-logging.properties sets the logging to log4j. The default log4j configuration logs to a juddi.log file in the tomcat/logs directory. The log4j configuration lives in the juddiv3/WEB-INF/classes/log4j.properties file, which is referenced in the web.xml


The commons-logging and log4j jars are shipped in the juddiv3/WEB-INF/lib directory.

If you are using CXF for the webservice stack you can log the request/response xml by adding


to your log4j.properties and the cxf.xml file should contains this:


The jUDDI beans.xml specifies the location of this file at META-INF/cxf/cxf.xml.

There are a few things worth mentioning for administering the jUDDI Graphical User Interface. The first is user authentication, which is covered in the authentication chapter. The other the the Digital Signature Applet. This applet enables users to digitally signed UDDI entities via the GUI. There are a number of requirements in order for this to work.

  • The applet must be digitally signed. It is recommended that this signed by the administrator using the SSL certificate of the jUDDI instance. If it is not signed, it may not be able to digital certificates.
  • The Oracle Java browser plugin must be installed. For details on this, visit Oracle’s website.
  • The end user must have a digital certificate installed that is accessible to the browser. On Windows computers, this is supported by Internet Explorer, Opera and Chrome which use the Windows Certificate Store (Start > Run > MMC, Add Certificates). Firefox uses its own certificate store. On MacOS, Safari uses the Mac Keychain.
jarsigner -keystore your.keystore -storepass yourpass -keypass keypass <pathto>/juddi-gui.war/applets/juddi-gui-dsig-all.jar

Note: Jarsigner comes with most JDKs and has many command line options.

Your instance of the jUDDI (juddiv3.war) can be managed via the administration console. It can be access url the following URL:


By default, only users with the role "uddiadmin" are allowed to access this page. In addition, it must be accessed from the same computer hosting juddiv3.war (this can be changed if needed). When accessing the URL, you should be prompted for login via username/password (this can also be changed to another mechanism).

After authenticating, you will be prompted with a very similar interface to the juddi-gui.war. From here, you can perform a number of tasks.

  • Access Status and Statistics of jUDDI
  • Configure jUDDI (juddiv3.war)
  • Access the jUDDIv3 API, which provides a number of administrative tasks and functions (requires an additional login)*

*Why is there another login required for the jUDDIv3 API functions?

The answer is because the admin console will be directly accesses a web service and it requires a user account with juddi admin rights. This may be the same username you use to access the admin console (juddiv3.war/admin) but unfortunately, this double login is unavoidable.

From the browser, it is possible to configure jUDDI’s web services via the web browser. All of the settings available from the chapter on configuring jUDDI can be set there.

The Statistics and Status page provides valuable information to administrators and developers looking to trouble shoot or debug problems with jUDDI.

The jUDDI API is a web service that extends the UDDI specification. It provides various functions for both configuring the jUDDI server and for performing administrative functions, such as authorizing a new username as a publisher, user rights assignment and so on. This page will let you access the functions from the web browser.


You must authenticate using the top right hand side login/password box in order to use this.

This guide contains general security guidelines to ensure that your jUDDI server and jUDDI Client based application are relatively safe and to prevent authorized users.

This section is broken down into guidance for the jUDDI server and for the jUDDI Client

  • Always use SSL or TLS for connections to and from the jUDDI server, especially connections where authentication is used. Use encrypted connections to the database server when possible. client configs (uddi.xml), database (juddiv3/WEB-INF/classes/META-INF/persistence.xml)
  • If the juddi-gui web app is not on the same server as the juddiv3 web services web app, use SSL or TLS. (juddi-gui/WEB-INF/classes/META-INF/uddi.xml)
  • Use UDDI Digital Signatures where appropriate. Enable all validation options. Java/.NET Clients + juddi-gui, uddi.xml uddi/client/signatures, checkTimestamps,checkTrust,checkRevocationCRL
  • Require authentication for Inquiry API. (config/juddi/auth/Inquiry=true)
  • Use a LDAP user store and set passwords to expire regularly. Enforce the usage of strong passwords of sufficient length and SSL for LDAP connections. (config/juddi/auth/token/authenticator)
  • Encrypt all stored credentials (database, key stores, email, etc) with the highest possible encryption available. (config/juddi/cryptor=org.apache.juddi.v3.client.cryptor.AES256Cryptor or AES128)
  • Configure Auth Tokens to expire with relatively short intervals. This should meet all automatic logout requirements and help reduce the risk that an intercepted auth token can’t be reused by a 3rd party. (config/juddi/auth/token/Expiration) and (config/juddi/auth/token/Timeout)
  • Configure Auth Tokens to require Same IP Enforcement. This is a mitigation factor for when a token is intercepted and attempted to be reused from another source. (config/juddi/auth/token/enforceSameIPRule=true)
  • Configure Custody Transfer Tokens to expire with relatively short intervals. (config/juddi/transfer/expiration/days)
  • Disable sending authentication tokens to subscription notifications (config/juddi/notification/sendAuthTokenWithResultList=false)
  • Enable automatic logouts (WEB-ING/classes/META-INF/uddi.xml)
  • All cached credentials are encrypted in the session tokens using an AES key that is generated at boot up time of the juddi-gui instance.
  • Use SSL or TLS when connecting using your web browser to juddi-gui.
  • The juddi-gui uses cookies to store user preferences, such as language and the current node.
  • The juddi-gui makes heavy use of JavaScript using Jquery and JqueryUI. Without a JavaScript enabled browser that supports AJAX, the juddi-gui will not be functional. This usually implies Firefox 1.6 or higher, IE 6, Chrome/Chromium (nearly all versions), Opera v8 or higher, and Safari v2 or higher.
  • The juddi-gui uses a Java applet that is used for Digital Signature support. This runs within your web browser. The Java plugin for your web browser must be enabled in order to use this functionality. In addition, the applet itself must be digitally signed (usually performed by the administrator, see article on this).
  • The juddi-gui has built in validation for digital signatures. This requires a trusted key store. Ensure that the passwords are encrypted using the highest available crypto class and that the validation settings are enabled.
  • The juddi-gui has a settings pages for altering the uddi.xml configuration file. By default, this is only accessible from the same machine running juddi-gui (i.e. localhost). This behavior can be changed by either using the setting page from localhost or by manually editing the uddi.xml page. Unless required, the recommended setting is to prevent remote configuration changes. If the settings page isn’t required, it can be removed.
  • The juddi-gui has a settings page that is password protected to prevent unauthorized changes. Use the strongest available mechanism to protect credentials. The default configuration is for HTTP BASIC. It is recommended to use this with SSL/TLS and/or switch to DIGEST based authentication. If the settings page isn’t required, it can be removed.

There are several different strategies for managing your jUDDI backups.

Sometimes, the jUDDI development team has no choice but to alter the database schema. In many cases, OpenJPA or Hibernate (both Java Persistence API provides) will automatically alter database columns when a new version is installed. In some cases, there may actually be data loss.


Check the jUDDI distribution notes before attempting an upgrade.


Always perform a database level backup of your instance before attempting the upgrade.

The capabilities and components provided by jUDDI are designed to scale. The following will describe the options and known limitations of jUDDI.