Using Security Roles

This chapter describes how to use exteNd Director security roles in your applications. It has these sections:

About J2EE role-based authorization

The exteNd Director Security subsystem supports declarative security in the form of role-based authorization. Role-base authorization applies to portlets as defined in the Servlet and Portlet specifications.

The steps for implementing J2EE-compliant roles for portlets are:

Define the roles in your portlet deployment descriptor (portlet.xml).

For details, see the portlet.xml schema descriptor, included with your installation at Director_install_dir/Common/SchemaCatalog/portal-app_1_o.xsd
Define the same roles in your EAR or WAR application descriptor.

For information about defining roles for a project, see the chapter on the Deployment Descriptor Editor in Utility Tools.
Map the roles to users in your directory realm. The role-mapping process is distinct for each application server type.

For information about mapping roles for deployment to the exteNd Application Server, see the chapter on the Deployment Plan Editor in Utility Tools.

About exteNd Director security roles

exteNd Director also provides its own role-based authorization in the form of security roles. A security role is an XML descriptor that defines user and/or group principals that can be mapped to access rights for certain exteNd Director application objects. exteNd Director security roles can be used outside of the J2EE context, for example, with a custom realm.

The Security subsystem defines declarative role mapping for workflow processes and for portal layouts. For all other application objects, the Security subsystem uses ACL-based authorization, as described in Using ACL-Based Authorization.

Creating a security role

Procedure To create a security role using the graphical view:

In the exteNd Director development environment, go to File>New>Portal>Security Role.

The graphical view of a new role descriptor displays.
- If you prefer to edit the source directly choose the XML Source View tab at the bottom of the form.

Use the editor to enter the XML data:

XML attribute	What you enter
display-name	(Optional) The display name of the access group. This can be any string.
description	(Optional) A description that matches the display name. This can be any string.
User	To add each user: Choose the User tab and click Add. Double-click the new user field and enter name of a valid user defined in your directory realm: If you are accessing an LDAP realm you need to specify the distinguished name, for example: cn=sample,o=acme. NOTE: Roles do not support LDAP container elements.
Group	To add each group: Choose the Group tab and click Add. Double-click the new group field and enter name of a valid group defined in your directory realm: If you are accessing an LDAP realm you need to specify the distinguished name, for example: cn=Administrators,o=acme. NOTE: Roles do not support LDAP container elements

Here is an example of a security role in the source view:

  <security-role>
     <display-name>System Administrator</display-name>
     <description>Administers Portal Applications</description>
     <user-map>
        <principal>jdoe</principal>
        <principal>jsmith</principal>
     </user-map>
     <group-map>
        <principal>administrators</principal>
     </group-map>
  </security-role>

Choose File>Save.

The role is saved in your exteNd Director project's resource set. For information about the file location click here: security role descriptor location.

Mapping a security role to a workflow process

The workflow process descriptor defines role mappings for user access to workflow processes. The access-role-map element determines the user and group principals who are authorized to start new process instances. Here is how the role map element is defined in the workflow process dtd.

  <!-- Access Role-Map Definition -->
  <!ELEMENT access-role-map (role-name*)>
  <!ELEMENT role-name (#PCDATA)>
  <!-- Description Definition -->
  <!ELEMENT description (#PCDATA)>

You can use the Workflow Modeler to map roles to the a workflow process. For details, see in the section on process properties in the Workflow Guide.

Mapping a security role to a portal page layout

The portal layout descriptor defines role mappings for list and run access to portal layouts. Here is an example showing list and run access mapped to a role named myRole.xml:

  <run-role-map>
     <role-name> myRole </role-name>
  </run-role-map>
  <list-role-map>
     <role-name> myRole </role-name>
  </list-role-map>

For more information For information about mapping roles to a portal layout, see the section on creating a layout descriptor in the Portal Guide.

Accessing security roles programmatically

After you set up roles and role mappings, you can access role information using the EbiSecurityDelegate interface. This example shows how to check whether a user is included in a specified role.

  // Variable to hold the name of the security role 
  // descriptor, without the ".xml" ext
    String mapfile = "mysecurityXML";
    // Get a security manager
    try {
     com.sssw.fw.security.api.EbiSecurityDelegate sd =            
       com.sssw.fw.security.client.EboFactory.getSecurityDelegate();
       // Check if user is in this role
       if (sd.isUserInRole(context, mapfile));  
       // get a document, else display "no access" message
    }
    catch (com.sssw.fw.exception.EboFactoryException e)
    {
       // display message
    }