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 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 25, "Developing with the User and Role API."
2.1 Terminology
This section defines most of the OPSS security terms.
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, "The Anonymous User and Role."
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, "The Anonymous User and Role." For details about the authenticated role, see Section 2.3, "The Authenticated Role."
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 21.5.6, "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.
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."
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, and keys. The only type of LDAP-based OPSS security store supported is Oracle Internet Directory.
For details, see Chapter 3, "Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing."
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 Role Mapping
OPSS supports many-to-many mapping of application roles in the policy 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 OPSS scripts, Fusion Middleware Control, or Oracle Entitlements Server, as explained in Section 9.2.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 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.
For details about managing an application role hierarchy with OPSS scripts, see Section 9.3.6, "grantAppRole," and Section 9.3.7, "revokeAppRole."
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
developerAppRolehas the following members:developer developer_group managerAppRole directorAppRole
-
In addition, the role
directorAppRolehas 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 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 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 21.2, "Configuring the Servlet Filter and the EJB Interceptor."
2.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 21.2, "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:
-
The anonymous user is removed from the subject and replaced, as appropriate, by an authenticated user.
-
The anonymous role is removed and the authenticated role is added.
-
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 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 Online Help, and section Using the WebLogic Scripting Tool in Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
2.6 Managing User Accounts
For information about creating user accounts and protecting their passwords, consult the following documents:
-
For general guidelines on creating passwords, see section Manage Users and Groups in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help. The default authentication provider requires a minimum password length of 8 characters, but this is configurable.
A few recommendations regarding password creation are explained in section Securing the WebLogic Server Host in Oracle Fusion Middleware Securing a Production Environment for Oracle WebLogic Server.
-
In general, passwords are stored in either an LDAP server or an RDBMS. The particular location in which they are stored is determined by the specific authentication provider that is configured in the environment (or more precisely, the security realm of a domain). For details about out-of-the-box authentication providers, see section Managing the Embedded LDAP Server in Oracle Fusion Middleware Securing Oracle WebLogic Server.
-
For information about how to configure the optional Password Validation provider, which is automatically called whenever you create a password and that enforces a set of customizable password composition rules, see section Configuring the Password Validation Provider in Oracle Fusion Middleware Securing Oracle WebLogic Server.
-
When adding or deleting a user, consider the recommendations explained in Section L.11, "User Gets Unexpected Permissions."
2.7 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 policy 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 policy 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:
-
In the left pane of the Console, under Domain Structure, select the domain for which you intend to set the parameters above.
-
Select Configuration > Security and click Advanced.
-
Check (to set to true) or uncheck (to set to false) the box next to the following entries:
-
Principal Equals Case Insensitive
-
Principal Equals Compare DN and GUID
-
-
Restart the server. Changes do not take effect until the server is restarted.
These parameters can alternatively be set using OPSS scripts. For more details about configuring the WebLogic server, see section Configuring a Domain to Use JAAS Authorization in Oracle Fusion Middleware Securing 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 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.