2 Understanding Users and Roles

This chapter describes various characteristics of users and roles, such as the anonymous role, the authenticated role, role mapping, and the role category. It also includes the definition of terms used throughout this guide.

OPSS delegates authentication to Oracle WebLogic Server authenticator providers managed with the WebLogic Administration Console.

This chapter is divided into the following sections:

For further details about managing users and roles programmatically, see Chapter 21, "Developing with the Identity Directory API."

2.1 Terminology

This section defines most of the OPSS security terms.

Users

A user, or enterprise user, is an end-user accessing a service. User information is stored in the identity store. An authenticated user is a user whose credentials have been validated.

An anonymous user is a user whose credentials have not been validated (hence unauthenticated) that is permitted access to only unprotected resources. This user is specific to OPSS and its use can be enabled or disabled by an application. For details about anonymous user support, see Section 2.4, "About the Anonymous User and Role."

Roles

An enterprise role or enterprise group is a collection of users and other groups. It can be hierarchical, that is, a group can include arbitrarily nested groups (other than itself).

A Java EE logical role is a role specified declaratively or programmatically by a Java EE application. It is defined in an application deployment descriptor and, typically, used in the application code. It can be mapped to only enterprise groups or users, and it cannot be mapped directly to application roles.

An application role is a collection of users, groups, and other application roles; it can be hierarchical. Application roles are defined by application policies and not necessarily known to a Java EE container. Application roles can be many-to-many mapped to external roles. For example, the external group employee (stored in the identity store) can be mapped to the application role helpdesk service request (in one stripe) and to the application role self service HR (in another stripe).

For details about the anonymous role, see Section 2.4, "About the Anonymous User and Role." For details about the authenticated role, see Section 2.3, "About the Authenticated Role."

Principal

A principal is the identity to which the authorization in the policy is granted. A principal can be a user, an external role, or an application role. Most frequently, it is an application role.

Application and System Policies

An application policy is a functional policy that specifies a set of permissions that a principal is allowed to perform within the application, such as viewing web pages or modifying reports.

An application policy uses:

  • Principals as grantees, and must have at least one principal.

  • Either one or more permissions, or an entitlement, but not both.

    Policies that use an entitlement are called entitlement-based policies; policies that use one or more permissions are called resource-based policies.

A system policy is a policy that specifies a set of permissions that a principal or a code source is allowed to perform, and it holds for an entire domain. System policies grant privileges to code sources and principals, while application policies can grant privileges to principals only. For an example of a source code system policy with multiple permissions, see Section 24.6.6, "Using Supported Permission Classes."

Application and system policies are packed in the application's jazn-data.xml file. In that file, system policies should be defined outside the application's scope.

Figure 2-1 illustrates the application policy model.

Figure 2-1 Application Policy Logical Model

Surrounding text describes Figure 2-1 .

OPSS Subject

An OPSS subject is a collection of principals and, possibly, user credentials such as passwords or cryptographic keys. The server authentication populates the subject with users and groups, and then augments the subject with application roles. The OPSS Subject is key in identity propagation using other Oracle Identity Management products such as OAM, for example. For details about how anonymous data is handled, see Section 2.4.1, "Anonymous Support and Subject."

Security Stores

The identity store is the repository of enterprise users and groups and must be LDAP-based. Out-of-the-box the identity store is the WebLogic LDAP DefaultAuthenticator. Other types of identity stores include Oracle Internet Directory, Sun Directory Server, and Oracle Virtual Directory.

The policy store is the repository of application and system policies. This store is administered with Oracle Enterprise Manager Fusion Middleware Control.

The credential store is the repository of credentials. This store is administered with Oracle Enterprise Manager Fusion Middleware Control.

The OPSS security store is the logical repository of system and application-specific policies, credentials, audit metadata, and keys. The only type of LDAP-based OPSS security store supported is Oracle Internet Directory; the only type of DB-based OPSS security store supported is Oracle database.

For details, see Chapter 3, "Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing."

Other Terms

A system component is a manageable process that is not a WebLogic component. Examples include Oracle Internet Directory, WebCache, and Java SE components.

A Java component is a peer of a system component, but managed by an application server container. Generally it refers to a collection of applications and resources in one-to-one relationship with a domain extension template. Examples include Oracle SOA applications, Oracle WebCenter Spaces.

2.2 Mapping Roles

OPSS supports many-to-many mapping of application roles in the OPSS security store to enterprise groups in the identity store, which allows users in enterprise groups to access application resources as specified by application roles. Since this mapping is many-to-many, it is alternatively referred to as the role-to-group mapping or as the group-to-role mapping.

Notes:

Oracle JDeveloper allows specifying this mapping when the application is being developed in that environment. Alternatively, the mapping can be also specified, after the application has been deployed, using WLST commands, Fusion Middleware Control, or Oracle Entitlements Server, as explained in Section 10.3.2, "Managing Application Roles."

The mapping of an application role to an enterprise group rewrites the privilege of the enterprise group as the union of its privileges and those of the mapped application role. Therefore, it (possibly) augments the privileges of the enterprise group but never removes any from it.

2.2.1 Permission Inheritance and the Role Hierarchy

OPSS roles can be structured hierarchically by the relation ”is a member of.” Thus a role can have as members users or other roles.

Important:

When building a role hierarchy, ensure that you do not introduce circular dependencies to prevent unwanted behavior. For example, setting roleA to be a member of roleB, and roleB to be a member of roleA would create such a circular dependency.

In a role hierarchy, role members inherit permissions from the parent role. Thus, if roleA is a member of roleB, then all permissions granted to roleB are also granted to roleA. Of course, roleA may have its own particular permissions, but, just by being a member of roleB, roleA inherits all the permissions granted to roleB.

For details about managing an application role hierarchy with WLST commands, see grantAppRole and revokeAppRole in Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

For details about managing an application role hierarchy with Oracle Entitlements Server, see Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server.

The following example illustrates a role hierarchy consisting of the following nested application users and roles:

  • The role developerAppRole has the following members:

    developer
developer_group
managerAppRole
directorAppRole

  • In addition, the role directorAppRole has the following members:

    developer
developer_group

Here is the relevant portions of the file jazn-data.xml specifying the above hierarchy:

<policy-store>
  <applications>
    <application>
      <name>MyApp</name>
      <app-roles>
        <app-role>
          <name>developerAppRole</name>
          <class>oracle.security.jps.service.policystore.ApplicationRole</class>
          <display-name>Application developer role</display-name>
          <description>Application developer role</description>
          <guid>61FD29C0D47E11DABF9BA765378CF9F5</guid>
          <members>
            <member>
                      <class>weblogic.security.principal.WLSUserImpl</class>
                      <name>developer</name>
            </member>
            <member>
                      <class>weblogic.security.principal.WLSUserImpl</class>
                      <name>directorAppRole</name>
            </member>
            <member>
                      <class>weblogic.security.principal.WLSGroupImpl</class>
                      <name>developer_group</name>
            </member>
            <member>
              <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
              <name>managerAppRole</name>
            </member>
          </members>
        </app-role>
        <app-role>
                          <name>directorAppRole</name>
                          <class>oracle.security.jps.service.policystore.ApplicationRole</class>
                          <display-name>Application director role </display-name>
                          <description>Application director role</description>
                          <guid>61FD29C0D47E11DABF9BA765378CF9F8</guid>
                          <members>
            <member>
                                      <class>weblogic.security.principal.WLSUserImpl</class>
                                      <name>developer</name>
            </member>
            <member>
                                        <class>weblogic.security.principal.WLSGroupImpl</class>
                                        <name>developer_group</name>
            </member>
                                   </members>
         </app-role> ...
       </app-roles>
 
      <jazn-policy>
        <grant>
          <grantee>
             <principals>
                <principal>
                   <class>
           oracle.security.jps.service.policystore.ApplicationRole</class>
                   <name>developerAppRole</name>
                </principal>
             </principals>
          </grantee>
          <permissions>
            <permission>
              <class>java.io.FilePermission</class>
              <name>/tmp/oracle.txt</name>
              <actions>write</actions>
             </permission>
           </permissions>
         </grant>

         <grant>
           <grantee>
             <principals>
               <principal>
                 <class>
           oracle.security.jps.service.policystore.ApplicationRole</class>
                 <name>managerAppRole</name>
               </principal>
             </principals>
           </grantee>
           <permissions>
             <permission>
               <class>java.util.PropertyPermission</class>
               <name>myProperty</name>
               <actions>read</actions>
             </permission>
            </permissions>

           </grant>
           <grant>
             <grantee>
               <principals>
                 <principal>
                   <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                   <name>directorAppRole</name>
                 </principal>
               </principals>
             </grantee>
             <permissions>
               <permission>
                 <class>foo.CustomPermission</class>
                 <name>myProperty</name>
                 <actions>*</actions>
               </permission>
             </permissions>
           </grant>
         </jazn-policy>
       </policy-store>

Table 2-1 summarizes the permissions that each of the five users and roles in the above hierarchy gets according the inheritance rule:

Table 2-1 Granted and Inherited Permissions

Role Permission Granted Actual Permissions

developerAppRole

P1=java.io.FilePermission

P1

managerAppRole

P2= java.util.PropertyPermission

P2 and (inherited) P1

directorAppRole

P3=foo.CustomPermission

P3 and (inherited) P1

developer

  

P1 and P3 (both inherited)

developer_group

  

P1 and P3 (both inherited)

2.3 About the Authenticated Role

OPSS supports the use of a special role: the authenticated role. This role has the following characteristics:

  • It need not be declared in any configuration file.

  • It is always represented by a principal attached to a subject after a successful authentication. In another words: it is granted by default to any authenticated user.

  • Its presence, within a subject, is mutually exclusive with the anonymous role, that is, either (a) a subject has not gone through authentication, in which case it contains a principal with the anonymous role as explained in Anonymous Support and Subject or (b) the subject has gone through authentication successfully, in which case it contains the authenticated role and, depending on the configuration, the anonymous role.

  • It is an application role and, therefore, it can be used by any application and participate in the application's role hierarchy.

The permissions granted to the authenticated role need not be specified explicitly but are implicitly derived from the enterprise groups and application roles of which it is a member.

A typical use of the authenticated role is to allow authenticated users access to common application resources, that is, resources available to a user that has been authenticated.

For details on how an application can manually configure the use of the authenticated role, see Section 24.3, "Configuring the Servlet Filter and the EJB Interceptor."

2.4 About the Anonymous User and Role

OPSS supports the use of two special entities: the anonymous user and the anonymous role. Like the authenticated role, these entities need not be declared and applications configure their use in the JpsFilter or JpsInterceptor. Any of them can be used by an application in the application's role hierarchy.

When enabled, before the user is authenticated and while the user is accessing unprotected resources, the user is represented by a subject populated with just the anonymous user and the anonymous role. Eventually, if that subject attempts access to a protected resource, then authorization handles the subject as explained in Anonymous Support and Subject.

The permissions granted to the anonymous user and role need not be specified explicitly but are implicitly derived from the enterprise groups and application roles of which they are a member.

A typical use of the anonymous user and role is to allow unauthenticated users to access public, unprotected resources.

For details on how an application can manually configure the use of the anonymous user and role, see Section 24.3, "Configuring the Servlet Filter and the EJB Interceptor."

2.4.1 Anonymous Support and Subject

Throughout this section, it is assumed that the use of the anonymous user and anonymous role are enabled.

When an end-user first accesses an unprotected resource, the system creates a subject and populates it with two principals corresponding with the anonymous user and the anonymous role. While unprotected resources are involved, that subject is not modified and authentication does not take place.

When a protected resource is accessed, then authentication kicks in, and the subject (which thus far contained just the anonymous role) is modified according to the result of the authentication process, as follows.

If authentication is successful, then:

  1. The anonymous user is removed from the subject and replaced, as appropriate, by an authenticated user.

  2. The anonymous role is removed and the authenticated role is added.

  3. Other roles are added to the subject, as appropriate.

Notice that a successful authentication results then in a subject that has exactly one principal corresponding to a non-anonymous user, one principal corresponding to the authenticated role, and possibly other principals corresponding to enterprise or application roles.

If authentication is not successful, then the anonymous user is retained, the anonymous role is removed or retained (according to how the application has configured the JpsFilter or JpsInterceptor), and no other principals are added. By default, the anonymous role is removed from the subject.

2.5 About Administrative Users and Roles

A WebLogic administrator is any user member of the group Administrators, and any user that exists in a security realm can be added to this group.

For details about the default groups that exist in a security realm, see section Users, Groups, And Security Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Generally, there is no default name for an administrator, with just one exception: when you install the examples, you get a default user name and password for the administrator of the sample domain. It is recommended, however, that these examples not be used in any production environment.

For details, see section Install WebLogic Server in a Secure Manner in Securing a Production Environment for Oracle WebLogic Server.

Once a domain is configured, users that have been created in the security realm can be added or removed from the Administrators group at anytime by any member of the Administrators group. The basic tools for managing these accounts are the Oracle WebLogic Administration Console, the Oracle WebLogic Scripting Tool (WLST), and Fusion Middleware Control.

For details, see section Add Users to Groups in Oracle WebLogic Server Administration Console Online Help, section Using the WebLogic Scripting Tool in Understanding the WebLogic Scripting Tool.

2.6 Managing User Accounts

For information about creating user accounts and protecting their passwords, consult the following documents:

2.7 About Principal Name Comparison Logic

This section explains how principal comparison affects OPSS authorization and describes the system parameters that control the principal name comparison logic, in the following sections:

2.7.1 How Does Principal Comparison Affect Authorization?

Upon a successful user authentication, the system populates a Subject with principals whose names accord with the user and enterprise group names (of enterprise groups the user is included in) stored in the identity store.

On the other hand, when the user (or enterprise group) needs to be authorized, the system considers how application roles have been mapped to enterprise groups, and builds another set of principals from names in application grants stored in the OPSS security store.

In order to authorized a principal, the principal names populated in the Subject (from names found in the identity store) and those built from names in the OPSS security store are compared. The user (or group) is authorized if and only if a match of principal names is found.

It is therefore crucial that principal names be compared properly for the authorization provider to work as expected.

Suppose, for instance, a scenario where the identity store contains the user name "jdoe", but, in grants, that user is referred to as "Jdoe". Then one would want the principal name comparison to be case insensitive, for otherwise the principals built from the names "jdoe" and "Jdoe" will not match (that is, they will be considered distinct) and the system will not authorize "jdoe" as expected.

2.7.2 System Parameters Controlling Principal Name Comparison

The following two WebLogic Server system parameters control the way principal names are compared in a domain and allow, furthermore, to compare principals using DN and GUID data:

PrincipalEqualsCaseInsensitive (True or False; False by default)
PrincipalEqualsCompareDnAndGuid (True or False; False by default)

To set these parameters using the WebLogic Server Console, proceed as follows:

  1. In the left pane of the Console, under Domain Structure, select the domain for which you intend to set the parameters above.

  2. Select Configuration > Security and click Advanced.

  3. Set the following entries to true or fase, as appropriate:

    • Principal Equals Case Insensitive

    • Principal Equals Compare DN and GUID

  4. Restart the server. Changes do not take effect until the server is restarted.

These parameters can alternatively be set using WLST commands. For more details about configuring the WebLogic server, see section Configuring a Domain to Use JAAS Authorization in Administering Security for Oracle WebLogic Server.

The name comparison logic chosen at runtime is described by the following pseudo-code fragment:

if PrincipalEqualsCompareDnAndGuid is true
//use GUID and DN to compare principals
{
  when GUID is present in both principals {
     use case insensitive to compare GUIDs
  } 
  when DN is present in both principals {
     use case insensitive to compare DNs
  }
}

if PrincipalEqualsCaseInsensitive is true
//use just name to compare principals
{
  use case insensitive to compare principal names
}
else
{
  use case sensitive to compare principal names
}

Since by default both PrincipalEqualsCompareDnAndGuid and PrincipalEqualsCaseInsensitive are false, name principal comparison defaults to case sensitive.

2.8 About the Role Category

The role category allows a security administrator to organize application roles. Rather than displaying the flat list of roles in an application, an administrator can organize them arbitrarily in sets or categories. Role categories are flat sets, that is, they contain no hierarchical structure.

For details about managing an application role category with Oracle Entitlements Server, see Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server.

The following fragment illustrates the configuration of a role category:

<app-roles>
  <app-role>
    <name>AppRole_READONLY</name>
    <display-name>display name</display-name>
    <description>description</description>
    <class>oracle.security.jps.service.policystore.ApplicationRole</class>
    <extended-attributes>
      <attribute>
        <name>ROLE_CATEGORY</name>
        <values>
          <value>RC_READONLY</value>
        </values>
      </attribute>
    </extended-attributes>
  </app-role>
</app-roles>
<role-categories>
  <role-category>
    <name>RC_READONLY</name>
    <display-name>RC_READONLY display name</display-name>
    <description>RC_READONLY description</description>
  </role-category>
</role-categories>

The members of a role category are not configured within the <role-category> element but within the element <extended-attributes> of the corresponding application role. The role category name is case insensitive. The role category can be managed with the interface RoleCategoryManager.

For details about the RoleCategoryManager interface, see the Javadoc document Oracle Fusion Middleware Java API Reference for Oracle Platform Security Services.