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."
This section contains the definition of terms, some generic and some specific to OPSS, consistently used throughout this guide.
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."
An enterprise group or group is a collection of users and other groups. It can be hierarchical, that is, a group can include arbitrarily nested groups.
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. It can be mapped to only enterprise groups or users, and it cannot be mapped directly to application roles.
An OPSS application role is a collection of users, groups, and application roles; it can be hierarchical. This role 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 in 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."
A permission consists of a class, a resource, and a subset of the actions allowed by the type of the resource. For a permission class that can be used out-of-the-box, see Section 18.4, "The Class oracle.security.jps.ResourcePermission." Permission names are case sensitive.
Suppose, for example, that the resource type Job allows the following actions: schedule, cancel, and view. If myJob1, myJob2 are resources type Job, then one can have the following permissions:
myJob1; schedule, view
myJob2; cancel, view
A principal is the identity assigned to a requesting entity (such as a user) by an authentication process. A principal can be a user, an enterprise group, or an application role. For details about the way principal names are compared, see Principal Name Comparison Logic.
A grant or functional policy consists of an entitlement or a list of permissions; a code source; and a principal. A grant describes who (the principals or code) can do what (the actions in permissions) on a given resource.
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."
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 Oracle Enterprise Manager Fusion Middleware Control.
For details about stores, see Chapter 4, "Understanding Identities, Policies, and Credentials."
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.
OPSS supports the mapping of application roles in the domain policy store to enterprise groups in the domain identity store. 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.
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, 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) |
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."
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."
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.
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.
This section provides several links to information about creating user accounts and protecting their passwords.
For general guidelines on creating passwords, see section Manage Users and Groups in Oracle Fusion Middleware Oracle WebLogic Server Administration Console 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 I.12, "User Gets Unexpected Permissions."
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:
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 domain 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.
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 WLST commands. 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.