3 Understanding Users and Roles

This chapter describes users and roles, the anonymous role, the authenticated role, and role mapping for Oracle Platform Security Services (OPSS). It also includes the definition of terms used throughout this guide and an overview of the User and Role API Framework.

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 19, "Developing with the User and Role API."

3.1 Terminology

This section contains the definition of terms, some of them generic and some specific to OPSS. A few of those terms have been introduced in preceding chapters, and a few others are be described in succeeding ones.

Users

A user, or enterprise user, is an end-user accessing a service. User information is stored in the domain identity store, typically instantiated by the WebLogic Server DefaultAuthenticator. 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 3.4, "The Anonymous User and Role."

Roles

An enterprise group or group is a role that comprises users or other groups. It can be defined in an application deployment descriptor (such as web.xml or ejb-jar.xml) or using annotations in code.

A JavaEE logical role is a role specified declaratively or programmatically by a JavaEE application. It is defined in an application deployment descriptor and, typically, used in the application code.

An OPSS application role is a collection of users, groups, and application roles, and it can be structured in a hierarchy. It is specific to the application, defined by the application policy, and not necessarily known to the JavaEE container. Application roles are scoped in the sense that they are visible only when the application runs. They can be mapped to other application roles defined in the same application scope (and also to enterprise users or groups), and they are used to make authorization decisions.

For details about the anonymous role, see Section 3.4, "The Anonymous User and Role." For details about the authenticated role, see Section 3.3, "The Authenticated Role."

Principal

A principal is the identity assigned to a requesting entity (such as a user) by an authentication process.

OPSS Subject

An OPSS subject is a collection of principals and, possibly, user credentials such as passwords or cryptographic keys. WebLogic authentication populates the subject with users and groups, and then augments the subject with application roles. For details about how anonymous data is handled, see Section 3.4.1, "Anonymous Support and Subject."

Security Stores

The Identity Store is the repository of enterprise users and groups. Out-of-the-box the identity store is the WebLogic DefaultAuthenticator. Other types of identity stores include LDAP, RDBMS, or custom. This store is administered with the WebLogic Administration Console.

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 domain credentials. OPSS uses one logical store to keep both policies and credentials. This store is administered with Fusion Middleware Control.

For details about stores, see Chapter 4, "Understanding Identities, Policies, and Credentials."

Other Terms

A system component is a manageable process that is not a WebLogic component. Examples include Oracle Internet Directory, WebCache, and JavaSE 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.

3.2 Role Mapping

OPSS supports the mapping of application roles to enterprise groups in the domain Policy Store, no matter the kind of domain policy repository employed: file-based or LDAP-based. This mechanism allows users in enterprise groups to access application resources as specified by application roles. The mapping is allowed to be many-to-many.

Notes:

Oracle JDeveloper allows specifying this mapping when the application is being developed. Alternatively, the mapping can be also specified, after the application has been deployed, using WLST or Fusion Middleware Control as explained in Section 8.4.1.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.

3.2.1 Permission Inheritance and the Role Hierarchy

OPSS application 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, members of a role inherit permissions from the parent role. Thus, if roleA is a member of roleB, then all permissions granted to roleB are also permissions 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.

The following example illustrates application role management with 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.WLSGroupImpl</class>
                      <name>developer_group</name>
            </membe>
            <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 3-1 summarizes the permissions that each of the five users and roles in the above hierarchy get according the inheritance rule:

Table 3-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)


3.3 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, to 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 15.1, "Configuring the Servlet Filter and the EJB Interceptor."

3.4 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 15.1, "Configuring the Servlet Filter and the EJB Interceptor."

3.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.

3.5 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 Oracle Fusion Middleware 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 Oracle Fusion Middleware 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 two basic tools for managing these accounts are the Oracle WebLogic Administration Console and the Oracle WebLogic Scripting Tool (WLST).

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

3.6 Managing User Accounts

This section provides several links to information about creating user accounts and protecting their passwords.