User Management Guide

CHAPTER 4    Role-Based Authorization

This chapter discusses role-based authorization and contains the following sections:

• Role-based authorization

• Customizing role-based authorization

• How role-based access works

• Accessing roles programmatically

    For an overview of role-based authorization, see Role-based authorization.

Role-based authorization

Role-based authorization, used in the Web tiers (such as portal components and pages) to comply with the J2EE security model, allows for run and list rights to be given to principals for application artifacts.

For application-level objects (portal components and PID pages), the object's XML descriptor associates the users and groups in the authentication directory with specific access rights.

A role corresponds to a user or group (a principal) in your directory realm. A role can have two types of access permission: a run role that allows execution of the object and a list role that allows viewing the object. You authorize access by mapping a run role or list role from the component or page descriptor to a security roles descriptor. You configure such mapping in a role-mapping file that is part of the component or page.

The Workflow subsystem leverages role-based authorization in a slightly different way, defining two security roles: the workflow admin who can run workflow administration tools and the workflow users who can participate in workflows. These are equivalent to a run role and list role, and the definition of those roles and the mapping with principals is identical to those just described. Security Manager API calls are available to check whether a user or group is mapped to a specific security role.

Here is a workflow example of role-based authorization:

Customizing role-based authorization

Role-based authorization uses standard XML files for defining roles. Using the same file format, you can define your own roles and through the available API check to see if a user belongs to a role, as well as gather information about a defined role.

How role-based access works

Role-based security consists of roles and role mappings. Roles are users and/or groups defined in a security XML descriptor in your project resource set. A role mapping consists of a run role or list role that is mapped to the security descriptor from the component or page descriptor.

Here is a summary of how role-based access works:

For example, when a user attempts to run a component from a listing in the Layout Manager, the Security subsystem follows this logic:

1. Is there a run-role mapping defined for this component?

   • No — Allow access

   • Yes — Go to Step 2

2. Is the context user in the list of principals this role is mapped to?

   • No — Go to Step 3

   • Yes — Allow access

3. Is the user defined in a J2EE role for the application?

   • No — Deny access; return HTTP status code 401

   • Yes — Allow access

   NOTE:   J2EE roles can be defined in the application.xml of an EAR or in the web.xml or ejb-jar.xml of a WAR. The role mapping is application-server specific. For more information, see your application server documentation.

To specify roles for security role mapping:

1. In your Director project source directory, go to the security data folder in the project resource set. The default location is ResourceSet/data/security-role.

       For information about the resource set, see the section on accessing application resources in the Core Development Guide.

2. Create a security role descriptor to associate with one or more of your Director project components and pages.

   TIP:   You can create multiple descriptors with different roles.

3. 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-map	The name of a valid user defined in your directory realm. You can specify multiple users (in separate tags). NOTE:   If you are accessing an LDAP realm you need to specify the distinguished name, for example: cn=sample,o=users
   group-map	The name of a valid group defined in your directory realm. You can specify multiple groups (in separate tags). NOTE:   you are accessing an LDAP realm you need to specify the distinguished name, for example: cn=Administrators,o=Administration.

   Here is an example:

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

To map security roles to principals for a component or PID page:

1. In Workbench, open the component or PID page XML descriptor in your project resource set.

   The default locations in your project source directory are:

   • ResourceSet/data/portal-component

   • ResourceSet/data/portal-page

2. Enter the XML data in the role-name attribute for each role type:

   XML attribute	What you enter
   run-role-map role-name	The name of the security descriptor with the roles you want to map to, without the.xml extension. Users with this mapping can run this object and, if applicable, view the result. NOTE:   The run role does not encompass the list role. Each access type must be mapped separately.
   list-role-map role-name	The name of the security descriptor with the roles you want to map to, without the.xml extension. Users with this mapping can view this object in a listing.

   NOTE:   If you don't specify a mapping for a role, all users will have the associated access.

   Here is an example:

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

Accessing roles programmatically

After you set up roles and role mappings, you can access role information through Director's Security API. This code 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.EbiSecurityManager sm =
         com.sssw.fw.security.client.EboFactory.getSecurityManager();
       // Check if user is in this role
       if (sm.isUserInRole(context, mapfile));  
       // get a document, else display "no access" message
    }
    catch (com.sssw.fw.exception.EboFactoryException e)
    {
       // display message
    }

	User Management Guide

Copyright © 2000, 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.