16 Understanding WebLogic JMS Security

Learn how to secure WebLogic JMS resources using thread-based and object-based security models.

Securing WebLogic JMS Resources

WebLogic JMS enables you to secure JMS resources by restricting access to JMS destinations.

By default, all users can access JMS resources in a WebLogic Server or WebLogic cluster. This includes users with remote access, and users running directly in the WebLogic Server or WebLogic cluster itself. To restrict access to WebLogic JMS destinations, you must create security policies on the user's system resources and ensure users have the required roles. See Overview of Securing WebLogic Resources for more information about security roles and policies, and Java Messaging Service (JMS) Resources for policies available to JMS.

JMS Security Terminology

WebLogic JMS uses either object-based security (OBS) or thread-based security to determine which user is checked when accessing a secured WebLogic JMS destination.

Understand some common terminology used in the context of JMS security before exploring the difference between the two security approaches:

  • Subject: The security object that represents a user in a WebLogic application.
  • Principal and Credentials: A user's user name and password respectively.
  • Credentials: Often used to represent the combination of a user's user name and password.

Thread-based security implies that the subject that a secured WebLogic JMS destination checks is implicitly derived from the current caller's thread. Object-based security implies that the subject is implicitly derived from a subject stored in the object the caller is using to make its JMS call. In general, WebLogic security is thread based. The following sections explore both approaches.

Understanding Thread-Based Security on Clients and Servers

By default, access to secured WebLogic JMS resources leverages thread-based security. This gives WebLogic JMS security behavior parity with Java EE's general security model for EJBs, web applications, and RMI.

It means that WebLogic JMS send and consume operations are:
  1. Checked using the security subject/role stored implicitly within the current thread.
  2. Not checked using the user name and password that can be passed to JMS javax.jms createConnection() or createJMSContext() calls. In other words, the thread's subject from (1) supersedes the user name and password that an application can optionally pass into createConnection() or createJMSContext().

Thread-Based Security for Server Applications

For server-side applications, there are multiple ways to set EJB and Web application thread's subject or role. See Oracle Fusion Middleware Developing Applications with the WebLogic Security Service. To override thread-based JMS security checking behavior for server-side WebLogic JMS send and consume calls, see Understanding Object Based Security on Server Applications.

Thread-Based Security for Client Applications

For client applications, the current thread's subject is generated and implicitly placed on the thread when the client application creates a JNDI context. A JNDI context can optionally specify credentials by using its SECURITY_PRINCIPAL and Context.SECURITY_CREDENTIALS properties.

The following code sample puts a subject on the current thread for user myusername and password user_password:
java.util.Hashtable env = new Hashtable();
    env.put(Context.PROVIDER_URL, url);  // typical url: t3://example.com:7001  
    env.put(Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory");
    env.put(Context.SECURITY_PRINCIPAL, "myusername");
    env.put(Context.SECURITY_CREDENTIALS, "user_password");
    javax.naming.InitialContext ic = new InitialContext(env); // throws an exception if user name/password is incorrect 
    // thread now implicitly has subject for the ic user name/password
    // thread now has original subject from before the ic was created

If a client creates an InitialContext object without specifying credentials, then:

  • The subject already on the current thread is unchanged.
  • If there is no subject on the thread, then it is assumed to be an anonymous subject.

If a client program needs to transfer a thread's subject to a different thread than the thread used to create an InitialContext object, the client program can use security APIs to store the current subject of the thread and then subsequently use this cached subject in a different thread.

For example:
// retrieve the subject that is implicitly store in the current thread
javax.security.auth.Subject subject =   
// use the given subject to perform an action:
// if the action throws, return an exception 
// if the action succeeds, return "OK" 
static Object doSomethingAsSubject(javax.security.auth.Subject subject) {   
try {     
return weblogic.security.Security.runAs(subject,       
    new java.security.PrivilegedExceptionAction() {         
        public java.lang.Object run() throws Exception {           
            //  do something or throw  
                 return "OK"; 
   } catch (java.security.PrivilegedActionException e) { 
    return e;   
} catch (Throwable t) {    
 return t;
Sometimes it is useful to get an anonymous subject:
 javax.security.auth.Subject anon = new javax.security.auth.Subject();

To override thread-based JMS security checking behavior for client-side WebLogic JMS send and consume calls, see Understanding Object-Based Security on Clients.

Understanding Object-Based Security

WebLogic JMS clients can optionally use a simpler security model called object-based security (OBS) instead of thread-based security. This option was introduced in WebLogic and is useful for multithreaded clients which otherwise need extra code to transfer thread-based security subjects between threads.

The following sections explain how to enable object-based security:

Enabling Object-Based Security on Clients

Enabling object-based security (OBS) causes message send and consume security checks to be based on credentials specified during JMS client initialization instead of on the calling thread's subject.

Enabling OBS requires using an OBS JNDI initial context. Any WebLogic JMS senders or consumers that are created using an OBS connection factory that is obtained from an OBS initial context will, by default, implicitly use the credential that is associated with the OBS initial context instead of the subject that is associated with the current sender or consumer thread. In addition, if a user name and password credential is passed as parameters to a standard JMS createConnection() or createJMSContext() call on an OBS connection factory, then this new credential supersedes the credential that is associated with the OBS initial context and the new credential will be used for sends or consumes on that connection or JMS context.

Steps to enable OBS on a JMS client's senders and consumers:

  1. Create a javax.naming.InitialContext object:
    1. Specify a Context.INITIAL_CONTEXT_FACTORY property with string value weblogic.jms.WLInitialContextFactory instead of weblogic.jndi.WLInitialContextFactory. This returns an OBS initial context, and is the only step required for the majority of applications that want to use JMS client OBS.
    2. (Optional) Specify user name and password credentials using the standard JNDI Context.SECURITY_PRINCIPAL and Context.SECURITY_CREDENTIALS properties (same as what you do for a non OBS context). This will become the default OBS credential that is associated with the OBS initial context. If these properties are not specified, then the credential associated with the OBS initial context is determined by the weblogic.jndi.securityPolicy setting.
    3. (Optional) Specify an initial context property named weblogic.jndi.securityPolicy with string value ObjectBased or ObjectBasedHybrid. This fine tunes behavior when no user name and password credential is specified using the initial context Context.SECURITY_PRINCIPAL and Context.SECURITY_CREDENTIALS properties.
      • ObjectBased (the default): If no credential is provided when the initial context is created, then, by default, use an anonymous subject for JNDI lookups and WebLogic JMS sends or consumes credentials that are associated with the factory.
      • ObjectBasedHybrid: If no credential is provided when the initial context is created, then, by default, use the credential that was on the current thread when the initial context was created for subsequent JNDI lookups and WebLogic JMS sends or consumes credentials that are associated with the factory.
  2. Use the OBS initial context created in step (1) to look up WebLogic JMS connection factories (same as you look up a connection factory for a non OBS context), which will then implicitly be OBS JMS connection factories. Any JMS senders or consumers that are created using an OBS JMS connection factory will use OBS.
  3. (Optional) Override the OBS credential associated with the OBS JMS connection factory by passing a user name and password into the JMS standard createConnection() or createJMSContext()call that is used to create a JMS connection or context.
Object-Based Security Limitations on Clients

Listed below are some of the limitations of OBS:

  • An OBS initial context only supports lookup() calls and will otherwise throw NotSupported exceptions. If you need a context that supports other calls, then create a second context that does not enable OBS.
  • An OBS initial context is supported only on WebLogic clients and is not supported on WebLogic Servers. An exception is thrown when attempting to use such a context in combination with WebLogic JMS server facilities like bridges, MDBs, or resource references. This restriction exists because these server-side JMS facilities already have their own security handling that provides similar semantics to OBS.
  • When an OBS initial context is created, the initial context's user is not placed on the current thread. This differs from a weblogic.jndi.WLInitialContextFactory context.

Enabling Object-Based Security on Server Applications

Learn how to enable object-based security (OBS) for inbound and outbound JMS applications:

Object-Based Security for Inbound JMS Applications
Server applications that make inbound WebLogic JMS calls, such as Message Driven Beans, are implicitly object based. Credentials or roles for these applications to access incoming JMS messages are supplied in one of the following ways:
  • Supplied with the application itself.


    Oracle does not recommend using this method.
  • Defined on the service itself (Messaging Bridges allow you to configure user name or password).


    Oracle does not recommend using this method.
  • Just as for the outbound case, specified using a foreign JMS Server in a JMS system resource module that maps a JMS resource into JNDI.
As a best practice, use the foreign JMS Server method for Message Driven Beans, Messaging Bridges, and outbound JMS, as this:
  • Ensures the credentials are dynamically configurable and not hard coded into an application or descriptor file.
  • Applies to almost all inbound and outbound use cases so it is useful as a way to centrally manage your JMS credentials.
See FAQs: Integrating Remote JMS Providers and Enhanced Support for Using WebLogic JMS with EJBs and Servlets.
Object-Based Security for Outbound JMS Applications

Server applications that make outbound WebLogic JMS calls can achieve an object-based security pattern that supersedes the current security subject on the current thread. For this to work, ensure the following:

  1. Map the current JNDI location of a JMS connection factory to a local JNDI by:
    • Configuring a foreign JMS Server in a JMS system resource module.
    • Configuring credentials in the foreign JMS Server for users who have the required permissions.
  2. In the application code, use a JMS resource reference or inject a JMS context that references the local JNDI name of the JMS connection factory.


    It is a general best practice for server applications to use resource references or JMS context injection to reference a JMS connection factory regardless of whether you need an object-based security pattern or a thread-based security pattern.

    After the above requirements are met, WebLogic Server subsequently injects the credentials that you configured in the foreign JMS Server into every outbound send or consume call that originates from the given JMS connection factory.