[jboss-cvs] jboss-portal-docs/referenceGuide/en/modules ...
Roy Russo
russo at jboss.com
Wed Jul 12 14:52:46 EDT 2006
User: russo
Date: 06/07/12 14:52:46
Modified: referenceGuide/en/modules xmldescriptors.xml security.xml
troubleshooting.xml
Log:
JBPORTAL-943
Revision Changes Path
1.25 +58 -7 jboss-portal-docs/referenceGuide/en/modules/xmldescriptors.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: xmldescriptors.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-portal-docs/referenceGuide/en/modules/xmldescriptors.xml,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -b -r1.24 -r1.25
--- xmldescriptors.xml 10 Jul 2006 19:06:39 -0000 1.24
+++ xmldescriptors.xml 12 Jul 2006 18:52:46 -0000 1.25
@@ -18,7 +18,7 @@
<xref linkend="desc_examples"/>
for samples on how they are used within a portlet application.
</para>
- <sect2>
+ <sect2 id="desc_objectxml">
<title>*-object.xml</title>
<para>
The *-object.xml file is used to define: portal instances, pages, windows, window layout. Additionally,
@@ -39,6 +39,12 @@
<region>center</region>
<height>1</height>
</window>
+ <security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>view</action-name>
+ </policy-permission>
+ </security-constraint>
</deployment>
</deployments>]]></programlisting>
<itemizedlist>
@@ -120,6 +126,53 @@
can be any number between 0-X.
</para>
</listitem>
+ <listitem>
+ <para>
+ <programlisting><![CDATA[
+<security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>view</action-name>
+ </policy-permission>
+</security-constraint>]]></programlisting>
+ The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to
+ secure a specific window/page/portal-instance based on a user's role.
+ </para>
+ <para>
+ <emphasis role="bold">Role definition:</emphasis>
+ You must define a role that this security constraint will apply to. Possible values are:
+ <itemizedlist>
+ <listitem>
+ <emphasis role="bold"><unchecked/></emphasis>
+ Anyone can view this page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold"><role-name>SOMEROLE</role-name></emphasis>
+ Access to this page is limited to the defined role.
+ </listitem>
+ </itemizedlist>
+ <emphasis role="bold">Access Rights:</emphasis>
+ You must define the access rights given to the role defined. Possible values are:
+ <itemizedlist>
+ <listitem>
+ <emphasis role="bold">view</emphasis>
+ Users can view the page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">viewrecursive</emphasis>
+ Users can view the page and child pages.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">personalize</emphasis>
+ Users are able to view AND personalize the page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">personalizerecursive</emphasis>
+ Users are able to view AND personalize the page AND its child pages.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
</itemizedlist>
</para>
<para>The example *-object.xml, above, makes reference to items found in other descriptor files. To
@@ -139,7 +192,7 @@
several times with different preference parameters.
<note>
<emphasis>Is this descriptor mandatory?</emphasis>
- Technially, no, as you can deploy your portlet without this descriptor AND without the *-object.xml and
+ Technically, no, as you can deploy your portlet without this descriptor AND without the *-object.xml and
then use the management portlet to create instances, assign the instances to windows, and then assign the
windows to pages.
</note>
@@ -454,15 +507,13 @@
value. This value will only display the error message whereas
<emphasis>show</emphasis>
will display the full stack trace if it is available.
-
-
</para>
</sect2>
</sect1>
<sect1 id="desc_examples">
<title>Descriptor Examples</title>
- <sect2>
- <title>Defining a new portal page.</title>
+ <sect2 id="desc_example_page">
+ <title>Defining a new portal page</title>
<para>This sample application and descriptor will create a new page, named
<emphasis>MyPage</emphasis>
in your portal. To illustrate our example, we have made available a portlet with a page descriptor that you
@@ -636,7 +687,7 @@
</itemizedlist>
</para>
</sect2>
- <sect2>
+ <sect2 id="desc_example_portal">
<title>Defining a new portal instance</title>
<para>To illustrate our example, we have made available a portlet that you can download
here:
1.12 +94 -686 jboss-portal-docs/referenceGuide/en/modules/security.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: security.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-portal-docs/referenceGuide/en/modules/security.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- security.xml 9 May 2006 22:16:56 -0000 1.11
+++ security.xml 12 Jul 2006 18:52:46 -0000 1.12
@@ -2,688 +2,96 @@
<chapter id="security">
<chapterinfo>
<author>
- <firstname>Thomas</firstname>
- <surname>Heute</surname>
- <email>theute at jboss.org</email>
- </author>
- <author>
- <firstname>Martin</firstname>
- <surname>Holzner</surname>
- <email>mholzner at novell.com</email>
+ <firstname>Roy</firstname>
+ <surname>Russo</surname>
+ <email>roy at jboss.org</email>
</author>
</chapterinfo>
-
<title>Security</title>
-<!--
- <para>
- New in version 2.2, the portal features role based access control for all portal resources. The definition
- of security constraints is strait forward and simple. Each portal resource can define zero, one, or more
- security constraints, each binding a role to the allowed actions for the role and resource. For more details
- on how to secure portal resources take a look at security section in the user guide.
- </para>
- <sect1>
- <title>Portal Security Configuration</title>
- <para>
- Portal security is governed by a set of portal policy configurations. Policy configurations can be created for
- different permission types, and accessed via the policy configuration service. The policy configuration maintains
- a set of security constraints, keyed by permission type and uri of the resource.
- </para>
- <sect2>
- <title>org.jboss.portal.security.config.SecurityConstraint</title>
-
+ <sect1 id="securing_objects">
+ <title>Securing Portal Objects</title>
<para>
- <programlisting>
- // create a new constraint
- SecurityConstraint constraint = new SecurityConstraint("view,read","Admin");
-
- // get the allowed actions as a set of strings
- Set allowedActions = constraint.getActions();
-
- // get the role this constraint is assigned to
- String allowedRole = constraint.getRole();
- </programlisting>
+ This section describes how to secure portal objects (windows, pages, and portal instances), using the JBoss
+ Portal *-object.xml descriptor. View the User Guide for information on how to secure objects using the
+ Management Portlet.
+ </para>
+ <para>Securing portal objects declaratively, is done through the *-object.xml (
+ <xref linkend="desc_objectxml"/>
+ ). The portion you will be adding to each object is denoted by the
+ <emphasis><security-constraint></emphasis>
+ tag:
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<deployments>
+ <deployment>
+ <if-exists>overwrite</if-exists>
+ <parent-ref>default.default</parent-ref>
+ <window>
+ <window-name>HelloWorldJSPPortletWindow</window-name>
+ <instance-ref>HelloWorldJSPPortletInstance</instance-ref>
+ <region>center</region>
+ <height>1</height>
+ </window>
+ <security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>view</action-name>
+ </policy-permission>
+ </security-constraint>
+ </deployment>
+</deployments>]]></programlisting>
+ </para>
+ <para>
+ A security constraint on an object (our example above, secures a specific portlet window), is explained as:
+ <para>
+ <programlisting><![CDATA[
+<security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>view</action-name>
+ </policy-permission>
+</security-constraint>]]></programlisting>
+ The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to
+ secure a specific window/page/portal-instance based on a user's role.
</para>
-
<para>
- Security constraints are the state holder of what role is allowed to execute what actions on a given
- resource. They are managed via a policy configuration. One policy configuration can be defined for each
- permission type.
+ <emphasis role="bold">Role definition:</emphasis>
+ You must define a role that this security constraint will apply to. Possible values are:
<itemizedlist>
- <para>
- Permissions are currently separated into 3 valid types:
- </para>
- <listitem>component</listitem>
- <listitem>instance</listitem>
- <listitem>portalobject</listitem>
+ <listitem>
+ <emphasis role="bold"><unchecked/></emphasis>
+ Anyone can view this page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold"><role-name>SOMEROLE</role-name></emphasis>
+ Access to this page is limited to the defined role.
+ </listitem>
</itemizedlist>
- </para>
- </sect2>
- <sect2>
- <title>org.jboss.portal.security.config.PortalPolicyConfig</title>
- <para>
- The policy configuration maintains the constraint information for one permission type.
- <programlisting>
- PortalPolicyConfig config = null;
- //.... get the config from the config service (see below)
- String uri = portalResourceHandle;
- Set constraints = config.getConstraints(uri);
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>org.jboss.portal.security.config.PortalPolicyConfigService</title>
- <para>
- The policy configuration service is the root access point for configuration information. All active
- policy configurations are registered with this service, and can be accessed from here via their permission
- type.
- </para>
- <para>
- <programlisting>
- import org.jboss.portal.security.config.PortalPolicyConfigService;
- import org.jboss.portal.security.config.PortalPolicyConfig;
- import org.jboss.portal.core.security.PermissionTypes;
-
- PortalPolicyConfigService configService = null;
- // configService = ... lookup the configService from the mbean server
-
- // get the policy config for all portlet instances
- PortalPolicyConfig instanceConfig = configService.getConfig(PermissionTypes.INSTANCE);
- PortalPolicyConfig portalObjectConfig = configService.getConfig(PermissionTypes.PORTAL_OBJECT);
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>org.jboss.portal.security.config.ConfigListener</title>
- <para>
- The policy configuration listener registers with the policy configuration, and listens to added, removed,
- and modified events. Each change of the security constraints maintained in a policy configuration is propagated
- to this listener. The listener builds the bridge to any security enforcement infrastructure.
- </para>
- <para>
- The default implementation of the enforcement infrastructure is based in the Java Authorization Contract
- for Containers (JACC). It is implemented as a policy configuration listener that reacts to configuration
- change events, and populates the JACC policy with permissions that are created based on the security
- constraints propagated by the change events.
- </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Portal Security Enforcement</title>
- <sect2>
- <title>org.jboss.portal.security.PortalPermission</title>
- <para>
- The defined security constraints are enforced via portal permissions. The default security implementation
- that comes with the portal contains a policy configuration listener that converts the constraint information
- into portal permissions, and populates a JACC (Java Authorization Contract for Containers) based security
- policy with them.
- </para>
- <para>
- The configured constraints are enforced via an interceptor in the server invocation stack. For each request
- to the portal it creates a new portal permission to check access rights. The created permission contains
- the requested resource and action. The permission is passed to the portal policy, together with the portal
- subject to check if the permission is implied in the policy.
- Access will be granted if one of the security constraints in the policy configurations implies the
- provided check permission.
- </para>
- <para>
- A factory is provided to create portal permissions. The PortalPermissionFactory is an interface that is
- implemented as an mbean, and can be injected wherever needed.
- <programlisting>
- import org.jboss.portal.security.PortalPermission;
- import org.jboss.portal.security.PortalPermissionFactory;
- import org.jboss.portal.core.security.PermissionTypes;
-
- PortalPermissionFactory portalPermissionFactory = ...;
- PortalPermission componentPerm = portalPermissionFactory.createPermission(PermissionTypes.COMPONENT, uri, "view");
- </programlisting>
-
- </para>
- </sect2>
- <sect2>
- <title>org.jboss.portal.security.PortalPolicy</title>
- <para>
- The portal policy is the interface that is being used to check if access to a requested resource is granted.
- It is made available as a thread local property throughout the lifetime of a portal request.
- The implementation of the policy is injected via a server invocation aspect (PolicyAssociationInterceptor).
- This interceptor gets the policy via the implementation of the PortalPolicyService.
-
- Here is the code to get to the portal policy:
- <programlisting>
- import org.jboss.portal.security.PolicyAssociation;
- import org.jboss.portal.security.PortalPolicy;
-
- PortalPolicy policy = PolicyAssociation.getPolicy();
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>org.jboss.portal.security.PortalSubject</title>
- <para>
- The portal subject represents the current user. Similar to the portal policy, it is made available for the
- lifetime of the portal request as a thread local property, which is injected by a server invocation aspect.
-
- Here is the code to get to the portal policy:
- <programlisting>
- import org.jboss.portal.security.SubjectAssociation;
- import org.jboss.portal.security.PortalSubject;
-
- PortalSubject subject = SubjectAssociation.getSubject();
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>Portal Policy Enforcement</title>
- <para>
- All the described pieces above taken together make up the security enforcement infrastructure.
- The remaining call to determine wether access is granted or not is:
- <programlisting>
- if (policy.implies(subject, permission)){
- // ....do something....
- </programlisting>
- </para>
- </sect2>
- <para></para>
- </sect1>
-
-
- <sect1>
- <title>Default Security Implementation</title>
- <para>
- The default implementation of the security APIs is based on the Java Authorization Contract for Containers
- (JACC).
- </para>
- <sect2>
- <title>What is JACC</title>
- <para>
- JACC is part of the J2EE specification, and defines a way for the servlet and ejb containers to secure
- web resources and ejbs with a role based model.
- </para>
- </sect2>
- <sect2>
- <title>JACC Policy and Policy Configuration</title>
- <para>
- <sect3>
- <title>javax.security.jacc.PolicyConfigurationFactory</title>
- <para>
- The policy configuration factory is an abstract singleton that serves as the access point for policy
- configurations. It features a static accessor to get the factory implementation.
- <programlisting>
- public static PolicyConfigurationFactory getPolicyConfigurationFactory()
- throws ClassNotFoundException, PolicyContextException
- {
- ....
- }
- </programlisting>
-
- The policy configuration factory to load can be specified in a VM system property (-D)
- "javax.security.jacc.PolicyConfigurationFactory.provider". The default implementation that will
- be loaded if nothing else is defined, is org.jboss.security.jacc.JBossPolicyConfigurationFactory.
- </para>
- </sect3>
- <sect3>
- <title>javax.security.jacc.PolicyConfiguration</title>
- <para>
- The policy configuration interface is the access point for all configured permissions of one context id.
- It allows to manipulate the content of the security policy (see below) which is the ultimate
- policy decission point. In the standard J2EE model, a context id is equivalent to the deployed
- context: the war or ejb archive. In the case of JBoss portal, this model was extended to allow a
- more flexible definition of the context id. The default implementation of the portal's
- JBossSecurityProvider (see below) creates a separate context id for each portal resource. This allows
- the portal to reload the content of a specific portal resources without having to refresh any of
- the other resource's security attributes.
- </para>
- </sect3>
- <sect3>
- <title>javax.security.jacc.Policy</title>
- <para>
- The jacc policy is the ultimate policy decission point. It makes the decission wether a permission
- is implied or not. To make this decission it can do whatever is needed. The default implementation
- (org.jboss.security.jacc.DelegatingPolicy) delegates the decission to the policy context, which
- in turn delegates it to the java.security.Permissions that make up all configured permissions for a
- given role in the requested policy context.
- </para>
- </sect3>
- <sect3>
- <title>org.jboss.portal.security.jacc.SecurityProvider</title>
- <para>
- The portal security provider interface wrapps the functionality in the jacc PolicyConfigurationFactory.
- It allows access to all available policy configurations. It also offers a method the check wether
- a particular policy context is in service or not. The jacc policy singleton is also available
- via this interface.
-
- <programlisting>
- // check if the provided policy context id is available
- boolean inService(String policyContextID) throws PolicyContextException;
- // get the policy configuration for the provided policy context id
- PolicyConfiguration getPolicyConfiguration(String contextID, boolean remove) throws PolicyContextException;
- // get the jacc policy singleton
- Policy getPolicy();
- </programlisting>
- </para>
- </sect3>
- <sect3>
- <title>org.jboss.portal.security.jacc.JBossSecurityProvider</title>
- <para>
- The jboss security provider extends the portal security provider, and adds access to the server
- configuration. This additional access allows a provider implementation to consider server
- configuration properties when making a decission about any of the policy context calls.
- <programlisting>
- // get the portal server configuration
- ServerConfig getServerConfig();
- </programlisting>
- </para>
- </sect3>
- </para>
- </sect2>
- <sect2>
- <title>Portal Policy and Policy Service</title>
- <para>
-
- <sect3>
- <title>org.jboss.portal.security.PortalPolicyService</title>
- <para>
- The portal policy service is the root service from where one can get access to the portal policy.
- The default implementation of this service interface (org.jboss.portal.security.impl.jacc.PortalPolicyServiceImpl)
- is an mbean. It uses the implementation of the JBossSecurityProvider interface to get to the jacc
- policy singleton. The security provider interface is a wrapper of the jacc PolicyConfigurationFactory.
- It's implementation delegates all calls to the standard jacc PolicyConfigurationFactory.
- </para>
- <para>
- The PortalPolicyService exposes only one method:
- <programlisting>
- PortalPolicy getPolicy();
- </programlisting>
- </para>
- </sect3>
- <sect3>
- <title>org.jboss.portal.security.PortalPolicy</title>
- <para>
- The portal policy has only one method:
- <programlisting>
- boolean implies(PortalSubject subject, PortalPermission permission);
- </programlisting>
- The default implementation of the portal policy, an inner class of the policy service implementation,
- (org.jboss.portal.security.impl.jacc.PortalPolicyServiceImpl$PortalPolicyImpl), uses the security
- provider to gain access to the portal policy implementation. It uses the JaccHelper class in the
- same package to determine the java.security.ProtectionDomain and the policy context id before
- calling the jacc policy to do the actual permission check.
- </para>
- </sect3>
- </para>
- </sect2>
- <sect2>
- <title>Who is asking?</title>
- <para>
- The remaining piece in the puzzle is the identity. How does the portal determine what user and ultimately
- what roles to check the access for?
- </para>
- <sect3>
- <title>The Jacc Portal Subject</title>
- <para>
- As described above, the portal injects the org.jboss.portal.security.PortalSubject as a thread local
- property that is available throughout the portal request. The default implementation of this portal
- subject (org.jboss.portal.security.impl.jacc.JaccPortalSubject) wraps the jacc way of getting to the
- authenticated java.security.Subject, and reading the role memberships off of it.
- In other words: the mechanism of getting the subject and the subjects roles is identical to the way
- the application server id handling this security aspect.
- </para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Write your own Security Implementation</title>
- <para>
- As you can probably see above, there are many ways to plug into this infrastructure and adapt it to your needs.
- You will encounter the least amount of work if you plugin at the JACC layer. All you need to do is provide
- your own implementation of the JACC policy. All the rest of the infrastructure can stay as is. If you don't want
- to stay with JACC as your security provider, it will require you to do some more work, depending on how far
- you want to get away from JACC.
- To implement a security layer without any JACC artifacts, you'll need to provide the policy configuration lister,
- the policy enforcement interceptor and the policy and subject interceptors. Let's look at this in more detail.
- </para>
- <sect2>
- <title>Overwriting the JACC policy</title>
- <sect3>
- <title>Write the Policy class</title>
- <para>
- As already mentioned above, the easiest way to get your own behavior for the portal authorization,
- you can provide your own implementation of the JACC policy. To do so, you'll need to create a class that
- extends java.security.Policy, and overwrites the implies method. Be aware that the portal goes beyond the
- JACC specification in that it allows new permission classes, other then the 5 predefined classes from the
- specification. All permissions used by the portal extend the abstract org.jboss.portal.security.PortalPermission
- class, which in turn extends java.security.Permission. The currently (as of 2.2) implemented permission
- classes are ComponentPermission, InstancePermission, and PortalObjectPermission. Your policy implementation
- can distinguish those permissions, and handle them differently if it so desires.
- </para>
- <para>
- For an example on how to implement your own, take a look at the portal's default policy implementation.
- The class is org.jboss.portal.security.impl.jacc.PortalJaccPolicy. This policy is basically a copy of the
- application servers DelegatingPolicy class. The idea behind it is that the portal policy is stacked ontop
- of the J2SE policy, configured in the VM. The portal policy will handle authorization checks for all the
- allowed JACC permissions (for ejb and servlet/jsp calls), In addition to the basic J2SE permission types.
- It allows to configure external permissions that will be treated just like the basic JACC permissions.
- If the incoming permission to check is an instance of any of the five JACC permission classes, or one of
- the configured external permission classes, the policy will handle the implies check, otherwise it will
- delegate to the J2SE policy that was in place in the VM, before the portal policy was created.
- Remember that the java security model allows only one policy to be active in the VM at any given time.
- By stacking the policies there is a way to have several policies active with only one policy
- configured at the VM level.
- </para>
- <para>
- It is up to your implementation if you want to copy this behavior of configurable external permissions and
- stacked policies or not. You could implement a flat policy that treats all permissions the same, but be
- aware that since your policy will take the place of the only policy in the system, that all policy
- decissions will be coming into your policy. So all security checks by the J2SE SecurityManager will
- have to be handled by your policy as well.
- </para>
- <para>
- One strange anomalie that is currently built into the portal is the fact that your policy needs to adhere
- to a naming convention. There needs to be a method that is used by the policy service to pick up the
- policy instance. Your policy needs to provide a method with the following signature:
- (Note: the method signature is not enforced by any interface or abstract class, since the origin of
- this requirement is a workaround for an underlying problem with the policy configuration and
- redeployments of the portal sar):
-
- <programlisting>
- public Policy getPolicyProxy()
- </programlisting>
-
- You can return 'this' , or any decorator class of your policy that would allow you to restrict the
- externally available functionality of the policy.
- </para>
- </sect3>
- <sect3>
- <title>Configure the Policy to be used by the Portal</title>
- <para>
- The policy implementation must be an mbean. It is injected into the policy service mbean to make it
- available to other interested parties. Take a look at the jboss-service.xml in the jboss-portal.sar
- (in the meta-inf folder). The mbean definition for the "portal:service=SecurityProvider" injects the
- "jboss.security:service=JaccPolicyProvider" via the PolicyName attribute.
- In other words: the service that is configured as "jboss.security:service=JaccPolicyProvider" needs
- to expose a method as described above, that returns an implementation of the java.security.Policy
- interface (public Policy getPolicyProxy(){...}). This method will be called by the SecurityProvider
- service at startup to read the configured policy from the mbean server.
-
- Here is the section defining the jacc policy from the jboss-service.xml:
-
- <programlisting>
- <![CDATA[
- <mbean
- code="org.jboss.portal.security.impl.jacc.PortalJaccPolicy"
- name="jboss.security:service=JaccPolicyProvider"
- xmbean-dd="org/jboss/portal/security/impl/jacc/PortalJaccPolicy.xml">
- <attribute name="ExternalPermissionTypes">
- org.jboss.portal.core.security.PortalObjectPermission,
- org.jboss.portal.core.security.InstancePermission,
- org.jboss.portal.core.security.ComponentPermission
- </attribute>
- </mbean>
- ]]>
- </programlisting>
-
- And here is the section defining the jacc security provider service, and injecting the policy via
- the policy proxy attribute:
-
- <programlisting>
- <![CDATA[
- <mbean
- code="org.jboss.portal.security.impl.jacc.JBossSecurityProviderImpl"
- name="portal:service=SecurityProvider"
- xmbean-dd="">
- <xmbean>
- ...more descriptor info here...
- </xmbean>
- <attribute name="PolicyName">jboss.security:service=JaccPolicyProvider</attribute>
- <attribute name="PolicyAttributeName">PolicyProxy</attribute>
- </mbean>
- ]]>
- </programlisting>
-
- Note: If there is no policy mbean active for the defined PolicyName and PolicyAttributeName in the
- SecurityProvider mbean, the policy currently set in the VM will be used instead. The policy will be
- determined via:
-
- <programlisting>
- import java.security.Policy;
- Policy policy = Policy.getPolicy();
- </programlisting>
-
- If your policy extends PortalJaccPolicy a new instance will be created everytime the portal starts.
- This instance will not be set as the VM wide policy, leaving the original policy in place. In other
- words: Policy.getPolicy() will not return your policy. To get to your policy, you'll have to lookup
- the portal security provider, and get it from there.
-
- <programlisting>
- JBossSecurityProvider provider = ....;
- Policy policy = provider.getPolicy();
- </programlisting>
-
- </para>
- <para>
- You could of course go even further and replace the implementation of the security provider itself.
- That way, you can decide how to get to the policy in whatever way.
- </para>
- <para>
- Note that the current implementation is more complex than it should be. This is due to problems in the
- application server's JACC policy implementation. Once those problems are fixed, the portal's implementation
- will be simplified. Effectively: the portal should be able to just get the current policy in the VM,
- (Policy p = Policy.getPolicy();) and use it. The policy would still have to be configured with the
- external permissions (PortalPermission classes) to treat them like JACC permissions, and not delegate
- the permission check to the underlying J2SE policy.
- </para>
- </sect3>
- </sect2>
- <sect2>
- <title>A Security implementation without JACC</title>
- <para>
- As already mentioned before, implementing an authorization solution for the portal without the use of JACC
- all together is a bit harder. The default implementation relies havily on many of the JACC concepts. You
- will have to replace all of them, but it is possible.
- </para>
- <sect3>
- <title>The ConfigListener</title>
- <para>
- To start, you'll need to change the way the security constraint information is converted into permissions.
- Or perhaps you wouldn't even want to convert them, and use the PortalPolicyConfigService and the
- PortalPolicyConfig as your one and only store of permission information. If you decide to create your
- own system of storing and enforcing permissions, you'll have to implement the
- org.jboss.portal.security.config.ConfigListener interface, and register it with the PortalPolicyConfig(s)
- you are interested in. Look at the org.jboss.portal.security.impl.JBossPortalPolicyConfigStoreImpl
- as an example of how this can be done. This is an mbean that injects the ConfigListener via an attribute
- (depends optional-attribute-name="ConfigListener"). If you take a look at the jboss-service.xml you'll
- see that this mbean is used three times, and each time a config listener is injected. The three mbeans
- represent three different policy configurations, and the same service (portal:policy=JaccPortalPolicyConfigurator)
- registers with all three of them as a ConfigListener.
- You would have to replace the implementation of the policy configurator (portal:policy=JaccPortalPolicyConfigurator)
- and configure the three instances of JBossPortalPolicyConfigStoreImpl to register your config listener
- instead. Your config listener can do whatever you desire. Just keep in mind that the result needs to
- be accessible for the policy enforcement.
- </para>
- </sect3>
- <sect3>
- <title>Policy Enforcement</title>
- <para>
- Policy enforcement is initiated via the PolicyEnforcementInterceptor in the server invocation stack.
- This interceptor uses the results of two other interceptors:
+ <emphasis role="bold">Access Rights:</emphasis>
+ You must define the access rights given to the role defined. Possible values are:
<itemizedlist>
- <listitem>PolicyAssociationInterceptor</listitem>
- <listitem>SubjectAssociationInterceptor</listitem>
+ <listitem>
+ <emphasis role="bold">view</emphasis>
+ Users can view the page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">viewrecursive</emphasis>
+ Users can view the page and child pages.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">personalize</emphasis>
+ Users are able to view AND personalize the page.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">personalizerecursive</emphasis>
+ Users are able to view AND personalize the page AND its child pages.
+ </listitem>
</itemizedlist>
- These two interceptors inject the PortalSubject and the PortalPolicy as thread local properties.
- The policy enforcement interceptor creates a permission based on the requested resource and action,
- and checks the portal policy to see if the permission implies for the determined portal subject.
- </para>
- <para>
- You would probably keep the concept of the subject around since this is what the JAAS login module
- populates with the authentication information from the login process.
- The portal policy is what is more interesting. Your ConfigListener will populate some store with the
- constraint information, and that store needs to be made available to the policy enforcement side.
- The way to do this is via the portal policy from the PolicyAssociationInterceptor. To inject your own
- implementation of the PortalPolicy interface, you can provide your own version of the PortalPolicyService
- interface. The default implementation is an mbean that is injected into the PolicyAssociationInterceptor.
- Write your own version of the PortalPolicyService and configure it in the jboss-service.xml, replacing
- the default PortalPolicyServiceImpl. Of course you could go even further and replace the PolicyAssociationInterceptor
- itself no make it independent from the PortalPolicyService. The important thing is that your
- implementation of the PortalPolicy needs to utilize what your ConfigListener stored before.
- </para>
- <para>
- For completeness sake, let's take a look at the SubjectAssociationInterceptor as well. It is responsible
- for injecting the PortalSubject. The PortalSubleject is a flagging interface (has no methods), and
- the default implementation (JaccPortalSubject) is simply newed up every time the SubjectAssociationInterceptor
- is invoked. The PortalSubject is later on used by the PortalPolicy to check if a given PortalPermission
- implies for the given PortalSubject.
</para>
- </sect3>
- </sect2>
- </sect1>
--->
-
-<!--
- <sect1>
- <title>Securing Portlet Content</title>
-
- <sect2>
- <title>Introduction</title>
-
- <para>JSR 168 specifications does not define any particular security
- implementation even though you can get the authenticated user and its
- role.</para>
-
- <para>In JBoss portal, each portlet defines its own security model, and
- the portal gives an easy way to check if a user has a permission.</para>
- </sect2>
-
- <sect2>
- <title>Defining the security model for your portlet</title>
-
- <para>To define your security model, you need to edit the file
- <literal>WEB-INF/jboss-portlet.xml</literal>
- . First you need to define all
- kind of permissions you want, and how those permissions are related one to
- the other.
- </para>
-
- <para>Let's take a small example, in your portlet you want to define two
- different permissions,
- <literal>read</literal>
+ We provide two live samples of this descriptors, here
+ <xref linkend="desc_example_page"/>
and
- <literal>write</literal>
- . Here is an example of security model:
- <programlisting><![CDATA[<security>
- <model>
- <permission-description>
- <permission-name>write</permission-name>
- <description>Writing permission</description>
- </permission-description>
- <permission-description>
- <permission-name>read</permission-name>
- <description>Reading permission</description>
- </permission-description>
- </model>
-</security>]]></programlisting>
- This would be sufficient but if a user can
- write usually he can read as well. With the current model, we would need
- to add the role to both permission. There is another way, we could just
- specify that the
- <literal>write</literal>
- permission implies the
- <literal>read</literal>
- permission. To do so we just need to write:
- <programlisting><![CDATA[<security>
- <model>
- <permission-description>
- <permission-name>write</permission-name>
- <description>Writing permission</description>
- <implies>read</implies>
- </permission-description>
- <permission-description>
- <permission-name>read</permission-name>
- <description>Reading permission</description>
- </permission-description>
- </model>
-</security>]]></programlisting>
- A permission can imply any number of
- permissions, just make sure you are not doing cycles (when a permission
- implies another that implies the first)
- </para>
- </sect2>
-
- <sect2>
- <title>Giving permissions to roles</title>
-
- <para>Once you defined what kind of permissions you want, you need to
- attribute roles to them, to do so you need to add a scheme to the model:
- <programlisting><![CDATA[<security>
- <model>
- <permission-description>
- <permission-name>write</permission-name>
- <description>Writing permission</description>
- <implies>read</implies>
- </permission-description>
- <permission-description>
- <permission-name>read</permission-name>
- <description>Reading permission</description>
- </permission-description>
- </model>
- <scheme>
- <domain></domain>
- <item>
- <path>/</path>
- <permission>
- <permission-name>read</permission-name>
- <role-name>Users</role-name>
- </permission>
- <permission>
- <permission-name>read</permission-name>
- <role-name></role-name>
- </permission>
- <permission>
- <permission-name>write</permission-name>
- <role-name>Admins</role-name>
- </permission>
- </item>
- </scheme>
-</security>]]></programlisting>
- Here we add the
- <literal>read</literal>
- permission to the
- <literal>Users</literal>
- role and anonymous users then
- the
- <literal>write</literal>
- permission to the
- <literal>Admins</literal>
- role. The
- <literal>path</literal>
- defines a scope on which the permissions
- will be defined. This will have different meanings for different portlets.
- For example the forums portlet uses a path to specify on which category or
- forum you want to apply the permissions (/mycategory/myforum for
- example)
- </para>
- </sect2>
-
- <sect2>
- <title>Checking a permission inside your portlet</title>
-
- <para>You can check a permission on a
- <literal>JBossRenderRequest</literal>
- or a
- <literal>JBossActionRequest</literal>
- using any of the
- <literal>hasPermission</literal>
- methods (see the API).
- </para>
-
- <para>In our simple example,
- <literal>req.hasPermission("write")</literal>
- will check if the user accessing the website has the
- <literal>write</literal>
- privilege.
+ <xref linkend="desc_example_portal"/>
</para>
- </sect2>
</sect1>
--->
</chapter>
\ No newline at end of file
1.4 +36 -4 jboss-portal-docs/referenceGuide/en/modules/troubleshooting.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: troubleshooting.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-portal-docs/referenceGuide/en/modules/troubleshooting.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- troubleshooting.xml 24 May 2006 02:53:10 -0000 1.3
+++ troubleshooting.xml 12 Jul 2006 18:52:46 -0000 1.4
@@ -47,6 +47,18 @@
</itemizedlist>
</para>
<para>
+ <emphasis role="bold">Errors</emphasis>
+ <itemizedlist>
+ <listitem>
+ <link linkend="error1">When I access a specific portal-instance or page, I keep seeing "401 - not
+ authorized" error in my browser.</link>
+ </listitem>
+ <listitem>
+ <link linkend="error2">How do I disable development-mode errors on the presentation layer?</link>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
<emphasis role="bold">Miscellaneous</emphasis>
<itemizedlist>
<listitem>
@@ -115,13 +127,33 @@
Note that all requests for cms content must be prepended with /content and then followed by the
path/to/the/file.gif as it is in your directory structure.
</para>
+ <para id="error1">
+ <emphasis role="bold">When I access a specific portal-instance or page, I keep seeing "401 - not
+ authorized" error in my browser.</emphasis>
+ <para></para>
+ You are likely not authorized to view the page or portal instance. You can either modify the security using the
+ Management Portlet under the Admin Tab, or secure your portlets via the object descriptor,
+ <xref linkend="securing_objects"/>
+ </para>
+ <para id="error2">
+ <emphasis role="bold">How do I disable development-mode errors on the presentation layer?</emphasis>
+ <para></para>
+ See:
+ <xref linkend="descriptor_debug"/>
+ </para>
<para id="misc1">
<emphasis role="bold">Is there a sample portlet I can look at to learn about portlet development and JBoss
Portal deployments?</emphasis>
<para></para>
- Sample HelloWorld Portlets can be found at
+ <itemizedlist>
+ <listitem>Sample portlets with tutorials can be found here,
+ <xref linkend="tutorials_tutorials"/>
+ </listitem>
+ <listitem>Additional Portlets can be found at
<ulink url="http://www.portletswap.com">PortletSwap.com</ulink>
.
+ </listitem>
+ </itemizedlist>
</para>
</sect1>
- </chapter>
+</chapter>
More information about the jboss-cvs-commits
mailing list