17.2. Exposing EJBs via CORBA

There are two steps to exposing an EJB via CORBA: setting up the TSS, and then configuring the EJB to use that TSS.

17.2.1. Configuring a TSS

The TSS configuration process is extremely complex, but it is driven by an XML configuration block, making it somewhat easier to deal with. The XML configuration is embedded in a GBean declaration (see the examples in Section 17.2.1.6, “Sample TSS Configuration”), and that GBean can be listed in any Geronimo deployment plan (though again, it's often included in the EJB JAR plan or the plan for an EAR containing the EJB JAR). The TSS configuration block looks like this:

Figure 17.1. TSS Configuration: Overview

TSS Configuration: Overview

The elements and attributes introduced here are:

tss:inherit

Not currently used. In theory, ORBs may be nested and therefore a TSS may inherit settings from the containing ORB, but this is not implemented for the ORB used in Geronimo 1.0.

description

A standard J2EE description block, with a lang attribute to say which language it applies to.

default-principal

Specifies a default principal to use in cases where the remote caller does not authenticate or otherwise provide a principal to use. See Section 17.2.1.1, “Default Security Principal”.

SSL

Configures an SSL transport for the CORBA communication. See Section 17.2.1.2, “SSL Configuration”.

SECIOP

Not currently used. An alternate secure network transport, SECIOP is not currently supported by Geronimo.

compoundSecMechTypeList

Lists and configures the authentication and identification strategies supported by this TSS. The caller must use one of the methods configured here or else the connection will fail.

compoundSecMechTypeList:stateful

Not currently used. A caller may pass a large amount of security information to the server (potentially including material that must be decrypted, etc.). To avoid additional overhead on each call, the server may configure a stateful connection, and cache that information from the first request on. Geronimo does not presently support this.

compoundSecMech

Each element of this type holds a single configuration. The caller must provide the information required by one of these configurations in order for the communication to proceed. See Section 17.2.1.3, “Authentication/Identity Mechanisms”.

17.2.1.1. Default Security Principal

The default security principal configuration looks like this:

Figure 17.2. TSS Configuration: Default Principal

TSS Configuration: Default Principal

The elements used here are:

principal

Configures a principal using simple principal mapping. Principal elements are discussed in the next section.

login-domain-principal

Configures a principal using login domain specific mapping. Principal elements are discussed in the next section.

realm-principal

Configures a principal using login domain and realm specific mapping. Principal elements are discussed in the next section.

named-username-password-credential

Named credentials are used by external resources (e.g. a J2EE Connector or Web Service) that use per-user authentication, but require different authentication than the calling web application. So for example, a the default principal may be a user "jsmith" and this element can be used to set up a second credential ("john_smith" with password "foo") where that second credential is named "ws_credentials". Then when the user invokes a web service, the web service reference can be configured to look for and use a credential named "ws_credentials" instead of the normal principal. Normally named credentials are added by the Geronimo security realm, but in the case of the default principal, they must be manually configured here.

name

The name to store this credential under (ws_credentials in the example above)

username

The username that this credential should contain.

password

The password that this credential should contain.

17.2.1.1.1. Principal Types

There are three types of principal elements available to specify the default principal.

Principals are normally identified by their principal class and principal name. Both values must match one of the principals for the current user in order for the user to successfully qualify for the application role. However, if the Support Advanced Mapping flag is enabled for the login modules used by the security realm that produced the principals (see Chapter 9, Security Configuration [DRAFT (1.0-pre)]), those principals are also identified by their login domain name and realm name, and the security mapping process can distinguish based on those characteristics of the principal as well.

17.2.1.1.1.1. Simple Configuration using the principal Element

The principal element is the most straightforward of the three:

Figure 17.3. Web Application Security: Principals

Web Application Security: Principals

The attributes used here are:

principal:class

Each principal is represented by an object of a particular class by the security realm (e.g. an LDAP realm might use the classes com.foo.LDAPUser and com.foo.LDAPGroup). This attribute holds the fully qualified Java class name of the principal class. The class is necessary to distinguish between different types of principals that may have the same name (such as a group Administrator and a user Administrator). The principal classes used by the default Geronimo security realms are org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal (for users) and org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal (for groups).

principal:name

This attribute holds the name of the default principal.

principal:designated-run-as

This attribute should not be used for principals within the default-principal element.

17.2.1.1.1.2. Advanced Configuration using the login-domain-principal Element

The login-domain-principal element let principals be identified by the login module that produced them, as well as by their class and name:

Figure 17.4. Web Application Security: Login Domain Principals

Web Application Security: Login Domain Principals

This includes all the same attributes as the principal element, plus:

login-domain-principal:domain-name

Specifies the login domain name to use for the default principal. When the current component attempts other restricted actions, they may consider the domain name as well as the principal name and principal class to see if the principal is authorized.

17.2.1.1.1.3. Advanced Configuration using the realm-principal Element

The realm-principal element let principals be identified by the realm that they came from, as well as by their class, name, and login domain:

Figure 17.5. Web Application Security: Realm Principals

Web Application Security: Realm Principals

This includes all the same attributes as the login-domain-principal element, plus:

realm-principal:realm-name

Specifies the security realm name to use for the default principal. When the current component attempts other restricted actions, they may consider the realm name as well as the login domain name, principal name, and principal class to see if the principal is authorized.

17.2.1.2. SSL Configuration

The SSL block is used to configure a CORBA service to listen over SSL:

Figure 17.6. TSS Configuration: SSL

TSS Configuration: SSL

The elements used here are:

SSL:port

Configures the network port that this service should listen on. The client must look up the service using the CORBA naming service (which listens on port 1050 by default), but once the client contacts the EJB it will use SSL over this port.

SSL:hostname

Used to set the specific host name or IP address the service should listen on. Normally set to 0.0.0.0 or localhost, if not a specific host name for the server.

SSL:handshakeTimeout

Not currently used.

supports

A list of security properties that this SSL connection will support. The protocol will allow but not require these attributes to be negotiated for the connection. The most common values are Integrity, Confidentiality, EstablishTrustInTarget, and EstablishTrustInClient. Other possible values for SSL include DetectReplay and DetectMisordering. Multiple values can be provided and should be listed separated by spaces.

requires

A list of security properties that this SSL connection requires. If a client cannot support these, the connection will be refused. The most common values are Integrity, Confidentiality, EstablishTrustInTarget, and EstablishTrustInClient. Other possible values for SSL include DetectReplay and DetectMisordering. Multiple values can be provided and should be listed separated by spaces.

trustGroup

Not currently used. This is used to configure clients or hosts that Geronimo trusts automatically, but it is not enabled in Geronimo 1.0.

The values used for the supports and requires elements are:

Table 17.1. TSS Configuration: CORBA SSL Attributes

ValueDescription
IntegrityThe data en route should not be able to be altered by a third party.
ConfidentialityThe data en route should not be able to be observed by a third party.
EstablishTrustInTargetThe target (e.g. server or EJB) should prove its validity to the client (e.g. by providing a valid SSL certificate)
EstablishTrustInClientThe client should prove it's validity to the server. In practice, this option is used to require client certificates.
DetectReplayThe server should not be fooled if a third party replays some previous traffic from the client.
DetectMisorderingThe server should notice if traffic from the client arrives out of order.

17.2.1.3. Authentication/Identity Mechanisms

The compundSecurityMech block configures a group of security settings that the server accepts to identify the incoming user:

Figure 17.7. TSS Configuration: Security Mechanisms

TSS Configuration: Security Mechanisms

Normally any one client will only provide either GSSUP or SAS information (either authentication information or an identity token). However, the TSS may be configured to accept more than one, in order to work with a wider variety of clients. The elements and attributes used here are:

GSSUP

Configures the GSSUP protocol, which sends a username and password along with the connection request. If this is configured then the server will authenticate the user against a Geronimo security realm using the provided username and password.

GSSUP:targetName

Names the Geronimo security realm to use to validate the GSSUP username and password. Additionally, the provided GSSUP information must specify a matching domain name.

GSSUP:required

If set to true then clients who do not provide GSSUP information cannot connect to the EJB.

sasMech

Groups SAS settings, which includes the various identity token types the server should accept.

serviceConfigurationList

Not currently used.

identityTokenTypes

Lists the types of identity tokens the EJB should accept. If an identity token is accepted by the server, it is the same as if a user provided a username and password and was successfully authenticated. Therefore it's important that the server trust either the client or the authority that issued the token.

17.2.1.4. Identity Tokens

The identityTokenTypes block configures the identity tokens that the server should accept:

Figure 17.8. TSS Configuration: Identity Tokens

TSS Configuration: Identity Tokens

The elements introduced here are:

ITTAbsent

If this element is present, it indicates that only client who provide no identity token should be allowed to connect. This is normally used when the EJB will accept only GSSUP connections.

ITTAnonymous

If this element is present, it means a client should provide a token that asserts that the connection will be anonymous.

ITTPrincipalNameGSSUP

If this element is present, the client will provide a principal name (but no password or other credential). Geronimo will turn this into a Geronimo Principal for purposes of role mapping, etc.

ITTPrincipalNameGSSUP:principal-class

The fully-qualified Java class name of the Principal class that should be used to represent incoming users of this type. Normally, this is set to org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal.

ITTPrincipalNameGSSUP:domain

If specified, the principal will be wrapped with a login domain name (which is used for advanced role mapping scenarios). The value here is the name of the login domain to use.

ITTPrincipalNameGSSUP:realm

If specified, the principal will be wrapped with a security realm name (which is used for advanced role mapping scenarios). The value here is the name of the realm to use.

ITTDistinguishedName

If this element is present, the caller can provide an X500 distringuished name. A JAAS X500Principal will be created to represent the user, with the provided name.

ITTDistinguishedName:domain

If specified, the principal will be wrapped with a login domain name (which is used for advanced role mapping scenarios). The value here is the name of the login domain to use.

ITTDistinguishedName:realm

If specified, the principal will be wrapped with a security realm name (which is used for advanced role mapping scenarios). The value here is the name of the realm to use.

ITTX509CertChain

Not currently used. A client may provide a certificate chain, but Geronimo 1.0 does not yet validate provided certificate chains or use them to generate appropriate Principals. However, it's possible to configure SSL with EstablishTrustInClient, which requires that the client provide a valid client certificate in order to connect, and then a suitable default principal could be used.

17.2.1.5. EJB Security and CORBA Security

With the settings discussed in the previous sections, Geronimo will either produce principals directly or execute a login against a Geronimo login module to generate principals for the CORBA user. After that process is complete, the resulting principals will be compared to the EJB security constraints and EJB role mapping to determine whether the CORBA user can access the EJB they are trying to invoke, as well as any other EJBs invoked during that call.

A key issue is understanding what kind of principals will be produced for each CORBA authentication or identification method. These principals will be used for role mapping -- to determine which J2EE roles the user has. That in turn controls which EJBs or EJB methods the user can access.

Starting with the principals:

default-principal

If the user is not otherwise authenticated or identifies, the default principal applies. Whatever default principal is configured will be used for role mapping.

GSSUP

A username and password are provided. These are used to execute a login against the login module named by the targetName attribute. The principals produced by that login are used for role mapping.

ITTPrincipalNameGSSUP

The principal name is provided by the caller, and the principal class is determined by the principal-class attribute. Exactly one principal is created for the user, with that class and name. This principal is used for role mapping.

ITTDistinguishedName

The principal name is the distinguished name provided by the caller, and the principal class is javax.security.auth.x500.X500Principal. Exactly one principal is created for the user with that class and name. This principal is used for role mapping.

The role mapping process uses the role-mappings block of the openejb-jar.xml file to determine which roles a user has based on the principals produced by the methods above. Finally, those roles are compared to the method permissions declared in ejb-jar.xml to determine whether the caller can access the targeted EJB.

Example 17.2. CORBA Security & Role Mapping

If the ejb-jar.xml deployment descriptor looks like this:

<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
         version="2.1">
  <!-- ...  EJBs listed here -->
  <assembly-descriptor>
    <security-role>
      <role-name>User</role-name>
    </security-role>
    <method-permission>
      <role-name>User</role-name>
      <method>
        <ejb-name>CORBASessionBean</ejb-name>
        <method-name>*</method-name>
      </method>
    </method-permission>
  </assembly-descriptor>
</ejb-jar>

Then it should be clear that any caller need the User role to access the EJB CORBASessionBean. Now, if the Geronimo deployment plan looks like this:

<openejb-jar
  xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.0"
  xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
  configId="CORBA-EJBs">
  <!-- ...  EJBs listed here -->
  <security:security>
    <security:default-principal>
      <security:principal
           class="org.apache.geronimo.security.realm.providers.
                                           GeronimoUserPrincipal"
           name="anonymous" />
    </security:default-principal>
    <security:role-mappings>
      <security:role role-name="User">
        <security:principal
           class="org.apache.geronimo.security.realm.providers.
                                           GeronimoUserPrincipal"
           name="system" />
      </security:role>
    </security:role-mappings>
  </security:security>
  <!-- ...  TSS listed here -->
</openejb-jar>

Then we're saying that only a caller with the principal system (with class org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal) counts as a member of the User role (which, from before, is required to access the EJB in question). Meanwhile unauthenticated callers are given the principal anonymous.

With this setup we can draw the following conclusions:

  • A caller who does not authenticate, or who uses only the ITTAbsent or ITTAnonymous identity token, will not be able to invoke the CORBASessionBean. At best they will be given the anonymous principal, and anonymous is not a member of the User role.

  • If the TSS is configured for GSSUP and the caller provides a user and password, then it is up to the security realm configured for GSSUP (identified by the targetName attribute) to determine whether the authentication succeeds and what principals to give the user. If they get the system principal with the correct principal class then they can access the session bean, otherwise not.

  • If the TSS is configured for ITTPrincipalNameGSSUP, then the principal-class attribute must be set to org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal or else there's no possibility that the caller will qualify for the User role. Even if the class is correct, the caller must provide the principal name system for the invocation to work.

  • If the TSS is configured for ITTDistinguishedName then there's no possibility that the caller can access the session bean because there are no X500Principal entries in the role mapping for the User role.

  • If more than one of the above strategies are configured, then at least one of them must grant access to the caller, based on the security information the caller provides.

17.2.1.6. Sample TSS Configuration

A sample TSS might look like this:

Example 17.3. TSS Configuration: GSSUP Only

This TSS configures a standard SSL connection (with optional client certificates), and accepts GSSUP connections only:

<gbean name="TSS-SSLWithGSSUP" class="org.openejb.corba.TSSBean">
  <attribute name="POAName">TSS-SSLWithGSSUP</attribute>
  <reference name="Server">
    <application>null</application>
    <moduleType>J2EEModule</moduleType>
    <module>geronimo/j2ee-corba/1.0/car</module>
    <name>Server</name>
  </reference>
  <xml-attribute name="tssConfig">
    <tss:tss
   xmlns:tss="http://www.openejb.org/xml/ns/corba-tss-config-2.0"
   xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1">
      <tss:default-principal>
        <sec:principal 
            class="org.apache.geronimo.security.realm.providers.
                                           GeronimoUserPrincipal"
            name="guest"/>
      </tss:default-principal>
      <tss:SSL port="2001" hostname="localhost">
        <tss:supports>
          Integrity Confidentiality EstablishTrustInTarget
          EstablishTrustInClient
        </tss:supports>
        <tss:requires>Integrity Confidentiality</tss:requires>
      </tss:SSL>
      <tss:compoundSecMechTypeList>
        <tss:compoundSecMech>
          <tss:GSSUP required="true"
                     targetName="geronimo-properties-realm"/>
          <tss:sasMech>
            <tss:identityTokenTypes>
              <tss:ITTAbsent/>
            </tss:identityTokenTypes>
          </tss:sasMech>
        </tss:compoundSecMech>
      </tss:compoundSecMechTypeList>
    </tss:tss>
  </xml-attribute>
</gbean>

Note that the principal class name has been split across lines to fit the page, but must be combined if this example is deployed!

Another example might look like this:

Example 17.4. TSS Configuration: Client Cert and Identity

This TSS configures a SSL connection (with mandatory client certificates), and it trusts the identity provided by the client:

<gbean name="TSS-ClientCert" class="org.openejb.corba.TSSBean">
  <attribute name="POAName">TSS-ClientCert</attribute>
  <reference name="Server">
    <application>null</application>
    <moduleType>J2EEModule</moduleType>
    <module>geronimo/j2ee-corba/1.0/car</module>
    <name>Server</name>
  </reference>
  <xml-attribute name="tssConfig">
    <tss:tss
   xmlns:tss="http://www.openejb.org/xml/ns/corba-tss-config-2.0"
   xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1">
      <tss:default-principal>
        <sec:principal 
            class="org.apache.geronimo.security.realm.providers.
                                           GeronimoUserPrincipal"
            name="guest"/>
      </tss:default-principal>
      <tss:SSL port="2001" hostname="localhost">
        <tss:supports>
          Integrity Confidentiality EstablishTrustInTarget
          EstablishTrustInClient
        </tss:supports>
        <tss:requires>
          Integrity Confidentiality EstablishTrustInTarget
          EstablishTrustInClient
        </tss:requires>
      </tss:SSL>
      <tss:compoundSecMechTypeList>
        <tss:compoundSecMech>
          <tss:sasMech>
            <tss:identityTokenTypes>
              <tss:ITTAnonymous />
              <tss:ITTPrincipalNameGSSUP
principal-class="org.apache.geronimo.security.realm.providers.
                                         GeronimoUserPrincipal"/>
              <tss:ITTDistinguishedName/>
            </tss:identityTokenTypes>
          </tss:sasMech>
        </tss:compoundSecMech>
      </tss:compoundSecMechTypeList>
    </tss:tss>
  </xml-attribute>
</gbean>

Note that the principal class names have been split across lines to fit the page, but must be combined if this example is deployed!

17.2.2. Configuring an EJB for CORBA

To expose an EJB via CORBA, the EJB is declared like normal in ejb-jar.xml, but additional settings are required in the Geronimo deployment plan. The plan format is described in detail in Chapter 12, Enterprise Java Beans (EJB JARs) [DRAFT (1.0)], but in short, each EJB must declare a JNDI name (also used as the CORBA naming service name) and a TSS reference -- and then the TSS itself is normally included in the same file. As well, the EJB JAR should import the Geronimo CORBA configuration, to ensure that the CORBA name server and other core services are started.

[Note]Note

Any EJB to be exposed via CORBA must have a Remote interface; a Local-only EJB will not work.

Example 17.5. CORBA EJB Deployment Plan

The openejb-jar.xml exposing a single session bean via CORBA might look like this:

<?xml version="1.0" encoding="UTF-8"?>

<openejb-jar
  xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.0"
  xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0"
  configId="CORBA-EJBs">

<!-- Make sure the CORBA name server is started -->
  <sys:import>
    <sys:uri>geronimo/j2ee-corba/1.0/car</sys:uri>
  </sys:import>

<!-- The CORBA EJBs -->
  <enterprise-beans>
    <session>
      <ejb-name>SomeSessionBean</ejb-name>
      <jndi-name>CORBASessionBean</jndi-name>
      <tss-link>TSS-SSLWithGSSUP</tss-link>
    </session>
  </enterprise-beans>

<!-- The TSS to use for these EJBs -->
  <sys:gbean name="TSS-SSLWithGSSUP"
             class="org.openejb.corba.TSSBean">
    ... (see above) ...
  </sys:gbean>
</openejb-jar>