User: starksm
Date: 01/04/05 01:31:21
Modified: src/docs jbosssx.xml
Log:
Further refine the content.
Revision Changes Path
1.6 +151 -168 manual/src/docs/jbosssx.xml
Index: jbosssx.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbosssx.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- jbosssx.xml 2001/04/02 03:25:40 1.5
+++ jbosssx.xml 2001/04/05 08:31:21 1.6
@@ -1,8 +1,8 @@
<?xml version = "1.0" encoding = "UTF-8"?>
-<!-- Version: $Revision: 1.5 $ -->
+<!-- Version: $Revision: 1.6 $ -->
<?xml-stylesheet href =
'file:///D:/usr/local/src/cvsroot/jBoss/manual/src/docs/jboss.xsl' type = 'text/xsl'?>
-<chapter id="JBossSX">
+<chapter id = "JBossSX">
<title>JBossSX Security Extension Framework</title>
<subtitle>Security in JBoss</subtitle>
<para>
@@ -12,9 +12,9 @@
</author>
<email>[EMAIL PROTECTED]</email>
</para>
- <caution>
- <para>This is still a very rough draft so read at your own risk</para>
- </caution>
+ <note>
+ <para>This is still a rough draft</para>
+ </note>
<section id = "sx.Introduction">
<title>Introduction</title>
<para>The JBossSX security extension provides support for both the
@@ -44,37 +44,20 @@
</para>
<section>
<title>Declarative Security Setup</title>
- <para>The EJB1.1 declarative security model is
specified using the
- ejb-jar security-role and method-permission elements.
- <xref linkend = "sx.ejb-jar.SecurityElements"/> illustrates
the security related
- elements of the ejb-jar.xml deployment descriptor.
- <figure id = "sx.ejb-jar.SecurityElements">
- <title>EJB 1.1 ejb-jar.xml Security
Elements</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref =
"images/ejb_11_security_dtd.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- </para>
- <para>The application assembler defines the required
method permissions
- for each security role. A method permission is a permission
to invoke a
- specified group of methods of the enterprise beans' home and
remote interfaces.
- A security role is a semantic grouping of method permissions.
A user must have
- have at least one security role associated with a method they
invoke. Because
- the application assembler does not, in general, know the
security environment
- of the operational environment, the security roles are meant
to be logical
- roles, each representing a type of user that should have the
same access rights
- to the grouping of methods.
- <note>
+ <para>The EJB1.1 declarative security model is
specified using the ejb-jar security-role and method-permission elements. <xref
linkend = "sx.ejb-jar.SecurityElements"/> illustrates the security related elements
of the ejb-jar.xml deployment descriptor.</para>
+ <figure id = "sx.ejb-jar.SecurityElements">
+ <title>EJB 1.1 ejb-jar.xml Security
Elements</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref =
"images/ejb_11_security_dtd.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The application assembler defines the required
method permissions for each security role. A method permission is a permission to
invoke a specified group of methods of the enterprise beans' home and remote
interfaces. A security role is a semantic grouping of method permissions. A user must
have at least one security role associated with a method in or to have permission
invoke the method. Because the application assembler does not, in general, know the
security environment of the operational environment, the security roles are meant to
be logical roles, each representing a type of user that should have the same access
rights to the grouping of methods.
+ <note>
<title>What is a Role</title>
- <para>From
- <citetitle pubwork = "article">Enterprise JavaBeans
Specification,
- v1.1, Section 15.3</citetitle>: <quote>It is
important to keep in mind that the
- security roles are used to define the logical
security view of an application.
- They should not be confused with the user groups,
users, principals, and other
- concepts that exist in the target enterprise's
operational environment.</quote>
- </para>
+ <para>From <citetitle pubwork =
"article">Enterprise JavaBeans Specification, v1.1, Section 15.3</citetitle>:
<quote>It is important to keep in mind that the security roles are used to define the
logical security view of an application. They should not be confused with the user
groups, users, principals, and other concepts that exist in the target enterprise's
operational environment.</quote>
+ </para>
</note>
</para>
<para>A security role is defined using the following
ejb-jar
@@ -139,48 +122,44 @@
]]></programlisting>
</example>
</para>
- <para>From
- <citetitle pubwork = "article">Enterprise JavaBeans
Specification,
- v1.1, Section 15.3.2</citetitle>, If the application
assembler has defined
- security roles for the enterprise beans in the ejb-jar file,
they can also
- specify the methods of the remote and home interface that
each security role is
- allowed to invoke. The sssembler defines the method
permissions relation in the
- deployment descriptor using the method-permission elements as
follows.
- <itemizedlist>
- <listitem>
- <para>Each method-permission
element includes a list of one or
+ <para>From <citetitle pubwork = "article">Enterprise
JavaBeans Specification, v1.1, Section 15.3.2</citetitle>, If the application
assembler has defined security roles for the enterprise beans in the ejb-jar file,
they can also specify the methods of the remote and home interface that each security
role is allowed to invoke. The assembler defines the method permissions relation in
the deployment descriptor using the method-permission elements as follows. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Each method-permission element
includes a list of one or
more security roles and a list of one or more
methods. All the listed security
roles are allowed to invoke all the listed
methods.</para>
- </listitem>
- <listitem>
- <para>Each security role in
the list is identified by the
+ </listitem>
+ <listitem>
+ <para>Each security role in the list
is identified by the
role-name element, and each method (or a set
of methods, as described below) is
identified by the method element. An optional
description can be associated
with a method-permission element using the
description element.</para>
- </listitem>
- <listitem>
- <para>The method permissions
relation is defined as the union of
+ </listitem>
+ <listitem>
+ <para>The method permissions relation
is defined as the union of
all the method permissions defined in the
individual method-permission
elements.</para>
- </listitem>
- <listitem>
- <para>A security role or a
method may appear in multiple
+ </listitem>
+ <listitem>
+ <para>A security role or a method may
appear in multiple
method-permission elements. It is possible
that some methods are not assigned
to any security roles. This means that none
of the security roles defined by
the Application Assembler needs access to the
methods.</para>
- </listitem>
- </itemizedlist>
- </para>
+ </listitem>
+ </itemizedlist>
+
<para>The method element uses the ejb-name,
method-name, and
method-params elements to denote one or more methods of an
enterprise bean's
home and remote interfaces. There are three legal styles for
composing the
- method element:
- <variablelist>
- <varlistentry>
- <term>Style 1:</term>
- <listitem>
- <para>
-
<literallayout><![CDATA[
+ method element: </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Style 1:</term>
+ <listitem>
+ <para>
+
<literallayout><![CDATA[
<method>
<ejb-name>EJBNAME</ejb-name>
@@ -188,13 +167,13 @@
</method>
]]></literallayout>This style is used for referring to all of the remote and
home interface methods of a specified
enterprise bean.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Style 2:</term>
- <listitem>
- <para>
-
<literallayout><![CDATA[
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Style 2:</term>
+ <listitem>
+ <para>
+
<literallayout><![CDATA[
<method>
<ejb-name>EJBNAME</ejb-name>
<method-name>METHOD</method-name>
@@ -203,13 +182,13 @@
the remote or home interface of the
specified enterprise bean. If there are
multiple methods with the same
overloaded name, this style refers to all of the
overloaded methods.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Style 3:</term>
- <listitem>
- <para>
-
<literallayout><![CDATA[
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Style 3:</term>
+ <listitem>
+ <para>
+
<literallayout><![CDATA[
<method>
<ejb-name>EJBNAME</ejb-name>
<method-name>METHOD</method-name>
@@ -224,10 +203,10 @@
specified enterprise bean's remote or
home interface. The optional method-intf
element can be used to differentiate
methods with the same name and signature
that are defined in both the remote
and home interfaces.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<para>The following EJB 1.1 spec example illustrates
how security roles
are assigned method permissions in the deploymentvdescriptor:
<example id = "sx.security-role-assignment.example">
@@ -270,24 +249,12 @@
...]]></programlisting>
</example>
</para>
- <para>The handling of declarative method permissions
is handled by the
- SecurityInterceptor. When a method is invoked, the
SecurityInterceptor obtains
- the set of roles declared in method-permission elements for
the method and
- invokes RealmMapping.doesUserHaveRole(principal, methodRoles)
to see if the
- prinicipal invoking the method has one of the roles in the
methodRoles set.
- When the JaasSecurityManager is used as the RealmMapping
implementation, the
- association of what roles a principal has occurs during
authentication. One or
- more of the LoginModules associated with the security domain
assigns the roles
- the principal belongs to the JAAS Subject instance that is
created by the login
- process. The roles found in the Subject are then used by the
- JaasSecurityManager in its RealmMapping
implementation.</para>
+ <para>The check of declarative method permissions is
handled by the JBoss container SecurityInterceptor. When a method is invoked, the
SecurityInterceptor obtains the set of roles declared in method-permission elements
for the method and invokes RealmMapping.doesUserHaveRole(principal, methodRoles) to
see if the prinicipal invoking the method has one of the roles in the methodRoles set.
When the JaasSecurityManager is used as the RealmMapping implementation, the
association of what roles a principal has occurs during authentication. One or more of
the LoginModules associated with the security domain assigns the roles the principal
belongs to the JAAS Subject instance that is created by the login process. The roles
found in the Subject are then used by the JaasSecurityManager in its RealmMapping
implementation.</para>
</section>
</section>
<section>
<title>EJB Custom Security</title>
- <para>While a good concept, in general I have found that the
declarative
- security model is too simplistic to cover business application
security
- requirements. Reasons for this include:</para>
+ <para>While a good concept, in general the declarative
security model is often too simplistic to cover business application security
requirements. Reasons for this include:</para>
<itemizedlist>
<listitem>
<para>method permissions can be a function of
the method arguments or
@@ -371,26 +338,13 @@
</section>
<section id = "sx.security-proxy">
<title>The JBossSX Security Proxy Model</title>
- <para>The custom security solution that the JBossSX
framework offers is
- an extension of the method interceptor paradigm. We will see
the details of
- this in <xref linkend = "sx.jboss.security-model"/>. The
concept of the security
- proxy is an implementation of the <quote>protection
proxy</quote> form of the
- Proxy pattern described in the
- <citetitle>Design Patterns</citetitle> book. The security
proxy model
- allows for development of an implementation of the business
object remote or
- home interface whose sole responsibility is the
implementation of the
- per-method security logic. This implementation object is the
security proxy.
- The container method interceptors first dispatch home and
remote method
- invocations to the security proxy for custom security logic
validation. If the
- security requirements are satisfied, the method invocation is
dispatched to the
- business logic EJB. If the security requirements are not
satisfied, a security
- exception is raised and the method invocation is
halted.</para>
+ <para>The custom security solution that the JBossSX
framework offers is an extension of the method interceptor paradigm. We will see the
details of this in <xref linkend = "sx.jboss.security-model"/>. The concept of the
security proxy is an implementation of the <quote>protection proxy</quote> form of the
Proxy pattern described in the <citetitle>Design Patterns</citetitle> book. The
security proxy model allows for development of an implementation of the business
object remote or home interface whose sole responsibility is the implementation of the
per-method security logic. This implementation object is the security proxy. The
container method interceptors first dispatch home and remote method invocations to the
security proxy for custom security logic validation. If the security requirements are
satisfied, the method invocation is dispatched to the business logic EJB. If the
security requirements are not satisfied, a security exception is raised and the method
invocation is halted.</para>
</section>
</section>
</section>
<section id = "sx.jboss.security-model">
<title>The JBoss Security Model</title>
- <para>The security model in JBoss is based on the server container
architecture's pluggable method interceptors. JBossSX itegrates into the JBoss server
through the server container interceptor chain. Container security is handled by the
org.jboss.ejb.plugins.SecurityInterceptor class. The SecurityInterceptor class relies
on implementations of three security interfaces:</para>
+ <para>The security model in JBoss is based on the server container
architecture's pluggable method interceptors. JBossSX integrates into the JBoss server
through the server container interceptor chain. Container security is handled by the
org.jboss.ejb.plugins.SecurityInterceptor class. The SecurityInterceptor class relies
on implementations of three security interfaces:</para>
<programlisting>package org.jboss.security; public interface
EJBSecurityManager
{
public boolean isValid(java.security.Principal principal, Object credential);
@@ -412,7 +366,7 @@
<varlistentry>
<term>org.jboss.security.EJBSecurityManager</term>
<listitem>
- <para>An interface responsible for validating
credentials associated with principals. Principals are identities and include things
like usernames, eployee numbers, social security numbers, etc. Credentials are proof
of the identity and include things like passwords, session keys, digital signatures,
etc.</para>
+ <para>An interface responsible for validating
credentials associated with principals. Principals are identities and include things
like usernames, employee numbers, social security numbers, etc. Credentials are proof
of the identity and include things like passwords, session keys, digital signatures,
etc.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -445,53 +399,56 @@
</imageobject>
</mediaobject>
</figure>
- <para>JBoss includes a default implementation of the
EJBSecurityManager and RealmMapping interfaces in a single implementation class in the
org.jboss.security.plugins.JaasSecurityManager class. It is a JAAS based class that
relies on JAAS LoginModules establishing the Principal identity and roles in the
authenticated Subject Principals set. When using the JaasSecurityManager, integration
with your security environments authentication and role mapping logic is achieved by
writing custom javax.security.auth.spi.LoginModule implementations. The
JaasSecurityManager will be discussed in detail in the next section.</para>
+ <para>JBossSX includes a default implementation of the
EJBSecurityManager and RealmMapping interfaces in a single implementation class:
org.jboss.security.plugins.JaasSecurityManager. It is a JAAS based implementation that
relies on JAAS LoginModules to establish the Principal identity and roles in the
authenticated Subject Principals set. When using the JaasSecurityManager, integration
with your security environments authentication and role mapping logic is achieved by
writing custom javax.security.auth.spi.LoginModule implementations. The
JaasSecurityManager will be discussed in detail in the next section.</para>
<para>Note that the security interfaces have no reliance on JAAS
specific classes. If you don't want to use JAAS for your security implementation or
integration you are free to write your own security manager implementation.</para>
</section>
<section id = "sx.JaasSecurityManager">
- <title>The JBossSX Default Security Manager</title>
+ <title>The JBossSX Default Security Manager:
JaasSecurityManager</title>
<para>This section will go into the details of the default JBoss
security manager implementation to illustrate the interaction between the
SecurityInterceptor and the security interfaces as well as usage of the
JaasSecurityManager.</para>
- <para>The default security implementation that JBoss comes
pre-configured with is a JMX service bean and a JAAS based implementation of the
EJBSecurityManager and RealmMapping interfaces. The JMX bean is
org.jboss.security.plugins.JaasSecurityManagerService and the security interfaces
implementation is org.jboss.security.plugins.JaasSecurityManager. However, by default
none of the EJB container configurations require security. To secure your EJBs you
must either change the default container configurations or specify the container
configuration at deployment time. The standard container configuration is found in the
config/config-name/standardjboss.xml directory of the JBoss distribution tree. The
<quote>config-name</quote> value is <quote>default</quote> by default. When specifying
container configurations at deployment time you include a jboss.xml descriptor in your
ear or ejb-jar META-INF directory. The key DTD elements for security configuration
elements is given <xref linkend = "sx.jboss.security-config.dtd"/>
- </para>
- <figure id = "sx.jboss.security-config.dtd">
- <title>standardjboss.xml/jboss.xml Deployment Descriptor
Security Configuration Elements</title>
- <mediaobjectco>
- <imageobjectco>
- <areaspec units = "calspair">
- <area id = "security.domain.element"
coords = "300 400"/>
- <area id =
"role.mapping.manager.element" coords = "300 400"/>
- <area id =
"authentication.module.element" coords = "300 400"/>
- <area id = "security.proxy.element"
coords = "300 400"/>
- </areaspec>
- <imageobject>
- <imagedata fileref =
"images/jbosssx/sx.jbossSecurityDTD.jpg"/>
- </imageobject>
- <calloutlist>
- <callout arearefs =
"security.domain.element">
- <para>The security-domain
element specifies the JNDI name of
+ <para>The default security implementation that JBoss comes
preconfigured with consists of a JMX service MBean and a JAAS based implementation of
the EJBSecurityManager and RealmMapping interfaces. The JMX bean is
org.jboss.security.plugins.JaasSecurityManagerService and the security interfaces
implementation is org.jboss.security.plugins.JaasSecurityManager. The JMX service
MBean handles configurable aspects of the security manager and integrates the security
manager into the JNDI namespace.</para>
+ <section>
+ <title>Enabling EJB Security</title>
+ <para>Even though there is a preconfigured security manager
with the JBoss distribution, by default none of the EJB container configurations
require security. The reason for this is that security may not be required and there
is no way to provide a reasonable default setup. To secure your EJBs you must either
change the default container configurations or specify the container configuration at
deployment time. The standard container configuration is found in the
config/config-name/standardjboss.xml directory of the JBoss distribution tree. The
<quote>config-name</quote> value is <quote>default</quote> by default. When specifying
container configurations at deployment time you include a jboss.xml descriptor in your
ear or ejb-jar META-INF directory. The key DTD elements for security configuration
elements is given <xref linkend = "sx.jboss.security-config.dtd"/>
+ </para>
+ <figure id = "sx.jboss.security-config.dtd">
+ <title>standardjboss.xml/jboss.xml Deployment
Descriptor Security Configuration Elements</title>
+ <mediaobjectco>
+ <imageobjectco>
+ <areaspec units = "calspair">
+ <area id =
"security.domain.element" coords = "300 400"/>
+ <area id =
"role.mapping.manager.element" coords = "300 400"/>
+ <area id =
"authentication.module.element" coords = "300 400"/>
+ <area id =
"security.proxy.element" coords = "300 400"/>
+ </areaspec>
+ <imageobject>
+ <imagedata fileref =
"images/jbosssx/sx.jbossSecurityDTD.jpg"/>
+ </imageobject>
+ <calloutlist>
+ <callout arearefs =
"security.domain.element">
+ <para>The
security-domain element specifies the JNDI name of
application wide security manager instance.
This is an object that implements
both the EJBSecurityMgr and RealmMapping
interfaces. This element is typically
used to establish the same security manager
across all deployment module
containers rather than specifying the
EJBSecurityMgr and RealmMapping instance
for each container.</para>
- </callout>
- <callout arearefs =
"role.mapping.manager.element">
- <para>The role.mapping.manager
element specifies the JNDI name
+ </callout>
+ <callout arearefs =
"role.mapping.manager.element">
+ <para>The
role.mapping.manager element specifies the JNDI name
of the RealmMapping interface instance to use
for the container. This overrides
any security-domain setting. A
role.mapping.manager element may be specified
without a authentication.module
element if there is a security-domain element.
In this case an alternate role mapping
implementation is used for the
container.</para>
- </callout>
- <callout arearefs =
"authentication.module.element">
- <para>The
authentication.module element specifies the JNDI name
+ </callout>
+ <callout arearefs =
"authentication.module.element">
+ <para>The
authentication.module element specifies the JNDI name
of the EJBSecurityMgr interface
instance to use for the container. This
overrides any security-domain setting.
When the authentication.module is
specified for a container there must
also be a role.mapping.manager element
specified.</para>
- </callout>
- <callout arearefs =
"security.proxy.element">
- <para>The security.proxy
element specifies gives the class name
+ </callout>
+ <callout arearefs =
"security.proxy.element">
+ <para>The
security.proxy element specifies gives the class name
of the security proxy implementation.
This may be an instance of
org.jboss.security.SecurityProxy, or
an just an object that implements methods
in the home or remote interface of an
EJB without implementating any common
@@ -500,11 +457,12 @@
SecurityProxy implementation that
delegates the method invocations to the
object. The
org.jboss.security.SubjectSecurityProxy is an example
implementation used by the
JaasSecurityManager class.</para>
- </callout>
- </calloutlist>
- </imageobjectco>
- </mediaobjectco>
- </figure>
+ </callout>
+ </calloutlist>
+ </imageobjectco>
+ </mediaobjectco>
+ </figure>
+ </section>
<section>
<title>JaasSecurityManagerService MBean</title>
<para>The JaasSecurityManagerService is a JMX MBean that
handles the configuration of security. This includes the security manager
implementation, the security proxy factory and the authentication cache policy.</para>
@@ -525,7 +483,7 @@
<varlistentry>
<term>AuthenticationCacheJndiName</term>
<listitem>
- <para>This is the JNDI name of the
org.jboss.util.CachePolicy instance that is to be used for caching of authentication
information. The cache is made available to the SecurityManager class if it implements
a setCachePolicy(CachePolicy) method.</para>
+ <para>This is the JNDI name of the
org.jboss.util.CachePolicy instance that is to be used for caching of authentication
information. The cache is made available to the security manager class if it
implements a <function>setCachePolicy(CachePolicy)</function> method. </para>
</listitem>
</varlistentry>
</variablelist>
@@ -546,11 +504,22 @@
]]></programlisting>
</example>
- <para>The JaasSecurityManagerService manages the association
of security manager instances to container SecurityInterceptors by implementing the
JNDI ObjectFactory interface and binding itself under java:/jaas in the JNDI
namespace. This allows one to use a naming convention of the form java:/jaas/XYZ to
access the security manager instance for the XYZ security domain. The security manager
instance is created on the first lookup by creating an instance of the
SecurityManagerClassName using a constructor that takes the name of the security
domain.</para>
+ <para>The JaasSecurityManagerService manages the association
of security manager instances to container SecurityInterceptors by implementing the
JNDI ObjectFactory interface and binding itself under java:/jaas in the JNDI
namespace. This allows one to use a naming convention of the form java:/jaas/XYZ to
access the security manager instance for the XYZ security domain. The security manager
instance is created on the first lookup by creating an instance of the
SecurityManagerClassName using a constructor that takes the name of the security
domain. For example, consider the following container security configuration
snippet:</para>
+ <figure id = "sx.JaasSecurityManager.container.xmlet">
+ <title>Example Container Security Configuration
Snippet</title>
+ <programlisting><![CDATA[
+<jboss>
+ <!-- Configure all containers to be secured under the "hades" security domain
-->
+ <security-domain>java:/jaas/hades</security-domain>
+ ...
+</jboss>
+]]></programlisting>
+ </figure>
+ <para>Any lookup on the JBoss JNDI IntialContext of the name
"java:/jaas/hades" will return a security manager instance that has been associated
with the security domain named "hades". This security manager will implement the
EJBSecurityMgr and RealmMapping security interfaces and will be of type
SecurityManagerClassName.</para>
</section>
<section>
<title>Inside the JaasSecurityManager</title>
- <para>As mentioned in the previous section, the
JaasSecurityManager is the default choice for the security manager implementation
class. Is uses the Java Authentication and Authorization Service(JAAS) extension to
implement its behavior. In particular, the behavior derives from the use of the login
modules(javax.security.auth.spi.LoginModule) whose configuration entry name matches
that of the security domain to which the JaasSecurityManager has been assigned. The
login modules implement the principal authentication and role mapping behavior for the
security domain. Hence, the JaasSecurityManager can be used across very different
security domains simply by plugging in different login module configurations for the
domains.</para>
+ <para>As mentioned in the previous section, the
JaasSecurityManager is the default choice for the security manager implementation
class. It uses the Java Authentication and Authorization Service(JAAS) packages to
implement its behavior. In particular, the behavior derives from the use of the login
modules(javax.security.auth.spi.LoginModule) whose configuration entry name matches
that of the security domain to which the JaasSecurityManager has been assigned. The
login modules implement the principal authentication and role mapping behavior for the
security domain. Hence, the JaasSecurityManager can be used across very different
security domains simply by plugging in different login module configurations for the
domains.</para>
<section>
<title>The Authentication Process</title>
<para>Consider a client that is invoking a method on
an EJB that has been configured to use a JaasSecurityManager instance for security.
<xref linkend = "sx.ClientAuthOverview"/> gives a diagram of some the components
involved in the access security check process.</para>
@@ -564,13 +533,13 @@
</figure>
<procedure>
<step>
- <para>The client first has to perform
a login to establish the principal and credentials that will be used for
authentication purposes. This entails creating a LoginContext and passing the name of
the configuration to use. In the above figure this is "beanDomain". This is a one time
process that associates the login principal and credentials with all subsequent EJB
method invocations. Note that the login process may not actually authenticate the
user. It depends on the login module configuration. In <xref linkend =
"sx.ClientAuthOverview"/> the beanDomain client side configuration is using the
ClientLoginModule(org.jboss.security.ClientLoginModule) and this module does not
perform client side authentication. It simply binds the username and password to the
EJB invocation layer for later authentication on the server.</para>
+ <para>The client first has to perform
a login to establish the principal and credentials that will be used for
authentication purposes. This entails creating a LoginContext and passing the name of
the configuration to use. In the above figure the configuration name is "beanDomain".
This is a one time process that associates the login principal and credentials with
all subsequent EJB method invocations. Note that the login process may not actually
authenticate the user. It depends on the login module configuration. In <xref linkend
= "sx.ClientAuthOverview"/> the beanDomain client side configuration is using the
ClientLoginModule(org.jboss.security.ClientLoginModule) and this module does not
perform client side authentication. It simply binds the username and password to the
JBoss EJB invocation layer for later authentication on the server.</para>
</step>
<step>
<para>The client at some later point
obtains the home interface for an EJB and attempts to create a bean. This results in a
home interface method invocation that is sent to the JBoss server. The invocation
includes the method arguments passed by the client along with the user identity and
credentials.</para>
</step>
<step>
- <para>The first step of the security
check is to authenticate the user invoking the call. As on the client side, this
involves invoking the login modules that are configured for the security domain the
EJB is secured under. If the user is authenticated, a JAAS Subject is created that
contains the following in its PrincipalsSet:</para>
+ <para>The first step of the security
check is to authenticate the user invoking the call. As on the client side, this
involves invoking the login modules that are configured for the security domain the
EJB is secured under. In the figure the EJB security domain is also named
"beanDomain". If the user is authenticated, a JAAS Subject is created that contains
the following in its PrincipalsSet:</para>
<itemizedlist>
<listitem>
<para>A Principal that
corresponds to the client identity</para>
@@ -582,12 +551,18 @@
<para>An optional
Group named "CallerPrincipal" that contains a single Principal that corresponds to the
identity of the caller in the application domain. This is the value returned by the
EJBContext getCallerPrincipal() method.</para>
</listitem>
</itemizedlist>
+ <note>
+ <para>This usage pattern of
the Subject Principals set is the standard usage that JBossSX expects of server side
login modules. To ensure proper conformance to this pattern any custom login module
you write should subclass the JBossSX AbstractServerLoginModule class. See <xref
linkend = "sx.loginmodules"/> for details.</para>
+ </note>
+ <note>
+ <para>Although the login
configuration names used by the client and server in this example happen to be the
same, there really is no requirement for this as the client and server login module
configurations are two indepdendent configurations. They are associated with each
other only by the values for the principal and credentials that the are exchanged. The
server side login modules have to be able to understand and validate the principal and
credentials that the client side login modules set.</para>
+ </note>
</step>
<step>
- <para>The authorization phase consists
of the following steps.</para>
+ <para>The final step in the security
check is the authorization phase which consists of the following steps.</para>
<substeps>
<step>
- <para>Obtain the names
of the roles that are allowed to access the EJB method. This is obtained from the EJB
container.</para>
+ <para>Obtain the names
of the roles that are allowed to access the EJB method. This is obtained from the EJB
container and consists of the ejb-jar.xml descriptor role-name elements of all
method-permission elements containing the invoked method.</para>
</step>
<step>
<para>If no roles have
been assigned then no access to the method is allowed. Otherwise, the
JaasSecurityManager doesUserHaveRole(Princpal, Set) method is invoked to see if the
caller principal has one of the role names assigned. This check is performed by
iterating through the role names and checking to see if the "Roles" group contains a
SimplePrincpal with the role name. Access is allowed if any role name is a member of
the "Roles" group. Access is denied if the none of the role names are members of the
"Roles" group.</para>
@@ -599,26 +574,34 @@
</step>
</procedure>
</section>
+ </section>
+ <section id = "sx.SecurityProxies">
+ <title>Using Custom Security Proxies</title>
+ <para>There are two ways to write a security proxy for
handling custom security that is outside the scope of the EJB declarative security
model. The first is to write an implementation of the org.jboss.security.SecurityProxy
interface allong with an implementation of the org.jboss.security.SecurityProxyFactory
interface and setup your factory class as the SecurityProxyFactoryClassName value for
the JaasSecurityManagerService. The other approach is to simply write an object that
implements one or more of the EJB home and/or remote interface methods and code your
security checks in each method. This section goes over each approach and highlights
the advanatges and disadvantages to each approach.</para>
</section>
</section>
<section id = "sx.SRP">
<title>The Secure Remote Password(SRP) Protocol</title>
<para>The SRP protocol is an implementation of a public key exchange
handshake described in RFC2945. The RFC2945 abstract states: <quote>This document
describes a cryptographically strong network authentication mechanism known as the
Secure Remote Password (SRP) protocol. This mechanism is suitable for negotiating
secure connections using a user-supplied password, while eliminating the security
problems traditionally associated with reusable passwords. This system also performs a
secure key exchange in the process of authentication, allowing security layers
(privacy and/or integrity protection) to be enabled during the session. Trusted key
servers and certificate infrastructures are not required, and clients are not required
to store or manage any long-term keys. SRP offers both security and deployment
advantages over existing challenge-response techniques, making it an ideal drop-in
replacement where secure password authentication is needed.</quote>
- </para>
+ </para>
+ <para>SRP is similar in concept and security to other public key
exchange algorithms like Diffie-Hellman and RSA. It does this using a simple
passwords in a way that does not require a clear text password to exist on the server.
This is in contrast to requiring client certificates and the corresponds certificate
management infrastructure.</para>
<para>The JBossSX framework includes an implementation of SRP that
consists of the following elements:</para>
<itemizedlist>
<listitem>
<para>An implementation of the SRP handshake protocol
that is independent of any particular client/server protocol</para>
</listitem>
<listitem>
- <para>An RMI implementation of the handshake protocol
as the default client/server SRP implimentation</para>
+ <para>An RMI implementation of the handshake protocol
as the default client/server SRP implementation</para>
</listitem>
<listitem>
- <para>A JAAS LoginModule implementation that uses the
RMI implimentation for use in authenticating clients in a secure fashion</para>
+ <para>A client side JAAS LoginModule implementation
that uses the RMI implimentation for use in authenticating clients in a secure
fashion</para>
</listitem>
<listitem>
- <para>A JMX mbean for managing the RMI server
implementation. The mbean allows the RMI server implementation to be plugged into a
JMX framework and externalizes the configuration of the verification information
store. It also establishes a authentication cache that is bound into the JBoss server
JNDI namespace.</para>
+ <para>A JMX MBean for managing the RMI server
implementation. The mbean allows the RMI server implementation to be plugged into a
JMX framework and externalizes the configuration of the verification information
store. It also establishes a authentication cache that is bound into the JBoss server
JNDI namespace.</para>
</listitem>
+ <listitem>
+ <para>A server side JAAS LoginModule implementation
that uses the authentication cache managed by the SRP JMX MBean.</para>
+ </listitem>
</itemizedlist>
<para>
<xref linkend = "sx.SRP.diagram"/> gives a diagram of the key
components involved in the SRP client/server framework.</para>
@@ -629,21 +612,22 @@
<imagedata fileref =
"images/jbosssx/SRPComponents.gif"/>
</imageobject>
</mediaobject>
- </figure>
+ </figure>
+ <section id = "sx.Configuring.SRP">
+ <title>Configuring SRP</title>
+ <para>Configuring JBoss to enable the use of the SRP
implementation consists of:</para>
+ </section>
</section>
<section id = "sx.loginmodules">
<title>Custom LoginModules</title>
<section>
<title>Bundled LoginModules</title>
- <para>This section documents key login module implementations
that are
- bundled with the JBossSX framework. There are two types of login
modules; those
- that run on the client and those that run in the JBoss
server.</para>
+ <para>This section documents key login module implementations
that are bundled with the JBossSX framework. There are two types of login modules;
those that run on the client and those that run in the JBoss server. Client side login
modules primarily are used to acquire the user identity and credentials that are
associated with EJB method invocations. Server side login modules are used to
implement the behavior of the JaasSecurityManager and thus perform authentication and
role mapping used during authorization.</para>
<section id = "sx.ServerSideLoginModules">
<title>Server Side LoginModules</title>
<section id = "sx.SubjectPatterns">
<title>LoginModule Subject Usage
Patterns</title>
- <para>There are six ways a one can obtain
security information that
- has been associated with a Subject:</para>
+ <para>To understand how server side login
modules are used in JBoss, you need to understand the information storage features of
the JAAS Subject class. There are six ways a one can obtain security information that
has been associated with a Subject:</para>
<itemizedlist>
<listitem>
<para>java.util.Set
getPrincipals()</para>
@@ -666,10 +650,10 @@
c)</para>
</listitem>
</itemizedlist>
- <para>For Subject identities and roles, the
most logical choice is to use the Principal Set obtained via getPrincipals() and
getPrincipals(java.lang.Class). This is the what JBossSX has choosen to use and the
usage is as follows:</para>
+ <para>For Subject identities and roles, the
most natural choice is to use the Principal Set obtained via getPrincipals() and
getPrincipals(java.lang.Class). This is the what JBossSX has choosen to use and the
usage pattern is as follows:</para>
<itemizedlist>
<listitem>
- <para>The identities of a
user(username, SSN, employeeID, etc.) are stored as java.security.Principal objects in
the Subject Principals set. The roles assigned to a user are also stored in the
Principals set, but the are stored in named role sets via java.security.acl.Group
which is a subinterface of java.security.Principal. A Group is a collection of
Principals and or Groups. There can be any number of role sets assigned to a Subject.
Currently the JBossSX framework uses two well known roles sets called Roles and
CallerPrincipal. The Roles set is the set of Principals for the application domain
roles the Subject has been assigned. This role set is used by methods like the
EJBContext.isCallerInRole(String) used by EJBs to query is the current caller belongs
to the named application domain role. The CallerPrincipal role set consists of the
Principal identity assigned to the user in the application domain. It is used by the
EJBContext.getCallerPrincipal() method to allow the application domain to map from the
operation environment to a user identity suitable for the application. If a Subject
does not have a CallerPrincipal role set then the application identity is that of the
operational environment identity.</para>
+ <para>The identities of a
user(username, SSN, employeeID, etc.) are stored as java.security.Principal objects in
the Subject Principals set. The roles assigned to a user are also stored in the
Principals set, but they are stored in named role sets using java.security.acl.Group
instances. The Group interface is a subinterface of java.security.Principal. A Group
is a collection of Principals and or Groups. There can be any number of role sets
assigned to a Subject. Currently the JBossSX framework uses two well known roles sets
named "Roles" and "CallerPrincipal". The "Roles" set is the set of Principals for the
named roles as known in the application domain the Subject has been assigned. This
role set is used by methods like the EJBContext.isCallerInRole(String) which is used
by EJBs to see if the current caller belongs to the named application domain role. The
CallerPrincipal role set consists of the Principal identity assigned to the user in
the application domain. It is used by the EJBContext.getCallerPrincipal() method to
allow the application domain to map from the operation environment identity to a user
identity suitable for the application. If a Subject does not have a CallerPrincipal
role set then the application identity is that of the operational environment
identity.</para>
</listitem>
</itemizedlist>
</section>
@@ -819,8 +803,7 @@
</section>
<section id = "ClientSideLoginModules">
<title>Client Side LoginModules</title>
- <para>The login modules docuemented in this section
are used by
- clients.</para>
+ <para>The login modules docuemented in this section
are used by clients to bind the identity and credentials that will passed to the JBoss
server with each EJB method invocation.</para>
<section id = "sx.login.ClientLoginModule">
<title>org.jboss.security.ClientLoginModule</title>
<para>The ClientLoginModule is a simple client
side login module that
@@ -904,4 +887,4 @@
</releaseinfo>
</biblioentry>
</bibliography>
-</chapter>
+</chapter>
\ No newline at end of file
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
