There are two steps to exposing an EJB via CORBA: setting up the TSS, and then configuring the EJB to use that 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:
The elements and attributes introduced here are:
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.
A standard J2EE description block, with a lang attribute to say which language it applies to.
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”.
Configures an SSL transport for the CORBA communication. See Section 17.2.1.2, “SSL Configuration”.
Not currently used. An alternate secure network transport, SECIOP is not currently supported by Geronimo.
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.
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.
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”.
The default security principal configuration looks like this:
The elements used here are:
Configures a principal using simple principal mapping. Principal elements are discussed in the next section.
Configures a principal using login domain specific mapping. Principal elements are discussed in the next section.
Configures a principal using login domain and realm specific mapping. Principal elements are discussed in the next section.
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.
The name to store this credential under (ws_credentials in the example above)
The username that this credential should contain.
The password that this credential should contain.
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.
The principal element is the most straightforward of the three:
The attributes used here are:
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).
This attribute holds the name of the default principal.
This attribute should not be used for principals within the default-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:
This includes all the same attributes as the principal element, plus:
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.
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:
This includes all the same attributes as the login-domain-principal element, plus:
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.
The SSL block is used to configure a CORBA service to listen over SSL:
The elements used here are:
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.
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.
Not currently used.
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.
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.
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
Value | Description |
---|---|
Integrity | The data en route should not be able to be altered by a third party. |
Confidentiality | The data en route should not be able to be observed by a third party. |
EstablishTrustInTarget | The target (e.g. server or EJB) should prove its validity to the client (e.g. by providing a valid SSL certificate) |
EstablishTrustInClient | The client should prove it's validity to the server. In practice, this option is used to require client certificates. |
DetectReplay | The server should not be fooled if a third party replays some previous traffic from the client. |
DetectMisordering | The server should notice if traffic from the client arrives out of order. |
The compundSecurityMech block configures a group of security settings that the server accepts to identify the incoming user:
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:
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.
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.
If set to true then clients who do not provide GSSUP information cannot connect to the EJB.
Groups SAS settings, which includes the various identity token types the server should accept.
Not currently used.
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.
The identityTokenTypes block configures the identity tokens that the server should accept:
The elements introduced here are:
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.
If this element is present, it means a client should provide a token that asserts that the connection will be anonymous.
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.
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.
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.
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.
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.
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.
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.
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.
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:
If the user is not otherwise authenticated or identifies, the default principal applies. Whatever default principal is configured will be used for role mapping.
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.
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.
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.
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!
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 | |
---|---|
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>