PK ].Foa,mimetypeapplication/epub+zipPK].FMETA-INF/container.xml PKYuPK].FOEBPS/devidd.htm Developing with the Identity Directory API

23 Developing with the Identity Directory API

This chapter explains how to access and work with identity stores using the Identity Directory API.

This chapter includes the following sections:

23.1 About the Identity Directory API

The Identity Directory API allows applications to access identity information (users and other entities) in a uniform and portable manner regardless of the particular underlying identity repository.

The Identity Directory API:

  • is flexible

  • is fully configurable by clients supporting a variety of identity stores having standard and specific schemas

  • supports retrieving and managing users, and groups

  • is extensible, supporting new entity types with relationships defined between those entities

  • is robust, with high-availability/fail-over support.

The Identity Directory API uses the Identity Governance framework, providing all the benefits of the framework to enable you to control how identity related information, including Personally Identifiable Information (PII), access entitlements, attributes, and other entities are used, stored, and propagated between organizations.

23.1.1 Feature Overview

This section explains the features supported by the Identity Directory API.

Features for User Entities

The following features are supported for users:

  • Perform Create, Read, Update, Delete (CRUD) operations on users

  • Perform the following actions:

    • get and set user attributes

    • authenticate the user with the identity store's native authentication mechanism

    • get the group to which the user belongs (optionally, including nested groups)

    • make user a member of a group

  • Change user password

  • Force user password change

  • Get and set user state (enable/disable, lockout, password must change)

Features for Group Entities

The following features are supported for groups:

  • Perform CRUD operations on groups

  • Perform the following actions:

    • get and set attributes

    • get and search for members of a group

    • get the groups to which a groups belongs (optionally, including nested groups)

    • determine if the group is a member of another group

  • Support multi-valued attributes

  • Support static and dynamic groups

23.2 Summary of Classes

Table 23-1 lists the classes in the Identity Directory API:

Table 23-1 Classes in the Identity Directory API

ClassDescription

Capabilities

Contains an entity's capabilities.

CreateOptions

Contains options for entity creation operations.

DeleteOptions

Contains options for entity deletion operations.

Entity

Generic entity class holding the list of attributes of the entity fetched using search or read methods.

EntityAlreadyExistsException

Returned following an attempt to create an existing entity.

EntityCapabilities


EntityManager

Handles operations like read, create and search of generic entity.

EntityNotFoundException

Returned when requested entity is not found.

EntityNotUniqueException

Returned when the entity is not uniquely defined.

EntityRelationManager

Handles entity relationship operations like read, create, delete, search relationship.

Group

A generic entity class holding the list of members of the group. It also provides methods to modify group membership.

GroupManager

Handles operations like creating, deleting, and searching for groups.

IDSException

Handles exceptions.

IDSPrincipal

Contains the principal related to the exception.

IdentityDirectory

Represents a handle to IdentityDirectory for creation of IdentityDirectory instance.

The instance provides handles to User, Group, and generic Entity Manager so that operations on the corresponding entities can be performed.

IdentityDirectoryFactory

A factory class for creating IdentityDirectoryService.

IdentityDirectoryInfo


InvalidAttributesException

Used for exceptions related to invalid entity attributes.

InvalidFilterException

Used for exceptions generated within Identity Beans

ModAttribute

ModifyOptions

Extends OperationOptions containing options for entity modify operation

OperationNotSupportedException

Used for exceptions generated within Identity Beans

ReadOptions

Extends OperationOptions containing options for entity read operation. Read options include Locale and Requested Attributes settings.

ResultSet

An interface for the object returned by search interaction with paged results.

SearchFilter

Used to construct simple or complex nested search filters for searching the entities

SearchOptions

Extends ReadOptions containing options for entity search operation.

User

Generic class for User entities.

UserCapabilities

Contains user capability attributes.

UserManager

Contains methods for creating, deleting, and searching for users by various criteria.


23.3 Identity Directory Configuration

The identity directory configuration is a combination of the logical entity configuration and the physical identity store configuration.

The identity directory with logical entity configuration is stored in:

DOMAIN_HOME/config/fmwconfig/ids-config.xml

The physical identity store configuration for the default identity directory is located at:

DOMAIN_HOME/config/fmwconfig/ovd/default

The default identity directory uses the same identity store properties (namely host, port, credentials, search base, create base, name attribute, and so on) configured in OPSS (weblogic authenticator or in jps-config.xml). For more information, see Section F.2.3, "LDAP Identity Store Properties".

23.4 Working with the Identity Directory API

This section explains how applications can use the Identity Directory API to view and manage identity store data. It contains these sections:

23.4.1 Getting an Identity Directory API Instance

You can obtain the identity directory handle from the jps-context and get a directory instance as follows:

JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext ctx = ctxFactory.getContext();
       
//find the JPS IdentityStore service instance
IdentityStoreService idstoreService =   ctx.getServiceInstance(IdentityStoreService.class)
 
//get the Identity Directory instance
oracle.igf.ids.IdentityDirectory ids = idstoreService.getIdentityStore();

23.4.2 Performing CRUD Operations on Users and Groups

You can perform Create, Retrieve, Update, and Delete (CRUD) operations on users and groups.

23.4.2.1 User Operations

Basic CRUD operations on users are as follows:

Create User

Principal UserManager.createUser(List<Attribute> attrVals, CreateOptions opts)

Get User

User UserManager.getUser(Principal principal, ReadOptions opts)

Search for User

User UserManager.searchUser(String id, ReadOptions opts)

Delete User

void UserManager.deleteUser(String id, DeleteOtions opts)

Update User

void UserManager.modify(List<ModAttribute> attrVals, ModifyOptions opts)

Retrieve List of Users

ResultSet UserManager.searchUsers(SearchFilter filter, SearchOptions opts)

23.4.2.2 Group Operations

Basic CRUD operations on groups are as follows:

Create Group

Principal GroupManager.createGroup(List<Attribute> attrVals, CreateOptions opts)

Get Group

User GroupManager.getGroup(Principal principal, ReadOptions opts)

Search for Group

User GroupManager.searchGroup(String id, ReadOptions opts)

Delete Group

void GroupManager.deleteGroup(String id, DeleteOtions opts)

Modify Group Attributes

void GroupManager.modify(List<ModAttribute> attrVals, ModifyOptions opts)

Retrieve List of Groups

ResultSet GroupManager.searchGroups(SearchFilter filter, SearchOptions opts)

23.5 Examples of Identity Directory API

This section contains the following examples of using the Identity Directory API:


See Also:

Section 19.1, "Using OPSS in Java SE Applications," for details about securing Java SE applications with OPSS.

23.5.1 Initialize and Obtain Identity Directory Handle

This sample code initializes and obtains a handle to the identity directory:

/**
 * This is a sample program for initializing Identity Directory Service with the configuration
 * that is already persisted in IDS config location.
 * Basic User and Group CRUDS are performed using this IDS instance
 */
 
import java.util.ArrayList;
import java.util.List;
import java.util.Iterator;
import java.util.Map;
 
import java.security.Principal;
 
import oracle.igf.ids.Entity;
import oracle.igf.ids.User;
import oracle.igf.ids.UserManager;
import oracle.igf.ids.Group;
import oracle.igf.ids.GroupManager;
import oracle.igf.ids.config.OperationalConfig;
import oracle.igf.ids.IdentityDirectoryFactory;
import oracle.igf.ids.IdentityDirectoryInfo;
import oracle.igf.ids.IdentityDirectory;
import oracle.igf.ids.IDSException;
import oracle.igf.ids.ReadOptions;
import oracle.igf.ids.CreateOptions;
import oracle.igf.ids.ModifyOptions;
import oracle.igf.ids.DeleteOptions;
import oracle.igf.ids.SearchOptions;
import oracle.igf.ids.SearchFilter;
import oracle.igf.ids.ResultSet;
import oracle.igf.ids.Attribute;
import oracle.igf.ids.ModAttribute;
 
import oracle.dms.context.ExecutionContext;
 
 
public class Ids1Test {
 
    private IdentityDirectory ids;
    private UserManager uMgr;
    private GroupManager gMgr;
 
 
    /**
     * Get Identity Store Service
     */
    public Ids1Test() throws IDSException {
 
        // Set Operational Config
        OperationalConfig opConfig = new OperationalConfig();
 
        // Set the application credentials: this overrides the credentials 
        // set in physical ID store configuration
        //opConfig.setApplicationUser("cn=test_user1,l=amer,dc=example,dc=com");
        //opConfig.setApplicationPassword("welcome123".toCharArray());
 
        // Set search/crate base, name, objclass, etc. config.  
        // This overrides default operational configuration in IDS
        opConfig.setEntityProperty("User", opConfig.SEARCH_BASE,          "l=amer,dc=example,dc=com");
        opConfig.setEntityProperty("User", opConfig.CREATE_BASE,          "l=amer,dc=example,dc=com");
        opConfig.setEntityProperty("User", opConfig.FILTER_OBJCLASSES, "person");
        opConfig.setEntityProperty("User", opConfig.CREATE_OBJCLASSES,          "inetorgperson");
        opConfig.setEntityProperty("Group", opConfig.SEARCH_BASE,          "cn=dlcontainerOCS,dc=example,dc=com");
        opConfig.setEntityProperty("Group", opConfig.CREATE_BASE,          "cn=dlcontainerOCS,dc=example,dc=com");
        opConfig.setEntityProperty("Group", opConfig.FILTER_OBJCLASSES,          "groupofuniquenames");
        opConfig.setEntityProperty("Group", opConfig.CREATE_OBJCLASSES,          "groupofuniquenames,orclgroup");
 
        // Get IdentityDirectoryService "userrole" configured in IDS config
        IdentityDirectoryFactory factory = new IdentityDirectoryFactory();
        //ids = factory.getDefaultIdentityDirectory(opConfig);
        ids = factory.getIdentityDirectory("userrole", opConfig);
 
        // Get UserManager and GroupManager handles
        uMgr = ids.getUserManager();
        gMgr = ids.getGroupManager();
    }
 

23.5.2 Create a User

This sample code creates a user in the identity store:

 public Principal createUser() {
        Principal principal = null;
        
        List<Attribute> attrs = new ArrayList<Attribute>();
        attrs.add(new Attribute("commonname", "test1_user1"));
        attrs.add(new Attribute("password", "welcome123".toCharArray()));
        attrs.add(new Attribute("firstname", "test1"));
        attrs.add(new Attribute("lastname", "user1"));
        attrs.add(new Attribute("mail", "test1.user1@example.com"));
        attrs.add(new Attribute("telephone", "1 650 123 0001"));
        attrs.add(new Attribute("title", "Senior Director"));
        attrs.add(new Attribute("uid", "tuser1"));
        // Adding locale specific value
        attrs.add(new Attribute("description", "created test user 1", 
         new java.util.Locale("us", "en")));
        try {
            CreateOptions createOpts = new CreateOptions();
            createOpts.setCreateBase("l=apac,dc=example,dc=com");
 
            principal = uMgr.createUser(attrs, createOpts);
 
            System.out.println("Created user " + principal.getName());
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
 
        return principal;
    }

23.5.3 Get a User

This sample code obtains a user from the identity store:

 public User getUser(Principal principal) {
        User user = null;
 
        try {
            ReadOptions readOpts = new ReadOptions();
            // Getting specific locale values
            readOpts.setLocale("us-en");
 
            user = uMgr.getUser(principal, readOpts);
            
            printEntity(user);
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
 
        return user;
    }

23.5.4 Modify a User

This sample code modifies an existing user by adding a new user attribute:

 public void modifyUser(User user) {
 
        try {
            ModifyOptions modifyOpts = new ModifyOptions();
 
            List<ModAttribute> attrs = new ArrayList<ModAttribute>();
            attrs.add(new ModAttribute("description", "modified test user 1"));
            //attrs.add(new ModAttribute("uid", "testuser1"));
 
            user.modify(attrs, modifyOpts);
            
            System.out.println("Modified user " + user.getName());
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.5.5 Simple Search for a User

This sample code performs a basic user search:

 try {
            ReadOptions readOpts = new ReadOptions();
            readOpts.setSearchBase("l=apac");
 
            User user = uMgr.searchUser("tuser1", readOpts);
            
            printEntity(user);
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.5.6 Complex Search for Users

This sample code uses a complex search filter to return matching users:

public void searchUsers() {
 
   try {
      // Complex search filter with nested AND and OR conditiions
      SearchFilter filter = new SearchFilter(
         SearchFilter.LogicalOp.OR,
         new SearchFilter(SearchFilter.LogicalOp.AND,
         new SearchFilter("firstname", SearchFilter.Operator.BEGINS_WITH, "ve"),
         new SearchFilter("telephone", SearchFilter.Operator.CONTAINS, "506")),
         new SearchFilter(SearchFilter.LogicalOp.AND,
         new SearchFilter("firstname", SearchFilter.Operator.BEGINS_WITH, "ra"),
         new SearchFilter(SearchFilter.LogicalOp.OR,
         new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH, "ldap"),
         new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH, "sun"),
         new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH,           "access")),
         new SearchFilter("telephone", SearchFilter.Operator.CONTAINS, "506")));
 
      // Requesting attributes
      List<String> reqAttrs = new ArrayList<String>();
      reqAttrs.add("jpegphoto");
 
      SearchOptions searchOpts = new SearchOptions();
      searchOpts.setPageSize(3);
      searchOpts.setRequestedPage(1);
      searchOpts.setRequestedAttrs(reqAttrs);
      searchOpts.setSearchBase("l=amer");
 
      ResultSet<User> sr = uMgr.searchUsers(filter, searchOpts);
         while (sr.hasMore()) {
            User user = sr.getNext();
            //printEntity(user);
            //System.out.println(" ");
            System.out.println(user.getSubjectName());
            System.out.println("    " + user.getAttributeValue("commonname"));
         }
 
      } catch (Exception e) {
         System.out.println(e.getMessage());
         e.printStackTrace();
      }
    }

23.5.7 Create a Group

This sample code creates a group:

 public Principal createGroup() {
        Principal principal = null;
        
        List<Attribute> attrs = new ArrayList<Attribute>();
        attrs.add(new Attribute("name", "test1_group1"));
        attrs.add(new Attribute("description", "created test group 1"));
        attrs.add(new Attribute("displayname", "test1 group1"));
        try {
            CreateOptions createOpts = new CreateOptions();
 
            principal = gMgr.createGroup(attrs, createOpts);
 
            System.out.println("Created group " + principal.getName());
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
 
        return principal;
    }

23.5.8 Get a Group

This sample code returns a specific group:

 public Group getGroup(Principal principal) {
        Group group = null;
 
        try {
            ReadOptions readOpts = new ReadOptions();
 
            group = gMgr.getGroup(principal, readOpts);
            
            printEntity(group);
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
 
        return group;
    }

23.5.9 Get Group Using a Search Filter

This sample code uses a search filter to return groups:

 public void searchGroups() {
 
        try {
            SearchFilter filter = new SearchFilter("name",
                                SearchFilter.Operator.BEGINS_WITH, "test");
 
            SearchOptions searchOpts = new SearchOptions();
            searchOpts.setPageSize(10);
 
            ResultSet<Group> sr = gMgr.searchGroups(filtJer, searchOpts);
            while (sr.hasMore()) {
                Group group = sr.getNext();
                System.out.println(group.getSubjectName());
            }
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.5.10 Delete a Group

This sample code deletes a group from the store:

 public void deleteGroup(Principal principal) {
 
        try {
            DeleteOptions deleteOpts = new DeleteOptions();
 
            gMgr.deleteGroup(principal, deleteOpts);
            
            System.out.println("Deleted group " + principal.getName());
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.5.11 Add a Member to a Group

This sample code adds a member to a group:

 public void addMember() {
        try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("testuser1", readOpts);
            Group group = gMgr.searchGroup("test1_group1", readOpts);
 
            ModifyOptions modOpts = new ModifyOptions();
            user.addMemberOf(group, modOpts);
 
            System.out.println("added testuser1 as member of test1_group1");
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.5.12 Delete a Member from a Group

This sample code deletes a member from a group:

 public void deleteMember() {
        try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("testuser1", readOpts);
            Group group = gMgr.searchGroup("test1_group1", readOpts);
 
            ModifyOptions modOpts = new ModifyOptions();
            group.deleteMember(user, modOpts);
 
            System.out.println("deleted testuser1 from the group test1_group1");
 
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

23.6 SSL Configuration

For details about SSL configuration when using the Identity Directory API, see Section 8.5, "SSL for the Identity Store Service".

PK^&PK].FOEBPS/apreferences.htm } OPSS API References

G OPSS API References

This appendix contains references to OPSS APIs.

The list of available OPSS APIs is presented in the following section:

PK PK].F OEBPS/toc.ncx;# Oracle® Fusion Middleware Securing Applications with Oracle Platform Security Services, 12c (12.1.2) Cover Title and Copyright Information Contents List of Examples List of Figures List of Tables Preface What's New in This Guide Part I Understanding Security Concepts 1 Introduction to Oracle Platform Security Services 2 Understanding Users and Roles 3 Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing 4 About Oracle Platform Security Services Scenarios Part II Basic OPSS Administration 5 Security Administration 6 Deploying Secure Applications Part III OPSS Services 7 Lifecycle of Security Artifacts 8 Configuring the Identity Store Service 9 Configuring the OPSS Security Store 10 Managing the Policy Store 11 Managing the Credential Store 12 Managing Keys and Certificates with the Keystore Service 13 Introduction to Oracle Fusion Middleware Audit Service 14 Configuring and Managing Auditing 15 Using Audit Analysis and Reporting Part IV Developing with Oracle Platform Security Services APIs 16 Integrating Application Security with OPSS 17 The OPSS Policy Model 18 Configuring Java EE Applications to Use OPSS 19 Configuring Java SE Applications to Use OPSS 20 Developing with the Authorization Service 21 Developing with the Credential Store Framework 22 Developing with the User and Role API 23 Developing with the Identity Directory API 24 Developing with the Keystore Service 25 Developing with the Audit Service Part V Appendices A OPSS Configuration File Reference B File-Based Identity and Policy Store Reference C Oracle Fusion Middleware Audit Framework Reference D User and Role API Reference E Administration with Scripting and MBean Programming F OPSS System and Configuration Properties G OPSS API References H Using an OpenLDAP Identity Store I Adapter Configuration for Identity Virtualization J Troubleshooting OPSS Copyright PK@#;#PK].FOEBPS/devkss.htm Developing with the Keystore Service

24 Developing with the Keystore Service

This chapter explains how to utilize the Keystore Service when developing applications.

Beginning with a survey of the Keystore Service API, the chapter describes what you need to know when invoking the service in your applications; explains how to configure the service; and presents examples of common keystore operations and ways to retrieve keys at runtime.

This chapter contains the following topics:

24.1 About the Keystore Service API

A keystore is used for secure storage of and access to keys and certificates. The Keystore Service API is used to access and perform operations on the keystores.

The Keystore Service:

  • enables you to manage keys and certificates securely

  • provides an API for storage, retrieval, and maintenance of keys and certificates in different back-end repositories

  • supports file, database, LDAP-based keystore management

Critical (create, update, delete) functions provided by the Keystore Service API include:

  • creating keystores

  • deleting keystores

  • obtaining a handle to the domain trust store

  • obtaining a handle to a keystore

  • obtaining the configured properties for a keystore

  • obtaining a list of the keystores within an application stripe

Operations on a KeyStore are secured by KeyStoreAccessPermission, which implements the fine-grained access control model utilized by the Keystore Service.

24.2 Overview of Application Development with the Keystore Service

Knowledge of the following areas is helpful in getting your applications to work with the Keystore Service:

  • Determining appropriate application stripe and keystore names to use.

  • Provisioning Java security policies.

    Policy permissions are set in the policy store, which can be file-based (system-jazn-data.xml) or LDAP-based. Setting appropriate permissions to enable application usage without compromising the security of your data requires careful consideration of permission settings.

  • Defining the Keystore Service instance in jps-config.xml.

    You will need to define the service instance in jps-config.xml only if manually crafting the configuration file.


    Note:

    The file-based provider is already configured by default, and can be changed to an LDAP-based provider. See Section 9.6, "Migrating the OPSS Security Store".

  • Steps to take in setting up the environment.

    The steps are different for stand-alone applications and those that operate in an Oracle WebLogic Server environment.

24.3 Setting the Java Security Policy Permission

The Oracle Platform Security Services keystore provider is set when the server is started. When the provider is file-based, the data is stored in system-jazn-data.xml.

Keystore Service supports securing keys:

  • at the application stripe level,

  • at the keystore level, or

  • with finer granularity for specific <application stripe, keystore, key>


Notes:

  • To properly access the Keystore Service APIs, you need to grant Java permissions in the policy store.

  • The code invoking Keystore Service APIs needs code source permission. The permissions are typically for specific code jars and not for the complete application.


This section provides guidelines for permission grants to keystore objects, along with several examples:


Note:

In the examples, the application jar file name is AppName.jar.

24.3.1 Guidelines for Granting Permissions

The Keystore Service relies on Java permissions to grant permissions to keystore or key objects. It is highly recommended that only the requisite permissions be granted, and no more.


WARNING:

It is risky and inadvisable to grant unnecessary permissions, particularly permissions to all application stripes and/or keystores.


24.3.2 Permissions Grant Example 1

The Keystore Service stores objects in a hierarchy:

application stripe -> keystore(s) -> key(s)/certificate(s)


See Also:

Section 12.1.1 for details about the object hierarchy in the Keystore Service.

This example grants permissions for a specific application stripe and a specific keystore name within that stripe.

<jazn-policy>
    <grant>
        <grantee>
            <principals>...</principals>
            <!-- This is the location of the jar -->
            <!-- as loaded with the run-time -->
            <codesource>
      <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
            </codesource>
        </grantee>
        <permissions>
            <permission>
               <class>oracle.security.jps.service.keystore.
                      KeyStoreAccessPermission</class>
               <name>stripeName=keystoreapp,keystoreName=ks1,alias=*</name>
              <!-- All actions are granted -->
              <actions>*</actions>
            </permission>
        </permissions>
    </grant>
</jazn-policy>

where:

  • stripeName is the name of the application stripe (typically the name of the application) for which you want to grant these permissions (read, write, update, and delete permissions denoted by the wildcarded actions).

  • keystoreName is the keystore name in use.

  • alias indicates the key alias within the keystore.


    Note:

    The wildcard indicates the application is granted permission for all aliases.

24.3.3 Permissions Grant Example 2

In this example, permissions are granted for a specific application stripe name and all its keystores.

<jazn-policy>
    <grant>
        <grantee>
            <principals>...</principals>
            <codesource>
      <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
            </codesource>
        </grantee>
        <permissions>
           <permission>
              <class>oracle.security.jps.service.keystore.
                     KeyStoreAccessPermission</class>
              <name>stripeName=keystoreapp,keystoreName=*,alias=*</name>
              <!-- Certain actions are explicitly specified -->
              <!-- Compare to wild-card grant in previous example -->
              <actions>read,write,update,delete</actions>
        </permission>
        </permissions>
    </grant>
</jazn-policy>

24.3.4 Permissions Grant Example 3

In this example, read permissions are granted for a specific key alias within an application stripe name and a keystore.

<jazn-policy>
    <grant>
        <grantee>
            <principals>...</principals>
            <codesource>
      <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
            </codesource>
        </grantee>
        <permissions>
           <permission>
              <class>oracle.security.jps.service.keystore.
                     KeyStoreAccessPermission</class>
              <name>stripeName=keystoreapp,keystoreName=ks1,alias=orakey</name>
              <actions>read</actions>
        </permission>
        </permissions>
    </grant>
</jazn-policy>

24.4 Configuring the Keystore Service

You need to define the Keystore Service instance in a configuration file which contains information about the location of the keystore and the provider classes. Configuration files are located in:

$DOMAIN_HOME/config/fmwconfig

and are named as follows:

  • jps-config.xml for Oracle WebLogic Server

  • jps-config-jse.xml for Java SE

24.5 Using the Keystore Service API

You can use the Keystore Service within Oracle WebLogic Server or in a standalone environment.

24.5.1 Using the Keystore Service API in Java SE Applications

To use the keystore service API in Java SE applications, proceed as follows:

  1. Set up the classpath. Ensure that the jps-manifest.jar file is in your classpath. For details, see Required JAR in Classpath in Section 1.5.3, "Scenario 3: Securing a Java SE Application".

  2. Set up the policy; to provide access to the Keystore Service APIs, you need to configure the access permissions in the reference policy store. For examples, see Section 24.3, "Setting the Java Security Policy Permission".

  3. Set JVM command-options. See details below.

  4. Run the application.

Command-line options include:

  • -Doracle.security.jps.config
    

    specifies the full path to the configuration file jps-config.xml, typically located in the directory domain_home/config/fmwconfig.

  • -Djava.security.policy
    

    specifies the location of the OPSS/Oracle WebLogic Server policy file weblogic.policy, typically located in the directory wl_home/server/lib.

  • -Dcommon.components.home
    

    specifies the location of the oracle_common directory under middleware home.

  • -Djrf.version
    

    specifies the version used in the environment; its value is 11.1.1.

  • -Djava.security.debug=all
    

    is helpful for debugging purposes

24.5.2 Using the Keystore Service API in Java EE Applications

To use the API in Java EE applications, proceed as follows:

  1. Out-of-the-box, the keystore service provider section of the jps-config.xml file is configured in the following directory:

    $DOMAIN_HOME/config/fmwconfig
    

    If needed, reassociate to an LDAP or database store.

  2. Set up the policy. To provide access to the Keystore Service APIs, you need to configure the access permissions in the reference policy store. For examples, see Section 24.3, "Setting the Java Security Policy Permission".

  3. Start Oracle WebLogic Server.

  4. Deploy and test the application.

24.6 Example of Keystore Service API Usage

This section provides an example of using the Keystore Service APIs. It contains these topics:

24.6.1 Java Program for Keystore Service Management Operations

The following Java code demonstrates common Keystore Service operations:

import oracle.security.jps.JpsContext;
import oracle.security.jps.JpsContextFactory;
import oracle.security.jps.JpsException;
import oracle.security.jps.service.keystore.KeyStoreProperties;
import oracle.security.jps.service.keystore.KeyStoreService;
import oracle.security.jps.service.keystore.KeyStoreServiceException;
 
import java.security.AccessController;
import java.security.PrivilegedAction;
 
public class KeyStoreTest {
 
    private static KeyStoreService ks = null;
 
 
    public KeyStoreTest() {
        super();
    }
 
    /*
     * This method performs a non-privileged operation. Either all code
     * in the call stack must have KeyStoreAccessPermission
     * OR
     * the caller must have the KeyStoreAccessPermission only and
     * invoke this operation in doPrivileged block
     */
    public static void doKeyStoreOperation() {
        doOperation();
    }

     /*
     * Since this method performs a privileged operation, only current class or
     * jar containing this class needs KeyStoreAccessPermission
     */
    public static void doPrivilegedKeyStoreOperation() {
        AccessController.doPrivileged(new PrivilegedAction<String>() {
            public String run() {
                doOperation();
                return "done";
            }
        });
    }
 
    private static void doOperation() {
        try {
            ks.deleteKeyStore("keystoreapp", "ks1", null);
        } catch(KeyStoreServiceException e) {
            e.printStackTrace();
        }

 public static void main(String args[]) throws Exception {
 
        try {
            new JpsStartup().start();
            JpsContext ctx = JpsContextFactory.getContextFactory().getContext();
            ks = ctx.getServiceInstance(KeyStoreService.class);
            
            // #1 - this call is in a doPrivileged block
            // #1 - this should succeed.
            doPrivilegedKeyStoreOperation();
 
            // #2 - this will also pass since granted all application
            // code necessary permission
            // NOTE: Since this call is not in a doPrivileged block,
            // this call would have failed if KeyStoreAccessPermission
            // wasn't granted to this class.
 
            /*
            doKeyStoreOperation();
            */
            
        } catch (JpsException je) {
            je.printStackTrace();
        }
 
    }
}

See Also:

Keystore API documentation at http://docs.oracle.com/javase/6/docs/api/index.html

24.6.2 Reading Keys at Runtime

This section explains ways an application can access keystore artifacts at runtime. It contains these topics:

24.6.2.1 Getting the Keystore Handle

To access a keystore at runtime and retrieve keys and certificates, an application must first get the keystore handle from the Keystore Service.

There are two approaches to this task:

  1. Obtain the handle by explicitly specifying the application stripe and keystore name as separate parameters

  2. Obtain the handle by specifying the application stripe and the keystore name as one parameter

Applications are free to use either method. Both methods work exactly in the same way for fetching keys and certificates, the only difference is the way the key store is loaded. Method 1 uses OPSS APIs while method 2 uses JDK KeyStore APIs.

24.6.2.2 Accessing Keystore Artifacts - Method 1

This example demonstrates the first method, in which the application stripe and keystore name are separate parameters.

// First get the KeyStoreService handle from JpsContext

JpsContext ctx = JpsContextFactory.getContextFactory().getContext();
KeyStoreService kss = ctx.getServiceInstance(KeyStoreService.class);
 
// Now get the keystore handle from KeyStoreService. There are two ways to 
// do this:
// Method 1: Explicitly specify application stripe and keystore name as
// separate parameters. In this example, the last parameter is null since
// we are demonstrating a permission-protected keystore. 

java.security.KeyStore keyStore = kss.getKeyStore("keystoreapp", "ks1", null);

// If this keystore is password-protected, provide the keystore password as the
// last parameter.
// java.security.KeyStore.ProtectionParameter pwd = new

java.security.KeyStore.PasswordProtection("password".toCharArray());

// java.security.KeyStore keyStore = kss.getKeyStore("keystoreapp", "ks1", pwd);
 
 
// Method 2: Specify application stripe and keystore name as one parameter
// using KSS URI. The last parameter is the keystore password, which is
// set to null in this example due to permission protected keystore.
// For password-protected keystore, set it to the keystore password.
// Since we are demonstrating Method 1 in this
// example, method 2 is commented out
 
// java.security.KeyStore keyStore kss.getKeyStore("kss://keystoreapp/ks1", null);
 
// Now you have a handle to the JDK KeyStore object. Use this handle to get
// key(s) and/or certificate(s)
 
// Get the private key or secret key associated with this alias. Pass the
// key password as the second parameter. In this case, it is null due to
// permission protected keystore.

Key key = keyStore.getKey("key-alias", null);
 
// Get the certificate associated with this alias

Certificate cert = keyStore.getCertificate("cert-alias");

Note:

Although this code fragment does not show this, calls to load, getKey, getCert are all privileged operations, and they should therefore be wrapped in a doPrivileged() block.

24.6.2.3 Accessing Keystore Artifacts - Method 2

This example demonstrates a method in which the application stripe and keystore name are provided as one parameter using the JDK Keystore URI.

// Create an object with parameters indicating the keystore to be loaded
FarmKeyStoreLoadStoreParameter param = new FarmKeyStoreLoadStoreParameter();
param.setAppStripeName("keystoreapp");
param.setKeyStoreName("ks1");
// The password is set to null in this example since it assumes this is a 
// permission protected keystore.
param.setProtectionParameter(null);
// If the keystore is password protected, use the following lines instead
// java.security.KeyStore.ProtectionParameter pwd = new java.security.KeyStore.PasswordProtection("password".toCharArray());
// param.setProtectionParameter(pwd);
 
// Initialize the keystore object by setting keystore type and provider
java.security.KeyStore keyStore = KeyStore.getInstance("KSS", new FarmKeyStoreProvider());
 
// Load the keystore. There are two ways to do this:
// Method 1: Explicitly specify application stripe and keystore name as
// separate parameters in param object
// keyStore.load(param);
 
// Method 2: Specify application stripe and keystore name as one parameter
// using KSS URI. Since we demonstrate method 2, in this
// example, method 1 is commented out
 
FarmKeyStoreLoadStoreParameter param = new FarmKeyStoreLoadStoreParameter();
param.setKssUri("kss://keystoreapp/ks1");
param.setProtectionParameter(null);
keyStore.load(param);
 
// Now you have a handle to JDK KeyStore object. Use this handle to get
// key(s) and/or certificate(s)
 
// Get the private key or secret key associated with this alias
Key key = keyStore.getKey("key-alias", null);
// Get the certificate associated with this alias
Certificate cert = keyStore.getCertificate("cert-alias");

Note:

Although this code fragment does not show it, calls to load, getKey, getCert are all privileged operations, and they should therefore be wrapped in a doPrivileged() block.

24.6.3 Policy Store Setup

For illustration, the example uses an XML-based policy store file (system-jazn-data.xml) which has the appropriate permissions needed to access the given keystore from the store. The file defines the permissions for different combinations of application stripe and keystore name. Other combinations, or attempts to access the store beyond the permissions defined here, will be disallowed.


Note:

This grant is added to the default policy store in
$DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml
.

Here the system property projectsrc.home is set to point to the directory containing the Java SE application, and clientApp.jar is the application jar file which is present in sub-directory dist.

The corresponding policy grant looks like this:

<grant>
   <grantee>
      <codesource>
         <url>file:${projectsrc.home}/dist/clientApp.jar</url>
      </codesource>
   </grantee>
   <permissions>
      <permission>
         <class>oracle.security.jps.service.keystore.KeyStoreAccessPermission
         </class>
         <name>stripeName=keystoreapp,keystoreName=ks1,alias=*</name>
         <actions>*</actions>
      </permission>
   </permissions>
</grant>

24.6.4 Configuration File

Here is a sample configuration file (jps-config-jse.xml). The keystore.file.path property of the keystore service shows the directory containing the keystores.xml file:


Note:

For the complete configuration file see the default file shipped with the distribution at $DOMAIN_HOME/config/fmwconfig/jps-config-jse.xml.

<jpsConfig>
 ...
    <serviceInstances>
        <serviceInstance name="keystore_file_instance"
                         provider="keystore_file_provider">
            <property name="keystore.file.path" value="store" />
            <property name="keystore.provider.type" value="file" />
        </serviceInstance>
    </serviceInstances>
 ...
</jpsConfig>

24.6.5 About Using the Keystore Service in the Java SE Environment

In the Java SE environment, the following calls are equivalent:

KeyStoreService store = JpsServiceLocator.getServiceLocator().lookup(KeyStoreService.class);

and:

KeyStoreService store = JpsContextFactory.getContextFactory().getContext().getServiceInstance
(KeyStoreService.class);

24.7 Best Practices

In a clustered environment and when the store is file-based, use the Keystore Service Mbean API over the Keystore Service API to create, retrieve, update, and delete keys for an application.

If you are simply reading keys, however, either API can be used.

PKh~PK].F OEBPS/toc.htm Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services, 12c (12.1.2)

Contents

List of Examples

List of Figures

List of Tables

Preface

What's New in This Guide

Part I Understanding Security Concepts

1 Introduction to Oracle Platform Security Services

2 Understanding Users and Roles

3 Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing

4 About Oracle Platform Security Services Scenarios

Part II Basic OPSS Administration

5 Security Administration

6 Deploying Secure Applications

Part III OPSS Services

7 Lifecycle of Security Artifacts

8 Configuring the Identity Store Service

9 Configuring the OPSS Security Store

10 Managing the Policy Store

11 Managing the Credential Store

12 Managing Keys and Certificates with the Keystore Service

13 Introduction to Oracle Fusion Middleware Audit Service

14 Configuring and Managing Auditing

15 Using Audit Analysis and Reporting

Part IV Developing with Oracle Platform Security Services APIs

16 Integrating Application Security with OPSS

17 The OPSS Policy Model

18 Configuring Java EE Applications to Use OPSS

19 Configuring Java SE Applications to Use OPSS

20 Developing with the Authorization Service

21 Developing with the Credential Store Framework

22 Developing with the User and Role API

23 Developing with the Identity Directory API

24 Developing with the Keystore Service

25 Developing with the Audit Service

Part V Appendices

A OPSS Configuration File Reference

B File-Based Identity and Policy Store Reference

C Oracle Fusion Middleware Audit Framework Reference

D User and Role API Reference

E Administration with Scripting and MBean Programming

F OPSS System and Configuration Properties

G OPSS API References

H Using an OpenLDAP Identity Store

I Adapter Configuration for Identity Virtualization

J Troubleshooting OPSS

PK*%^JPK].FOEBPS/devauthoriz.htm%> Developing with the Authorization Service

20 Developing with the Authorization Service

This chapter explains how to use OPSS authorization in Java SE applications and lists some unsupported methods.

These topics are presented in the following sections:

For other OPSS services for Java SE applications, see Section 19.2, "Security Services in Java SE Applications."

20.1 Policy and Credential Stores in Java SE Applications

The configuration of policy and credential stores in Java SE applications is explained in the following sections:

System properties should be set, as appropriate, for authorization to work in Java SE applications. For a complete list of properties, see Section F.1, "OPSS System Properties."

A Java SE application can use file-, LDAP-, or DB-based store providers; these services are configured in the application file jps-config-jse.xml.

20.1.1 Configuring File-Based Policy and Credential Stores

A file-based policy store is specified in the file system-jazn-data.xml; a file-based credential store is specified in the file cwallet.sso (this wallet file should not be confused with the bootstrap file, also named cwallet.sso, which contains the credentials to access LDAP stores, when the application security is LDAP-based).

For details about wallets, see Section 18.5.3, "Using a Wallet-Based Credential Store." For details about modifying or adding bootstrap credentials, see modifyBootStrapCredential and addBootStrapCredential.

The following fragments illustrate the configuration of file-based policy and credential stores, and the jpsContext that reference them:

<serviceProviders>
  <serviceProvider type="CREDENTIAL_STORE" name="credstoressp"
        class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider">
    <description>SecretStore-based CSF Provider</description>
  </serviceProvider>
  <serviceProvider type="POLICY_STORE" name="policystore.xml.provider"
        class="oracle.security.jps.internal.policystore.xml.XmlPolicyStoreProvider">
  <description>XML-based PolicyStore Provider</description>
  </serviceProvider>
</serviceProviders>

<serviceInstances>
  <serviceInstance name="credstore" provider="credstoressp" location="./">
    <description>File-based Credential Store Service Instance</description>
  </serviceInstance>
 
  <serviceInstance name="policystore.xml" provider="policystore.xml.provider" location="./system-jazn-data.xml">
   <description>File-based Policy Store Service Instance</description>
   <property name="oracle.security.jps.policy.principal.cache.key" value="false"/>
  </serviceInstance>
</serviceInstances>

<jpsContexts default="TestJSE">
  <jpsContext name="TestJSE">
            <serviceInstanceRef ref="credstore"/>
            <serviceInstanceRef ref="policystore.xml"/>
    ...
  </jpsContext>
  ...
</jpsContexts>

Note the required setting of the property oracle.security.jps.policy.principal.cache.key to false in the policy store instance.

20.1.2 Configuring LDAP-Based Policy and Credential Stores

This section assumes that an LDAP-based store has been set to be used as the policy and credential stores; for details about setting up nodes in an Oracle Internet Directory, see section Section 9.2.1, "Prerequisites to Using an LDAP-Based Security Store."

The following fragments illustrate the configurations of providers and instances for LDAP-based policy and credential stores for a Java SE application:

<serviceProviders
  <serviceProvider type="POLICY_STORE" mame="ldap.policystore.provider"
 class=oracle.security.jps.internal.policystore.ldap.LdapPolicyStoreProvider"/>
   
  <serviceProvider type="CREDENTIAL_STORE" mame="ldap.credential.provider"
 class=oracle.security.jps.internal.credstore.ldap.LdapCredentialStoreProvider"/>
</serviceProviders>

<serviceInstances>
 <serviceInstance provider="ldap.policystore.provider" name="policystore.ldap">
  <property value="OID" name="policystore.type"/>
  <property value="bootstrap" name="bootstrap.security.principal.key"/>
  <property value="cn=PS1domainRC3" name="oracle.security.jps.farm.name"/>
  <property value="cn=myTestNode" name="oracle.security.jps.ldap.root.name"/>
  <property value="ldap://myComp.com:1234" name="ldap.url"/>
 </serviceInstance>

 <serviceInstance provider="ldap.credential.provider" name="credstore.ldap">
  <property value="bootstrap" name="bootstrap.security.principal.key"/>
  <property value="cn=PS1domainRC3" name="oracle.security.jps.farm.name"/>
  <property value="cn=myTestNode" name="oracle.security.jps.ldap.root.name"/>
  <property value="ldap://myComp.com:1234" name="ldap.url"/>
 </serviceInstance>
</serviceInstances>

The following fragment illustrates the configuration of the bootstrap credentials file (cwallet.sso), which allows the program access to the LDAP server:

<serviceInstance location="./bootstrap" provider="credstoressp" name="bootstrap.cred">
  <property value="./bootstrap" name="location"/>
</serviceInstance>

The following fragment illustrates the configuration of the necessary jpsContexts that reference the instances above:

<jpsContexts default="TestJSE">
  <jpsContext name="TestJSE">
    <serviceInstanceRef ref="policystore.ldap"/>
    <serviceInstanceRef ref="credstore.ldap"/>
  </jpsContext>
  <jpsContext name="bootstrap_credstore_context">
    <serviceInstanceRef ref="bootstrap.cred"/>  
  </jpsContext>
</jpsContexts>

The following code fragment illustrates how to obtain programmatically a reference to the LDAP-based policy store configured above, and it assumes that the system property oracle.security.jps.config has been set to the location of the file jps-config-jse.xml:

String contextName="TestJSE"; ...
public static PolicyStore getPolicyStore(String contextName) {
      try-block    
            JpsContextFactory ctxFact;  
            ctxFact = JpsContextFactory.getContextFactory();   
            JpsContext ctx = ctxFact.getContext(contextName);  
            return ctx.getServiceInstance(PolicyStore.class);      
      catch-block
...

20.1.3 Configuring DB-Based OPSS Security Stores

This section assumes that a DB-based store has been set to be used as the OPSS security store. For details about setting up nodes in a DB, see section Section 9.3.1, "Prerequisites to Using a DB-Based Security Store."

Note the following important points regarding the sample configuration below:

  • The value of the configuration property jdbc.url should be identical to the name of the JDBC data source entered when the data source was created.

  • The values of the bootstrap credentials (map and key) must match those passed to the WLST command addBootStrapCredential when the bootstrap credential was created.

The following fragment illustrates configuration of DB-based policy, credential, and key stores in the file jps-config-jse.xml:

<jpsConfig  …>
  <propertySets>
   <propertySet name="props.db.1">
    <property value="cn=myDomain" name="oracle.security.jps.farm.name"/>
    <property value="DB_ORACLE" name="server.type"/>
    <property value="cn=myRoot" name="oracle.security.jps.ldap.root.name"/>
    <property name="jdbc.url" value="jdbc:oracle:thin:@myhost.com:1521/srv_name"/>
    <property name="jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="bootstrap.security.principal.key" value="myKeyName" />
    <property name="bootstrap.security.principal.map" value="myMapName" />
   </propertySet> 
  </propertySets>
  <serviceProviders>
    <serviceProvider class="oracle.security.jps.internal.policystore.OPSSPolicyStoreProvider"
           type="POLICY_STORE" name="policy.rdbms">
      <description>DBMS based PolicyStore</description>
    </serviceProvider>

    <serviceProvider class="oracle.security.jps.internal.credstore.rdbms.DbmsCredentialStoreProvider"
               type="CREDENTIAL_STORE" name="db.credentialstore.provider" >

  <serviceProvider class="oracle.security.jps.internal.keystore.KeyStoreProvider" 
               type="KEY_STORE" name="keystore.provider" >
    <property name="provider.property.name" value="owsm"/>
  </serviceProvider>
 </serviceProviders>
 
 <serviceInstances>
   <serviceInstance name="policystore.rdbms" provider="db.policystore.provider">  
    <propertySetRef ref = "props.db.1"/>
    <property name="policystore.type"  value="DB_ORACLE"/>
   </serviceInstance>

   <serviceInstance name="credstore.rdbms" provider="db.credstore.provider">
    <propertySetRef ref = "props.db.1"/>  
   </serviceInstance>
 
   <serviceInstance name="keystore.rdbms" provider="db.keystore.provider">  
    <propertySetRef ref = "props.db.1"/> 
    <property name="keystore.provider.type"  value="db"/>
   </serviceInstance>
  </serviceInstances>
 
  <jpsContexts default="default">
    <jpsContext name="default">
      <serviceInstanceRef ref="policystore.rdbms"/>      
      <serviceInstanceRef ref="credstore.rdbms"/>
      <serviceInstanceRef ref="keystore.rdbms"/>
    </jpsContext>
  </jpsContexts>
</jpsConfig>

20.2 Unsupported Methods for File-Based Policy Stores

This release does not support, for file-based policy stores, methods involving the following features:

  • Complex queries

  • Cascading deletions

Complex queries relates to any method that takes a query. When the policy store is file-based, the query must be simple; if such a method is passed a complex query and the policy store is file-based, the method will throw an exception.

A simple query is a query with just one search criterion; a complex query is a query with two or more search criteria; each call to addQuery adds a criterion to the query.

The following code fragment that illustrates the building of a simple query that returns of all permissions with a display name matching the string MyDisplayName:

PermissionSetSearchQuery query = new PermissionSetSearchQuery();
query.addQuery(PermissionSetSearchQuery.SEARCH_PROPERTY.DISPLAY_NAME,
               false,
               ComparatorType.EQUALITY,
               "MyDisplayName",
               BaseSearchQuery.MATCHER.EXACT);
getPermissionSets(query);

The following example illustrates the building of a complex query that returns all permission sets with a given resource type and a given resource instance name:

PermissionSetSearchQuery query = new PermissionSetSearchQuery();
query.addQuery(PermissionSetSearchQuery.SEARCH_PROPERTY.RESOURCE_TYPE,
               false,
               ComparatorType.EQUALITY, 
               "MyResourceType",
               BaseSearchQuery.MATCHER.EXACT);
  
query.addQuery(PermissionSetSearchQuery.SEARCH_PROPERTY.RESOURCE_NAME,
               false, 
               ComparatorType.EQUALITY, 
               "MyResourceInstanceName", 
               BaseSearchQuery.MATCHER.EXACT);
 
query.setANDMatch();
getPermissionSets(query);

Cascading deletions relates to any method that includes the Boolean argument cascadeDelete. The only value allowed for this argument in case the policy store is file-based is FALSE. Here is an example of such a method in the interface ResourceTypeManager:

void deleteResourceType(EntryReference rtRef, boolean cascadeDelete)
                 throws PolicyObjectNotFoundException,
                        PolicyStoreOperationNotAllowedException,
                        PolicyStoreException
PK[o*>%>PK].FOEBPS/preface.htm0 Preface

Preface

This manual explains the features and administration of the Oracle Platform Security Services.

Audience

The intended audience of this guide are experienced Java developers, administrators, deployers, and application managers who want to understand and use Oracle Platform Security Services.

The overall structure of the guide is divided into parts, each of which groups related major topics. Parts I through III are relevant to administrators; parts IV contains information about the OPSS policy model and is intended for developers; and part V contains reference information.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Conventions

The following text conventions are used in this document:

ConventionMeaning
boldfaceBoldface type indicates graphical user interface elements associated with an action.
italicItalic type indicates book titles, emphasis, terms defined in text, or placeholder variables for which you supply particular values.
monospaceMonospace type within a paragraph indicates commands, URLs, Java class names and method names, file and directory names, text that appears on the screen, or text that you enter.

PKu 50PK].FOEBPS/stores.htmfw Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing

3 Understanding Identities, Policies, Credentials, Keys, Certificates, and Auditing

Applications use the identity, policy, credential stores, keystores, and audit repository configured in the domain in which they run. This chapter introduces the basic concepts regarding identity, policy, credential, keystore, and audit data. In addition, it presents a matrix that shows the compatible versions of security artifacts.

This chapter is divided into the following sections:

For definitions of the terms used in this chapter, see Section 2.1, "Terminology."

For scenarios illustrating the use of stores, see Chapter 4, "About Oracle Platform Security Services Scenarios."

3.1 Compatibility Matrix for 11g and 12c Versions

This section states the compatible versions of binaries, configurations, schemas, and stores for releases 11.1.1.5.0, 11.1.1.6.0, 11.1.1.7.0, 11.1.1.9.0 and 12.1.2.0.0. The compatible versions of these artifacts apply to both DB-based and OID-based OPSS stores.

The OPSS security store is a composite store, that is, a store that includes all security artifacts such as policies, keys, credentials, and audit metadata. In DB-based stores, exactly one logical security store is assumed per DB schema.

The following table shows the versions compatible and it applies to both DB-based and OID-based security stores. Note the following terminology symbols:

  • The prefix => next to a version number denotes a version equal to or higher than the stated version number.

  • The prefix > next to a version number denotes a version higher than the stated version number.

  • The prefix < next to a version number denotes a version lower than the stated version number.

BinaryConfigurationSchemaStoreStatus
11.1.1.5.011.1.1.5.0=>11.1.1.5.011.1.1.5.0Certified
11.1.1.5.011.1.1.5.0>11.1.1.5.0>11.1.1.5.0Not supported
11.1.1.6.011.1.1.5.0=>11.1.1.5.011.1.1.5.0Certified
11.1.1.6.011.1.1.5.0>11.1.1.5.0>11.1.1.5.0Not supported
11.1.1.6.011.1.1.6.0=>11.1.1.6.011.1.1.6.0Certified
11.1.1.6.011.1.1.6.0>11.1.1.6.0>11.1.1.6.0Not supported
11.1.1.7.011.1.1.7.0=>11.1.1.6.0<11.1.1.7.0Not supported
11.1.1.7.011.1.1.6.0=>11.1.1.6.011.1.1.6.0Certified
11.1.1.7.011.1.1.6.0>11.1.1.6.0>11.1.1.6.0Not supported
11.1.1.7.011.1.1.7.0=>11.1.1.7.011.1.1.7.0Certified
11.1.1.9.011.1.1.7.011.1.1.6.011.1.1.5.0=>11.1.1.7.0=>11.1.1.6.0=>11.1.1.5.011.1.1.7.011.1.1.6.011.1.1.5.0Certified
11.1.1.9.011.1.1.9.0=>11.1.1.9.011.1.1.9.0Certified (schema only upgrade)
12.1.2.0.012.1.2.0.0=>12.1.2.0.012.1.2.0.0Certified
12.1.2.0.0<12.1.2.0.0<12.1.2.0.0<12.1.2.0.0Not supported

3.2 Authentication Basics

OPSS uses server authentication providers, components that validate user credentials or system processes based on a user name-password combination or a digital certificate. Authentication providers also make user identity information available to other components in a domain (through subjects) when needed.

Java EE applications use LDAP- or DB-based authentication providers. Java SE applications use a file-based identity store out-of-the-box, but they can be configured to use also LDAP- or DB-based authenticator providers.

For further details, see section Authentication in Understanding Security for Oracle WebLogic Server.

This section covers the following topics:

3.2.1 Identity Store Types and WebLogic Authenticators

The information in this section applies only to Java EE applications. For details about using authenticators in Java SE applications, see Section 19.3.2, "Configuring an LDAP Identity Store in Java SE Applications."

The following list enumerates the repositories supported for an identity store (note that all are LDAP-based except for the last one):

  • Oracle Internet Directory 11g

  • Oracle Virtual Directory

  • Open LDAP 2.2

  • Oracle Unified Directory 11gR1

  • Oracle Directory Server Enterprise Edition 11.1.1.3.0

  • Sun DS 6.3, 7.0

  • Novell eDirectory 8.8

  • Tivoli Access Manager

  • Active Directory

  • Active Directory AM

  • Active Directory 2008

  • Oracle DB 10g, 11gR1, 11gR2

Open LDAP 2.2 requires a special set up; for details see Appendix H, "Using an OpenLDAP Identity Store."

For support for reference integrity in Oracle Internet Directory servers, see Important note Section 9.2, "Using an LDAP-Based OPSS Security Store."

For details about WebLogic Authenticators, consult the document Understanding Security for Oracle WebLogic Server.

To create and configure a new authenticator using the WebLogic console, proceed as follows:

  1. Create a new authenticator. For details see list of topics following this procedure.

    Select the appropriate WebLogic authenticator; the parameters you enter depend on the authenticator selected; for example, in case of OidAuthenticator, you enter the host information, as illustrated in the following sample:

    host name: example.com
    port: 5555
    principal: cn=orcladmin
    credential: myPassword
    user base DN: cn=Users,dc=us,dc=oracle,dc=com
    group base DN: cn=Groups,dc=us,dc=oracle,dc=com
    
  2. Save your input to create a new authenticator.

  3. Set the appropriate control flag in the created authenticator.

  4. Reorder the list of authenticators in your domain, as appropriate.

  5. Restart the WebLogic server.


Important:

Any LDAP-based authenticator used in a domain, other than the DefaultAuthenticator, requires that the flag UseRetrievedUserNameAsPrincipal be set. Out-of-the-box, this flag is set in the DefaultAuthenticator.

For further information about WebLogic authenticators, consult the following topics:

3.2.2 WebLogic Authenticators

By default and out-of-the-box, Oracle WebLogic Server stores users and groups in the DefaultAuthenticator. This authenticator is setup to use cn as the default attribute.

The data stored in any LDAP authenticator can be accessed by the User and Role API to query user profile attributes, but custom code may be required to query non-LDAP identity store repositories.

This section contains the following topics:

For details about X.509 identity assertion, see section How an LDAP X509 Identity Assertion Provider Works in Administering Security for Oracle WebLogic Server.

For details about authentication using the SAML 1.1 or SAML 2.0 identity assertion provider, see section Configuring the SAML Authentication Provider in Administering Security for Oracle WebLogic Server.

3.2.2.1 Multiple Authenticators

Oracle WebLogic Server allows the configuration of multiple authenticators in a given context. One of them must be an LDAP-based authenticator.

OPSS initializes the identity store service with the LDAP authenticator chosen from the list of configured authenticators according to the following algorithm:

  1. Consider the subset of LDAP authenticators configured. Note that, since the context is assumed to contain at least one LDAP authenticator, this subset is not empty.

  2. Within that subset, consider those that have set the maximum flag. The flag ordering used to compute this subset is the following:

    REQUIRED > REQUISITE > SUFFICIENT > OPTIONAL
    

    Again, this subset (of LDAPs realizing the maximum flag) is not empty.

  3. Within that subset, consider the first configured in the context.

The LDAP authenticator singled out in step 3 is the one chosen to initialize the identity store service. For details about host name verification when establishing an SSL connection with an LDAP authenticator, see Securing a Production Environment for Oracle WebLogic Server.

For details about the default values that OPPS uses to initialize the various supported LDAP authenticators, see javadoc User and Role API documentation in Section G.1, "OPSS API References." If a service instance initialization value is provided by default and also (explicitly) in the service instance configuration, the value configured takes precedence over the default one.

3.2.2.2 Additional Authentication Methods

The WebLogic Identity Assertion providers support certificate authentication using X.509 certificates, SPNEGO tokens, SAML assertion tokens, and CORBA Common Secure Interoperability version 2 (CSIv2) identity assertion.

The Negotiate Identity provider is used for SSO with Microsoft clients that support the SPNEGO protocol. This provider decodes SPNEGO tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users.

For general information about identity assertion providers, see section Identity Assertion Providers in Understanding Security for Oracle WebLogic Server.

For an overview of SSO with Microsoft clients, see section Overview of Single Sign-On with Microsoft Clients in Administering Security for Oracle WebLogic Server.

For details about Kerberos identification, see section Creating a Kerberos Identification for WebLogic Server in Administering Security for Oracle WebLogic Server.

3.3 Policy Store Basics

A Java 2 policy specifies the permissions granted to signed code loaded from a given location.

A JAAS policy extends Java 2 grants by allowing an optional list of principals; the semantics of the permissions are granted to only code from a given location, possibly signed, and run by a user represented by those principals.

JACC extends the Java 2 and JAAS permission-based policy to EJBs and Servlets by defining an interface to plug custom authorization providers, that is, pluggable components that allow the control and customizing of authorizations granted to running Java EE applications.

An application policy is a collection of Java 2 and JAAS policies, which is applicable to just that application (in contrast to a Java 2 policy, which is applicable to the whole JVM).

The policy store is a repository of system and application-specific policies and roles. Application roles can include enterprise users and groups specific to the application (such as administrative roles). A policy can use any of these groups or users as principals.

In the case of applications that manage their own roles, Java EE application roles (configured in files web.xml or ejb-jar.xml) get mapped to enterprise users and groups and used by application-specific policies.

Policy Store Types

A policy store can be file-, LDAP-, or DB-based. A file-based policy store is an XML file, and this store is represented by the out-of-the-box policy store provider. The only LDAP-based policy store type supported is Oracle Internet Directory. The only DB-based policy store type supported is Oracle RDBMS.

Policy Store Scope, Migration, and Reassociation

There is exactly one policy store per domain. During development, application policies are file-based and specified in the file jazn-data.xml.

When the application is deployed on WebLogic with Fusion Middleware Control, they can be automatically migrated into the policy store. For details about this feature, see Section 9.6.1, "Migrating with Fusion Middleware Control." By default, the policy store is file-based.

For reassociation details, see Section 9.5, "Reassociating the OPSS Security Store."


Note:

All permission classes must be specified in the system class path.

For details about the resource catalog support within a policy store, see Section 17.3.1, "The Resource Catalog."

3.4 Credential Store Basics

A credential store is a repository of security data (credentials) that certify the authority of users, Java components, and system components. A credential can hold user name and password combinations, tickets, or public key certificates. This data is used during authentication, when principals are populated in subjects, and, further, during authorization, when determining what actions the subject can perform.

OPSS provides the Credential Store Framework, a set of APIs that applications can use to create, read, update, and manage credentials securely.

Credential Store Types

A credential store can be file-, LDAP-, or DB-based. A file-based credential store, also referred to as wallet-based and represented by the file cwallet.sso, is the out-of-the-box credential store. The only LDAP-based credential store type supported is Oracle Internet Directory. The only DB-based credential store type supported is Oracle RDBMS (releases 11.1.0.7 or later; and releases 11.2.0.3 or later).

Credential Store Scope, Migration, and Reassociation

An application can use either the domain credential store or its own wallet-based credential store. The domain credential store can be wallet-based (by default), LDAP-, or DB-based. The only LDAP-based credential store type supported is Oracle Internet Directory.

The migration of application credentials to the credential store can be configured to take place automatically when the application is deployed. For details, see Section 9.6.1, "Migrating with Fusion Middleware Control."

Credentials can also be reassociated from one type of store to another. For details, see Section 9.5, "Reassociating the OPSS Security Store."

3.5 Keystore Service Basics

The Keystore Service provides a central repository for keystores and trust stores containing all the keys and certificates used by a domain's components and applications. This eliminates the need to associate keystores with individual applications.

The administrator works with a single user interface providing a unified way to view and manage all keystores.

3.5.1 Keystore Repository Types

The central repository can be any of the following:

  • XML file-based

    This is the out-of-the-box keystore repository, and it is named keystores.xml.


    Note:

    This file is not present immediately after installation; rather, it is generated the first time the Administration Server is started.

  • Oracle Database

  • Oracle Internet Directory (Note: No other LDAP servers are supported.)


See Also:

Chapter 12 for details about the Keystore Service.

3.5.2 Keystore Repository Scope and Reassociation

Keys and certificates in the domain keystore repository can be reassociated from one type to another. For details, see Section 9.5, "Reassociating the OPSS Security Store".

3.6 Audit Service Basics

The Audit Service supports a central repository of audit records for the domain. Administrators can conveniently leverage the service to audit events triggered by configuration changes as well as operational activity for components and deployed applications.

Audit Repository Types

The repository for audit records can be:

  • file-based

  • Oracle Database


See Also:

Chapter 13 for details about the audit service.

PKkwfwPK].FOEBPS/part_adaa.htme OPSS Services

Part III

OPSS Services

This part describes OPSS services in the following chapters:

PK jePK].FOEBPS/openid.htm Using an OpenLDAP Identity Store

H Using an OpenLDAP Identity Store

This appendix describes the special set up required in case the identity store uses OpenLDAP 2.2.

It includes the following section:

H.1 Using an OpenLDAP Identity Store

To use OpenLDAP 2.2 as an identity store, proceed as follows:

  1. Use the WebLogic Server administration console to create a new authenticator provider. For this new provider:

    • Select OpenLDAPAuthenticator from the list of authenticators.

    • Set the control flag of the OpenLDAPAuthenticator to SUFFICIENT.

    • Set the control flag of the DefaultAuthenticator to SUFFICIENT.

    • Change the order of authenticators to make the OpenLDAPAuthenticator the first in the list.

    • In the Provider Specific page for the OpenLDAPAuthenticator, enter User Base DN and Group Base DN, and set the value of the objectclass in the Group From Name Filter to something other than groupofnames.

  2. From the Home directory of the OpenLDAP installation:

    • Open the file slapd.conf for edit.

    • In that file, insert the following line in the "include" section at the top:

      include ./schema/inetorgperson.schema
      
    • Save the file, and restart the OpenLDAP.

The above settings make possible adding the object class inetorgperson to every new external role you create in the OpenLDAP; this object class is required to map the external role to an application role.

PK PK].FOEBPS/audreport.htm,% Using Audit Analysis and Reporting

15 Using Audit Analysis and Reporting

This chapter describes how to configure audit reporting and how to view audit reports.

This chapter contains these topics:


Note:

To determine whether you can use the reporting features described in this chapter, read Section 15.1 before proceeding.

15.1 About Audit Reporting

Two approaches to audit reporting are possible in Oracle Fusion Middleware Audit Framework. The approach you adopt is dictated by the audit model and component(s) in use at your site:

  • Dynamic Metadata Model

    This audit metadata model was introduced in 11g Release 1 (11.1.1.6.0). New Oracle Fusion Middleware 12c (12.1.2) installations automatically use this model.

    Section 15.2 explains how to create audit reports based on this model.

  • Report Template Model

    This earlier model is used by system components. In addition, when you upgrade, the audit framework continues to use the model.

    Section C.2 and Section C.3 explain how to create audit reports based on this model.

15.2 Generate Reports of Audit Data

The ultimate goal of audit integration is to create reports of audit events stored in audit database tables. As described in Section 14.6.1, audit events are saved into the common attribute table iau_common (Section 13.4.2.2), and the custom attribute tables iau_custom_nnn (Section 13.4.2.4). OPSS Common Audit Framework generates SQL scripts for components to create Oracle database views which component reporting applications can use to query audit event data from audit database tables.

15.2.1 Configuring for Audit Reports

The following steps (some of which you have already accomplished) are required:

  • Integrate with the audit framework using dynamic or declarative registration (Section 25.2 through Section 25.4).

  • Configure audit policies so that the run-time audit service logs events to generate audit data (Section 25.5 and Section 25.6).

  • Configure the audit loader to ensure bus-stop files are migrated to the database (Section 14.2).

  • Use the createAuditDBView command to generate a SQL script of audit definitions ("Viewing Audit Definitions for your Component" in Section 13.5.3.2).

  • Log in to the database as the IAU schema user to create a view using the SQL script from the previous step.

  • Configure your reporting application to query the view.


See Also:

Section C.3.2.

Here is a sample output of createAuditDBView for component ApplicationAudit:

-- Audit View for Component
 
CREATE VIEW ApplicationAudit_AUDITVIEW AS
 
SELECT IAU_AUDITSERVICE.IAU_TRANSACTIONID AS AUDITSERVICE_TRANSACTIONID,
 
IAU_COMMON.IAU_COMPONENTTYPE AS ComponentType,
 
IAU_COMMON.IAU_MAJORVERSION AS MajorVersion,
 
IAU_COMMON.IAU_MINORVERSION AS MinorVersion,
 
IAU_COMMON.IAU_INSTANCEID AS InstanceId,
 
IAU_COMMON.IAU_HOSTID AS HostId,
 
IAU_COMMON.IAU_HOSTNWADDR AS HostNwaddr,
 
IAU_COMMON.IAU_MODULEID AS ModuleId,
 
IAU_COMMON.IAU_PROCESSID AS ProcessId,
 
IAU_COMMON.IAU_ORACLEHOME AS OracleHome,
 
IAU_COMMON.IAU_HOMEINSTANCE AS HomeInstance,
 
IAU_COMMON.IAU_ECID AS ECID,
 
IAU_COMMON.IAU_RID AS RID,
 
IAU_COMMON.IAU_CONTEXTFIELDS AS ContextFields,
 
IAU_COMMON.IAU_SESSIONID AS SessionId,
 
IAU_COMMON.IAU_TARGETCOMPONENTTYPE AS TargetComponentType,
 
IAU_COMMON.IAU_APPLICATIONNAME AS ApplicationName,
 
IAU_COMMON.IAU_EVENTTYPE AS EventType,
 
IAU_COMMON.IAU_EVENTCATEGORY AS EventCategory,
 
IAU_COMMON.IAU_EVENTSTATUS AS EventStatus,
 
IAU_COMMON.IAU_TSTZORIGINATING AS TstzOriginating,
 
IAU_COMMON.IAU_THREADID AS ThreadId,
 
IAU_COMMON.IAU_COMPONENTNAME AS ComponentName,
 
IAU_COMMON.IAU_INITIATOR AS Initiator,
 
IAU_COMMON.IAU_MESSAGETEXT AS MessageText,
 
IAU_COMMON.IAU_FAILURECODE AS FailureCode,
 
IAU_COMMON.IAU_REMOTEIP AS RemoteIP,
 
IAU_COMMON.IAU_TARGET AS Target,
 
IAU_COMMON.IAU_RESOURCE AS IAU_RESOURCE,
 
IAU_COMMON.IAU_ROLES AS Roles,
 
IAU_COMMON.IAU_DOMAINNAME AS DomainName,
 
IAU_COMMON.IAU_COMPONENTDATA AS ComponentData,
 
IAU_COMMON.IAU_AUDITUSER AS AuditUser,
 
IAU_COMMON.IAU_TENANTID AS TenantId,
 
IAU_COMMON.IAU_TRANSACTIONID AS TransactionId,
 
IAU_COMMON.IAU_USERTENANTID AS UserTenantId,
 
IAU_CUSTOM.IAU_INT_001 AS AccountNumber,
 
IAU_CUSTOM.IAU_DATETIME_001 AS Date,
 
IAU_CUSTOM.IAU_FLOAT_001 AS Amount,
 
IAU_CUSTOM.IAU_STRING_002 AS Status,
 
IAU_CUSTOM.IAU_FLOAT_002 AS Balance,
 
IAU_USERSESSION.IAU_AUTHENTICATIONMETHOD AS AuthenticationMethod
 
FROM IAU_AUDITSERVICE, IAU_COMMON, IAU_CUSTOM, IAU_USERSESSION WHERE IAU_COMMON.IAU_ID = IAU_AUDITSERVICE.IAU_ID AND IAU_COMMON.IAU_ID = IAU_CUSTOM.IAU_ID AND IAU_COMMON.IAU_ID = IAU_USERSESSION.IAU_ID AND IAU_COMMON.IAU_ComponentType = 'ApplicationAudit';

15.2.2 Using Oracle Business Intelligence Publisher

You can leverage Oracle Business Intelligence Publisher to generate reports from your application's audit data, utilizing the same reporting capabilities available to Oracle components.

The basic steps are as follows:

  1. Use a database view (created with the createAuditDBView command) to generate an Oracle BI Publisher report template.

  2. Set up the Oracle BI Publisher report service.

  3. Copy the report template into Oracle BI Publisher to view component audit events.

  4. Generate reports with Oracle BI Publisher.


See Also:

Section C.2

PKL1%,%PK].FOEBPS/intregrating.htm Integrating Application Security with OPSS

16 Integrating Application Security with OPSS

This chapter describes a number of security-related use cases, including the propagation of identities in domains and across domains, and the typical lifecycle of an ADF application security. It also lists code and configuration samples presented elsewhere in this Guide.

This chapter contains the following sections:

16.1 Introduction

The audience for the material presented in this chapter are developers, security architects, and security administrators. The presentation is not feature-driven, as in most topics in this Guide, but use case-driven: a number of use cases that solve typical application security challenges are introduced as a departing point to solve particular application security requirements. Some of the use cases describe a declarative approach (and do not require changes in application code); others provide a programmatic approach; and others require both approaches.

The top security issues that security architects and developers face include managing users, user passwords, and access to resources. OPSS is a suite of security services that provides solutions to these challenges by supporting:

  • Externalizing security artifacts and the security logic from the application

  • A declarative approach to security

  • A complete user identity lifecycle

  • Policy-driven access controls

Figure 16-1 illustrates how applications access the security stores and the tools to manage those stores.

Figure 16-1 Applications, Security Stores, and Management Tools

Surrounding text describes Figure 16-1 .

Links to Related Documentation

Topics explained elsewhere include the following:

For the list of OPSS APIs, see Appendix G, "OPSS API References."

16.2 Security Integration Use Cases

This section introduces a number of use cases categorized according to a main security feature or security artifact, in the following sections:

Each use case contains a brief description of the problem it attempts to solve, the security artifacts required, the features involved, and links to details solving the stated problem.

16.2.1 Authentication

The authentication use cases are the following:

16.2.1.1 Java EE Application Requiring Authenticated Users

In order to access a Java EE application, users must be authenticated against the identity store in cases where the identity store is any of the following:

  • Single LDAP-based store

  • Several LDAP-based stores of the same kind (such as all OID, for example)

  • Several LDAP-based stores of different kinds; in particular two LDAP-based stores: one AD LDAP and a second one OID LDAP

  • Single DB-based store

  • Several LDAP- and DB-based stores

This use case requires:

  • Allowing access to the application to only authenticated users

  • Not modifying the application code, even when customers have user identities in different repositories

This use case features:

  • Deploying an application to a WebLogic container

  • Configuring the appropriate authenticators according to the particular set of user repositories

  • Configuring the OVD authenticator in case of a mixed LDAP types or mixed LDAP and DB types

According to the repository used, the details of this use case are split into the following scenarios:

  • Single user repository - Configure the appropriate authenticator with the WebLogic console

  • Multiple user repositories (or split profiles across LDAP of the same of different kinds) - Configure the OVD authenticator

  • DB-based repositories - Configure the OVD authenticator

For details, see Section 3.2.2, "WebLogic Authenticators."

16.2.1.2 Java EE Application Requiring Programmatic Authentication

A Java EE application, not using deployment descriptors, must authenticate the user programmatically against the configured identity store(s); it applies only to Java EE applications deployed to the Oracle WebLogic Application Server.

This use case requires using the OPSS public API to authenticate a user, and it features:

  • Configuring authenticators for a Java EE container

  • Using the LoginService API to authenticate the user

For details about this use case, see Section 18.1, "Links to Authentication Topics for Java EE Applications."

16.2.1.3 Java SE Application Requiring Authentication

A Java SE application must authenticate users against the LDAP identity store in use in a domain; the application code requesting authentication must be same regardless of the specifics of the domain's identity store.

This use case requires configuring the identity store(s) against which the authentication should take place and using the LoginService; note that a Java SE application can use only one id login module.

For details about this use case, see Section 19.3.4, "Using the OPSS API LoginService in Java SE Applications."

16.2.2 Identities

The identity use cases are the following:

16.2.2.1 Application Running in Two Environments

An application, which runs in two different environments, needs to access user profile information, such as a user's email address, stored in an LDAP-based store; the type of the LDAP server can be any of the supported types, and that type may differ with the environment. For details on supported types, see Section 4.1, "Supported File-, LDAP-, and DB-Based Services."

More specifically, this use case assumes that:

  • The application uses the method UserProfile.getEmail().

  • In one environment, there is an AD LDAP configured as follows:

    mail.attr = msad_email
    
  • In the second environment, there is an OID LDAP configured as follows:

    mail.attr = mail
    

In order for the application to retrieve the correct information without modifying the code and regardless of the environment (first or second) in which it runs, the identity store provider must be configured with the correct property in each of those two environments.

In the first environment (AD LDAP), the identity store provider is set to have the following property:

<property name="mail.attr" value="msad_mail">

In the second one (OID LDAP), the identity store provider is set to have the following property:

<property name="mail.attr" value="mail"

For details about this use case, see Section 8.2, "Configuring the Identity Store Provider."

16.2.2.2 Application Accessing User Profiles in Multiple Stores

An application needs access to user profile information located in more than one LDAP-based stores.

This use case requires configuring the environment for multiple LDAP-based stores.

For details about:

16.2.3 Authorization

The authorization use cases are the following:

16.2.3.1 Java EE Application Accessible by Specific Roles

A Java EE application needs to be accessible only by users that had been assigned specific roles in web descriptors; the group-to-role assignment must be configurable at deployment based on the customer's environment.

For details about this use case, see sections Using Declarative Security with Web Applications and Using Declarative Security with EJBs in Developing Applications with the WebLogic Security Service.

16.2.3.2 ADF Application Requiring Fine-Grained Authorization

An ADF application in container requires fine-grained authorization at the level of individual controls on the pages in the web application; while the application initiates the authorization check, the policies need to be externalized and customizable per customer post application deployment.

For details on how to develop and secure Oracle ADF applications, see chapter 30, Enabling ADF Security in a Fusion Web Application, in Developing Fusion Web Applications with Oracle Application Development Framework.

For general information about ADF applications, see Section 1.5.2, "Scenario 2: Securing an Oracle ADF Application."

For details about the lifecycle of an ADF application, see Appendix - Security Lifecycle of an ADF Application.

16.2.3.3 Web Application Securing Web Services

A web application requires securing web services with fine grained policies.

For details about web services security administration, see Securing Web Services and Managing Policies with OWSM.

16.2.3.4 Java EE Application Requiring Codebase Permissions

A Java EE application requires codebase permissions to perform specific actions; typical examples are reading a credential from the credential store or looking up policies in the OPSS security store.

For details about creating codebase policies with Fusion Middleware Control, see Section 10.2.3, "Managing System Policies."

16.2.3.5 Non-ADF Application Requiring Fine-Grained Authorization

A non-ADF application needs to be secured with fine-grained authorization checks.

This use case requires:

  • Placing checks in the application code at the appropriate places

  • Configuring the appropriate policies

For details see Section 17.3, "The JAAS/OPSS Authorization Model."

16.2.4 Credentials

The credential use case is the following:

16.2.4.1 Application Requiring Credentials to Access System

An application requires a credential to connect to a back-end system, such as a database or an LDAP server. The application code should reference this credential in such a way that the specifics of the credential can be changed per customer post deployment without modifying the application code. Furthermore, this use case also requires specifying who can access the credential store and what operations an authorized user can perform on credential data.

This use case features:

  • Using the credential store to persist credentials

  • Fetching credentials at runtime with the CSF API in application code

  • Defining and enforcing system policies on codebase

For details about:

16.2.5 Audit

The audit use cases are the following:

16.2.5.1 Auditing Security-Related Activity

An application needs to record security-related activity in several security areas; specifically, the application requires logging the following information:

  • Changes to a policy: what and when

  • The policies that were evaluated in a particular time interval

  • Changes to credentials or keys: what and when

The settings explained in this use case apply to all applications and components in a domain.

This use case requires that auditable applications:

  • Integrate with the Common Audit Framework (CAF)

  • Have built-in capabilities to log security activities

  • Set the proper audit filter level to capture activities in specific security areas

This use case features:

  • Integrating with the Common Audit Framework

  • Allowing applications to define their own audit categories and events in security areas, and making the application audit-aware

  • Allowing applications to set the appropriate filter level

For details about:

16.2.5.2 Auditing Business-Related Activity

An application needs to record business-related activity in the context of a functional flow. Specifically, the application requires logging the users and the business actions performed by them in a particular time interval.

The settings explained in this use case apply to all applications and components in a domain.

This use case requires that applications:

  • Create their own audit events based on their business needs

  • Be able to log business activities with runtime attributes to audit data repository

  • Generate audit reports from audit events

  • Manage runtime audit policies

  • Modify audit event definitions, if necessary

This use case features:

  • Allowing applications to define business functional areas (as audit categories), business activities (as audit events in categories), and attributes in each category.

  • Registering applications at deployment; updating audit definitions; deregistering applications after deployment.

  • Managing audit artifacts with Fusion Middleware Control or WSLT scripts.

For details about:

16.2.6 Identity Propagation

The identity propagation use cases are the following:

16.2.6.1 Propagating the Executing User Identity

A client application in container needs to propagate the executing user identity to a web service over SOAP; the web service can be running on a different managed server, in the same domain, or in a different domain.

This use case requires that the current executing user identity be propagated to a web service over SOAP.

The features that facilitate this use case are primarily those of Oracle Web Services Manager (OWSM).

For details about OWSM, see Securing Web Services and Managing Policies with OWSM.

For details about propagating identities over SOAP, see Securing Web Services and Managing Policies with OWSM.

16.2.6.2 Propagating a User Identity

A client application in container needs to propagate a user identity (which is not the executing user identity) to a web service over SOAP; the identity to be propagated is stored in the OPSS security store.

This use case requires that an identity of a user, distinct from the current executing user, be propagated to a web service over SOAP.

This use case features:

  • The OPSS security store, where credentials are stored, from where the application gets the specific identity that needs to be propagated as a PasswordCredential.

  • Oracle Web Services Manager ability to fetch and propagate the identity to a remote web service.

For details about this use case, see Securing Web Services and Managing Policies with OWSM.

16.2.6.3 Propagating Identities Across Domains

A client application in container in a WebLogic domain needs to propagate a user identity (stored in the OPSS security store) to a different WebLogic domain over RMI.

For details about this use case, see section Enabling Trust Between WebLogic Server Domains.

16.2.6.4 Propagating Identities over HTTP

A client application in container (in a WebLogic domain) needs to propagate identities over HTTP.

For requirements and details about this use case, see Propagating Identities with the OPSS Trust Service, the recommended implementation. An alternate implementation (not using the OPSS Keystore Service) is described in Appendix - Propagating Identities with JKS-Based Key Stores.

16.2.7 Administration and Management

The administration use cases are the following:

16.2.7.1 Application Requiring a Central Store

An application requires a central repository of policies, credentials, audit configuration, trusts, and keys, and a set of tools to manage that central repository, which is the OPSS security store.

This use case features:

  • The OPSS security store

  • Managing security artifacts with Fusion Middleware Control

  • Managing security artifacts with WLST commands

For details about:

16.2.7.2 Application Requiring Custom Management Tool

An application requires a custom tool to manage externalized security artifacts in a context that is meaningful to the application's business.

This use case requires building a custom graphical user interface with calls to OPSS APIs to display and manage security artifacts in the OPSS security store in a context that is meaningful to the application.

This use case features:

  • Managing security artifacts with OPSS API

For details about:

16.2.7.3 Application Running in a Multiple Server Environment

Application running in a WebLogic domain where several server instances are distributed across multiple machines requires modifying security artifacts; changes must take effect in all components of the application regardless of where they are running.

This use case features:

  • Propagating changes to security artifacts whenever those changes are initiated on the administration server; data on managed server nodes is refreshed based on caching policies.

  • Using the MBeans API or Management API to modify security artifacts.

For details about:

16.2.8 Integration

The integration use case is the following:

16.2.8.1 Application Running in Multiple Domains

A product requires multiple WebLogic domains to run and those domains share a single central OPSS security store.

This use case features:

  • OPSS support for several domains to share a security store

For details about:

16.3 The OPSS Trust Service

The OPSS trust service allows the propagation of identities across HTTP-enabled applications by providing and validating tokens. The OPSS trust service uses an asserter that is available only on the following platform:

  • Oracle WebLogic Application Server - the Identity Asserter

There is one asserter per WebLogic domain.

For details about the service configuration properties, see Section F.2.6, "Trust Service Properties." For details about configuring this service with Fusion Middleware Control, see Section 9.7.3, "Configuring the Trust Service Provider," or alternatively, use the WLST command updateTrustServiceConfig. For details about this command, see Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

16.4 Propagating Identities over the HTTP Protocol

Identity propagation using HTTP calls typically runs as follows (see Figure 16-2):

  1. A client application in Domain1 requests a token for an authenticated user from Domain1's OPSS trust service instance.

  2. The trust service accesses Domain1's keystore and issues a token to the client application.

  3. The client application encodes the token in an HTML header and dispatches an HTTP request to a servlet application in Domain2. Domain 2's asserter intercepts the request and extracts the token.

  4. The asserter requests a validation of that token from Domain2's OPSS trust service instance.

  5. The trust service accesses Domain2's keystore to validate the token and returns a response.

  6. Assuming that the validation is successful, the asserter sends the request to the servlet application using the asserted identity.

  7. The servlet application sends an HTTP response to the client application request.

Figure 16-2 Identity Propagation with HTTP Calls

Surrounding text describes Figure 16-2 .

The out-of-the-box configuration sets the key alias based on the WebLogic server name.


Note:

The recommended way to implement identity propagation is using the OPSS Trust Service and the OPSS Keystore, as explained in Propagating Identities with the OPSS Trust Service.

16.5 Propagating Identities with the OPSS Trust Service

This section explains how to propagate identities across multiple domains and across containers in a single domain using the OPSS Trust Service. Identity Propagation using the Trust service is supported only on the Oracle Weblogic Server platform.

For details about the OPSS keystore service see Chapter 12, "Managing Keys and Certificates with the Keystore Service."

This section contains code and configuration samples needed to propagate identities on the Oracle WebLogic platform using the OPSS Trust Service, in the following sections:

16.5.1 Across Multiple WebLogic Domains

In this scenario there are two different domains: Domain1 and Domain2. The client application is running in Domain1; the servlet application is running in Domain2. The client application uses Domain1's OPSS trust service for token generation, and the servlet application uses Domain2's OPSS trust service for token validation.

The samples and configurations required in this scenario are explained in the following sections:

16.5.1.1 Token Generation on the Client-Side Domain

On the client side, that is, in the domain where the token is issued, the following are required:

16.5.1.1.1 Developing the Client Application

The client application can be a Java SE or Java EE application. The following code sample illustrates the skeleton of a client application:

// Authentication type name
public static final String AUTH_TYPE_NAME = "OIT";
// The authenticated username
String user = "weblogic"; 
// URL of the target application
URL url = "http://<host>:<port>/<destinationApp>"; 
//-----------------------------------------
JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext jpsCtx = ctxFactory.getContext();
final TrustService trustService = jpsCtx.getServiceInstance(TrustService.class);
final TokenManager tokenMgr = trustService.getTokenManager();
final TokenContext ctx = tokenMgr.createTokenContext(
    TokenConfiguration.PROTOCOL_EMBEDDED);
UsernameToken ut = WSSTokenUtils.createUsernameToken("wsuid", user);
GenericToken gtok = new GenericToken(ut);
ctx.setSecurityToken(gtok);
ctx.setTokenType(SAML2URI.ns_saml);
Map<String, Object> ctxProperties = ctx.getOtherProperties();
ctxProperties.put(TokenConstants.CONFIRMATION_METHOD,
    SAML2URI.confirmation_method_bearer);
 
AccessController.doPrivileged(new PrivilegedAction<String>() {
    public String run() {
        try {
            tokenMgr.issueToken(ctx);
        } catch (Exception e) {        
            e.printStackTrace();
        }
        return null;
    }
});
 
Token token = ctx.getSecurityToken();
String b64Tok = TokenUtil.encodeToken(token);
 
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setDoOutput(true);
connection.setReadTimeout(10000);
connection.setRequestProperty("Authorization", AUTH_TYPE_NAME + " " + b64Tok);
connection.connect();
BufferedReader rd = new BufferedReader(new InputStreamReader(
    connection.getInputStream()));
StringBuilder sb = new StringBuilder();
 
String line = null;
while ((line = rd.readLine()) != null) {
    sb.append(line);
}
connection.disconnect();        
System.out.println(sb.toString());
16.5.1.1.2 Configuring the OPSS Keystore Service

The trust service keystore should be provisioned with a client certificate and a private key; that certificate is then exported from the keystore and imported into the trust store. Both these stores, the keystore and the trust store, are managed by OPSS KSS in the client domain.


Note:

When the trust service property trust.keystoreType is set to KSS, it is recommended not to use passwords for the keystore or the trust store; in this case, by default, the keystore and trust store used by the trust service are protected by codesource permissions and therefore they do not require password protection.

The following script illustrates these tasks:

# Update following values with correct value
user = "<username>"
password = "<password>"
wlsurl = "t3(s)://<host>:<port>"
stripeName = "<stripeNmae>"
 
#-----------------------------------------------
ksName = "<trustservice_ks>"
tsName = "<trustservice_ts>"
aliasName = "<trustservice>"
issuerDN = "cn=" + aliasName
 
print "Stripe Name: " + stripeName
 
print "KeyStore Name: " + ksName
print "TrustStore Name: " + tsName
print "Alias Name: " + aliasName
print "Issuer DN: " + issuerDN
 
#-----------------------------------------------
connect(user, password, wlsurl)
 
svc = getOpssService(name='KeyStoreService')
svc.listKeyStores(appStripe=stripeName)

svc.createKeyStore(appStripe=stripeName, name=ksName, password="", permission=true)
svc.generateKeyPair(appStripe=stripeName, name=ksName, password="", dn=issuerDN, keysize="1024", alias=aliasName, keypassword="")
svc.exportKeyStoreCertificate(appStripe=stripeName, name=ksName, password="", alias=aliasName, keypassword="", type="Certificate", filepath="./trustservice.cer")
 
svc.createKeyStore(appStripe=stripeName, name=tsName, password="", permission=true)
svc.importKeyStoreCertificate(appStripe=stripeName, name=tsName, password="", alias=aliasName, keypassword="", type="TrustedCertificate", filepath="./trustservice.cer")
 
svc.listKeyStores(appStripe=stripeName)
svc.listKeyStoreAliases(appStripe=stripeName, name=ksName, password="", type="Certificate")
exit()
16.5.1.1.3 Adding a TrustServiceAccessPermission Grant

The following system policy illustrates a codesource grant that allows clients to use the Trust Service APIs, and should be included in the application's jazn-data.xml file:

<grant>
  <grantee>
    <codesource> 
       <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
    </codesource>
  </grantee>
  <permissions>
    <permission> 
       <class>oracle.security.jps.service.trust.TrustServiceAccessPermission</class>
      <name>appId=*</name>
      <actions>issue</actions>
    </permission>
  </permissions>
</grant>

The grant can be added to the OPSS security store using a WLST command; for details see script grantPermission, in Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

Alternatively, if the application is a Java EE application and the file jazn-data.xml is packed with the application, the lifecycle listener can be set so that the grant is migrated to the OPSS security store when the application is deployed; for details, see Section 18.2, "Configuring the Servlet Filter and the EJB Interceptor."

16.5.1.1.4 Configuring the Trust Service Provider

The following sample illustrates a configuration of the trust service provider in the jps-config.xml file:

<propertySet name="trust.provider.embedded">
        <property name="trust.keystoreType" value="KSS"/>
  <property name="trust.keyStoreName" value="kss://<stripeName>/<keystoreName>"/>
  <property name="trust.trustStoreName" value="kss://<stripeName>/<truststoreName>"/>
  <property name="trust.aliasName" value="<aliasName>"/>
  <property name="trust.issuerName" value="<issuerName>"/>
  <property name="trust.provider.className" value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
  <property name="trust.clockSkew" value="60"/>
  <property name="trust.token.validityPeriod" value="1800"/>
  <property name="trust.token.includeCertificate" value="false"/>
</propertySet>

16.5.1.2 Server Side or Token Validation Domain

On the server side, that is, in the domain where the token is received, the following are required:

16.5.1.2.1 Developing the Server Application

The servlet code can obtain an asserted user as illustrated in the following sample:

public void doGet(HttpServletRequest request, HttpServletResponse response)
   throws ServletException, IOException {
   String username = request.getRemoteUser();
   ServletOutputStream out = response.getOutputStream();
   out.print("Asserted username: " + username);
   out.close();
}
16.5.1.2.2 Configuring web.xml

The file web.xml must set the login configuration method to CLIENT-CERT as illustrated in the following sample:

<web-app id="WebApp_ID"
…
 <login-config>
   <auth-method>CLIENT-CERT</auth-method>
   <realm-name>Identity Assertion </realm-name>
 </login-config>
…
</web-app>
16.5.1.2.3 Configuring the WebLogic Trust Service Asserter

To configure the WebLogic Trust Service Asserter proceed as follows:

  1. Perform one of the following:

    • Login to the WebLogic console as an administrator, and navigate to Security Realms -> myrealm -> Providers Tab -> Authentication; then select TrustServiceIdentityAsserter.

      This asserter calls the Trust Service APIs to decode and validate the token from the incoming request, and pass the user name to the WebLogic Server to establish the asserted subject.

    • Use the following script:

      connect("<username>","<password>","t3://<host>:<port>")
      edit()
      startEdit()
      realm = cmo.getSecurityConfiguration().getDefaultRealm()
      tsia = realm.lookupAuthenticationProvider("TSIA")
      if tsia != None:
          realm.destroyAuthenticationProvider(tsia)
      tsia = realm.createAuthenticationProvider("TSIA", "oracle.security.jps.wls.providers.trust.TrustServiceIdentityAsserter")
      save()
      activate()
      disconnect()
      
16.5.1.2.4 Provisioning the OPSS Keystore Service

The client certificate provisioned in the Domain1's key store must be exported from that domain and imported into the Domain2's trust store, as illustrated in the script below.


Note:

In case of multi-domain setup, the issuerName set during token generation on the client side is used as the alias name to search for the certificate name on the server side. The certificate in the keystore should be imported with an alias that matches the issuer name on the client side.

# Update following values with correct value
user = "<username>"
password = "<password>"
wlsurl = "t3(s)://<host>:<port>"
 
stripeName = "<stripeName>"
 
#-----------------------------------------------
ksName = "<trustservice_ks>"
tsName = "<trustservice_ts>"
aliasName = "<trustservice>"
 
print "Importing certificate for : " + aliasName
print "Stripe Name: " + stripeName
 
print "TrustStore Name: " + tsName
print "Alias Name: " + aliasName
 
#-----------------------------------------------
connect(user, password, wlsurl)
 
svc = getOpssService(name='KeyStoreService')
 
svc.listKeyStores(appStripe=stripeName)
 
# switch Trust service to using FKS
svc.createKeyStore(appStripe=stripeName, name=tsName, password="", permission=true)
 
svc.importKeyStoreCertificate(appStripe=stripeName, name=tsName, password="", alias=aliasName, keypassword="", type="TrustedCertificate", filepath="./trustservice.cer")
 
svc.listKeyStoreAliases(appStripe=stripeName, name=tsName, password="", type="TrustedCertificate")
 
exit()
16.5.1.2.5 Adding a TrustServiceAccessPermission

The following system policy illustrates a codesource grant that allows clients to validate the Trust Service APIs, and should be included in the application's jazn-data.xml file:

<grant>
  <grantee>
    <codesource> 
       <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
    </codesource>
  </grantee>
  <permissions>
    <permission> 
       <class>oracle.security.jps.service.trust.TrustServiceAccessPermission</class>
      <name>appId=*</name>
      <actions>validate</actions>
    </permission>
  </permissions>
</grant>
16.5.1.2.6 Configuring the Trust Service Provider

The following sample illustrates a configuration of the trust service provider in the jps-config.xml file:

<propertySet name="trust.provider.embedded">
        <property name="trust.keystoreType" value="KSS"/>
  <property name="trust.keyStoreName" value="kss://<stripeName>/<keystoreName>"/>
  <property name="trust.trustStoreName" value="kss://<stripeName>/<truststoreName>"/>
  <property name="trust.aliasName" value="<aliasName>"/>
  <property name="trust.issuerName" value="<issuerName>"/>
  <property name="trust.provider.className" value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
  <property name="trust.clockSkew" value="60"/>
  <property name="trust.token.validityPeriod" value="1800"/>
  <property name="trust.token.includeCertificate" value="false"/>
</propertySet>

Note:

If the server is used only for token validation, the aliasName and issuerName set in the example above are not used for token validation and are optional attributes. In this case, to validate a token, the trust service looks for the certificate using the issuer name included in the token.

16.5.2 Across Containers in a Single WebLogic Domain

In this scenario the client and server applications run in the same domain; hence both applications can use the same keystore, and therefore it is not necessary to import the client certificate (into some other keystore). All other information remains identical to that explained in the multiple-domain scenario.

16.5.3 Embedded Trust Service Provider Properties

The following properties are used to configure the embedded trust service provider in single or multiple domain scenarios:

  • trust.keyStoreType

  • trust.keyStoreName

  • trust.trustStoreName

  • trust.aliasName

  • trust.issuerName

  • trust.provider.className

  • trust.clockSkew

  • trust.token.validityPeriod

  • trust.token.includeCertificate

The following sample illustrates a sample configuration of the embedded trust service provider in the file jps-config.xml:

<propertySet name="trust.provider.embedded">
  <property name="trust.keystoreType" value="KSS"/>
  <property name="trust.keyStoreName" value="kss://<stripeName>/<keystoreName>"/>
  <property name="trust.trustStoreName" value="kss://<stripeName>/<truststoreName>"/>
  <property name="trust.aliasName" value="<aliasName>"/>
  <property name="trust.issuerName" value="<aliasName>"/>
  <property name="trust.provider.className" 
              value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
  <property name="trust.clockSkew" value="60"/>
  <property name="trust.token.validityPeriod" value="1800"/>
  <property name="trust.token.includeCertificate" value="false"/>
</propertySet>

To set properties for the embedded trust service provider, use the WLST command updateTrustServiceConfig, or alternatively, use Fusion Middleware Control as explained in Section 9.7.3, "Configuring the Trust Service Provider." For details about the command, see Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

In the configuration explained in Configuring the OPSS Keystore Service, set the values <stripName>, <keystoreName>, <trustStoreName>, <aliasName> accordingly.

16.6 A Custom Graphical User Interface

This use case illustrates some of the operations needed, for example, when implementing a custom graphic UI to manage policies. The samples presented use the OPSS APIs and demonstrate the following operations:

  • Querying users in the identity store.

  • Querying application roles in the OPSS security store.

  • Querying the mapping of users and groups to application roles; specifically, given a user identify all the application roles mapped to that user (Recall that the mapping of users and groups to application roles is a many-to-many relationship).

  • Creating, reading, updating, and deleting the mapping of users and groups to application roles.

This use case assumes that:

  • The identity store is an OID LDAP-based store.

  • The OPSS security store is an OID LDAP-based store.

  • The identity store contains the following hierarchy of users and groups (enterprise roles):

    • The users Mary, John, Tom, and Helen.

    • The groups IT, Training, and Development.

    • The groups Training and Development are members of the group IT.

    • The user Mary is a member of the group Training.

    • The users Tom and John are members of the group Development.

  • The OPSS security store contains the following application policies and hierarchy of application roles:

    • The application policies ApplicationPolicy1 and ApplicationPolicy2.

    • The roles System Manager, System Developer, and System Analyst are application roles referenced in the policy ApplicationPolicy1; the System Manager role is a member of the System Developer role; the System Developer role is a member of the System Analyst role.

    • The roles Director, Instructor, and Lecturer are application roles referenced in the application policy ApplicationPolicy2; the Director role is a member of the Instructor role; the Instructor role is a member of the Lecturer role.

  • The mapping of application roles to users and groups is as follows:

    • The role System Manager is mapped to the user Helen.

    • The role System Developer is mapped to the group Development.

    • The role Director is mapped to the user Tom.

    • The role Instructor is mapped to the groups Training and Development.

Figure 16-3 illustrates the hierarchy of application roles, the users and groups, and the mapping of application roles to users and groups, as assumed in this use case.

Figure 16-3 Mapping of Application Roles to Users and Groups

Surrounding text describes Figure 16-3 .

Note that the above role hierarchy implies, for instance, that a user in the System Manager role is also in the System Developer role, and similarly with the other roles. Therefore the role membership for each of the four users is as follows:

  • User Tom is a member of the following application roles: System Developer, System Analyst, Director, Instructor, and Lecturer.

  • User Helen is a member of the following application roles: System Manager, System Developer, and System Analyst.

  • User Mary is a member of the following application roles: Instructor and Lecturer.

  • User John is a member of the following application roles: System Developer, System Analyst, Instructor, and Lecturer.

The code samples are detailed in the following sections:

16.6.1 Imports Assumed

The sample codes in this use case assume the following import statements:

import java.security.AccessController;
import java.security.Policy;
import java.security.Principal;
import java.security.PrivilegedExceptionAction;
import java.security.Security;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import javax.security.auth.Subject;
import oracle.security.idm.Identity;
import oracle.security.idm.IdentityStore;
import oracle.security.idm.ObjectNotFoundException;
import oracle.security.idm.Role;
import oracle.security.idm.RoleManager;
import oracle.security.idm.SearchParameters;
import oracle.security.idm.SearchResponse;
import oracle.security.idm.SimpleSearchFilter;
import oracle.security.idm.User;
import oracle.security.idm.UserProfile;
import oracle.security.jps.ContextFactory;
import oracle.security.jps.JpsContext;
import oracle.security.jps.JpsContextFactory;
import oracle.security.jps.principals.JpsApplicationRole;
import oracle.security.jps.service.idstore.IdentityStoreService;
import oracle.security.jps.service.policystore.ApplicationPolicy;
import oracle.security.jps.service.policystore.PolicyObjectNotFoundException;
import oracle.security.jps.service.policystore.PolicyStore;
import oracle.security.jps.service.policystore.PolicyStoreException;
import oracle.security.jps.service.policystore.entitymanager.AppRoleManager;
import oracle.security.jps.service.policystore.info.AppRoleEntry;
import oracle.security.jps.service.policystore.search.AppRoleSearchQuery;
import oracle.security.jps.service.policystore.search.ComparatorType;
import oracle.security.jps.util.JpsAuth;
import weblogic.security.principal.PrincipalFactory;

16.6.2 Code Sample 1

The following sample code illustrates two queries to users in the identity store:

private void queryUsers() throws Exception {
        // Using IDM U/R to query ID store
        IdentityStore idmStore = idStore.getIdmStore();
 
        // Query an individual user by name
        User employee = idmStore.searchUser(USER_TOM);
        log("----------------------------------------------------------");
        log("### Query individual user (Tom) from ID store ###");
        log(USER_TOM + ": " + employee.getName() + " GUID: " +
            employee.getGUID());
        log();
 
        // Get all users whose name is not "Paul"
        SimpleSearchFilter filter =
            idmStore.getSimpleSearchFilter(UserProfile.NAME,
                                           SimpleSearchFilter.TYPE_NOTEQUAL,
                                           "Paul");
        SearchParameters sps =
            new SearchParameters(filter, SearchParameters.SEARCH_USERS_ONLY);
        SearchResponse result = idmStore.searchUsers(sps);
        log("----------------------------------------------------------");
        log("### Query all users (whose name is not Paul) from ID store ###");
        log("Found the following users:");
        while (result.hasNext()) {
            Identity user = result.next();
            log("\t user: " + user.getName() + ", GUID: " + user.getGUID());
        }
        log();
    }

16.6.3 Code Sample 2

The following sample code illustrates how to create an application role and how to make a role a member of another role:

private void createAppRoles1() throws Exception {
        AppRoleManager arm1 = ap1.getAppRoleManager();
        log("----------------------------------------------------------");
        log("### Creating app roles in app policy1 with hierachy ###");
 
        AppRoleEntry sysAnalystRole =
            arm1.createAppRole(APP_ROLE_SYS_ANALYST, APP_ROLE_SYS_ANALYST,
                               APP_ROLE_SYS_ANALYST);
        AppRoleEntry sysDeveloperRole =
            arm1.createAppRole(APP_ROLE_SYS_DEVELOPER, APP_ROLE_SYS_DEVELOPER,
                               APP_ROLE_SYS_DEVELOPER);
        AppRoleEntry sysManagerRole =
            arm1.createAppRole(APP_ROLE_SYS_MANAGER, APP_ROLE_SYS_MANAGER,
                               APP_ROLE_SYS_MANAGER);
 
        ap1.addPrincipalToAppRole(sysManagerRole, APP_ROLE_SYS_DEVELOPER);
        ap1.addPrincipalToAppRole(sysDeveloperRole, APP_ROLE_SYS_ANALYST);
        log("### App roles in app policy #1 have been created ###");
        log();
 
    }

16.6.4 Code Sample 3

The following code sample illustrates several ways to query application roles:

private void queryAppRolesInApplicationPolicy1() throws Exception {
        AppRoleManager arm1 = ap1.getAppRoleManager();
 
        // Get role that matches a name
        AppRoleEntry are = arm1.getAppRole(APP_ROLE_SYS_MANAGER);
        log("----------------------------------------------------------");
        log("### Query app roles in application policy #1, by name ###");
        log("Found " + are.getName() + " by app role name.");
        log();
 
        // Get the role that matches a name exactly
        AppRoleSearchQuery q =
            new AppRoleSearchQuery(AppRoleSearchQuery.SEARCH_PROPERTY.NAME,
                                   false, ComparatorType.EQUALITY,
                                   APP_ROLE_SYS_ANALYST,
                                   AppRoleSearchQuery.MATCHER.EXACT);
        List<AppRoleEntry> arel = arm1.getAppRoles(q);
        log("### Query app roles in application policy #1, by exact query ###");
        log("Found " + arel.get(0).getName() + " by exact query.");
        log();
 
        // Get roles with names that begin with a given string
        q =
   new AppRoleSearchQuery(AppRoleSearchQuery.SEARCH_PROPERTY.NAME, false,
                          ComparatorType.EQUALITY,
                          APP_ROLE_SYS_DEVELOPER.subSequence(0, 7),
                          AppRoleSearchQuery.MATCHER.BEGINS_WITH);
        arel = arm1.getAppRoles(q);
        log("### Query app roles in app policy #1, by begins_with query ###");
        log("Found " + arel.get(0).getName() + " by begins_with query.");
        log();
 
        // Get roles with names that contain a given substring
        q =
   new AppRoleSearchQuery(AppRoleSearchQuery.SEARCH_PROPERTY.NAME, false,
                          ComparatorType.EQUALITY, "dummy",
                          AppRoleSearchQuery.MATCHER.ANY);
        arel = arm1.getAppRoles(q);
        log("### Query app roles in app policy #1, by matcher any ###");
        log("Found " + arel.size() + " app roles by matcher any.");
        for (AppRoleEntry ar : arel) {
            log("\t" + ar.getName());
        }
        log();
    }

16.6.5 Code Sample 4

The following sample illustrates how to map application roles to users and groups:

private void assignAppRoleToUsersAndGroups() throws Exception {
        // Obtain the user/group principals
        IdentityStore idmStore = idStore.getIdmStore();
        User tom = idmStore.searchUser(USER_TOM);
        User helen = idmStore.searchUser(USER_HELEN);
 
        Role trainingRole =
            idmStore.searchRole(IdentityStore.SEARCH_BY_NAME, GROUP_TRAINING);
        Role devRole =
            idmStore.searchRole(IdentityStore.SEARCH_BY_NAME, GROUP_DEV);
 
        Principal tomPrincipal =
            PrincipalFactory.getInstance().createWLSUser(tom.getName(),
                                                         tom.getGUID(),
                                                         tom.getUniqueName());
        Principal helenPrincipal =
            PrincipalFactory.getInstance().createWLSUser(helen.getName(),
                                                         helen.getGUID(),
                                                         helen.getUniqueName());
 
        Principal trainingPrincipal =
            PrincipalFactory.getInstance().createWLSGroup(trainingRole.getName(),
                                                          trainingRole.getGUID(),
                                                          trainingRole.getUniqueName());
        Principal devPrincipal =
            PrincipalFactory.getInstance().createWLSGroup(devRole.getName(),
                                                          devRole.getGUID(),
                                                          devRole.getUniqueName());
 
        // Application policy #1
        log("----------------------------------------------------------");
        log("### Assigning appl roles to users and groups, app policy #1 ###");
        ap1.addPrincipalToAppRole(helenPrincipal, APP_ROLE_SYS_MANAGER);
        ap1.addPrincipalToAppRole(devPrincipal, APP_ROLE_SYS_DEVELOPER);
 
        // Application policy #2
        log("### Assigning app roles to users and groups, app policy #2 ###");
        ap2.addPrincipalToAppRole(tomPrincipal, APP_ROLE_DIRECTOR);
        ap2.addPrincipalToAppRole(devPrincipal, APP_ROLE_INSTRUCTOR);
        ap2.addPrincipalToAppRole(trainingPrincipal, APP_ROLE_INSTRUCTOR);
 
        log("### App roles have been assigned to users and groups ###");
        log();
    }

16.6.6 Code Sample 5

The following code sample illustrates how to get all the roles that have a given user as a member:

private void showAppRoles() throws Exception {
        Subject tomSubject = getUserSubject(USER_TOM);
        Subject helenSubject = getUserSubject(USER_HELEN);
        Subject johnSubject = getUserSubject(USER_JOHN);
        Subject marySubject = getUserSubject(USER_MARY);
 
        Set<String> applications = new HashSet<String>();
        applications.add(APPLICATION_NAME1);
        applications.add(APPLICATION_NAME2);
 
        log("----------------------------------------------------------");
        log("### Query application roles for Tom ###");
        showAppRoles(applications, USER_TOM, tomSubject);
        log();
 
        log("### Query application roles for Helen ###");
        showAppRoles(applications, USER_HELEN, helenSubject);
        log();
 
        log("### Query application roles for John ###");
        showAppRoles(applications, USER_JOHN, johnSubject);
        log();
 
        log("### Query application roles for Mary ###");
        showAppRoles(applications, USER_MARY, marySubject);
        log();
    }

private Subject getUserSubject(String userName) throws Exception {
        Subject subject = new Subject();
 
        // Query users from ID store using user/role API,for user principal
        IdentityStore idmStore = idStore.getIdmStore();
        User user = idmStore.searchUser(userName);
 
        Principal userPrincipal =
            PrincipalFactory.getInstance().createWLSUser(user.getName(),
                                                         user.getGUID(),
                                                         user.getUniqueName());
 
        subject.getPrincipals().add(userPrincipal);
 
        // Query users from ID store using user/role API, for enterprise roles
        RoleManager rm = idmStore.getRoleManager();
        SearchResponse result = null;
        try {
            result = rm.getGrantedRoles(user.getPrincipal(), false);
        } catch (ObjectNotFoundException onfe) {
            // ignore
        }
 
        // Add group principals to the subject
        while (result != null && result.hasNext()) {
            Identity role = result.next();
            Principal groupPrincipal =
                PrincipalFactory.getInstance().createWLSGroup(role.getName(),
                                                              role.getGUID(),
                                                        role.getUniqueName());
            subject.getPrincipals().add(groupPrincipal);
        }
 
        // The subject now contains both user and group principals.
        // In the WebLogic Server, this setting is done by a login module
        return subject;
    }

private void showAppRoles(Set<String> applications, String user, Subject subject) {
        // Get all granted application roles for this subject
        Set<JpsApplicationRole> result = null;
        try {
            result = JpsAuth.getAllGrantedAppRoles(subject, applications);
        } catch (PolicyStoreException pse) {
            log(pse.toString());
        }
 
        if (result.size() <= 1) {
            log(user + " has " + result.size() + " application role.");
            if (result.size() == 1) {
                for (JpsApplicationRole ar : result) {
                    log("\tApplication role: " + ar.getName());
                }
            }
        } else {
            System.out.println(user + " has " + result.size() +
                               " application roles.");
            for (JpsApplicationRole ar : result) {
                log("\tApplication role: " + ar.getAppID() + "/" +
                    ar.getName());
            }
        }
    }

16.6.7 Code Sample 6

The following sample code illustrates how to remove the mapping of an application role to a group:

private void removeAppRoleForUserDirector() throws Exception {
        // Remove instructor role from Dev group
        log("----------------------------------------------------------");
        log("### Removing Instructor application role from Dev group ###");
 
        IdentityStore idmStore = idStore.getIdmStore();
        Role devRole =
            idmStore.searchRole(IdentityStore.SEARCH_BY_NAME, GROUP_DEV);
        Principal devPrincipal =
            PrincipalFactory.getInstance().createWLSGroup(devRole.getName(),
                                                          devRole.getGUID(),
                                                          devRole.getUniqueName());
 
        ap2.removePrincipalFromAppRole(devPrincipal, APP_ROLE_INSTRUCTOR);
        log("### Instructor app role has been removed from Dev group ###");
        log();
 
        log("----------------------------------------------------------");
        log("### Now query application roles for user John, again ###");
        Set<String> applications = new HashSet<String>();
        applications.add(APPLICATION_NAME1);
        applications.add(APPLICATION_NAME2);
 
        Subject johnSubject = getUserSubject(USER_JOHN);
        showAppRoles(applications, USER_JOHN, johnSubject);
        log();
    }

16.7 Appendix - Security Lifecycle of an ADF Application

This section explains the phases that the security of an application goes through. It is assumed that the application uses ADF and that it is developed in the Oracle JDeveloper environment.

The phases of the security lifecycle of an application are the development phase, the deployment phase, and the management phase. The participants are the product manager or application architect, application developers, and application security administrators. For a summary of tasks, see Summary of Tasks per Participant per Phase.

16.7.1 Development Phase

In the development phase developers design the application to work with the full range of security options available in Oracle Fusion Middleware. Developers have access to a rich set of security services exposed by Oracle JDeveloper, the built-in ADF framework, and the Oracle WebLogic Server. All these components are based on OPSS, which ensures a consistent approach to security throughout the application's life span.

Typically, a developer uses the ADF Security Wizard (an authorization editor) and an expression language editor, all within Oracle JDeveloper; additionally and optionally, he may use OPSS APIs to implement more complex security tasks. Thus, some parts of the application use declarative security, others use programmatic security, and they both rely on security features available in the development and run-time environment.

Application developers also define a number of application entitlements and roles (policy seed data) required to secure the application. This policy seed data is kept in a source control system together with the application source code.

16.7.2 Deployment Phase

Once developed, the application is typically tested in a staging environment before being deployed to a production environment. In a production environment, both the application and the run-time services are integrated with other security components, such as user directories, single sign-on systems, user provisioning systems, and auditing. The security services usually change with the phase: for example, during development, a developer relies on a file or Oracle Wallet to store user credentials, but, in a production environment, credentials are stored in an LDAP directory (the OPSS security store).

In the deployment phase, typically, an administrator migrates the policy seed data to the production OPSS security store, and maps application roles to enterprise groups according to application policies.

16.7.3 Management Phase

The management phase starts once an application has been deployed to a production environment. In this phase, application administrators or enterprise security administrators manage day-to-day security tasks, such as granting users access to application resources, reviewing audit logs, responding to security incidents, and applying security patches.

16.7.4 Summary of Tasks per Participant per Phase

The following tables summarize the major responsibilities per participant in each of the security lifecycle phases and Figure 16-4 illustrates the basic flow.

Figure 16-4 Application Lifecycle Phases

Surrounding text describes Figure 16-4 .

Table 16-1 Security Tasks for the Application Architect

PhaseTask

Development

Defines high-level application roles based on functional security and data security requirements.

Populates the initial file-based application policy store (jazn-data.xml).

Deployment

Defines real-world customer scenarios to be tested by the QA team.

Management

Understands and identifies the requirements to customize application policies.

Considers defining templates for vertical industries.


Table 16-2 Security Tasks for the Application Developer

PhaseTask

Development

Uses tools and processes, specifically Oracle JDeveloper, to build the application and to create security artifacts, such as application roles and permissions.

Uses FND Grants to specify data-level security.

Tests the application using a local policy store with sample users and roles.

Deployment

Assists the QA team to troubleshoot and resolve runtime issues.


Table 16-3 Security Tasks for the Application Security Administrator

PhaseTask

Deployment

Uses deployment services to migrate security seed data in jazn-data.xml to the production policy store.

Maps application roles to enterprise groups so that security policies can be enforced.

Management

Applies patches and upgrades software, as necessary.

Manages users and roles, as enterprise users and the application role hierarchy changes overtime.

Manages policies packed with the application and creates new ones.

Integrates with and manages the IAM infrastructure.


16.8 Appendix - Code and Configuration Examples

This section lists most of the code and configuration samples found elsewhere in this Guide, and a fully-written code example.

16.8.1 Code Examples

The following list includes typical security-related programming tasks and links to sample code illustrating implementations:

16.8.2 Configuration Examples

The following list includes typical security-related configuration tasks and links to sample configuration:

16.8.3 Full Code Example of a Java EE Application with Integrated Security

ezshare is a full example of a Java EE application whose security has been integrated with OPSS that uses permission-based grants and available at the Oracle Network. To locate the example, search for the keyword ezshare.

16.9 Appendix - Propagating Identities with JKS-Based Key Stores

The out of box configuration is set so that the token issuer name and the key alias are based on the WebLogic server name. To change these default values, use the procedures explained in Section 16.9.1.8, "Updating the Trust Service Configuration Parameters."

Propagating identities over the HTTP protocol using JKS-based key stores is explained in the following sections:

16.9.1 Single Domain Scenario

In this scenario, the client and the servlet applications use the same trust service instance to issue and validate tokens. The following sections illustrate code and configuration samples for a client and servlet applications running in the same domain:

16.9.1.1 Client Application Code Sample

The following sample illustrates a client application; note that the file jps-api.jar and the OSDT jars: osdt_ws_sx.jar, osdt_core.jar, osdt_xmlsec.jar, osdt_saml2.jar must be included the class path for the code sample to compile.

// Authentication type name
public static final String AUTH_TYPE_NAME = "OIT";
// The authenticated username
String user = "weblogic"; 
// URL of the target application
URL url = "http://<host>:<port>/<destinationApp>"; 
//-----------------------------------------
JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext jpsCtx = ctxFactory.getContext();
final TrustService trustService = jpsCtx.getServiceInstance(TrustService.class);
final TokenManager tokenMgr = trustService.getTokenManager();
final TokenContext ctx = tokenMgr.createTokenContext(
    TokenConfiguration.PROTOCOL_EMBEDDED);
UsernameToken ut = WSSTokenUtils.createUsernameToken("wsuid", user);
GenericToken gtok = new GenericToken(ut);
ctx.setSecurityToken(gtok);
ctx.setTokenType(SAML2URI.ns_saml);
Map<String, Object> ctxProperties = ctx.getOtherProperties();
ctxProperties.put(TokenConstants.CONFIRMATION_METHOD,
    SAML2URI.confirmation_method_bearer);
 
AccessController.doPrivileged(new PrivilegedAction<String>() {
    public String run() {
        try {
            tokenMgr.issueToken(ctx);
        } catch (Exception e) {        
            e.printStackTrace();
        }
        return null;
    }
});
 
Token token = ctx.getSecurityToken();
String b64Tok = TokenUtil.encodeToken(token);
 
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setDoOutput(true);
connection.setReadTimeout(10000);
connection.setRequestProperty("Authorization", AUTH_TYPE_NAME + " " + b64Tok);
connection.connect();
BufferedReader rd = new BufferedReader(new InputStreamReader(
    connection.getInputStream()));
StringBuilder sb = new StringBuilder();
 
String line = null;
while ((line = rd.readLine()) != null) {
    sb.append(line);
}
connection.disconnect();
System.out.println(sb.toString());

16.9.1.2 Configuring the Keystore Service

Assuming that the WebLogic server name is jrfServer_admJCin, the following command illustrates the creation of the keystore, represented by the generated file default-keystore.jks.

JAVA_HOME/bin/keytool -genkeypair 
  -alias orakey 
  -keypass welcome 
  -keyalg RSA 
  -dname "CN=jrfServer_admin,O=Oracle,C=US" 
  -keystore default-keystore.jks 
  -storepass password
 
# the generated file must be placed on the domain configuration location
cp default-keystore.jks ${domain.home}/config/fmwconfig

Make sure that the keystore service configured in the file jps-config.xml points to the generated default-keystore.jks; the following sample illustrates a keystore service configuration:

<!-- KeyStore Service Instance -->
<serviceInstance name="keystore" 
    provider="keystore.provider"  location="./default-keystore.jks">
    <description>Default JPS Keystore Service</description>
    <property name="keystore.provider.type" value="file"/>
    <property name="keystore.file.path" value="./"/>
    <property name="keystore.type" value="JKS"/>
    <property name="keystore.csf.map" value="oracle.wsm.security"/>
    <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
    <property name="keystore.sig.csf.key" value="sign-csf-key"/>
    <property name="keystore.enc.csf.key" value="enc-csf-key"/>
</serviceInstance >

16.9.1.3 Configuring CSF

Create a map/key pair used to open the keystore and another map/key pair used to issue tokens. The following commands illustrate these operations using the WLST command createCred:

// JKS keystore opening password
createCred(map="oracle.wsm.security", key="keystore-csf-key", 
           user="keystore", password="password") 
 
// Private key password to issue tokens
createCred(map="oracle.wsm.security", key="sign-csf-key", 
           user="orakey", password="password")

For details about the WLST command createCred, see Section 11.4, "Managing Credentials with WLST commands."

16.9.1.4 Configuring a Grant

Add to the OPSS security store a system policy with a codesource grant like the following, which allows the client application to use the trust service API:

<grant>
  <grantee>
    <codesource>    
      <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
    </codesource>
  </grantee>
  <permissions>
    <permission>          
<class>oracle.security.jps.service.trust.TrustServiceAccessPermission</class>
        <name>appId=*</name>
        <actions>issue</actions>
     </permission>
    </permissions>
</grant>

The Oracle WebLogic Server must be stopped and re-started for the above grant to take effect.

16.9.1.5 Servlet Code Sample

The following sample illustrates how a servlet can obtain an asserted user name:

public void doGet(HttpServletRequest request, HttpServletResponse response)
   throws ServletException, IOException {
   String username = request.getRemoteUser();
   ServletOutputStream out = response.getOutputStream();
   out.print("Asserted username: " + username);
   out.close();
}

16.9.1.6 Configuring web.xml

Set the appropriate login method in the file web.xml, as illustrated in the following snippet:

<web-app id="WebApp_ID"
…
 <login-config>
   <auth-method>CLIENT-CERT</auth-method>
   <realm-name>Identity Assertion</realm-name>
 </login-config>
…
</web-app>

16.9.1.7 Configuring the webLogic Asserter and the Trust Service

To configure the WebLogic asserter, proceed as follows:

  1. Copy the WebLogic identity asserter JAR jps-wls-trustprovider.jar to the location ${domain.home}/lib/mbeantypes, as illustrated by the following command, and then restart the WebLogic Server:

    cp ${common.components.home}/modules/oracle.jps_11.1.1/jps-wls-trustprovider.jar ${domain.home}/lib/mbeantypes
    
  2. Use WebLogic Console to configure the asserter, as follows:

    1. Login to the console as an administrator.

    2. Navigate to Security Settings > Security Realms > myrealm > Providers Tab > Authentication, and click New to open the Create a New Authentication Provider dialog.

    3. In that dialog, enter TrustServiceIdentityAsserter in the name box, and select TrustServiceIdentityAsserter from the pull-down in the type box; then click OK.

  3. Verify that a grant like the following is present in the OPSS security store; this grant is required for the asserter to use the OPSS trust service API; if necessary, use WSLT scripts to specify the following codesource system policy:

    <grant>
        <grantee>
            <codesource>
                <url>file:${domain.home}/lib/mbeantypes/jps-wls-trustprovider.jar</url>
            </codesource>
        </grantee>
        <permissions>
            <permission>
                <class>oracle.security.jps.service.trust.TrustServiceAccessPermission</class>
                <name>appId=*</name>
                <actions>validate</actions>
            </permission>
        </permissions>
    </grant>
    

    Any changes to the file jps-config.xml) requires the server to be re-started before updates take effect.

16.9.1.8 Updating the Trust Service Configuration Parameters

This section explains how to modify the trust service parameters in the file jps-config.xml with a script.

Out-of-the-box the values of the parameters trust.aliasName and trust.issuerName are set to the WebLogic server name. To modify their values to deployment-specific values, use a script like the following:

import sys
 
wlsAdmin = 'weblogic'
wlsPwd ='password_value'
wlUrl='t3://localhost:7001'
issuer= 'issuer'
alias = 'alias'
 
print "OPSS Trust Service provider configuration management script.\n"
 
instance = 'trust.provider'
name = 'trust.provider.embedded'
cfgProps = HashMap()
cfgProps.put("trust.issuerName", issuer)
cfgProps.put("trust.aliasName", alias)
pm = PortableMap(cfgProps);
 
connect(wlsAdmin, wlsPwd, wlUrl)
domainRuntime()
 
params = [instance, name, pm.toCompositeData(None)]
sign = ["java.lang.String", "java.lang.String", "javax.management.openmbean.CompositeData"]
on = ObjectName("com.oracle.jps:type=JpsConfig")
mbs.invoke(on, "updateTrustServiceConfig", params, sign)
mbs.invoke(on, "persist", None, None)
 
print "Done.\n"

16.9.2 Multiple Domain Scenario

In this scenario there are two different domains: Domain1 and Domain2. The client application is running in Domain1; the servlet application is running in Domain2. It is assumed that each of these two domains have each a trust store service and keystore properly configured as explained under the heading WebLogic Asserter and Trust Store Configuration in the Single Domain Scenario. In this scenario, the client application uses Domain1's trust service for token generation, and the servlet application uses Domain2's trust service for token validation.

In Domain1, the client sample code and the following configurations are identical to those described in the Single Domain Scenario:

In Domain 2, the servlet sample code and web.xml configuration are identical to those described in the Single Domain Scenario, but there is some extra setup required:

  • The servlet application code as illustrated in Servlet Code Sample.

  • The configuration of the file web.xml as illustrated in Configuring web.xml.

  • The client certificate that is used to sign the token in Domain1 must be present in Domain2's keystore; therefore, the administrator proceeds as follows:

    1. Exports the certificate from Domain 1's keystore, as illustrated by the following command:

      JAVA_HOME/bin/keytool -export
      -orakey orakey.cer
      -keystore default-keystore.jks
      -storepass password
      
    2. Imports the certificate into Domain 2's keystore as illustrated by the command below; note that the alias used to import the certificate must match the name of the issuer on the client side.

      JAVA_HOME/bin/keytool -importcert 
        -alias orakey 
        -keypass welcome 
        -keyalg RSA 
        -keystore default-keystore.jks 
        -storepass password
      
    3. Sets the Domain2's keystore password in the (Domain2's) credential store using the WLST command createCred as follows:

      createCred(map="oracle.wsm.security", key="keystore-csf-key", user="keystore", password="password")
      

    For details about this command, see Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

16.9.3 Domains Using Both Protocols

In this scenario, applications use either the HTTP protocol or the SOAP protocol, and not all applications in the domain use the same protocol. In such scenario, the keystore can be shared by the trust service used by the HTTP protocol and the SOAP service used by Oracle Web Services Manager. But in order for the trust service to work in this case, some special configurations in the file jps-config.xml are required as explained in the following sections:

16.9.3.1 Single Domain Scenario

In this scenario, there is one keystore. The following snippet illustrates the configuration required for a certificate with alias orakey:

<propertySet name="trust.provider.embedded">
    <property name="trust.provider.className"
     value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
    <property name="trust.clockSkew" value="60"/>
    <property name="trust.token.validityPeriod" value="1800"/>
    <property name="trust.token.includeCertificate" value="false"/>
    
    <!-- The alias used to get the signing certificate from JKS -->
    <property name="trust.aliasName" value="orakey"/> 
 
    <!-- The issuer name to be added in the token used by the destination
    trust service instance as an alias to pick up the corresponding certificate 
    to validate the token signature -->
    <property name="trust.issuerName" value="orakey"/>
</propertySet>

16.9.3.2 Multiple Domain Scenario

In this scenario, there are two domains and two keystores. The following snippet illustrates the configuration required in the domain that is issuing tokens for a certificate with alias orakey:

<!-- issuer domain trust store must have a signing certif. w. alias orakey -->
<propertySet name="trust.provider.embedded">
    <property name="trust.provider.className"
        value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
    <property name="trust.clockSkew" value="60"/>
    <property name="trust.token.validityPeriod" value="1800"/>
    <property name="trust.token.includeCertificate" value="false"/>
 
    <!-- the signing certificate alias in local JKS -->
    <property name="trust.aliasName" value="orakey"/> 
    
    <!-- the token issuer's name -->
    <property name="trust.issuerName" value="domain1"/> 
</propertySet>

Note 1:

On the client side, the value of trust.issuerName can be same as trust.aliasName. However the issuer name value can be overridden by setting a different value for trust.issuerName (as shown in the sample above). This issuer name will be set in the token generated on the client side.
Note 2

On the server side, if the server is used only for token validation, it is not mandatory to set trust.aliasName and trust.issuerName. The issuer name set during the token generation is used while looking for a certificate on the server side. Hence the certificate imported from the client should be exported on the server side with the client side issuer name as the alias ('domain1' in the example above).


The following snippet illustrates the configuration required in the domain that is receiving tokens for a certificate with alias orakey:

<!- important: recipient domain must have a token validation certificate for domain1, 
which is the one was used to sign the token with alias "domain1" -->
<propertySet name="trust.provider.embedded">
    <property name="trust.provider.className"
        value="oracle.security.jps.internal.trust.provider.embedded.EmbeddedProviderImpl"/>
    <property name="trust.clockSkew" value="60"/>
    <property name="trust.token.validityPeriod" value="1800"/>
    <property name="trust.token.includeCertificate" value="false"/>
    
    <!-- the signing certificate alias in local JKS -->
    <property name="trust.aliasName" value="orakey"/> 
 
    <!-- the token issuer's name -->
    <property name="trust.issuerName" value="domain2"/> 
</propertySet>
PKAOO^JPK].FOEBPS/audpolicy.htm Configuring and Managing Auditing

14 Configuring and Managing Auditing

This chapter explains how to perform day-to-day audit administration tasks.


See Also:

Chapter 13, "Introduction to Oracle Fusion Middleware Audit Service" for background information about auditing in Oracle Fusion Middleware.

14.1 Audit Administration Tasks

As audit administrator, you should plan the site's audit setup carefully by following the steps in these areas:

  • Implementation Planning

    This includes planning the type of store to use for audit records, data store configuration details, and so on.

    See Section 14.2, "Managing the Audit Data Store" for details.

  • Policy Administration

    You must configure the appropriate audit policies to ensure that the required audit events are generated.

    This is an ongoing activity since the audit policies must be able to reflect changes to the application environment, addition of components and users, and so on.

    See Section 14.3, "Managing Audit Policies" for details.

  • Reports Management

    This includes planning for and configuring audit reports and queries.

    See Chapter 15, "Using Audit Analysis and Reporting" for details.

  • Data Administration

    This includes planning/increasing the database size required to store the audit data generated, backing up the audit data and, purging the audit data based on company policy.

    See Section 14.6, "Advanced Management of Database Store" for details about audit data store administration.

14.2 Managing the Audit Data Store

Out of the box, the audit framework uses the file system to store audit records. However, in a production environment, Oracle recommends that you use a database audit data store to provide scalability and high-availability for the audit framework.

In addition, an audit data store residing in a database allows the audit data to be viewed through Oracle Business Intelligence Publisher with pre-packaged audit reports that are available with that product. Oracle Business Intelligence Publisher is available in the 12c (12.1.2) CD pack.

This section explains these audit data store management tasks in detail:

14.2.1 Create the Audit Schema using RCU

To switch to a database as the permanent store for your audit records, you first use the Repository Creation Utility (RCU) to create a database store for audit data. Out-of-the-box, Release 12.1.2 offers two profiles: compact and expanded (default).

This section explains how to create the audit schema.


Note:

The bus-stop files store audit records in the absence of database storage.


Note:

This discussion assumes that RCU and the database is already installed in your environment. See the Installation Guide for more information.

Once the database schema is created, you can:


Notes:

These actions are not required if you have specified audit artifact details as shown in Chapter 7.

Before You Begin

Before you begin, make sure to collect the details on which database to use, along with the DBA credentials to use.

Configuring the Database Schema

The procedure shown here configures a schema for the audit data store.

The steps are as follows:

  1. Go to $RCU_HOME/bin and execute the RCU utility.

  2. Choose Create at the starting screen. Click Next.

  3. The Database Connection Details page appears. Enter your database details:

    Surrounding text describes audrcu1.gif.

    Click Next. RCU verifies prerequisites; click OK to proceed.

  4. The Select Components page appears. Choose the option to create a new prefix, for example DEV4. The prefix is applied to schema owner and tablespace names. Three schema users are created using this prefix; in the example, they are DEV4_IAU, DEV4_IAU_APPEND, and DEV4_IAU_VIEWER.

    Also, select 'Audit Services' from the list of schemas; the next two schemas are automatically selected. (Note: Do not select these two schemas by themselves as they are only auxiliary schemas.)

    Surrounding text describes audrcu2.gif.

    Click Next. RCU verifies component prerequisites; click OK to proceed.

  5. The Schema Passwords page appears.

    Surrounding text describes audrcu3.gif.

    Enter the password and click Next.

  6. The Map Tablespaces page appears. Click Next and accept the tablespace creation.

    Surrounding text describes audrcu4.gif.

    Click OK to dismiss the tablespace creation confirmation box.

  7. The Summary page appears.

    Surrounding text describes audrcu5.gif.

    Check the details and click Create.

  8. Check for any errors while the schemas are being created. Verify that the job is successful on the Completion Summary page:

    Surrounding text describes audrcu6.gif.

This process will take several minutes to complete.


Note:

Oracle Fusion Middleware 12c (12.1.2) does not support creating an IAU schema in Oracle Database enabled for Edition Based Redefinition (EBR).

14.2.2 Set Up Audit Data Sources

As explained in Section 14.2.1, "Create the Audit Schema using RCU", after you create a database schema to store audit records in a database, you must set up an Oracle WebLogic Server audit data source that points to that schema.

Take these steps to set up an audit data source:


Note:

This task is performed with the Oracle WebLogic Server administration console.

  1. Connect to the Oracle WebLogic Server administration console:

    http://host:7001/console
    
  2. Under JDBC, click the Data Sources link.

  3. The Data Sources page appears. Click New to create a new data source.

  4. Enter the following details for the new data source:

    • Name: Enter a name such as Audit_Data_Source-0.

    • JNDI Name: jdbc/AuditDB

    • Database Type: Oracle

    • Database Driver: Oracle's Driver (Thin XA) Versions: 9.0.1, 9.0.2, 10, 11

    If deploying to a managed cluster server, also check AdminServer; this ensures that the data source is listed in the audit data store when switching from file to database store.

    Click Next.

  5. The Transaction Options page appears. Click Next.

  6. The Connection Properties page appears. Enter the following information:

    • Database Name: Enter the name of the database to which you will connect. This usually maps to the SID.

    • Host Name: Enter the hostname of the database.

    • Port: Enter the database port.

    • Database User Name: This is the name of the audit schema that you created in RCU. The following conventions apply to this entry:

      • Use all upper-case letters.

      • Prepend the schema prefix used when creating the audit schema in the database.

      • Append the schema name. For this data source, the schema name is IAU_APPEND.

      For example, if you used "ENG" as your schema prefix, the value you enter here must be "ENG_IAU_APPEND".

    • Password: This is the password for the audit schema that you created in RCU.

    Click Next.

  7. The next page lists the JDBC driver class and database details. Accept the defaults, and click Test Configuration to test the connection. If you see the message "Connection established Successfully", click Next. If it displays any error, go back and check the connection details.

  8. In the Select Targets page, select the servers where this data source needs to be configured, and click Finish.

14.2.2.1 Multiple Data Sources

For scalability and high availability, you can configure Oracle Real Application Clusters for your audit data.

For details, see "Real Application Clusters" in Oracle Fusion Middleware High Availability Guide.

14.2.3 Configure a Database Audit Data Store for Java Components

After the schema is created, configuring a database-based audit data store involves:

  • creating a data source that points to the audit schema you created, and

  • configuring the audit data store to point to the data source

This section describes the following tasks related to audit data store configuration:


Note:

These steps configure the audit data store for Java components only. Separate steps are needed to configure the audit data store for system components. See Section 14.2.4, "Configure a Database Audit Data Store for System Components".

By configuring the same database to store audit records for Java components and system components, you can ensure that reports for both types of components can be viewed together.


14.2.3.1 View Audit Data Store Configuration


Note:

This task is performed with Oracle Enterprise Manager Fusion Middleware Control.

To view the current audit data store configuration:

  1. Navigate to Domain, then Security, then Security Provider Configuration.

  2. Under the Audit Service section, click Configure.

Surrounding text describes audrepos1.gif.

This page shows:

  • Datasource JNDI Name - If a database store is configured for audit records, this field shows the JNDI name of the datasource. The field is empty when the audit data store is not configured. By default a database is not configured, and audit records are stored in bus-stop files.

  • Audit Loader Frequency - This field shows the frequency, in seconds, at which data is moved from bus-stop files to the audit data store.

See Section 14.2.2, "Set Up Audit Data Sources" for datasource examples.

14.2.3.2 Configure the Audit Data Store and Bus-Stop Storage

In 12c domains, the audit store can be provisioned through the product template when an Oracle Fusion Middleware domain is created or extended. This process is explained in Chapter 7.

You can also perform certain tasks related to audit store configuration manually:

  • Change from storing audit records in a file to using a database audit data store.

  • Configure bus-stop storage properties for a component's audit records.

Take these steps to configure these features (the user needs to be IAU_APPEND):

  1. Navigate to Domain, then Security, then Security Provider Configuration .

  2. Click the Audit Service Configuration button. The Audit Service Configuration page appears.

    Surrounding text describes aud_svc_cfg.gif.
  3. To configure the audit data store:

    • Click the searchlight icon next to the Datasource JNDI Name field.

    • A dialog box appears showing the list of datasources available for audit records in the domain. Select the desired datasource and click OK.

    • The selected datasource is displayed in the Datasource JNDI Name field. Click Apply to continue, or Revert to abandon the update.


      Note:

      You can also use the WLST setAuditRepository() command to change the audit data store settings. See Oracle Fusion Middleware Infrastructure Security WLST Command Reference for details.

    • Enter the audit loader frequency in seconds. The audit loader checks for and pushes records to the repository at the specified intervals.

    • Click Apply.

  4. To configure bus-stop file parameters for components:

    • Select the component from the Audit Component Name drop-down.

    • Enter the maximum file size.

    • The maximum directory size is not used; setting this parameter has no effect on configuration.

    • Click Apply.

  5. Restart all the Oracle WebLogic Servers in the domain. This enables Audit Loader Startup Class present in Oracle WebLogic Server to re-read the configuration.

  6. You can test the changes by setting an audit policy to test event collection. For example, you can set the Medium audit policy for Oracle Platform Security Services. For details, see Section 14.3.1, "Manage Audit Policies for Java Components with Fusion Middleware Control".

  7. Execute a scenario so that auditing can generate an audit event. For example, creating a credential will trigger an audit record based on the policy you configured in Step 6.

  8. Check for errors and exceptions in the server logs:

    • Check $DOMAIN_HOME/jrfServer_admin.out

    • Check $DOMAIN_HOME/servers/$SERVER_NAME/logs/.

14.2.3.3 Deconfigure the Audit Data Store

Since a database is the recommended store for audit records, switching from database to file mode is discouraged. However, Section 14.3.4, "Manage Audit Policies Manually" discusses a property called the audit.repositoryType whose value can be set to 'File' to switch to file storage.


Note:

You cannot use Fusion Middleware Control or WLST to switch from database to file mode; this requires manual configuration as explained in Section 14.3.4, "Manage Audit Policies Manually".

When you switch from database to file, events that were collected in the database are not transferred back to the file system. If this switch is temporary, then the audit events collected in the file are automatically pushed to database when you switch to database store again.

14.2.4 Configure a Database Audit Data Store for System Components

The StandAloneAuditLoader java command is the mechanism through which audit events are pushed from local bus-stop files to the database audit data store. This section explains how to configure your environment so audit records are sent to the audit data store.


Note:

If your system component runs in a clustered deployment, you must configure the audit data store at each instance of the component so that all instances push out records to the store.

You must execute the following steps in every instance of the component to configure an audit data store:


Note:

These steps configure the audit data store for system components only. Separate steps are needed to configure the audit data store for Java components. See Section 14.2.3, "Configure a Database Audit Data Store for Java Components".

You can ensure that reports for both types of components can be viewed together by configuring the same database to store audit records for Java components and system components.


  1. Open the opmn.xml file, which resides in

    (UNIX) $ORACLE_INSTANCE/config/OPMN/opmn/opmn.xml 
    (Windows) %ORACLE_INSTANCE%/config/OPMN/opmn/opmn.xml 
    
  2. Locate the rmd-definitions element, which looks like this :

    (UNIX)
    <rmd-definitions>
             <rmd name="AuditLoader" interval="15">
                <conditional>
                <![CDATA[({time}>=00:00)]]>
                </conditional>
                <action value="exec $ORACLE_HOME/jdk/bin/java -classpath 
     $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar: 
     $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar: 
     $ORACLE_HOME/oracle_common/modules/oracle.jdbc_11.2.0/ojdbc6dms.jar: 
     $COMMON_COMPONENTS_HOME/modules/oracle.iau_11.1.1/fmw_audit.jar: 
     $COMMON_COMPONENTS_HOME/modules/oracle.pki_11.1.1/oraclepki.jar:
                     -Doracle.home=$ORACLE_HOME 
                     -Doracle.instance=$ORACLE_INSTANCE           
                     -Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid           
                     -Dauditloader.username=username 
                     oracle.security.audit.ajl.loader.StandaloneAuditLoader"/>
                <exception value="exec /bin/echo 
    PERIODICAL CALL For Audit Loader FAILED"/> </rmd> </rmd-definitions> (Windows) <rmd-definitions> <rmd name="AuditLoader" interval="15"> <conditional> <![CDATA[({time}>=00:00)]]> </conditional> <action value="exec %ORACLE_HOME%\jdk\bin\java -classpath %COMMON_COMPONENTS_HOME%\modules\oracle.osdt_11.1.1\osdt_cert.jar; %COMMON_COMPONENTS_HOME%\modules\oracle.osdt_11.1.1\osdt_core.jar; %ORACLE_HOME\oracle_common\modules/oracle.jdbc_11.2.0\ojdbc6dms.jar; %COMMON_COMPONENTS_HOME%\modules\oracle.iau_11.1.1\fmw_audit.jar; %COMMON_COMPONENTS_HOME%\modules\oracle.pki_11.1.1\oraclepki.jar; -Doracle.home=%ORACLE_HOME% -Doracle.instance=%ORACLE_INSTANCE% -Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid -Dauditloader.username=username oracle.security.audit.ajl.loader.StandaloneAuditLoader"/> <exception value="exec \bin\echo PERIODICAL CALL For Audit Loader FAILED"/> </rmd> </rmd-definitions>
  3. Replace the existing RMD definition for audit loader. You need to modify only these values:

    • jdbcString - this is the database JDBC connection string; change this from the default string to a valid connection string.

    • username

    • interval - this is the interval in seconds at which audit records are pushed from the component's bus-stop file to the audit data store.

      By default the interval value is set very high (31536000 seconds) so that the audit loader is effectively disabled. Change this to a reasonable interval such as 15 seconds.


      Note:

      Insert these lines after the <ias-instance> tag is closed.

  4. Ensure that ORACLE_HOME, ORACLE_INSTANCE , and COMMON_COMPONENTS_HOME are defined. For example:

    (UNIX) ORACLE_HOME = /u01/oracle/as11_oh
    ORACLE_INSTANCE = /u01/oracle/instances/instance 
    COMMON_COMPONENTS_HOME = $MW_HOME/oracle_common
     
    (Windows) ORACLE_HOME = \u01\oracle\as11_oh
    ORACLE_INSTANCE = \u01\oracle\instances\instance 
    COMMON_COMPONENTS_HOME = %MW_HOME%\oracle_common
    
  5. Populate the audit data store password in the secret store (the password that you have specified when creating the audit schema in RCU):

    (UNIX) ORACLE_HOME/jdk/bin/java -classpath 
             $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar:
             $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar:
             $ORACLE_HOME/oracle_common/modules/oracle.jdbc_11.2.0/ojdbc6dms.jar:
             $COMMON_COMPONENTS_HOME/modules/oracle.iau_11.1.1/fmw_audit.jar:
             $COMMON_COMPONENTS_HOME/modules/oracle.pki_11.1.1/oraclepki.jar:
             -Doracle.home=$ORACLE_HOME -Doracle.instance=$ORACLE_INSTANCE 
             -Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid 
             -Dauditloader.username=username 
             -Dstore.password=true 
             -Dauditloader.password=password 
             oracle.security.audit.ajl.loader.StandaloneAuditLoader
    
    (Windows) ORACLE_HOME\jdk\bin\java -classpath 
                %COMMON_COMPONENTS_HOME%\modules\oracle.osdt_11.1.1\osdt_cert.jar;
                %COMMON_COMPONENTS_HOME%\modules\oracle.osdt_11.1.1\osdt_core.jar;
               %ORACLE_HOME%\
    oracle_common\modules\oracle.jdbc11.2.0\ojdbc6dms.jar; %COMMON_COMPONENTS_HOME%\modules\oracle.iau_11.1.1\fmw_audit.jar; %COMMON_COMPONENTS_HOME%\modules\oracle.pki_11.1.1\oraclepki.jar; -Doracle.home=%ORACLE_HOME% -Doracle.instance=%ORACLE_INSTANCE% -Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid -Dauditloader.username=username -Dstore.password=true -Dauditloader.password=password oracle.security.audit.ajl.loader.StandaloneAuditLoader

    Enter the appropriate values for jdbcString, username, and password.

  6. Save and exit the file.

  7. Reload OPMN:

     $ORACLE_INSTANCE/bin/opmnctl validate (Validation step to verify edits)
          $ORACLE_INSTANCE/bin/opmnctl reload
    
  8. Execute a scenario in an audited component to generate an audit event. For example, log in to an Oracle HTTP Server instance; assuming that Oracle HTTP Server is configured to audit "User Logins" under the User Sessions category, then logging in will generate an audit event.

  9. Check for errors/events uploaded at $ORACLE_INSTANCE/diagnostics/logs/OPMN/opmn/rmd.out. The output will look like this

    8/08/26 10:54:24 global:AuditLoader
    

14.2.4.1 Deconfigure the Audit Data Store

A database is the recommended store for audit records. Switching from database to file mode is discouraged. However, if needed, you can use the same steps that were shown in the preceding task for configuring the audit data store through the opmn.xml file to update the RMD definition to deconfigure the audit data store. Locate the rmd-definitions element and replace the existing RMD definition for audit loader:



Note:

If your system component runs in a clustered deployment, you must deconfigure the audit data store at each instance of the component.

  • jdbcString - Change the database JDBC connection string back to the default string jdbc:oracle:thin:@host:port:sid.

  • interval - Set this interval back to the default value of 31536000.

Save and exit the file, and reload OPMN.

14.2.5 Tune the Bus-stop Files

This section contains topics related to maintaining file-based storage of audit records, including:

  • bus-stop file locations

  • file size


Note:

Manually purging audit files to free up space is not recommended. Instead, use file and directory sizing features to control space, as described below.

Location of Bus-stop Files

Bus-stop files for Java components are located in:

$DOMAIN_HOME/servers/$SERVER_NAME/logs/auditlogs/Component_Type 

Bus-stop files for system components are located in:

$ORACLE_INSTANCE/auditlogs/Component_Type/Component_Name

File Size

Java Components

The size of a file for the file storage mode can be managed using the max.fileSize property described in the configuration file jps-config.xml. This property controls the maximum size of a bus-stop file for Java components.

Specify the sizes in bytes as described in Section 14.3.4, "Manage Audit Policies Manually".

System Components

The size of a file for the file storage mode can be set in the auditconfig.xml file. SeeSection 14.3.4.4, "Audit Configuration File for System Components".


Note:

If you switch from file to database store for audit data, all the events collected in the audit files are pushed into the database tables and the audit files are deleted.

14.2.6 Configure the Stand-alone Audit Loader

As shown in Figure 13-1, Common Audit Framework's audit loader moves records from bus-stop files to the audit data store. The mechanism driving the audit loader depends on the application environment:

  • Java EE components and applications deployed on Oracle WebLogic Server use the audit loader functionality provided through the application server.

  • System components and non-Java applications use the audit loader functionality provided through the StandAloneAuditLoader java command.

  • Java SE applications, which run outside an application server container, also use the stand-alone audit loader.

This section explains how to set up and execute the stand-alone audit loader:

14.2.6.1 Configuring the Environment

Before you can run the stand-alone audit loader, you must a) configure certain properties, and b) ensure that the password for the database schema user exists in the secret store.

14.2.6.1.1 Property Configuration

You must configure the following properties:

  • ORACLE_HOME environment variable

  • COMMON_COMPONENTS_HOME environment variable

  • ORACLE_INSTANCE environment variable

  • auditloader.jdbcString system property

  • auditloader.username system property

14.2.6.1.2 Password Storage for the Database Schema User

The password for the database schema user is kept in the secret store. Storing the password is a one-time operation for which you use the java StandAloneAuditLoader command with the -Dstore.password=true property.

Issue the StandAloneAuditLoader command to store the password as follows:

$COMMON_COMPONENTS_HOME/jdk/jre/bin/java 
-classpath $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.iau_11.1.1/fmw_audit.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.pki_11.1.1/oraclepki.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.jdbc_11.2.0/ojdbc6dms.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.dms_11.1.1/dms.jar 
-Doracle.home=$ORACLE_HOME 
-Doracle.instance=$ORACLE_INSTANCE 
-Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid 
-Dauditloader.username=db-user-name 
-Dstore.password=true  
oracle.security.audit.ajl.loader.StandaloneAuditLoader 

There are two variations of the StandAloneAuditLoader command to store the password, depending on whether the password is included on the command line.

  • If you do not include the password property (-Dauditloader.password) when issuing the command, you are prompted for the password.

  • You can include the password property when issuing the command.


Note:

There should not be any spaces in the classpath specification.

This command generates a cwallet.sso file.

14.2.6.2 Running the Stand-Alone Audit Loader

Issue the StandAloneAuditLoader command to load audit records as follows:

$COMMON_COMPONENTS_HOME/jdk/jre/bin/java 
-classpath $COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.iau_11.1.1/fmw_audit.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.pki_11.1.1/oraclepki.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.jdbc_11.2.0/ojdbc6dms.jar:
$COMMON_COMPONENTS_HOME/modules/oracle.dms_11.1.1/dms.jar:
-Doracle.home=$ORACLE_HOME 
-Doracle.instance=$ORACLE_INSTANCE -Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid -Dauditloader.username=db-user-name oracle.security.audit.ajl.loader.StandaloneAuditLoader 

You can schedule this command through a batch or kron job so that audit records are periodically uploaded to the audit data store.

14.3 Managing Audit Policies

What is an Audit Policy?

An audit policy is a declaration of the type of events to be captured by the audit framework for a particular component. For Java components, the audit policy is defined at the domain level. For system components, the audit policy is managed at the component instance level.

For example, an audit policy could specify that all authentication failures should be audited for an Oracle Internet Directory instance.

How Policies are Configured

Oracle Fusion Middleware Audit Framework lets you configure audit policies and provides highly granular controls over the types of events and data being audited. You can configure policies through the Oracle Enterprise Manager Fusion Middleware Control UI tool or with WLST commands.

Policy changes do not require server or instance restart.

The remainder of this section explains how to view, and update audit policy:


See Also:


14.3.1 Manage Audit Policies for Java Components with Fusion Middleware Control

The domain Audit Policy Settings page manages audit events for all Java components such as Oracle Access Manager, and system libraries like Oracle Platform Security Services.


Notes:



See Also :

Section C.1.1, "What Components Can be Audited?" for the list of auditable components.

Use these steps to view and update the currently configured audit policies:

  1. Log in to Fusion Middleware Control.

  2. Using the topology panel to the left, navigate to the domain of interest under "WebLogic Domain".

  3. From the domain menu, navigate to Domain, then Security, then Audit Policy. The Audit Policy page appears.

  4. Use the Audit Component Name drop-down to select the Java component whose audit policy you wish to configure.

    Surrounding text describes audpolcomp.gif.

    When you select a component, a table of audit categories relevant to the component appears in the area of the page titled Audit Policy Settings. The following example is for Oracle Access Manager:

    Surrounding text describes audpol1a.gif.
  5. Use the Audit Level drop-down to select a subset of the audit events for the component. The choices are:

    Surrounding text describes audpol1.gif.
    • None - No event categories selected.

    • Low, Medium, High - Subsets of event categories representing pre-defined levels of auditing.

    • Custom - Enables you to create or modify a custom filter definition.

    Depending on the level you select, check flags appear in the column Select for Audit. Events in the checked categories will be audited. For example, at the Medium level for Oracle Access Manager:

    Surrounding text describes audpol1b.gif.

    The flagged categories are selected for audit. You can view the events within a flagged category by clicking on that row in the categories table. For example, clicking on the "OAM Server" category produces the following event table below it:

    Surrounding text describes audpol1c.gif.

    Note:

    The table of events can only be edited in custom level. It cannot be edited at the pre-defined levels.

  6. While the pre-defined levels are sufficient in many cases, you may wish to fine-tune the audit policy for the component.

    To customize the audit policy, use the "Custom" option from the drop-down. This preserves the pre-defined categories but the green check-marks now appear as check-boxes, and all categories are available for selection:

    Surrounding text describes audpol1d.gif.

    You can select desired categories and events to fine-tune the audit policy. For example, you might wish to audit only failed authentication attempts in the Server category:

    Surrounding text describes audpol1e.gif.
  7. Filters are rule-based expressions that you can define to qualify or filter events for audit. The expressions are based on attributes of the event. For example, you may wish to further fine-tune the policy to narrow down the types of failed authentication attempts to audit.

    A pencil icon in the Edit Filter column denotes that a filter is available for the event. Click on the icon to bring up the Edit Filter dialog:

    Surrounding text describes audpol3.gif.

    Specify the filter using the condition boxes, which consist of the filter condition, an operator, and a value. After specifying each condition, click the add button. When finished adding conditions, click OK to save the changes.

    In this example, a failed authentication attempt triggers an audit event only if the server hosting the protected application is named myhost1:

    Surrounding text describes audpol3a.gif.

    Note:

    Each filter attribute has a formal name and a display name. You may see either name in the filter edit dialog. Display names are shown in the drop-down, while names are shown in the edit dialog. For example, if you select 'Client Address IP' in the drop-down box, it is renamed to 'RemoteIP' after you add it to the filter expression.

  8. Import/Export - These buttons enable you to save and re-use a policy configuration. At any time while editing the policy, click Export to save the current settings to a file, and Import to load the settings from a saved file.

  9. Optionally, under ”Users to Always Audit”, you can specify a comma-separated list of users to force the audit framework to audit events initiated by these users; auditing occurs regardless of the audit level or filters that have been specified.

    Surrounding text describes audpol4.gif.

    Notes:

    • Be aware that if you use this feature to audit key users such as system administrators, this will generate audit traffic anytime that user touches any of the auditable events for any component. For example, a component's audit policy may be set to None, but if the user performs some activity in the component instance, it is still audited.

    • User names you enter in this field are not validated.


  10. If you made any policy changes, click Apply to save the changes. For Java components, you must restart the managed Oracle WebLogic Server (on which the affected Java component is running) for the changes to be effective. Changes are effective after a pre-defined refresh interval, which is 10 minutes by default.

    Click Revert to discard any policy changes and revert to the existing policy.

About Component Events

Each component and application in the domain defines its own set of auditable events. Thus, when you expand the Names column of the table, each component displays a list of events that applies to instances of that component.

14.3.2 Manage Audit Policies for System Components with Fusion Middleware Control

This section describes how to view and update audit policies for system components.


Notes:


Audit policy for system components is managed in their home pages. The domain Audit Policy Settings page manages audit events for Java components running in the domain.


See Also :

Section C.1.1, "What Components Can be Audited?" for the list of auditable components.

The events are organized in a tree structure under the Name column. The tree can be expanded to reveal the details of the events available.

Use these steps to view and update audit policies for system components:

  1. Log in to Fusion Middleware Control.

  2. Using the topology panel to the left, navigate to the system component of interest such as Oracle HTTP Server.

  3. From the component menu, navigate to Security, then Audit Policy. The Audit Policy Settings page appears.

  4. You can select from a drop-down list of pre-configured audit levels. Three pre-defined levels (Low, Medium, High) will automatically pick up a subset of the audit events for the component.

    Surrounding text describes audpol6.gif.

    Note:

    The selection of events under the drop-down box cannot be edited for the pre-defined levels. It can only be edited in custom level.

    • None - No events are selected for audit.

    • Low - A small set of events is selected, typically those having the smallest impact on component performance.

    • Medium or High- This is a larger set of events. These events may have a higher impact on component performance.

    • Custom - This level enables you to fine-tune the policy, and is described in Step 5 below.

    The table shows the events you can audit for the component instance. This example is for Oracle HTTP Server:

    Surrounding text describes audpol7.gif.

    The table consists of these columns:

    • Name - shows the component events grouped by type, such as Authorization events.

    • Enable Audit - shows whether the corresponding event type is being audited. This column is greyed out unless the Custom audit policy is in force.

    • Filter - shows any filters in effect for the event type.

  5. To customize the audit policy, use the "Custom" option from the drop-down. This allows you to select event categories; to get started, check the "Select For Audit" box for the category you wish to customize.

    A second table lists the events in each category, enabling you to additionally filter for success and failure outcomes of each individual event to further control how they are audited. You can fine-tune filters as explained in Step 6.

  6. Filters are rule-based expressions that you can define to qualify or filter events for audit. The expressions are based on attributes of the event. For example, a Login type event could specify an initiator as a user filter in which case the event would generate an audit record whenever the specified user logged in.

    A pencil icon indicates that a filter is available for the corresponding event.

    Surrounding text describes audpol8.gif.

    Click on a pencil icon to bring up the Edit Filter dialog.

    Surrounding text describes audpol9.gif.

    Note:

    Each filter attribute has a formal name and a display name. You may see either name in the filter edit dialog. Display names are shown in the drop-down, while names are shown in the edit dialog. For example, if you select 'Client Address IP' in the drop-down box, it is renamed to 'RemoteIP' after you add it to the filter expression.

  7. Click "Select Failures Only" to select only failed events in the policy - for example, a failed authentication. The Enable Audit box is now checked for failed events.

  8. Import/Export - These buttons enable you to save and re-use a policy configuration. At any time while editing the policy, click Export to save the current settings to a file, and Import to load the settings from a saved file.

  9. Optionally, under ”Users to Always Audit”, a comma-separated list of users can be specified to force the audit framework to audit events initiated by these users; auditing occurs regardless of the audit level or filters that have been specified.

    Surrounding text describes audpol4.gif.

    Notes:

    • Be aware that if you use this feature to audit key users such as system administrators, this will generate audit traffic anytime that user touches any of the auditable events for any component. For example, a component's audit policy may be set to None, but if the user performs some activity in the component instance, it is still audited.

    • No validation is performed for user names you enter in this field.


  10. If you made any policy changes, click Apply to save the changes.

    Click Revert to discard any policy changes and revert to the existing policy.

14.3.3 Manage Audit Policies with WLST

This section explains how to view and update audit policies using the Oracle WebLogic Scripting Tool (WLST) command-line tool:


Note:

When running audit WLST commands, you must invoke the WLST script from the Oracle Common home. See "Using Custom WLST Commands" in Administering Oracle Fusion Middleware for more information.

14.3.3.1 View Audit Policies with WLST

Take these steps to view audit policies with WLST:


Note:

This discussion assumes that you are invoking WLST interactively. For details about WLST and the different options for invoking the tool, see "Getting Started Using the Oracle WebLogic Scripting Tool (WLST)" in Administering Oracle Fusion Middleware.

  • Connect to the WebLogic Server using the following commands:

    >java weblogic.WLST
    >connect('userName', 'userPassword', 'url', 'adminServerName')
    
  • Use the getAuditPolicy command to view the audit policy configuration. For example, the following command shows all audit policies:

    wls:/mydomain/serverConfig> getAuditPolicy()
    

    The following command shows audit policy for a specific component:

    wls:/mydomain/serverConfig> getAuditPolicy(componentType="JPS")
    
  • For system components:

    • obtain the MBean name using the getNonJava EEAuditMBeanName command. See Appendix C, "Oracle Fusion Middleware Audit Framework Reference." for details.

    • Use the getAuditPolicy command and include the MBean name to view the audit policy configuration. For example:

      wls:/mydomain/serverConfig> getAuditPolicy
       (on="oracle.security.audit.test:type=CSAuditMBean,name=CSAuditProxyMBean")
      

14.3.3.2 Update Audit Policies with WLST

Take these steps to update audit policies with the Oracle WebLogic Scripting Tool (WLST) command-line tool:


Note:

This discussion assumes that you are invoking WLST interactively. For details about WLST and the different options for invoking the tool, see "Getting Started Using the Oracle WebLogic Scripting Tool (WLST)" in the Administering Oracle Fusion Middleware.

  • Connect to the WebLogic Server using the following commands:

    >java weblogic.WLST
    >connect('userName', 'userPassword', 'url', 'adminServerName')
    
  • Navigate the bean hierarchy to access the domain of interest. For example, if the domain is called mydomain:

    wls:/mydomain/serverConfig>
    
  • Use the setAuditPolicy command to update the audit policy configuration.

  • For components that manage their policy locally, use the setAuditPolicy command and include an MBean name to update the audit policy configuration.

  • Explicitly call save after issuing a setAuditPolicy, or importAuditConfig, command.

    If you do not invoke save, the new settings will not take effect.

    For an example of this call, see Managing Auditing by Using WLST in the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory, which demonstrates this call for Oracle Internet Directory auditing.

14.3.3.3 Example 1: Configuring an Audit Policy for Users with WLST

In this scenario, the domain's current policy audits a user named user1. The administrator would like to add two names, user2 and user3, to the list of users who are always audited, and remove user1 from the list.

The following invocation of setAuditPolicy performs this task:

setAuditPolicy
   (filterPreset="None",addSpecialUsers="user2,user3",removeSpecialUsers="user1")

14.3.3.4 Example 2: Configuring an Audit Policy for Events with WLST

In this scenario, the domain's current policy audits user logout events. The administrator would like to remove the logout events from the policy and, instead, audit login events.

The following invocation of setAuditPolicy performs this task:


Note:

This example uses the component type OHS for Oracle HTTP Server. Substitute the relevant component type when using the command.

setAuditPolicy
(filterPreset="Custom",addCustomEvents="OHS:UserLogin",
removeCustomEvents="OHS:UserLogout")

Notice that the Custom filter preset was invoked to add and remove events.

14.3.3.5 Custom Configuration is Retained when the Audit Level Changes

When auditing is configured at the custom audit level, and you subsequently use WLST to switch to a different (non-custom) audit level, the custom audit settings are retained unless you explicitly remove those custom settings.

An example illustrates this behavior:

  1. Custom audit level is set for a component's policy. An audit filter is specified as part of the configuration.

  2. At run-time, audit data is collected according to the specified filter.

  3. The component's audit policy is now changed from custom audit level to, say, the low audit level using the WLST setAuditPolicy command. However, the filter that was set up as part of the custom audit level persists in the audit configuration.

  4. Audit data is now collected based on the low audit level, not the custom level.

  5. The component's audit policy is changed back to custom level. An additional filter is added. This filter is appended to the originally configured filter. Unless the original filter is explicitly deleted, it remains part of the configuration.

  6. At run-time, audit data is collected based on all prevailing filters at the custom level.

14.3.4 Manage Audit Policies Manually

This section explains how to configure auditing policies and other features by manually updating:

  • the platform configuration file jps-config.xml for Java components

  • component-specific files for system components

This section contains these topics:

14.3.4.1 Location of Configuration Files for Java Components

The jps-config.xml domain configuration file can be found at this location:

$DOMAIN_HOME/config/fmwconfig/jps-config.xml

14.3.4.2 Audit Service Configuration Properties in jps-config.xml for Java Components

The Audit Service Configuration in jps-config.xml consists of the properties shown in Table F-9. Taken together, the set of properties and their values are known as the audit policy.


Note:

  • The policy settings in the audit store take precedence over the policy settings in jps-config.xml.

  • In the dynamic metadata model, the audit policy for a specific component is stored in audit-store.xml.


Example jps-config.xml file

Here is a sample file illustrating an audit policy:

<?xml version="1.0" encoding="UTF-8" standalone='yes'?>
<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" schema-major-version="11" schema-minor-version="1">
 
    <serviceProviders>
     <serviceProvider name="audit.provider" type="AUDIT" class="oracle.security.jps.internal.audit.AuditProvider">
     </serviceProvider>
    </serviceProviders>
 
  <serviceInstances>
    <serviceInstance name="audit" provider="audit.provider"       location="./audit-store.xml">
       <description>Audit Service</description>
       <property name="audit.filterPreset" value="None"/>
       <property name="audit.maxDirSize" value="0"/>
       <property name="audit.maxFileSize" value="104600"/>
       <property name="audit.timezone" value="utc"/>
       <property name="audit.loader.jndi" value="jdbc/AuditAppendDataSource"/>
       <property name="audit.loader.interval" value="15"/>
       <property name="audit.loader.repositoryType" value="File"/>
       <property name="auditstore.type" value="file"/>
    </serviceInstance>
  </serviceInstances>
    <jpsContexts default="default">
        <jpsContext name="default">
            <serviceInstanceRef ref="audit"/>
        </jpsContext>
    </jpsContexts>
</jpsConfig>

14.3.4.3 Switching from Database to File for Java Components

In rare instances, you may wish to revert from using a (database) data store to using a file for audit records. This requires manual configuration of the property audit.loader.repositoryType described in Table F-9.

To switch from database to file, set the audit.loader.repositoryType to File.

When you switch from database to file, events that were collected in the database are not transferred back to the file system. If this switch is temporary, the audit events collected in the file are automatically pushed to the database when you switch to a database store again.

14.3.4.4 Audit Configuration File for System Components

System components such as Oracle HTTP Server do not use the jps-config.xml file to store the audit configuration. Instead, Oracle HTTP Server uses the auditconfig.xml file which is located in:

ORACLE_INSTANCE/instance_name/config/OHS/<ohs_name>/auditconfig.xml

Format of the auditconfig.xml File

Here is the format of the auditconfig.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<ns0:AuditConfig xmlns:ns0="http://xmlns.oracle.com/ias/audit/audit.xsd">
<ns0:Filters>
<ns0:CustomEvents> </ns0:CustomEvents>
<ns0:FilterPreset>None</ns0:FilterPreset>
<ns0:SpecialUsers> </ns0:SpecialUsers>
</ns0:Filters>
<ns0:LogsDirectory>
<ns0:MaxDirSize></ns0:MaxDirSize>
<ns0:MaxFileSize></ns0:MaxFileSize>
<ns0:Location></ns0:Location>
</ns0:LogsDirectory>
</ns0:AuditConfig>

14.4 Audit Timestamps

Prior to 11g Release 1 (11.1.1.7), the audit service wrote out database records using the application server's time zone. In 11g Release 1 (11.1.1.7), the audit service can account for different time zones for the application server and the audit data store.

This means:

  • New 11g Release 1 (11.1.1.7) sites will see audit events written in Coordinated Universal Time (UTC).

  • Sites that upgrade from 11g Release 1 (11.1.1.6) to 11g Release 1 (11.1.1.7) will, by default, continue to use the application server time zone for audit records unless you explicitly switch to UTC.


Note:

Records to bus-stop files always use UTC.

New 11g Release 1 (11.1.1.7) Sites

At new installations starting with 11g Release 1 (11.1.1.7), audit records use UTC timestamps. A new service property (audit.timezone=utc) in the default audit service configuration implements this convention.

Out-of-the-box, audit service configuration looks like this:

<serviceInstance name="audit" provider="audit.provider"       location="./audit-store.xml">
   <property name="audit.filterPreset" value="None"/>
   <property name="audit.timezone" value="utc" />
   <property name="audit.loader.repositoryType" value="File" />
   <property name="auditstore.type" value="file"/>
</serviceInstance>

Sites Upgrading to 11g Release 1 (11.1.1.7)

Audit records that existed prior to the upgrade used the application server timestamp. After the upgrade, the audit service configuration remains unchanged and, by default, the records continue to be written using the application server timestamp.

If you wish to use the UTC timestamp after upgrade, you can add the new service property audit.timezone=utc in the configuration file to get the UTC behavior.

If you switch to UTC after the upgrade, Oracle recommends that you move the existing records first to avoid any potential inconsistency which can affect reporting.


See Also:

Section F.2.7

14.5 Audit Logs and Bus-stop Files

This section contains the following topics:

14.5.1 Location of Audit Logs

Fusion Middleware Audit Framework provides a set of log files to help with audit administration. You can use these logs to trace errors and for diagnostic purposes when the audit framework is not functioning properly.

For a listing of all audit log locations, how to configure the loggers, and how to use the logs to diagnose issues, see Section J.1.1.7, "Audit Loggers".

14.5.2 Audit Timestamps in Bus-stop Files

Time stamps in the audit bus-stop files are recorded in Coordinated Universal Time. This may differ from the machine time depending on the machine's time zone setting.

14.6 Advanced Management of Database Store

The audit schema is created through the Repository Creation Utility (RCU). This section explains the organization of the audit schema and contains the following topics related to maintaining the schema:


See Also:

For more information on RCU, see Oracle Fusion Middleware Repository Creation Utility User's Guide.

14.6.1 Schema Overview

The common tables in the Oracle Fusion Middleware Audit Framework schema consist of the following:

  • common attributes in the IAU_COMMON table

  • generic attributes in dedicated tables

  • custom attribute tables in the IAU_CUSTOM_nnn tables.

For details about these tables, see Section 13.4.

The audit schema also contains the following:

  • A base table

  • A translation table

  • A set of component-specific tables of audit data

For details about these tables, see Section 14.6.2.

About the Bus-stop File

By default, the bus-stop file is maintained in the directory

WebLogic Domain Home/servers/server_name/diagnostics/auditlogs/JPS/audit.log

Here is a sample bus-stop file for Oracle Platform Security Services.

#Fields:Date Time Initiator EventType EventStatus MessageText HomeInstance ECID RID ContextFields SessionId TargetComponentType ApplicationName EventCategory ThreadId InitiatorDN TargetDN FailureCode RemoteIP Target Resource Roles CodeSource InitiatorGUID Principals PermissionAction PermissionClass mapName key
#Remark Values:ComponentType="JPS"
2008-12-08 10:46:05.492  - "CheckAuthorization" true "Oracle Platform Security Authorization Check Permission SUCCEEDED." - - - - - - - "Authorization" "48" - - "true" - - "(oracle.security.jps.service.policystore.PolicyStoreAccessPermission context=APPLICATION,name=SimpleServlet getApplicationPolicy)" - "file:/oracle/work/middleware/oracle_common/modules/oracle.jps_11.1.1/jps-internal.jar" - "[]" - - - -

Common Table and Custom Tables

Figure 14-1 shows the data in the common table and how it relates to the custom tables.

Figure 14-1 Common and Custom Audit Tables

Surrounding text describes Figure 14-1 .

Base Table and Component Tables

Figure 14-2 shows the data in the base table and how it relates to the component-specific tables.

Figure 14-2 Audit Base and Component Tables

Surrounding text describes Figure 14-2 .

14.6.2 Base and Component Table Attributes

When generated, audit records are stored in a file; if an audit database store is configured, the audit loader stores each audit record in one row of the base table and one row of a component table:

  • General information (such as Time, EventType, and EventStatus) is written into the base table.

  • Component-specific information (such as CodeSource) is written into the component table.

The average record size in the base table IAU_BASE is approximately 0.3 KB. When you plan for tablespace sizing:

  • use this number as a guideline for the average record size

  • monitor how audit database size is growing based on the audit policy selected and the level of activity

  • take into account the period of time for which the audit data is being stored.

The attributes of the base table and the component-specific tables respectively are derived from these files:

  • $ORACLE_HOME/modules/oracle.iau_12.1.2/components/generic/generic_events.xml
    

    for the base table, and

  • $ORACLE_HOME/modules/oracle.iau_12.1.2/components/componentName/component_events.xml
    

    for each component table.

Table 14-1 lists a few important attributes defined in the base table IAU_BASE. The first four attributes are common in that table and all component tables. The primary key is defined as IAU_ID + IAU_TSTZORIGINATING.

Table 14-1 Attributes of Base Table IAU_BASE

AttributeDescription

IAU_ID

A unique sequential number for every audit record

IAU_TstzOriginating

Date and time when the audit event was generated (data type TIMESTAMP)

IAU_EventType

The type (name) of the audit event

IAU_EventCategory

The category of the audit event

IAU_EventStatus

The outcome of the audit event - success or failure

IAU_MessageText

Description of the audit event

IAU_Initiator

UID of the user who was doing the operation



Note:

A SEQUENCE, an Oracle database object, is created to coordinate the assignment of sequential numbers (IAU_ID) for audit records.

You can use the listAuditEvents WLST command to get a list of all attribute names for individual component tables.

14.6.3 Indexing Scheme

For efficient queries, an index is created by default on the Timestamp (IAU_TSTZORIGINATING) in the base table and on each of the component-specific tables.

The default index in IAU_BASE is named EVENT_TIME_INDEX, and in the component tables it is named tableName_INDEX (such as OVDCOMPONENT_INDEX, OIDCOMPONENT_INDEX, JPS_INDEX and so on).

14.6.4 Backup and Recovery

Compliance regulations require that audit data be stored for long periods. A backup and recovery plan is needed to protect the data.

A good backup plan takes account of these basic guidelines:

  • Growth rate of Audit Events

    The number of audit events generated depends on your audit policy. The number of audit events generated daily determines, in turn, how often you want to perform backups to minimize the loss of your audit data.

  • Compliance regulations

    Consult you organization's compliance regulations to determine the frequency of backups and number of years for which audit data storage is mandatory.

  • Online or Offline Data Management

    Consult you organization's compliance regulations to determine the frequency of backups and the portion of audit data that needs to be easily accessible.

Oracle Database uses Oracle Recovery Manager (RMAN) for backup and recovery. For details, see:

http://www.oracle.com/technology/deploy/availability/htdocs/BR_Overview.htm

http://www.oracle.com/technology/deploy/availability/htdocs/rman_overview.htm


Note:

The translation table, IAU_DISP_NAMES_TL, needs to be backed up only once, since it should not change over time.

14.6.5 Importing and Exporting Data

You can import and export the audit schema to migrate data if you started with multiple audit databases and wish to combine them into a single audit data store, or if you wish to change the database to scale up.

Oracle Database sites can utilize the utilities of Oracle Data Pump to import and export data. For details, refer to:

http://www.oracle.com/technology/products/database/utilities/htdocs/data_pump_overview.html

14.6.6 Partitioning

Not all database systems support partitioning, all the tables in the audit schema are unpartitioned by default.

Since audit data is cumulative and older data is never removed, if you store a high volume of audit data you should consider partitioning the audit schema, as it will allow for easier archiving.

Benefits of partitioning include:

  • Improved Performance: If a table is range-partitioned by Timestamps, for example, queries by Timestamps can be processed on the partitions within that time-frame only.

  • Better Manageability: Partitions can be created on separate tablespaces (thus different disks). This enables you to move older data to slower and larger disks, while keeping newer data in faster and smaller disks.

    In addition, partitioning makes archival much easier. For example, you can compress a singlve partition rather than having to partition the entire table.

  • Increased Availability: If a single partition is unavailable, for example, and you know that your query can eliminate this partition from consideration, the query can be successfully processed without needing to wait for the unavailable partition.

14.6.6.1 Partition Tables


Note:

This discussion applies to releases prior to 11g Release 1 (11.1.1.7). New 11g Release 1 (11.1.1.7) installations do not use these tables.

In this example, IAU_BASE is used as an example to demonstrate ho'2w to convert the unpartitioned tables in the audit schema into partitioned tables.

It is recommended that partitioning is done before using this schema for an audit data store to minimize the application down time.


Note:

Two sample SQL scripts are shipped with the product:
  • $MW_HOME/oracle_common
    /common/sql/iau/scripts/convertPartitionedTables.sql
    (linux) or %MW_HOME\oracle_common
    \common\sql\iau/scripts\convertPartitionedTables.sql
    (Windows) converts the base and component tables in the audit schema into partitioned tables.

  • $MW_HOME/oracle_common
    /common/sql/iau/scripts/createPartitionsByQuarter.sql
    (linux) or %MW_HOME\oracle_common
    \common\sql\iau/scripts\createPartitionsByQuarter.sql
    (Windows) creates partitions by quarter for the base and component tables in the audit schema.


The partitioning steps are as follows:


Note:

It is recommended that you deactivate the audit loader prior to partitioning. See Section 14.2.4.1, "Deconfigure the Audit Data Store" for details.

  1. Rename the existing unpartitioned table. For example:

    RENAME IAU_BASE TO IAU_BASE_NONPART;
    
  2. Create a new partitioned table that follows the table structure of the unpartitioned table. This example uses the range-partitioning (by Timestamp) scheme:

    CREATE TABLE IAU_BASE
    PARTITION BY RANGE (IAU_TSTZORIGINATING)
    (
        PARTITION IAU_BASE_DEFAULT VALUES LESS THAN (MAXVALUE)
    )
    AS SELECT * FROM IAU_BASE_NONPART;
    
  3. Enable row movement to allow data to automatically move from partition to partition when new partitions are created. For example:

    ALTER TABLE IAU_BASE
    ENABLE ROW MOVEMENT;
    
  4. Create a local prefix index for the partitioned table. For example:

    ALTER INDEX EVENT_TIME_INDEX
    RENAME TO EVENT_TIME_INDEX_NONPART;
     
    CREATE INDEX EVENT_TIME_INDEX
    ON IAU_BASE(IAU_TSTZORIGINATING) LOCAL;
    
  5. Partitions can now be created. In this example partitions are created by calendar quarter:

    ALTER TABLE IAU_BASE
    SPLIT PARTITION IAU_BASE_DEFAULT AT (TO_DATE('01/04/2008', 'DD/MM/YYYY')) INTO (PARTITION IAU_BASE_Q1_2008, PARTITION IAU_BASE_DEFAULT)
    UPDATE INDEXES;
     
    ALTER TABLE IAU_BASE
    SPLIT PARTITION IAU_BASE_DEFAULT AT (TO_DATE('01/07/2008', 'DD/MM/YYYY')) INTO (PARTITION IAU_BASE_Q2_2008, PARTITION IAU_BASE_DEFAULT)
    UPDATE INDEXES;
     
    ALTER TABLE IAU_BASE
    SPLIT PARTITION IAU_BASE_DEFAULT AT (TO_DATE('01/10/2008', 'DD/MM/YYYY')) INTO (PARTITION IAU_BASE_Q3_2008, PARTITION IAU_BASE_DEFAULT)
    UPDATE INDEXES;
     
    ALTER TABLE IAU_BASE
    SPLIT PARTITION IAU_BASE_DEFAULT AT (TO_DATE('01/01/2009', 'DD/MM/YYYY')) INTO (PARTITION IAU_BASE_Q4_2008, PARTITION IAU_BASE_DEFAULT)
    UPDATE INDEXES;
    

    Note:

    New partitions should be created periodically for new quarters.

14.6.6.2 Backup and Recovery of Partitioned Tables

Backup and recovery were discussed in Section 14.6.4, "Backup and Recovery". Note that read-only tablespaces can be excluded from whole database backup, so long as a backup copy was created. Thus, you can improve performance by avoiding unnecessary backups for the partitions of archived data residing on those tablespaces.

14.6.6.3 Import and Export

Import and export were discussed in Section 14.6.5, "Importing and Exporting Data". Keep in mind that with a range-partitioned table it is much more efficient to drop a partition when you want to remove old data, rather than deleting the rows individually.

ALTER TABLE IAU_BASE DROP PARTITION IAU_BASE_Q4_2008;

It is also easy to load a partition of new data without having to modify the entire table. However, you have to remove the default partition of "values less than (MAXVALUE)" first, and add it back once finished, using a command like the following:

ALTER TABLE IAU_BASE ADD PARTITION IAU_BASE_Q4_2008 VALUES LESS THAN ('01-JAN-2009');

Once partitions are created, you can purge or back up a particular partition. Refer to Section 14.6.6.4 for details.

In the database mode, the audit loader automatically manages bus-stop files.

14.6.6.4 Data Purge

Oracle Fusion Middleware Audit Framework provides SQL scripts to enable you to purge records from the audit store.

Location of Scripts

The purge scripts are located at:

[Linux]
$MW_HOME/oracle_common/common/sql/iau/scripts


[Windows]
%MW_HOME\oracle_common\common\sql\iau\scripts

The following scripts reside at this location:

  • auditDataPurge.sql

  • auditDeleteData.sql

  • auditReclaimSpace.sql

Deleting Audit Records

To delete records without taking any other action, use auditDeleteData.sql. The script takes two parameters:

  • Audit Schema user

  • Number of Days to keep - older records are deleted.

auditDeleteData.sql audit_schema_user number_of_days_to_keep

For example:

sqlplus> @auditDeleteData.sql DEV_IAU 100

deletes all records older than 100 days.

Reclaiming Space in Data Store

To reclaim space, use the auditReclaimSpace.sql script. The script takes only one parameter, the audit schema user.

@auditReclaimSpace.sql audit_schema_user

For example:

sqlplus> @auditDataPurge.sql DEV_IAU

Deleting Records and Reclaiming Space

To both delete audit records and reclaim space, use the auditDataPurge.sql script. This script takes two parameters:

  • Audit Schema user

  • Number of Days to keep; older records are deleted.

@auditDataPurge.sql audit_schema_user number_of_days_to_keep

For example:

sqlplus> @auditDataPurge.sql DEV_IAU 100

deletes all records older than 100 days, and enables row movements to shrink space.

14.6.6.5 Tiered Archival

Partitioning enables individual partitions (or groups of partitions) to be stored on different storage tiers. You can create tablespaces in high-performance or low-cost disks, and create partitions in different tablespaces based on the value of the data or other criteria. It is also easy to move data in partitions between the tablespaces (storage tiers).

Here is an example:

ALTER TABLE IAU_BASE MOVE PARTITION IAU_BASE_Q1_2008
TABLESPACE AUDITARCHIVE UPDATE INDEXES;

Note :

Partitions can be moved only in Range, List, System, and Hash partitioning schemes.

Oracle Information Lifecycle Management (ILM) features streamlined data management through partitioning and compression. For details, refer to:

http://www.oracle.com/technetwork/database/enterprise-edition/index-090321.html

PKsͧPK].FOEBPS/devauthn.htm Configuring Java SE Applications to Use OPSS

19 Configuring Java SE Applications to Use OPSS

The information in this chapter applies only to Java SE applications, and the intended audience are developers of Java SE applications.

For similar information about Java EE applications, see Chapter 18, "Configuring Java EE Applications to Use OPSS."

This chapter includes in the following topics:

19.1 Using OPSS in Java SE Applications

In order to use OPSS in a Java SE application, the developer should aware that:

  • The file jps-manifest.jar must be in the class path.

  • The application must call JpsStartup.start() at initialization.

  • The following system properties must be set:

    • oracle.security.jps.config, the file path to the file jps-config-jse.xml.

    • common.components.home, the path to the oracle common directory.

    • java.security.policy, the file path to the file java.policy.

    For other (optional) system properties you can set, see Section F.1, "OPSS System Properties."

  • The application should use the OPSS class AppSecurityContext, as illustrated in the following sample snippet:

    String appID = AppSecurityContext.getApplicationID();
     
           try {
                setApplicationID(appName);
                        .....
            } finally {
                setApplicationID(appID );
            }
        }
    
        private static void setApplicationID(final String applicationID) {
                    AccessController.doPrivileged(new PrivilegedAction() {
                public Object run() {
                    AppSecurityContext.setApplicationID(applicationID);
                    return null;
                }
            });
        } 
    

    The call AppSecurityContext.setApplicationID requires a codesource permission like the following:

    <grant>
        <grantee>
            <codesource>
              <url>myJavaSEapp/-</url>
            </codesource>
        </grantee>
        <permissions>
            <permission>
                <class>oracle.security.jps.JpsPermission</class>
                <name>AppSecurityContext.setApplicationID.myAppStripeID</name>
            </permission>
        </permissions>
    </grant>
    

For information about how to configure the OPSS security store, see Chapter 9, "Configuring the OPSS Security Store."

19.3 Authentication in Java SE Applications

This section explains the identity store support for Java SE applications, and it includes the following sections:

19.3.1 The Identity Store

Authentication is the mechanism by which callers prove that they are acting on behalf of specific users or system. Using data, such as name-password combinations, authentication answers the question Who are you? The term identity store refers to the storage where identity data is kept, and authentication providers are ways to access an identity store.

An application obtains information from an OPSS security store (identity, policy, or credential store) and manages its contents using the OPSS APIs, as illustrated in the following graphic:

Surrounding text describes jisec013.gif.

19.3.2 Configuring an LDAP Identity Store in Java SE Applications

A Java SE application can use an LDAP-based identity store configured in the file jps-config-jse.xml with the elements <serviceProvider>, <serviceInstance>, and <jpsContext>, as illustrated in the following snippet:

<serviceProviders>
  <serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider">
    <description>Prototype LDAP-based ID store</description>
  </serviceProvider>
</serviceProviders>

<serviceInstances>
 <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
   <property name="idstore.type" value="OID"/>
   <property name="max.search.filter.length" value="500"/>
   <extendedProperty>
     <name>user.search.bases</name>
     <values>
       <value>cn=users,dc=us,dc=oracle,dc=com</value>
     </values>
   </extendedProperty>
   <extendedProperty>
     <name>group.search.bases</name>
     <values>
       <value>cn=groups,dc=us,dc=oracle,dc=com</value>
      </values>
   </extendedProperty>
 </serviceInstance>
</serviceInstances>

<jpsContexts default="ldap_idstore">
  <jpsContext name="ldap_idstore">
    <serviceInstanceRef ref="idstore.ldap"/>
  </jpsContext>

  <jpsContext name="bootstrap_credstore_context">
     <serviceInstanceRef ref="bootstrap.cred"/>  
   </jpsContext>
</jpsContexts>

Note the following points:

  • The name of the <serviceInstance> (idstore.ldap in the example above) can have any value, but it must match the instance referenced in element <serviceInstanceRef>.

  • The name of the <serviceProvider> (idstore.ldap.provider in the example above) can have any value, but it must match the provider in element <serviceInstance>.

  • To add properties to a provider instance with a prescribed script, see Appendix E, "Configuring OPSS Service Provider Instances with a Script."

19.3.3 Login Modules

A login module is a component that authenticates users and populates a subject with principals. This process occurs in two distinct phases: during the first phase, the login module attempts to authenticate a user requesting, as necessary, a name and a password or some other credential data; only if this phase succeeds, the second phase is invoked. During the second phase, the login module assigns relevant principals to a subject, which is eventually used to perform some privileged action.

In any of the supported login modules, you can set the following properties:

enable.anonymous (default: false)
remove.anonymous.role (default: true)
add.application.roles (default: true)
add.authenticated.role (default: true)

For a sample configuration, see "<serviceInstance>"

The supported login modules are the following:

19.3.3.1 The Identity Store Login Module

A Java SE application can use a stack of login modules to authenticate its users; each module performs its own computations independently from the others in the stack. These and other services are specified in the file jps-config-jse.xml.

OPSS APIs includes the interface oracle.security.jps.service.login.LoginService which allows a Java SE application to invoke not just all login modules in a stack, but a subset of them in a prescribed order.

The name of the jps context (defined in the configuration file jps-config-jse.xml) passed to the method LoginContext in the LoginService interface determines the stack of login modules that an application uses. The standard JAAS API LoginContext can also be used to invoke the login modules defined in the default context

The sequence in which a jps context lists the login modules in a stack is significant, since the authentication algorithm takes this order into account in addition to other data, such as the flag that identifies the module security level (required, sufficient, requisite, or optional).

Out-of-the-box, the identity store service is file-based, its contents being provisioned in the file system-jazn-data.xml; the service can be reconfigured to use an LDAP-based identity store.

OPSS supports the Identity Store login module in Java SE applications, which can be used for authentication or identity assertion, as explained in the following sections:

Identity Store Login Module

The class associated with this login module is the following:

oracle.security.jps.internal.jaas.module.idstore.IdStoreLoginModule

An instance of this module is configured in the file jps-config-jse.xml as illustrated in the following fragment:

<serviceInstance name="idstore.loginmodule" provider="jaas.login.provider">
  <description>Identity Store Login Module</description>
  <property name="loginModuleClassName" value="oracle.security.jps.internal.jaas.module.idstore.IdStoreLoginModule"/>
  <property name="jaas.login.controlFlag" value="REQUIRED"/>
</serviceInstance>

Properties specific to this login module include the following:

remove.anonymous.role (defaults to true)
add.application.role (defaults to true)
19.3.3.1.1 Using the Identity Store Login Module for Authentication

This section illustrates the use of the Identity Store login module for basic username and password authentication.

Invoke IdStoreLoginModule

The following code fragment illustrates how to set a callback handler and a context:

import javax.security.auth.Subject;
import javax.security.auth.login.LoginContext;

Subject sub = new Subject();
CallbackHandler cbh = new YourCallbackHandler();
LoginContext context = new LoginContext(appName, subject,  cbh);
context.login();

The callback handler must be able to handle NameCallback and PasswordCallback.

Configure jps-config-jse.xml

The following jps-config-jse.xml fragment illustrates the configuration of the context appName:

<jpsContext name="appName">
   <serviceInstanceRef ref="jaaslm.idstore1"/>
</jpsContext>

<serviceProvider type="JAAS_LM" name="jaaslm.idstore" 
      class="oracle.security.jps.internal.jaas.module.idstore.IdStoreLoginModule">
   <description>Identity Store-based LoginModule
   </description>
</serviceProvider>

<serviceInstance name="jaaslm.idstore1" provider="jaaslm.idstore">
   <property name="jaas.login.controlFlag" value="REQUIRED"/>
   <property name="debug" value="true"/>
   <property name="addAllRoles" value="true"/>
</serviceInstance>

Write the Callback Handler

The following code snippet illustrates a callback handler able to handle name and password callback:

import javax.security.auth.callback.*;
import java.io.IOException; 
public class SampleCallbackHandler implements CallbackHandler {
//For name/password callbacks
private String name = null;private char[] password = null; 
public SampleCallbackHandler(String name, char[] pwd) { 
   if (name == null || name.length() == 0 )         
      throw new IllegalArgumentException("Invalid name ");
   else 
      this.name = name; 
   if (pwd == null || pwd.length == 0)
      throw new IllegalArgumentException("Invalid password ");
   else
      this.password = pwd;
}
public String getName() {
   return name;
   } public char[] getPassword()  {
   return password;
 }    
public void handle(Callback[] callbacks) 
   throws IOException, UnsupportedCallbackException {
   if (callbacks != null && callbacks.length > 0) {
      for (Callback c : callbacks) {
      if (c instanceof NameCallback) {
            ((NameCallback) c).setName(name);
            } 
   else 
      if (c instanceof PasswordCallback) {
         ((PasswordCallback) c).setPassword(password);
              }           
   else {
      throw new UnsupportedCallbackException(c);
 }
          }
      }
  }
}
19.3.3.1.2 Using the Identity Store Login Module for Assertion

To use the Identity Store login module for assertion, a developer must:

  • Provide the appropriate permission for the caller to execute the protected method setIdentity. This requires granting the permission oracle.security.jps.JpsPermission with the name IdentityAssertion.

  • Implement a callback handler that uses the class oracle.security.jps.callback.IdentityCallback as shown in the code sample below.

The above two requirements are illustrated in the following configuration and code samples.

Provisioning the JpsPermission

The following configuration sample illustrates a grant allowing the code MyApp the required JpsPermission to execute protected methods in the assertion login module:

<grant>
  <grantee>
    <codesource>
      <url>file:${soa.oracle.home}/application/myApp.ear</url>
                      <--! soa.oracle.home is a system property set when 
      the server JVM is started -->
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
    </permission>
  </permissions>
</grant>

The following configuration sample illustrates a grant allowing the principal jdoe the required JpsPermission to execute the assertion login module:

<grant>
  <grantee>
    <principals>
      <principal>
        <class>weblogic.security.principal.WLSUserImpl</class>
        <name>jdoe</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
    </permission>
  </permissions>
</grant>

Implementing the CallbackHandler

The following code fragment illustrates an implementation of the callback handler:

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.callback.UnsupportedCallbackException;
 
import oracle.security.jps.callback.IdentityCallback;
 
public class CustomCallbackHandler implements CallbackHandler {
    private String name = null;
    private char[] password;
 
    public CustomCallbackHandler(String name) {
        this.name = name;
    }
    
    public CustomCallbackHandler(String name, char[] password) {
      this.name  = name;
      this.password = password;
    }
 
    public void handle(Callback[] callbacks) throws IOException,
                                                    UnsupportedCallbackException {
        for (Callback callback : callbacks) {
            if (callback instanceof NameCallback) {
              NameCallback nc = (NameCallback) callback;
              nc.setName(name);
            }
            else if (callback instanceof PasswordCallback) {
              PasswordCallback pc = (PasswordCallback) callback;
              pc.setPassword(password);
            }
            else if (callback instanceof IdentityCallback) {
                IdentityCallback idcb = (IdentityCallback)callback;
                idcb.setIdentity(name);
                idcb.setIdentityAsserted(true);
                idcb.setAuthenticationType("CUSTOM");
            } else {
                //throw exception
                throw new UnsupportedCallbackException(callback);
            }
        }
    }
}

The following code fragment illustrates the implementation of a login module:

import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.LoginContext;
 
import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.login.LoginService;
 
public class LoginModuleExample {
    private static final String CONTEXT_NAME = "JSE_UserAuthnAssertion";
 
    public LoginModuleExample() {
        super();
    }
 
    public Subject assertUser(final String username) throws Exception {
        CallbackHandler cbh =
            AccessController.doPrivileged(new PrivilegedExceptionAction<CallbackHandler>() {
                public CallbackHandler run() throws Exception {
                    return new CustomCallbackHandler(username);
                }
            });
        Subject sub = new Subject();
        LoginService ls =
            JpsServiceLocator.getServiceLocator().lookup(LoginService.class);
        LoginContext context = ls.getLoginContext(sub, cbh);
 
        context.login();
        Subject s = context.getSubject();
 
        return s;
    }
 
    public Subject authenticate(final String username, final char[] password) throws Exception {
        CallbackHandler cbh = new CustomCallbackHandler(username, password);
        Subject sub = new Subject();
        LoginService ls =
            JpsServiceLocator.getServiceLocator().lookup(LoginService.class);
        LoginContext context = ls.getLoginContext(sub, cbh);
 
        context.login();
        Subject s = context.getSubject();
 
        return s;
    }
 
    public static void main(String[] args) {
        LoginModuleExample loginModuleExample = new LoginModuleExample();
        try {
            System.out.println("authenticated user subject = " + 
                               loginModuleExample.authenticate("testUser", 
 "welcome1".toCharArray()));
            System.out.println("asserted user subject = " +
                               loginModuleExample.assertUser("testUser"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

19.3.3.2 The User Authentication Login Module

The User Authentication login module can be used by both Java EE and Java SE applications to authenticate a user given a user name and a password. The configuration of this login module is available out-of-the-box. This login module authenticates against the domain identity store.

Here is a code fragment using this module for programmatic authentication:

import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
public class MyCallbackHandler  extends CallbackHandler {
        private String name = null;
        private char[] password = null;
 
        public MyCallbackHandler(String name, char[] password) {
          this.name = name;
          this.password = password;
        }
 
        public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (Callback callback : callbacks) {
                if (callback instanceof NameCallback) {
                    NameCallback ncb  = (NameCallback) callback;
                    ncb.setName(name);
                }
                else if (callback instanceof PasswordCallback) {
                    PasswordCallback pcb  = (PasswordCallback) callback;
                    pcb.setPassword(password);
                }
                else {
                    throw UnsupportedCallbackException(callback);
                }
            }
        }
}
 
JpsLoginModuleFactory factory = JpsLoginModuleFactory.getLoginModuleFactory();
CallbackHandler cbh = new  MyCallbackHandler("name", "password".toCharArray());
LoginContext ctx = factory.getLoginContext(JpsLoginModuleType.USER_AUTHENTICATION, null, cbh);
ctx.login();
Subject s = ctx.getSubject();

19.3.3.3 The User Assertion Login Module

The User Assertion login module can be used by both Java EE and Java SE applications to assert a user identity. This login module asserts against the domain identity store, and it requires implementing the callback oracle.security.jps.callback.IdentityCallback. Moreover, execution of this login module requires an IdentityAssertion permission (with execute as action) for oracle.security.jps.JpsPermission.

To use the User Assertion login module for programmatic assertion, a developer must:

  • Provide the appropriate permission for the caller to execute login module protected methods. This requires granting the permission oracle.security.jps.JpsPermission with name IdentityAssertion (and action execute).

  • Implement a callback handler that uses the class oracle.security.jps.callback.IdentityCallback.Implement the programmatic assertion code.

The above requirements are illustrated in the following configuration and code samples:

19.3.3.3.1 Provisioning the jpsPermission

The following configuration sample illustrates a grant allowing the principal jdoe the required JpsPermission to execute the User Assertion login module:

<grant>
  <grantee>
    <principals>
      <principal>
        <class>weblogic.security.principal.WLSUserImpl</class>
        <name>jdoe</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>IdentityAssertion</name>
      <action>execute</action>
    </permission>
  </permissions>
</grant>

For a codesource example, see grant sample in Section 18.5.6, "Supported Permission Classes."

19.3.3.3.2 Implementing the CallbackHandler

The following code fragment illustrates an implementation of the callback handler:

import oracle.security.jps.callback.IdentityCallback;
 
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import java.io.IOException;
 
    public class AssertCallbackHandler implements CallbackHandler {
        private String name = null;
 
        public AssertCallbackHandler(String name) {
            this.name = name;
        }
 
 
        public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (Callback callback : callbacks) {
                if (callback instanceof IdentityCallback) {
                    IdentityCallback nc = (IdentityCallback) callback;
                    nc.setIdentity(name);
                }
                else {
                    throw new UnsupportedCallbackException(callback);
                }
            }
        }
    }
19.3.3.3.3 Implementing the Programmatic Assertion

The following code fragment illustrates how to assert a user:

import oracle.security.jps.callback.IdentityCallback;
import oracle.security.jps.internal.api.jaas.module.JpsLoginModuleFactory;
import oracle.security.jps.internal.api.jaas.module.JpsLoginModuleType;
 
import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.login.LoginContext;
import java.io.IOException;
import java.security.AccessController;
import java.security.PrivilegedActionException;
import java.security.PrivilegedExceptionAction;
 
        Subject subject = AccessController.doPrivileged(new PrivilegedExceptionAction<Subject>() {
            public Subject run() throws Exception {
                JpsLoginModuleFactory f = JpsLoginModuleFactory.getLoginModuleFactory();
                CallbackHandler cbh = new AssertCallbackHandler(name);
                LoginContext c = f.getLoginContext(JpsLoginModuleType.USER_ASSERTION, null, cbh);
                c.login();
                return c.getSubject();
            }
        });

19.3.4 Using the OPSS API LoginService in Java SE Applications

To invoke a login module programmatically in Java SE applications, use the method getLoginContext of the interface oracle.security.jps.service.login.LoginService.

Similar to the method LoginContext in the standard JAAS API, getLoginContext returns an instance of a LoginContext object that can be used to authenticate a user, but, more generally, it also allows the use of any number of login modules in any order. Authentication is then performed on just those login modules and in the order they were passed.

The following code fragment illustrates user authentication against a subset of login modules in a prescribed order using getLoginContext:

import oracle.security.jps.service.ServiceLocator;
import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.login.LoginService;

//Obtain the login service
ServiceLocator locator = JpsServiceLocator.getServiceLocator();
LoginService loginService = locator.lookup(LoginService.class);

//Create the handler for given name and password
CallbackHandler cbh = new MyCallbackHandler("name", "password".toCharArray());

//Invoke login modules selectively in a given order
selectiveModules = new String[]{"lmName1", "lmName2", "lmName3"};
LoginContext ctx = loginService.getLoginContext(new Subject(), cbh, selectiveModules);
ctx.login();
Subject s = ctx.getSubject();

selectiveModules is an array of (login module) names, and the authentication uses precisely those login modules named in the array in the order listed in the array. Each name in the array must be the name |&of a service instance listed in the default context of the file jps-config-jse.xml.

The following fragment illustrates the configuration of a stack of two login modules:

<serviceProvider type="LOGIN" name="jaas.login.provider" class="oracle.security.jps.internal.login.jaas.JaasLoginServiceProvider">
   <description>Common definition for any login module instances</description>
</serviceProvider>

<serviceInstance name="auth.loginmodule" provider="jaas.login.provider">
   <description>User Authentication Login Module</description>
   <property name="loginModuleClassName" value="oracle.security.jps.internal.jaas.module.authentication.JpsUserAuthenticationLoginModule"/>
   <property name="jaas.login.controlFlag" value="REQUIRED"/>
</serviceInstance>
 
<serviceInstance name="custom.loginmodule" provider="jaas.login.provider">
   <description>My Custom Login Module</description>
   <property name="loginModuleClassName" value="my.custom.MyLoginModuleClass"/>
   <property name="jaas.login.controlFlag" value="REQUIRED"/>
</serviceInstance>
 
<jpsContexts default="aJpsContext">
   <jpsContext name="aJpsContext">
     <serviceInstanceRef ref="auth.loginmodule"/>
     <serviceInstanceRef ref="custom.loginmodule"/>
   </jpsContext>
</jpsContexts>

19.4 Configuration Examples

This section illustrates the configuration of the following artifacts:

  • XML policy and credential stores

  • XML and LDAP identity stores

  • Login Module Principals

XML Policy and Credential Stores Configuration

The following snippets illustrate the configuration of XML-based policy and credential stores. The contents of an XML-based policy store is specified in the file system-jazn-data.xml; the contents of an XML-based credential store is specified in the file cwallet.sso.

<serviceProviders> <serviceProvider class="oracle.security.jps.internal.policystore.xml.XmlPolicyStoreProvider" name="policystore.xml.provider" type="POLICY_STORE">
  <description>XML-based PolicyStore Provider</description>
 </serviceProvider>

 <serviceProvider class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider" name="credstoressp" type="CREDENTIAL_STORE">
  <description>SecretStore-based CSF Provider</description>
 </serviceProvider>
</serviceProviders>

<serviceInstances>
 <serviceInstance location="./" provider="credstoressp" name="credstore">
  <description>File-based Credential Store Service Instance</description>
 </serviceInstance>

<serviceInstance location="./system-jazn-data.xml" provider="policystore.xml.provider" name="policystore.xml">
   <description>File-based Policy Store Service Instance</description>
 </serviceInstance>
</serviceInstances>

XML Identity Store Configuration

The following snippets illustrate the configuration of an XML-based identity store. The contents of an XML-based identity store is specified in the file system-jazn-data.xml.

<serviceProvider
  class="oracle.security.jps.internal.idstore.xml.XmlIdentityStoreProvider"
  name="idstore.xml.provider" 
  type="IDENTITY_STORE">
 <description>XML-based Identity Store Service Provider</description>
</serviceProvider>

<serviceInstance 
  location="./system-jazn-data.xml" provider="idstore.xml.provider"
  name="idstore.xml">
 <description>File Based Identity Store Service Instance</description>
 <property value="jazn.com" name="subscriber.name"/>
</serviceInstance>

LDAP Identity Store Configuration

The snippets below illustrate the configuration of an LDAP-based identity store, which includes the required configuration of the bootstrap credentials to access the LDAP server. The service instance property idstore.type can have the following values, according to the LDAP used:

Table 19-1 Idstore Types

Supported LDAPIdstore.type value

Oracle Internet Directory 10g and 11g

OID

Oracle Virtual Directory 10g and 11g

OVD

Sun Java System Directory Server 6.3

IPLANET

Active Directory 2003, 2008

ACTIVE_DIRECTORY

Novell eDirectory 8.8

EDIRECTORY

Oracle Directory Server Enterprise Edition 11gR1 (11.1.1.3+)

IPLANET

IBM Tivoli DS 6.2

OPEN_LDAP

OpenLDAP 2.2.

OPEN_LDAP


        <serviceProvider
   class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider"
   name="idstore.ldap.provider" type="IDENTITY_STORE">
         <description>LDAP-based Identity Store Service Provider</description>
</serviceProvider>

<serviceProvider
   class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider"
   name="credstoressp" type="CREDENTIAL_STORE">
 <description>SecretStore-based CSF Provider</description>
</serviceProvider>
 
<serviceInstance name="idstore.oid" provider="idstore.ldap.provider">
         <property name="subscriber.name" value="dc=us,dc=oracle,dc=com"/>
         <property name="idstore.type" value="OID"/>
         <property value=ldap://myOID.com:3555 name="ldap.url"/>
        <extendedProperty>
                 <name>user.search.bases</name>
                  <values>
                           <value>cn=users,dc=us,dc=oracle,dc=com</value>
                  </values>
         </extendedProperty>
         <extendedProperty>
                 <name>group.search.bases</name>
                  <values>
                           <value>cn=groups,dc=us,dc=oracle,dc=com</value>
                  </values>
         </extendedProperty>
         <property name="username.attr" value="uid"/>
         <propperty name="group.attr" value="cn"/>
</serviceInstance>

<serviceInstance location="./bootstrap" provider="credstoressp"
 name="bootstrap.cred">
 <property value="./bootstrap" name="location"/>
</serviceInstance>

Login Module Principals

The following properties are set in the out-of-the-box jps-config-jse.xml:

 <property name="oracle.security.jps.enterprise.user.class"
          value="weblogic.security.principal.WLSUserImpl"/>
 
    <property name="oracle.security.jps.enterprise.role.class"
             value="weblogic.security.principal.WLSGroupImpl"/>

The above propeties must be used in any login module; this implies that the principals that represent users and groups in the identity store are the following:

weblogic.security.principal.WLSUserImpl
weblogic.security.principal.WLSGroupImpl
PK8|PK].FOEBPS/part_devaa.htmy Developing with Oracle Platform Security Services APIs

Part IV

Developing with Oracle Platform Security Services APIs

This part explains how to develop custom security solutions in your applications using OPSS APIs, and it contains the following chapters:

PKu~ y PK].FOEBPS/dcommon/doccd_epub.jsM /* Copyright 2006, 2012, Oracle and/or its affiliates. All rights reserved. Author: Robert Crews Version: 2012.3.17 */ function addLoadEvent(func) { var oldOnload = window.onload; if (typeof(window.onload) != "function") window.onload = func; else window.onload = function() { oldOnload(); func(); } } function compactLists() { var lists = []; var ul = document.getElementsByTagName("ul"); for (var i = 0; i < ul.length; i++) lists.push(ul[i]); var ol = document.getElementsByTagName("ol"); for (var i = 0; i < ol.length; i++) lists.push(ol[i]); for (var i = 0; i < lists.length; i++) { var collapsible = true, c = []; var li = lists[i].getElementsByTagName("li"); for (var j = 0; j < li.length; j++) { var p = li[j].getElementsByTagName("p"); if (p.length > 1) collapsible = false; for (var k = 0; k < p.length; k++) { if ( getTextContent(p[k]).split(" ").length > 12 ) collapsible = false; c.push(p[k]); } } if (collapsible) { for (var j = 0; j < c.length; j++) { c[j].style.margin = "0"; } } } function getTextContent(e) { if (e.textContent) return e.textContent; if (e.innerText) return e.innerText; } } addLoadEvent(compactLists); function processIndex() { try { if (!/\/index.htm(?:|#.*)$/.test(window.location.href)) return false; } catch(e) {} var shortcut = []; lastPrefix = ""; var dd = document.getElementsByTagName("dd"); for (var i = 0; i < dd.length; i++) { if (dd[i].className != 'l1ix') continue; var prefix = getTextContent(dd[i]).substring(0, 2).toUpperCase(); if (!prefix.match(/^([A-Z0-9]{2})/)) continue; if (prefix == lastPrefix) continue; dd[i].id = prefix; var s = document.createElement("a"); s.href = "#" + prefix; s.appendChild(document.createTextNode(prefix)); shortcut.push(s); lastPrefix = prefix; } var h2 = document.getElementsByTagName("h2"); for (var i = 0; i < h2.length; i++) { var nav = document.createElement("div"); nav.style.position = "relative"; nav.style.top = "-1.5ex"; nav.style.left = "1.5em"; nav.style.width = "90%"; while (shortcut[0] && shortcut[0].toString().charAt(shortcut[0].toString().length - 2) == getTextContent(h2[i])) { nav.appendChild(shortcut.shift()); nav.appendChild(document.createTextNode("\u00A0 ")); } h2[i].parentNode.insertBefore(nav, h2[i].nextSibling); } function getTextContent(e) { if (e.textContent) return e.textContent; if (e.innerText) return e.innerText; } } addLoadEvent(processIndex); PKo"nR M PK].FOEBPS/dcommon/cpyr.htmD Oracle Legal Notices

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2015, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Oracle Logo

PKMPK].FOEBPS/dcommon/oracle-logo.jpgbJFIFC    $.' ",#(7),01444'9=82<.342C  2!!22222222222222222222222222222222222222222222222222'7" }!1AQa"q2#BR$3br %&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz w!1AQaq"2B #3Rbr $4%&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz ?( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( (QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQE!KEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEzE7V%ȣOΏ9??:a"\fSrğjAsKJ:nOzO=}E1-I)3(QEQEQEQEQEQEQE֝Hza<["2"pO#f8M[RL(,?g93QSZ uy"lx4h`O!LŏʨXZvq& c՚]+: ǵ@+J]tQ]~[[eϸ (]6A&>ܫ~+כzmZ^(<57KsHf妬Ϧmnẁ&F!:-`b\/(tF*Bֳ ~V{WxxfCnMvF=;5_,6%S>}cQQjsOO5=)Ot [W9 /{^tyNg#ЄGsֿ1-4ooTZ?K Gc+oyڙoNuh^iSo5{\ܹ3Yos}$.nQ-~n,-zr~-|K4R"8a{]^;I<ȤL5"EԤP7_j>OoK;*U.at*K[fym3ii^#wcC'IIkIp$󿉵|CtĈpW¹l{9>⪦׺*ͯj.LfGߍԁw] |WW18>w.ӯ! VӃ :#1~ +މ=;5c__b@W@ +^]ևՃ7 n&g2I8Lw7uҭ$"&"b eZ":8)D'%{}5{; w]iu;_dLʳ4R-,2H6>½HLKܹR ~foZKZ࿷1[oZ7׫Z7R¢?«'y?A}C_iG5s_~^ J5?œ tp]X/c'r%eܺA|4ծ-Ե+ْe1M38Ǯ `|Kյ OVڅu;"d56, X5kYR<̭CiطXԮ];Oy)OcWj֩}=܅s۸QZ*<~%뺃ȶp f~Bðzb\ݳzW*y{=[ C/Ak oXCkt_s}{'y?AmCjޓ{ WRV7r. g~Q"7&͹+c<=,dJ1V߁=T)TR՜*N4 ^Bڥ%B+=@fE5ka}ędܤFH^i1k\Sgdk> ֤aOM\_\T)8靠㡮3ģR: jj,pk/K!t,=ϯZ6(((((((49 xn_kLk&f9sK`zx{{y8H 8b4>ÇНE|7v(z/]k7IxM}8!ycZRQ pKVr(RPEr?^}'ðh{x+ՀLW154cK@Ng C)rr9+c:׹b Жf*s^ fKS7^} *{zq_@8# pF~ [VPe(nw0MW=3#kȵz晨cy PpG#W:%drMh]3HH<\]ԁ|_W HHҡb}P>k {ZErxMX@8C&qskLۙOnO^sCk7ql2XCw5VG.S~H8=(s1~cV5z %v|U2QF=NoW]ո?<`~׮}=ӬfԵ,=;"~Iy7K#g{ñJ?5$y` zz@-~m7mG宝Gٱ>G&K#]؃y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6Sgp~;4֌W+חc"=|ř9bc5> *rg {~cj1rnI#G|8v4wĿhFb><^ pJLm[Dl1;Vx5IZ:1*p)إ1ZbAK(1ׅ|S&5{^ KG^5r>;X׻K^? s fk^8O/"J)3K]N)iL?5!ƾq:G_=X- i,vi2N3 |03Qas ! 7}kZU781M,->e;@Qz T(GK(ah(((((((Y[×j2F}o־oYYq $+]%$ v^rϭ`nax,ZEuWSܽ,g%~"MrsrY~Ҿ"Fت;8{ѰxYEfP^;WPwqbB:c?zp<7;SBfZ)dϛ; 7s^>}⍱x?Bix^#hf,*P9S{w[]GF?1Z_nG~]kk)9Sc5Ո<<6J-ϛ}xUi>ux#ţc'{ᛲq?Oo?x&mѱ'#^t)ϲbb0 F«kIVmVsv@}kҡ!ˍUTtxO̧]ORb|2yԵk܊{sPIc_?ħ:Ig)=Z~' "\M2VSSMyLsl⺿U~"C7\hz_ Rs$~? TAi<lO*>U}+'f>7_K N s8g1^CeКÿE ;{+Y\ O5|Y{/o+ LVcO;7Zx-Ek&dpzbӱ+TaB0gNy׭ 3^c T\$⫫?F33?t._Q~Nln:U/Ceb1-im WʸQM+VpafR3d׫é|Aү-q*I P7:y&]hX^Fbtpܩ?|Wu󭏤ʫxJ3ߴm"(uqA}j.+?S wV ~ [B&<^U?rϜ_OH\'.;|.%pw/ZZG'1j(#0UT` Wzw}>_*9m>󑓀F?EL3"zpubzΕ$+0܉&3zڶ+jyr1QE ( ( ( ( ( ( ( (UIdC0EZm+]Y6^![ ԯsmܶ捆?+me+ZE29)B[;я*wGxsK7;5w)}gH~.Ɣx?X\ߚ}A@tQ(:ͧ|Iq(CT?v[sKG+*רqҍck <#Ljα5݈`8cXP6T5i.K!xX*p&ќZǓϘ7 *oƽ:wlຈ:Q5yIEA/2*2jAҐe}k%K$N9R2?7ýKMV!{W9\PA+c4w` Wx=Ze\X{}yXI Ү!aOÎ{]Qx)#D@9E:*NJ}b|Z>_k7:d$z >&Vv󃏽WlR:RqJfGإd9Tm(ҝEtO}1O[xxEYt8,3v bFF )ǙrPNE8=O#V*Cc𹾾&l&cmCh<.P{ʦ&ۣY+Gxs~k5$> ӥPquŽўZt~Tl>Q.g> %k#ú:Kn'&{[yWQGqF}AЅ׮/}<;VYZa$wQg!$;_ $NKS}“_{MY|w7G!"\JtRy+贾d|o/;5jz_6fHwk<ѰJ#]kAȎ J =YNu%dxRwwbEQEQEQEQEQEQEQEQEQE'fLQZ(1F)hQ@X1KEQE-Q@ 1KE3h=iPb(((1GjZ(-ʹRPbR@ 1KE7`bڒyS0(-&)P+ ڎԴP11F)h&:LRmQ@Q@Š(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((_ğ<+F; sU%ԑ >,BH(uSU xþ1Wϲs${wgoQn_swB/'L\ܓFgԏZ ^dj^L^NmH Ҁ6(?nƓjh%ةlΣ /F6}pj2E3HgHЌ(UQR8oX,G8OB]>o9@$xWy'ڹOM=ҼWb"٠9-*r⬻zWokeh͝(F@n~X=q+⟇1b>ƑeIX.~C,o5የ-m;D Nʬ` `+CcE??Ki!R!cxw[ jvc}&Eٱ7T)8&þ/?os$wSn^bo:-4^js4JKm!#rv89>' O59t , \8r,Vk|IgxEv((RmĜ+bkz6,u/}-|.'<VÚ~tk,^cH61¢ !;M;Ėz[#CuAƶ+j_&*/;Q8d ǹHyAsM↷7l-6rò,%Fs;A*',}'f[]tݷs~UWhk?:4JE]WpcY=" ƚw/|_xSw(kycH#r28,X7D5Kh76 mɍ~0H;6194WpGӧգ%8Z&GdPƧo6kcO5Kv`{}fyq \`@?Kv=26OޝyAe Qɼ芍H8͟2敮j#;iѻm؏6+wTx;KYY\-%'Aӣ?|=\-ٴk+٬$ɷ$MқUR@FԐ+T(^ NMz5K &ӡӢ -#`#ZM V rI aa(rH:qEq" m6X_n\[\!20Nx#=mOxsJ`Ӵ^;wvDm .wnEwYe?ۿ<ͣ/wg1\=SX4S!#nD6kC狮ihROJؠ((((((((((((((((?Q?/?zFsc޻ (+𝏏My5̊dAp7]5k,jH٣i%#d #sî+(+džuˏXrxOMnʏme,R> aXj 8#+bޫ?:Ǚ`ƻsym22H|ѼoO88L2_r^_ik7<4\X2Hy}S<)}u9H9 un^xJ[NIy7"u2G+#k;{k9wyyv<'*q"5 խn\y~d!SrrF8밢.Y? un,290ɷd### qTKi5ZKtt^5fػaTjʯ5嵜pGuu(h3xJMgmt}~=} w:e\Zۛk'T+Ag6e;%H xd7Q@om?RY>~%Oo,(1$haԊԼ|oX0}W2rwyW6?Žnq^Ey>=f|{c͹8-r06`(čWuHS0M&ps ŷu\ՏƗ~+tM+ĐĉyI}ԅeuJx~TԳ>^峖k9o3Ѡ 'vrJ`pk(/Ѯ~#CNO'l1  h$0}n𧉴{oD=\ǜNmݎNHށUo;8,.໵;&A"6  88 €/$v@1#cx]l$iI*׌&dDBϷ}@)5ox7f/GV&+f+Pȣ7|յ}"6O 28#'aGF;K/[_Yyy "`6Vmy5/T ^7Ϋxppx+: }?۾yOqN.ķ;'S:[lMg0zco_u=+ ]N W&>:-N{X|' r }*|.][X@x>@x.Fw?t)KtH#L7o0bc tn6j^+O@T;rzc"K3 5ᵊ#.wTdz_[_ZEM #r58<:W%xAd݊gPtKx8 r8R-+5[]Hy^JKddTx{O%ԒUմEu1TuA{/3ƓIaaiC;~D0O~ C\xRm {IE:;29;W;EHZv2&٘|9+6rV7iKݪ 2-uH*;TD(Ʒj\%UR9QYTXVq :Ů,38E00951&.kι8ij]HFl# s`[/m=:?2'dF`C FA=(}nvgj<п`S$qWQw':w-4,*v`s#ij>,M;#>U. |`Z֥Ki-k'k(U\oӂmaa}Ú_hT(\ )?_ iW qF) Wq+c8iKakZwzmLwu' V[T}HF ?֗B)gUkC0-a@о]YcM[U]J(tqK-_"{ -pHz'_W#~<۹wkfc|H^xZ3JOp;sO$Cᛋ.M_iC Fe.;"lx7Dԯ5HEx9#APm_y7~%I?.4rfmGLd8{߈|Ej2YEFXf[}Vd~ KM'Wª\"p"I; A, |L$qr36X37Ls:~ΞHy4A+Yi[ N8Y<w7/bL i3!bNyfp1^_<_INM2.>ol/#ۺ3һhz_xHt #s,rN94_Hյ#gtIHUGyPzQލǚ(& M-JGq Ӯ27ͅ]݌dVCGſ?ME,њW*BUSn3ksnO B,)} gWH6m*g܂ /*AFlEhֻHa@q p `GtV_|G7Y ynI6#MéVʞ +R ( ( ( ( ( ( ( ( ( ( ( ( ( (8}{_徆{YlzM5d`@3zp1YtO׾ OiiBKi< o l P *ƉC|̄P+Cм)fmt=2 ($r͍'<_G&"k__}c[M{ClKC9?QnIKF).s^_[Svj㴈!|99w'xJ 熯 ?ڶ>Lo]vzr2υ]6?/b-F 𤃁\~m9<3꺔z ͆p%n Mg!1ki^ƿp!q\^H =&vy]8#g$Cv=@oo@kd7{S3>_w㮳~#\~#/{M$ghLL*vN(]g|+xZd.xA;\a;FpFqS׀|/ 4-&;Y@Hdyh9.ā39V6 4٠dr4q;HуOq뚧s>(o,iz Z~Y`Gly?.@ z&itˋ{>Xē'Y'O|c_?eH9ڽ}(&Ѿk^TKQi#1&f:)Q|ɮoWA d_۾}?#}1?.}ON̵7#OJ74 cH[alFIF9@.>}_7͍-swl׃(PSCoۛ=q}zSXT(JPw㌎pHMI^U4H'fFxd 7g@=Ëk\ҭ/ }e[8@>]#~1;_ui-?.lf Tq L\w?]xGF |'s3~qoӊ^.'дgI!mpHz ܆$R@^-+G+ZXzMgU{. ZK<eaTp!z'6sayku2n#r0!G# ܩuki."W| i՝A'9?R_?^ۏ9[ÿ va^}fh|ŒeX/\ Ƹ|ah ߖ/&<:irDj!ۤ!py#;%'w9Y㮃D[kjN{7yrg۹J<9_0 {M r쌄2px D˧n/:AYXweyE8:P>o-uNg%LJdq <8'bu|n0xmm常8` $Q@$ K ;q+񦓪k-dżs@]{ʀJ 1 4)"rWRL짞H *[XYЛڊQX((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((PK2cbPK].FOEBPS/dcommon/oracle.gifJGIF87aiyDT2F'G;Q_oKTC[ 3-Bq{ttsoGc4I)GvmLZ).1)!ꑈ53=Z]'yuLG*)g^!8C?-6(29K"Ĩ0Яl;U+K9^u2,@@ (\Ȱ Ë $P`lj 8x I$4H *(@͉0dа8tA  DсSP v"TUH PhP"Y1bxDǕ̧_=$I /& .)+ 60D)bB~=0#'& *D+l1MG CL1&+D`.1qVG ( "D2QL,p.;u. |r$p+5qBNl<TzB"\9e0u )@D,¹ 2@C~KU 'L6a9 /;<`P!D#Tal6XTYhn[p]݅ 7}B a&AƮe{EɲƮiEp#G}D#xTIzGFǂEc^q}) Y# (tۮNeGL*@/%UB:&k0{ &SdDnBQ^("@q #` @1B4i@ aNȅ@[\B >e007V[N(vpyFe Gb/&|aHZj@""~ӎ)t ? $ EQ.սJ$C,l]A `8A o B C?8cyA @Nz|`:`~7-G|yQ AqA6OzPbZ`>~#8=./edGA2nrBYR@ W h'j4p'!k 00 MT RNF6̙ m` (7%ꑀ;PKl-OJPK].FOEBPS/dcommon/blafdoc.cssc@charset "utf-8"; /* Copyright 2002, 2011, Oracle and/or its affiliates. All rights reserved. Author: Robert Crews Version: 2011.10.7 */ body { font-family: Tahoma, sans-serif; /* line-height: 125%; */ color: black; background-color: white; font-size: small; } * html body { /* http://www.info.com.ph/~etan/w3pantheon/style/modifiedsbmh.html */ font-size: x-small; /* for IE5.x/win */ f\ont-size: small; /* for other IE versions */ } h1 { font-size: 165%; font-weight: bold; border-bottom: 1px solid #ddd; width: 100%; text-align: left; } h2 { font-size: 152%; font-weight: bold; text-align: left; } h3 { font-size: 139%; font-weight: bold; text-align: left; } h4 { font-size: 126%; font-weight: bold; text-align: left; } h5 { font-size: 113%; font-weight: bold; display: inline; text-align: left; } h6 { font-size: 100%; font-weight: bold; font-style: italic; display: inline; text-align: left; } a:link { color: #039; background: inherit; } a:visited { color: #72007C; background: inherit; } a:hover { text-decoration: underline; } a img, img[usemap] { border-style: none; } code, pre, samp, tt { font-family: monospace; font-size: 110%; } caption { text-align: center; font-weight: bold; width: auto; } dt { font-weight: bold; } table { font-size: small; /* for ICEBrowser */ } td { vertical-align: top; } th { font-weight: bold; text-align: left; vertical-align: bottom; } ol ol { list-style-type: lower-alpha; } ol ol ol { list-style-type: lower-roman; } li { text-align: left; } dd { text-align: left; } td p:first-child, td pre:first-child { margin-top: 0px; margin-bottom: 0px; } table.table-border { border-collapse: collapse; border-top: 1px solid #ccc; border-left: 1px solid #ccc; } table.table-border th { padding: 0.5ex 0.25em; color: black; background-color: #f7f7ea; border-right: 1px solid #ccc; border-bottom: 1px solid #ccc; } table.table-border td { padding: 0.5ex 0.25em; border-right: 1px solid #ccc; border-bottom: 1px solid #ccc; } span.gui-object, span.gui-object-action { font-weight: bold; } span.gui-object-title { } p.horizontal-rule { width: 100%; border: solid #cc9; border-width: 0px 0px 1px 0px; margin-bottom: 4ex; } div.zz-skip-header { display: none; } td.zz-nav-header-cell { text-align: left; font-size: 95%; width: 99%; color: black; background: inherit; font-weight: normal; vertical-align: top; margin-top: 0ex; padding-top: 0ex; } a.zz-nav-header-link { font-size: 95%; } td.zz-nav-button-cell { white-space: nowrap; text-align: center; width: 1%; vertical-align: top; padding-left: 4px; padding-right: 4px; margin-top: 0ex; padding-top: 0ex; } a.zz-nav-button-link { font-size: 90%; } div.zz-nav-footer-menu { width: 100%; text-align: center; margin-top: 2ex; margin-bottom: 4ex; } p.zz-legal-notice, a.zz-legal-notice-link { font-size: 85%; /* display: none; */ /* Uncomment to hide legal notice */ } /*************************************/ /* Begin DARB Formats */ /*************************************/ .bold, .codeinlinebold, .syntaxinlinebold, .term, .glossterm, .seghead, .glossaryterm, .keyword, .msg, .msgexplankw, .msgactionkw, .notep1, .xreftitlebold { font-weight: bold; } .italic, .codeinlineitalic, .syntaxinlineitalic, .variable, .xreftitleitalic { font-style: italic; } .bolditalic, .codeinlineboldital, .syntaxinlineboldital, .titleinfigure, .titleinexample, .titleintable, .titleinequation, .xreftitleboldital { font-weight: bold; font-style: italic; } .itemizedlisttitle, .orderedlisttitle, .segmentedlisttitle, .variablelisttitle { font-weight: bold; } .bridgehead, .titleinrefsubsect3 { font-weight: bold; } .titleinrefsubsect { font-size: 126%; font-weight: bold; } .titleinrefsubsect2 { font-size: 113%; font-weight: bold; } .subhead1 { display: block; font-size: 139%; font-weight: bold; } .subhead2 { display: block; font-weight: bold; } .subhead3 { font-weight: bold; } .underline { text-decoration: underline; } .superscript { vertical-align: super; } .subscript { vertical-align: sub; } .listofeft { border: none; } .betadraft, .alphabetanotice, .revenuerecognitionnotice { color: #e00; background: inherit; } .betadraftsubtitle { text-align: center; font-weight: bold; color: #e00; background: inherit; } .comment { color: #080; background: inherit; font-weight: bold; } .copyrightlogo { text-align: center; font-size: 85%; } .tocsubheader { list-style-type: none; } table.icons td { padding-left: 6px; padding-right: 6px; } .l1ix dd, dd dl.l2ix, dd dl.l3ix { margin-top: 0ex; margin-bottom: 0ex; } div.infoboxnote, div.infoboxnotewarn, div.infoboxnotealso { margin-top: 4ex; margin-right: 10%; margin-left: 10%; margin-bottom: 4ex; padding: 0.25em; border-top: 1pt solid gray; border-bottom: 1pt solid gray; } p.notep1 { margin-top: 0px; margin-bottom: 0px; } .tahiti-highlight-example { background: #ff9; text-decoration: inherit; } .tahiti-highlight-search { background: #9cf; text-decoration: inherit; } .tahiti-sidebar-heading { font-size: 110%; margin-bottom: 0px; padding-bottom: 0px; } /*************************************/ /* End DARB Formats */ /*************************************/ @media all { /* * * { line-height: 120%; } */ dd { margin-bottom: 2ex; } dl:first-child { margin-top: 2ex; } } @media print { body { font-size: 11pt; padding: 0px !important; } a:link, a:visited { color: black; background: inherit; } code, pre, samp, tt { font-size: 10pt; } #nav, #search_this_book, #comment_form, #comment_announcement, #flipNav, .noprint { display: none !important; } body#left-nav-present { overflow: visible !important; } } PKT' hcPK].F OEBPS/loe.htm 2 List of Examples PKGy0 PK].FOEBPS/audintro.htm Introduction to Oracle Fusion Middleware Audit Service

13 Introduction to Oracle Fusion Middleware Audit Service

This chapter introduces the Audit Service in Oracle Fusion Middleware.

In Oracle Fusion Middleware, auditing provides a measure of accountability and answers the "who has done what and when" types of questions. This chapter contains the following topics:

13.1 Benefits and Features of the Oracle Fusion Middleware Audit Framework

This section contains these topics:

13.1.1 Objectives of Auditing

With compliance becoming an integral part of any business requirement, audit support is also becoming a focus in enterprise deployments. Customers are looking for application vendors to provide out-of-the-box audit support. In addition, middleware customers who are deploying custom applications would like to centralize the auditing of their deployed applications wherever audit is appropriate.

IT organizations are looking for several key audit features driven by compliance, monitoring, and analytics requirements.

Compliance

Compliance is obviously a major requirement in the enterprise. With regulations such as Sarbanes-Oxley (financial) and Health Insurance Portability and Accountability Act (healthcare), many customers must now be able to audit on identity information and user access on applications and devices. These include events like:

  • User profile change

  • Access rights changes

  • User access activity

  • Operational activities like starting and stopping applications, upgrades, and backups

This allows compliance officers to perform periodic reviews of compliance policies.

Monitoring

The audit data naturally provides a rich set of data for monitoring purpose. In addition to any log data and component metrics that are exposed, audit data can be used to create dashboards and to build Key Performance Indicators (KPIs) for alerts to monitor the health of the various systems on an ongoing basis.

Analytics

Audit data can also be used in assessing the efficacy of controls through analysis on the audit data. The data can also be used for risk analysis. Based on historical data, a risk score can be calculated and assigned to any user. Any runtime evaluation of user access can include the various risk scores as additional criteria to protect access to the systems.

13.1.2 Today's Audit Challenges

To satisfy the audit requirements, IT organizations often battle with the deficiencies in audit support for their deployed applications. There is no reliable standard for:

  • Audit Record Generation

  • Audit Record Format and Storage

  • Audit Policy Definition

As a result, today's audit solutions suffer from a number of key drawbacks:

  • There is no centralized audit framework.

  • The quality of audit support is inconsistent from application to application.

  • Audit data is scattered across the enterprise.

  • Complex data correlation is required before any meaningful cross-component analysis can be conducted.

  • Audit policies and their configurations are also scattered.

These factors are costing IT organization considerable amount of time and resources to build and maintain any reasonable audit solutions. With the data scattered among individual silos, and the lack of consistency and centralization, the audit solutions also tend to be fragile with idiosyncrasies among applications from different vendors with their current audit capabilities.

13.1.3 About the Oracle Fusion Middleware Audit Framework

Oracle Fusion Middleware Audit Framework is designed to provide a centralized audit framework for the middleware family of products. The framework provides an audit service for the following:

  • Middleware Platform - This includes Java components such as Oracle Platform Security Services (OPSS) and Oracle Web Services. These components are leveraged by applications deployed on the middleware. Indirectly, all the deployed applications leveraging these Java components benefit from the auditing events that happen at the platform level.

  • Java EE applications - The objective is to provide a service for Java EE applications, including Oracle's own Java EE-based components. Java EE applications are able to create application-specific audit events.

  • System Components - For system components like Oracle HTTP Server, the audit service also provides an end-to-end structure similar to that for Java components, including an audit API for C/C++ based applications.


See Also:

Understanding Key Oracle Fusion Middleware Concepts in the Administering Oracle Fusion Middleware.

13.2 Overview of Audit Features

Key features of the Oracle Fusion Middleware Audit Framework and audit service include:

  • A uniform system for administering audits across a range of Java components, system components, and applications

  • Extensive support for Java component auditing, which includes:

    • support for Oracle Platform Security Services auditing for non-audit-aware applications

    • the ability to search for audit data at any application level

  • Capturing authentication history/failures, authorization history, user management, and other common transaction data

  • Flexible audit policies

    • pre-seeded audit policies, capturing customers' most common audit events, are available for ease of configuration

    • tree-like policy structure simplifies policy setup

  • Prebuilt compliance reporting features

    • Oracle Fusion Middleware Audit Framework provides out-of-the-box analytical reporting capabilities within Oracle BI Publisher; data can be analyzed on multiple dimensions (Execution Context ID (ECID), user ID, and so on) across multiple components. These reports can also be customized according to your preferences.

    • Reports are based on centralized audit data.

    • Customers can customize the reports or write their own based on the published audit schema.

      See Chapter 15, "Using Audit Analysis and Reporting" for details.

  • Audit record storage

    Audit data store (database) and files (bus-stop) are available. Maintaining a common location for all audit records simplifies maintenance.

    Using an audit data store lets you generate reports with Oracle Business Intelligence Publisher.

  • Common audit record format

    Highlights of the audit trail include:

    • baseline attributes like outcome (status), event date-time, user, and so on

    • event-specific attributes like authentication method, source IP address, target user, resource, and so on

    • contextual attributes like the execution context ID (ECID), session ID, and others

  • Common mechanism for audit policy configuration

    Oracle Fusion Middleware Audit Framework offers a unified method for configuring audit policies in the domain.

  • Leverages the Oracle Fusion Middleware infrastructure

    • is usable across Oracle Fusion Middleware components and services

    • integrates with Oracle Enterprise Manager Fusion Middleware Control for UI-based configuration and management

    • integrates with wlst for command-line, script-based configuration

    • leverages the SPI infrastructure of Oracle Platform Security Services

  • Utilizes a dynamic metadata model to enable applications to integrate with the audit framework:

    • applications can register with the audit service at any time

    • simplifies the ability of applications to leverage the audit framework to define and log audit events

    • provides versioning of event definitions and enables audit clients to upgrade definitions independent of release cycles.

13.3 Oracle Fusion Middleware Audit Framework Concepts

This section introduces basic concepts of the Oracle Fusion Middleware Audit Framework:

13.3.1 The Audit Architecture

Figure 13-1 shows the architecture of the Oracle Fusion Middleware Audit Framework:

Figure 13-1 Audit Architecture

Surrounding text describes Figure 13-1 .

The figure illustrates essential elements of the architecture, including development and run-time services, the audit event flow, and key features, which are described below.

13.3.1.1 The Audit Service Model

At the heart of the framework is the audit service model, which like other OPSS services, provides a standards-based, integrated framework for Java EE and SE applications and Oracle components alike.

Used across Oracle Fusion Middleware, this model enables you to conveniently leverage the platform's audit features, and includes:

  • A dynamic audit metadata model that allows audit clients to manage audit event definitions and make version changes independent of build and release cycles. Audit event definitions can be dynamically updated at redeployment.

  • Support for all aspects of the application lifecycle from design to development to deployment.

  • A registration service to register your applications to the audit service

    • declaratively; Java EE applications do so by packaging an XML configuration in ear files in the META-INF directory at deployment

    • programatically, by invoking the audit registration API

    • at the command line, through WLST commands

    • through bundling of security artifacts in a product template (see Section 7.1).

13.3.1.2 Audit APIs

These APIs are provided by the audit framework for any audit-aware components integrating with the Oracle Fusion Middleware Audit Framework. During runtime, applications may call these APIs where appropriate to manage audit policies and to audit the necessary information about a particular event happening in the application code. The interface allows applications to specify event details such as username and other attributes needed to provide the context of the event being audited.

The audit framework provides these APIs:

  • audit service API

  • audit client API

  • audit administration service API

See Chapter 25 for details.

13.3.1.3 Run-time Support and Audit Event Flow

The process can be illustrated by looking at the actions taken in the framework when an auditable event (say, login) occurs within an application server instance:


Note:

The architecture shown in Figure 13-1 contains an audit data store; if your site did not configure an audit data store, the audit records reside in the bus-stop files.

  1. During application deployment or audit service start-up, a client such as a Java EE application or Oracle component registers with the audit service.

  2. The service reads the application's pre-configured audit definition file and updates the metadata store with the audit definitions.

  3. When a user accesses the component or application, an audit API function is called to audit the event.

  4. The audit framework checks if events of this type, status, and with certain attributes need to be audited.

  5. If so, the audit function is invoked to create the audit event structure and collect event information like the status, initiator, resource, ECID, and so on.

  6. The event is stored on a local file in an intermediate location known as the bus-stop; each component has its own bus-stop.

  7. If a database is configured for an audit store, the audit loader pulls the events from the bus-stops, uses the application's metadata to format the data, and moves the data to the audit store.

  8. Reports can also be generated from the audit data using Oracle BI Publisher. A set of pre-defined reports are available. (See Chapter 15, "Using Audit Analysis and Reporting".)

Application Behavior in Case of Audit Failure

It is important to note that an application does not stop execution if it is unable to record an audit event for any reason.

13.3.2 Key Technical Concepts

This section introduces key concepts in the Oracle Fusion Middleware Audit Framework.

Audit-Aware Components

The term "audit-aware" refers to components that are integrated with the Oracle Fusion Middleware Audit Framework so that audit policies can be configured and events can be audited for those components. Oracle Internet Directory is an example of an audit-aware component.

Stand-alone applications can integrate with the Oracle Fusion Middleware Audit Framework through configuration with the jps-config.xml file. For details, see <serviceInstances> in Appendix A.

Audit Metadata Store

The audit metadata store contains audit event definitions for components and for applications integrated with the audit framework.

For details, see Section 13.3.3.

Audit Data Store

The audit data store is the repository of audit event records. It is a database that contains a pre-defined Oracle Fusion Middleware Audit Framework schema, created by Repository Creation Utility (RCU). Once the audit data store is configured, the audit loader is aware of the store and uploads data to it periodically. The audit data in the store is expected to be cumulative and will grow overtime. Ideally, this should not be an operational database used by any other applications - rather, it should be a standalone database used for audit purposes only.

The audit database can store audit events generated by Oracle components as well as user applications integrated with the audit framework.


Note:

The audit metadata store is separate from the audit data store.

For details about the data store, see Section 13.3.4. For details about using RCU to create the audit schema, see Section 14.2.1.

Audit Definition Files

Applications use audit definition files to specify to the audit service the auditing rules (events, filters, and so on) that will govern audit actions.

For details, see Section 13.5.

Audit Events

The Oracle Fusion Middleware Audit Framework provides a set of generic events for convenient mapping to application audit events. Some of these include common events such as authentication. The framework also allows applications to define application-specific events.

These event definitions and configurations are implemented as part of the audit service in Oracle Platform Security Services. Configurations can be updated through Enterprise Manager (UI) and WLST (command-line tool)

Audit Loader

The Audit Loader is a module of the Oracle WebLogic Server instance and supports audit activity in that instance. When an audit data store is configured, audit loader is responsible for collecting the audit records for all components running in that instance and loading them to the data store.

For Java components, the audit loader is started as part of the container start-up.

System components can either register to the audit store (using the registerAudit() WLST command) to upload their events through the container audit loader, or use the command-line stand-alone audit loader.

Audit Policy

An audit policy is a declaration of the type of events to be captured by the audit framework for a particular component. For Java components, the audit policy can be defined at either the component level or the domain level. For system components, the audit policy is managed at the component instance level.

Oracle Fusion Middleware Audit Framework provides several pre-defined policy types:

  • None (audit is disabled for the component)

  • Low (definition is component-dependent)

  • Medium (definition is component-dependent)

  • High (definition is component-dependent)

  • Custom (implements filters to narrow the scope of audited events)

Audit Policy Component Type

This refers to the component type to be audited; for example, Oracle Internet Directory is a source of auditable events during authentication.

For lists of the events that can be audited for each component, see Section C.1, "Audit Events".

Audit Service

The audit service model provides a standards-based, integrated framework for Java EE and SE applications to leverage audit features.

Bus-stop

Bus-stops are local files containing audit data records before they are pushed to the audit data store. In the event that no audit data store is configured, audit data remains in these bus-stop files. The bus-stop files are simple text files that can be queried easily to look up specific audit events. When an audit data store is in place, the bus-stop acts as an intermediary between the component and the audit data store. The local files are periodically uploaded to the audit data store based on a configurable time interval.

A key advantage of the audit data store is that audit data from multiple components can be correlated and combined in reports, for example, authentication failures in all middleware components, instances and so on.

Event Filters

Certain audit events implement filters to control when the event is logged. For example, a successful login event for the Oracle Internet Directory component may be filtered for specific users.

For details, see Section 14.3, "Managing Audit Policies".

Configuration MBeans

All audit configuration is managed through audit configuration MBeans. For Java components and applications, these MBeans are present in the domain administration server and the audit configuration is centrally managed. For system components, separate MBean instances are present for every component instance. Enterprise Manager UI and command-line tools manage Audit configuration using these MBeans.

Oracle Business Intelligence Publisher

The data in the audit data store is exposed through pre-defined reports available for certain components (primarily system components) in Oracle Business Intelligence Publisher. The reports allow users to drill down the audit data based on various criteria. For example:

  • Username

  • Time Range

  • Application Type

  • Execution Context Identifier (ECID)

You can also use Oracle Business Intelligence Publisher to create your own audit reports.

Oracle Platform Security Services

Oracle Platform Security Services, a key component of Oracle Fusion Middleware, is the Oracle Fusion Middleware security implementation for Java features such as Java Authentication and Authorization Service (JAAS) and Java EE security.

For more information about OPSS, see Section 1.1, "What is Oracle Platform Security Services?".

13.3.3 The Audit Metadata Store

The audit metadata store provides the repository for the metadata model and contains component audit definitions, NLS translation entries, runtime policies, and database mapping tables.


Note:

The audit metadata store is separate from the audit data store which contains the actual audit records.

The audit metadata store supports several critical auditing functions:

  • The audit registration service creates, modifies, and deletes event definition entries.

  • The audit runtime service retrieves event definitions and runtime policies.

  • The audit data loader creates attribute database mappings to store audit data.

  • Audit MBean commands look up and modify component audit definitions and runtime policies.

The audit framework supports database metadata store.

When a new application registers to the audit service, the following audit artifacts are stored in the audit store:

  • audit event definitions including custom attribute group, categories, events, and filter preset definitions

  • localized translation entries

  • custom attribute-database column mapping table

  • run-time audit policies

13.3.4 Audit Data Storage

As shown in Figure 13-1, audit data can reside in two types of storage:

  • bus-stop files for intermediate storage of audit data. Each component instance writes to its own bus-stop.

    Bus-stop files are the default out-of-the-box storage mechanism for audit records. There is a separate bus-stop file for each component.

    Bus-stop files are text-based and easy to query. For further details, see Section 13.3.1, "The Audit Architecture"

  • permanent storage in a database; this is known as the audit data store.

    If using a database, audit records generated by all components in all Oracle Fusion Middleware instances in the domain are written to the same store. You must use an audit data store to utilize Oracle Business Intelligence Publisher reports.

You can move from file-based storage to an audit data store. This requires a specific configuration procedure. See Section 14.2.3, "Configure a Database Audit Data Store for Java Components" for details.

Advantages of Using a Database Store

Having the audit records in the bus-stop files has some practical limitations:

  • you cannot view domain-level audit data

  • reports cannot be run on Oracle BI Publisher

Thus, there are certain advantages to using a database audit data store:

  • You can use Oracle Business Intelligence Publisher for reporting.

  • The database store centralizes records from all components in the domain, whereas the bus-stop stores audit records on a per-instance basis.

  • performance may be improved compared to file-based storage

For these reasons, Oracle recommends that customers switch to a database store for enhanced auditing capabilities.

13.3.5 Analytics

With Oracle Fusion Middleware, you can utilize Oracle Business Intelligence Publisher as a full-featured tool for structured reporting. You can also use your own reporting application.

A large number of pre-defined reports are available in Oracle Business Intelligence Publisher, such as:

  • Users created/deleted

  • User transactions

  • Authentication and authorization failures

  • Policy violations

With Oracle Business Intelligence:

  • You can select records based on criteria like username, date-time range, and so on.

    Note that Oracle Business Intelligence works with the database audit store only, and is not usable with bus-stop files.

Description of cafintro1.gif follows

The pre-defined audit report types available with Oracle Business Intelligence include:

  • errors and exceptions

  • operational

  • user activity

  • authentication and authorization history

  • transaction history

For further details, see Section C.2, "Pre-built Audit Reports." You can also use the audit schema details to create custom audit reports as needed.

13.3.6 Understanding the Audit Lifecycle

From the standpoint of an administrator auditing into an environment consisting of Oracle Fusion Middleware components and applications, the key phases of implementing a functional audit system are as follows:

  • Understand the architecture of the Common Audit Framework.

    For a review of the essential elements of the framework, the flow of actions, and the features of the audit service model, see Section 13.3.1.

  • Integrate applications with the audit framework.

    For details about integration steps, see Section 25.2.

  • Create the audit definition files that describe your application's audit events and how they map to the audit schema.

    For details on this topic, see Section 25.3.

  • Register the application with the audit service.

    There are various ways to enable registration. For details, see Section 25.4.

  • Migrate audit information from test to production.

    See Section 6.6.3.

  • Generate audit reports.

    Descriptions of the tools and techniques of audit reporting appear in Chapter 15 and Appendix C.

13.4 The Audit Metadata Model

The audit framework supports a metadata model which enables applications to specify their audit artifacts in a flexible manner. Applications can dynamically define attribute groups, categories, and events.

Topics include:

13.4.1 Naming Conventions for Audit Artifacts

The following naming restrictions apply to category, event and attribute names:

  • They must be in English only

  • They must be less than 26 characters

  • They can contain only the characters a through z, A through Z, and numbers 0 through 9

  • They must start with a letter.

13.4.2 Attribute Groups

Attribute groups provide broad classification of audit attributes and consist of three types:

  • The common attribute group contains all the system attributes common to all applications, such as component type, system IP address, hostname, and others.

    The IAU_COMMON database table contains attributes in this group.

  • Generic attribute groups contain attributes for audit application areas such as authentication and user provisioning.

  • Custom attribute groups are those defined by an application to meet its specific needs. Attributes in a custom group are limited to that component scope.


See Also:

Table C-5 for a list of common OPSS attributes.

13.4.2.1 Audit Attribute Data Types

Table 13-1 shows the supported attribute data types and the corresponding Java object types:

Table 13-1 Audit Attribute Data Types

Attribute Data TypeJava Object TypeNotes

Integer

Integer


Long

Long


Float

Float


Double

Double


Boolean

Boolean


DateTime

java.util.Date


String

String

Maximum length 2048 bytes

LongString

String

Unlimited length

Binary

byte[]



13.4.2.2 Common Attribute Groups

The common attribute group is stored in the IAU_COMMON database table.

13.4.2.3 Generic Attribute Groups

A generic attribute group is defined with a namespace, a version number, and one or more attributes. This example defines an attribute group with namespace authorization and version 1.0:

<AuditConfig xmlns="http://xmlns.oracle.com/ias/audit/audit-2.0.xsd" >
    <Attributes ns="authorization" version="1.0">
        <Attribute displayName="CodeSource" maxLength="2048" name="CodeSource" type="string"/>
        <Attribute displayName="Principals" maxLength="1024" name="Principals" type="string"/>
        <Attribute displayName="InitiatorGUID" maxLength="1024" name="InitiatorGUID" type="string"/>
        <Attribute displayName="Subject" maxLength="1024" name="Subject" type="string">
          <HelpText>Used for subject in authorization</HelpText>
        </Attribute>
    </Attributes>
        ……

Your application can reference the CodeSource attribute like this:

<Attribute name="CodeSource" ns="authorization" version="1.0" />

Each generic attribute group is stored in a dedicated database table. The naming conventions are:

  • IAU_GENERIC_ATTRIBUTE_GROUP_NAME for table names

  • IAU_ATTRIBUTE_NAME for table columns

For example, the attribute group authorization is stored in database table IAU_AUTHORIZATION with these columns:

  • IAU_CODESOURCE as string

  • IAU_PRINCIPALS as string

  • IAU_INITIATORGUID as string

13.4.2.4 Custom Attribute Groups

A custom attribute group is defined with a namespace, a version number, and one or more attributes.

Attributes consist of:

  • attribute name

  • data type

  • attribute-database column mapping order - This property specifies the order in which an attribute is mapped to a database column of a specific data type in the custom attribute table.

  • help text (optional)

  • maximum length

  • display name

  • size - This property denotes how many values of the same data type the attribute can have. The default size value is 1. A size greater than 1 denotes a multi-valued attribute which can have two or more values of the same data type. The multi-value attribute supports all data types except for binary.

This example defines attribute group Accounting with namespace accounting and version 1.0:

<Attributes ns="accounting" version="1.0">
 
            <Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1"/>
            <Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
                <HelpText>Account number.</HelpText>
            </Attribute>
            ……
        </Attributes>

The following example shows a multi-valued attribute named AccountBalance:

<Attribute order="3" displayName="AccountBalance" type="double" name="Balance" size="2" sinceVersion="1.1">
            <MultiValues>
                <MultiValueName displayName="Previous Balance" index="0">
                     <HelpText>the previous account balance</HelpText>
                </MultiValueName>
                <MultiValueName displayName="Current Balance" index="1"/>
            </MultiValues>
</Attribute>

Custom attribute groups and attributes are stored in the IAU_CUSTOM table.

13.4.3 Event Categories and Events

An audit event category contains related events in a functional area. For example, a session category could contain login and logout events that are significant in a user session's lifecycle.

An event category does not itself define attributes. Instead, it references attributes in component and system attribute groups.

There are two types of event categories:

  • System Categories

  • Component and Application Categories


See Also:

Table C-1 for definitions of system categories and events.

13.4.3.1 System Categories and Events

A system category references common and generic attribute groups and contains audit events. System categories are the base set of component event categories and events. Applications can reference them directly, log audit events, and set filter preset definitions.

The following example shows several elements of the metadata model:

  • common attribute group

  • generic attribute groups identity and authorization

  • system category UserSession with an attribute referencing to a common attribute AuthenticationMethod

  • audit events such as UserLogin and UserLogout

<SystemComponent major="1" minor="0">
+<Attributes ns="common" version ="1.0"></Attributes>
+<Attributes ns="identity" version ="1.0"></Attributes>
+<Attributes ns="authorization" version ="1.0"></Attributes>
-<Events>
 -<Category name="UserSession" displayName="User Sessions">
  -<Attributes>
     <Attribute name="AuthenticationMethod" ns="common" version ="1.0" />
   </Attributes>
  -<HelpText></HelpText>
  -<Event name="UserLogin" displayName="User Logins" shortName="uLogin"></Event>
  -<Event name="UserLogout" displayName="User Logouts" shortName="uLogout" 
    xdasName="terminateSession"></Event>
  -<Event name="Authentication" displayName="Authentication"></Event>
  -<Event name="InternalLogin" displayName="Internal Login" shortName="iLogin"
    xdasName="CreateSession"></Event>
  -<Event name="InternalLogout" displayName="Internal Logout" shortName="iLogout"
    xdasName="terminateSession"></Event>
  -<Event name="QuerySession" displayName="Query Session"     shortName="qSession"></Event>
  -<Event name="ModifySession" displayName="Modify Session"     shortName="mSession"></Event>
  </Category>
 +<Category displayName="Authorization" name="Authorization"></Category>
 +<Category displayName="ServiceManagement" name="ServiceManagement"></Category>
 </Events>
</SystemComponent>

13.4.3.2 Component/Application Categories

A component or application can extend system categories or define new component event categories. In this example, a transaction category references attributes AccountNumber, Date, and Amount from the accounting attribute group, and includes events 'purchase' and 'deposit':

 <Category displayName="Transaction" name="Transaction">
    <Attributes>
       <Attribute name="AccountNumber" ns="accounting" version="1.0"/>
       <Attribute name="Date" ns="accounting" version="1.0" />
       <Attribute name="Amount" ns="accounting" version="1.0" />
 </Attributes>
 
    <Event displayName="purchase" name="purchase"/>
    <Event displayName="deposit" name="deposit">
       <HelpText>depositing funds.</HelpText>
    </Event>
……
 </Category>

You extend system categories by creating category references in your application audit definitions. List the system events that the system category includes, and add new attribute references and events to it.

In this example, a new category references a system category ServiceManagement with a new attribute reference ServiceTime, and a new event restartService:

<CategoryRef name="ServiceManagement" componentType="SystemComponent">
                <Attributes>
                    <Attribute name="ServiceTime" ns="accounting" version="1.0" />
                </Attributes>
 
                <EventRef name="startService"/>
                <EventRef name="stopService"/>
 
                <Event displayName="restartService" name="restartService">
                    <HelpText>restart service</HelpText>
                </Event>
                
</CategoryRef>

13.5 About Audit Definition Files

There are two types of definition files:

  • component_events.xml definition file

  • translation files

13.5.1 The component_events.xml File

The component_events.xml file specifies the properties the audit service needs to log audit events, including:

  • basic properties - and the major and minor version

    • the component type, which is the property that applications use to register with the audit service and obtain runtime auditor instances

    • Major and minor version of the application.

  • at most one custom attribute group

  • event categories with attribute references and events

  • component level filter definitions

  • runtime policies, which include:

    • filterPreset - specifies the audit filter level

    • specialUsers - specifies the users to always audit

    • maxBusstopDirSize

    • maxBusstopFileSize

    For details about run-time policies, see Section 14.3.

Here is an example component_events.xml file:

<?xml version="1.0"?>
<AuditConfig xmlns="http://xmlns.oracle.com/ias/audit/audit-2.0.xsd">
    <AuditComponent componentType="ApplicationAudit" major="1" minor="0">
        <Attributes ns="accounting" version="1.0">

            <Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1">
               <HelpText>Transaction type.</HelpText>
           </Attribute>
            <Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
                <HelpText>Account number.</HelpText>
            </Attribute>
            <Attribute name="Date" displayName="Date" type="dateTime" order="3"/>
            <Attribute name="Amount" displayName="Amount" type="float" order="4">
                <HelpText>Transaction amount.</HelpText>
            </Attribute>
            <Attribute name="Status" displayName="Account Status" type="string" order="5">
                <HelpText>Account status.</HelpText>
            </Attribute>
 
        </Attributes>
 
        <Events>
            <Category displayName="Transaction" name="Transaction">
                <Attributes>
                    <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                    <Attribute name="Date" ns="accounting" version="1.0" />
                    <Attribute name="Amount" ns="accounting" version="1.0" />
                </Attributes>
 
                <Event displayName="purchase" name="purchase">
                    <HelpText>direct purchase.</HelpText>
                </Event>
                <Event displayName="deposit" name="deposit">
                    <HelpText>depositing funds.</HelpText>
                </Event>
                <Event displayName="withdrawing" name="withdrawing">
                    <HelpText>withdrawing funds.</HelpText>
                </Event>
                <Event displayName="payment" name="payment">
                    <HelpText>paying bills.</HelpText>
                </Event>
            </Category>
            <Category displayName="Account" name="Account">
                <Attributes>
                    <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                    <Attribute name="Status" ns="accounting" version="1.0" />
                </Attributes>
 
                <Event displayName="open" name="open">
                    <HelpText>Open a new account.</HelpText>
                </Event>
                <Event displayName="close" name="close">
                    <HelpText>Close an account.</HelpText>
                </Event>
                <Event displayName="suspend" name="suspend">
                    <HelpText>Suspend an account.</HelpText>
                </Event>
            </Category>
        </Events>
        <FilterPresetDefinitions>
            <FilterPresetDefinition displayName="Low" helpText="" name="Low">
                <FilterCategory enabled="partial" name="Transaction">deposit.SUCCESSESONLY(HostId -eq &quot;NorthEast&quot;),withdrawing</FilterCategory>
                <FilterCategory enabled="partial" name="Account">open.SUCCESSESONLY,close.FAILURESONLY</FilterCategory>
            </FilterPresetDefinition>
            <FilterPresetDefinition displayName="Medium" helpText="" name="Medium">
                <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing</FilterCategory>
                <FilterCategory enabled="partial" name="Account">open,close</FilterCategory>
            </FilterPresetDefinition>
            <FilterPresetDefinition displayName="High" helpText="" name="High">
                <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing,payment</FilterCategory>
                <FilterCategory enabled="true" name="Account"/>
            </FilterPresetDefinition>
        </FilterPresetDefinitions>
 
        <Policy filterPreset="Low">
            <CustomFilters>
                <FilterCategory enabled="partial" name="Transaction">purchase</FilterCategory>
            </CustomFilters>
 
        </Policy>
 
    </AuditComponent>
</AuditConfig>

13.5.2 Translation Files

Translation files are used to display audit definition in different languages.

13.5.3 Understand Mapping and Versioning Rules

The registration service uses certain rules to create the audit metadata for the application. This metadata is used to maintain different versions of the audit definition, and to load audit data and generate reports.

13.5.3.1 Version Numbers

Each audit definition must have a major and a minor version number, which are integers, for example, major = 1 minor=3. Any change to an audit event definition requires that the version ID be modified by changing the minor and/or major number.

Version numbers are used by the audit registration service to determine the compatibility of event definitions and attribute mappings between versions.


Note:

These version numbers have no relation to Oracle Fusion Middleware version numbers.

Versioning for Oracle Components

When registering an Oracle component, the audit registration service checks if this is a first-time registration or an upgrade.

For a new registration, the service:

  1. retrieves the component audit and translation information.

  2. parses and validates the definition, and stores it in the audit metadata store.

  3. generates the attribute-column mapping table, and saves this in the audit metadata store.

For upgrades, the current major and minor numbers for the component in the metadata store are compared to the new major and minor numbers to determine whether to proceed with the upgrade.

Versioning for JavaEE Applications

When modifying your application's audit definition, it is recommended that you set the major and minor numbers as follows:

  • Only increase the minor version number when making version-compatible changes, meaning changes in an audit definition such that the attribute database mapping table generated from the new audit definition should still work with the audit data created by the previous attribute database mapping table.

    For example, suppose the current definition version is major=2 and minor=1. When adding a new event that does not affect the attribute database mapping table, you can change the minor version to 2 (minor=2), while the major version remains unchanged (major=2).

  • Increase major version number when making version changes where the new mapping table is incompatible with the previous table.

13.5.3.2 Custom Attribute to Database Column Mappings

When registering a new component or application, the registration service creates an attribute-to-database column mapping table from the component's custom attributes, and then saves this table to the audit metadata store.

Attribute-database mapping tables are required to ensure unique mappings between your application's attribute definitions and database columns. The audit loader uses mapping tables to load data into the audit store; the tables are also used to generate audit reports from custom database table IAU_CUSTOM.

Viewing Audit Definitions for your Component

You can use the WLST command createAuditDBView to create a database view of the audit definitions of your component.

For details about command syntax, see Appendix C, "Oracle Fusion Middleware Audit Framework Reference.".

Using the createAuditDBView command requires an understanding of how your component's attributes are mapped to database columns; see the discussion below for details.

Understanding the Mapping Table for your Component

A custom attribute-database column mapping has properties of attribute name, database column name, and data type.

Each custom attribute must have a mapping order number in its definition. Attributes with the same data type are mapped to the database column in the sequence of attribute mapping order. For example, if the definition file looks like this:

<Attributes ns="accounting" version="1.1">
   <Attribute name="TransactionType" type="string" maxLength="0"     displayName="Transaction Type" order="1"/>
   <Attribute name="AccountNumber" type="int" displayName="Account Number"     order="2">
   <Attribute name="Date" type="dateTime" displayName="Date" order="3"/>
   <Attribute name="Amount" type="float" displayName="Amount" order="4"/>
   <Attribute name="Status" type="string" maxLength="0" displayName="Account     Status" order="5"/>
   <Attribute name="Balance" type="float" displayName="Account Balance"     order="6"/>
</Attributes>

then the mapping is as follows:

<AttributesMapping ns="accounting" tableName="IAU_CUSTOM" version="1.1">
   <AttributeColumn attribute="TransactionType" column="IAU_STRING_001"     datatype="string"/>
   <AttributeColumn attribute="AccountNumber" column="IAU_INT_001"     datatype="int"/>
   <AttributeColumn attribute="Date" column="IAU_DATETIME_001"     datatype="dateTime"/>
   <AttributeColumn attribute="Amount" column="IAU_FLOAT_001" datatype="float"/>
   <AttributeColumn attribute="Status" column="IAU_STRING_002" datatype="string"/>
   <AttributeColumn attribute="Balance" column="IAU_FLOAT_002" datatype="float"/>
</AttributesMapping>

The version ID of the attribute-database column mapping table matches the version ID of the custom attribute group. This allows your application to maintain the backward compatibility of attribute mappings across audit definition versions. For more information about versioning, see Section 13.5.3.1.

PKpr$PK].FOEBPS/cfgauthr.htm Configuring the OPSS Security Store

9 Configuring the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, keys, and audit metadata.

This chapter explains the features of the OPSS security store in the following sections:

For details about Java EE and WebLogic Security, see section Java EE and WebLogic Security in Understanding Security for Oracle WebLogic Server.


Note:

When a WebLogic domain is setup to use policies based on the OPSS security store, JACC policies and the Java Security Manager become unavailable on all managed servers in that domain.


Important:

All permission classes used in policies in the OPSS security store must be included in the class path, so the policy provider can load them when a service instance is initialized.

9.1 Introduction to the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, and keys. This centralization facilitates the administration and maintenance of policy, credential, and key data.

The OPSS security store can be file-, LDAP-, or DB-based depending on the choice of repository type, and it can be reassociated (that is, the repository type can be changed) from file-based to LDAP- or DB-based; from DB-based to LDAP- or DB-based; and from LDAP-based to LDAP- or DB-based. No other reassociation is supported. For details about the tools and procedures available to reassociate the OPSS security store, see sections Reassociating with Fusion Middleware Control and Reassociating with the Script reassociateSecurityStore. Out-of-the-box, the OPSS security store is DB-based for production WebLogic domains.

The security artifacts relevant to a Java EE application are typically packaged with the application and they can be migrated at deploy time to the OPSS security store. For details about the tools and procedures available to migrate to the OPSS security store, see sections Migrating with Fusion Middleware Control and Migrating with the Script migrateSecurityStore.

9.1.1 Multi-Server Environments

Production WebLogic domains with several server instances (administration and managed servers) on the same host or distributed across multiple machines, must use an OID- or an Oracle RDBMS-based OPSS security store.


Note:

File-based providers are not supported in production environments.

For details about the properties you can set on policies and credentials, see sections Appendix F, "Policy Store Properties," and Appendix F, "Credential Store Properties."

9.2 Using an LDAP-Based OPSS Security Store

An LDAP-based OPSS security store is typically used in production environments. The only LDAP server supported is the Oracle Internet Directory (release 10.1.4.3 or later).


Note:

Depending on the version, the following patches to Oracle Internet Directory are required:
  • Patch to fix bug 9093298 in Oracle Internet Directory 10.1.4

  • Patch to fix bug 8736355 in Oracle Internet Directory 11.1.x

  • Patch to fix bug 8426457 in Oracle Internet Directory 11.1.x and 10.1.4.3

  • Patch to fix bug 8351672 in Oracle Internet Directory 10.1.4.3

  • Patch to fix bug 8417224 in Oracle Internet Directory 10.1.4.3

  • Patch to fix bug 13782459 in Oracle Internet Directory 11.1.1.6.0

To apply a patch, proceed as follows:

  1. Visit Oracle Automated Release Updates.

  2. Click the Patches tab.

  3. Enter the bug number in the Request Number box, and click Search.

  4. Apply the patch.


To use a domain LDAP-based OPSS security store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or WLST commands.


Important:

OPSS does not support enabling referential integrity on Oracle Internet Directory servers. The server will not work as expected if referential integrity is enabled.

To disable a server's referential integrity, use Oracle Enterprise Manager Fusion Middleware Control as follows:

  1. Select Administration, then Shared Properties from the Oracle Internet Directory menu, and then select General.

  2. Select Disabled from the Enable referential Integrity list.


For a list of properties that can be specified in a service instance, see Appendix F, "Properties Common to All LDAP-Based Instances."

9.2.1 Prerequisites to Using an LDAP-Based Security Store

The only supported LDAP-based OPSS security store is Oracle Internet Directory. In order to ensure the proper access to the Oracle Internet Directory, you must set a node in the server directory as explained below.

Fusion Middleware Control automatically provides bootstrap credentials in the file cwallet.sso when that tool is used to reassociate to an LDAP-based repository. To specify these required credentials manually, see section Section 18.5.7, "Specifying Bootstrap Credentials Manually."

Setting a Node in an Oracle Internet Directory Server

The following procedure is carried out by an Oracle Internet Directory administrator.

To set a node in an LDAP Oracle Internet Directory, proceed as follows:

  1. Create an LDIF file (assumed jpstestnode.ldif, for illustration purpose) specifying the following DN and CN entries:

    dn: cn=jpsroot
    cn: jpsroot
    objectclass: top
    objectclass: OrclContainer
    

    The distinguished name of the root node (illustrated by the string jpsroot above) must be distinct from any other distinguished name. Some LDAP servers enforce case sensitivity by default. One root node can be shared by multiple WebLogic domains. It is not required that this node be created at the top level, as long as read and write access to the subtree is granted to the Oracle Internet Directory administrator.

  2. Import this data into the LDAP server using the command ldapadd, as illustrated in the following example (there should be no line break in the command invocation):

    >ldapadd -h ldap_host -p ldap_port -D cn=orcladmin -w password -v -f  jpstestnode.ldif
    
  3. Verify that the node has been successfully inserted using the command ldapsearch, as illustrated in the following example (there should be no line break in the command invocation):

    >ldapsearch -h ldap_host -p ldap_port -D cn=orcladmin -w password -s base 
    -b "cn=jpsroot" objectclass="orclContainer"
    
  4. Run the utility oidstats.sql to generate database statistics for optimal database performance, as illustrated in the following example:

    >$ORACLE_HOME/ldap/admin/oidstats.sql
    

    The above utility must be run just once after the initial provisioning. For details about this utility, consult the Oracle Fusion Middleware Reference for Oracle Identity Management.

    To reassociate the OPSS security store, see Reassociating the OPSS Security Store.

9.2.2 Setting Up a One- Way SSL Connection to the LDAP

This section describes how to set up a one-way SSL channel between Oracle WebLogic server or a Java SE application and the LDAP Oracle Internet Directory. Such connection may be required, for example, when reassociating to an LDAP-based target store.

Prerequisite: Configuring the Oracle Internet Directory Server

To configure the Oracle Internet Directory server to listen in one-way SSL mode, see section Enabling SSL on Oracle Internet Directory Listeners in Administering Oracle Fusion Middleware.

Exporting Oracle Internet Directory's Certificate Authority (CA)

The use of orapki to create a certificate is needed only if the CA is unknown to the Oracle WebLogic server.

The following sample illustrates the use of this command to create the certificate serverTrust.cert:

>orapki wallet export -wallet CA -dn "CN=myCA" -cert serverTrust.cert

The above invocation prompts the user to enter the keystore password.

Before You Begin

Before configuring SSL, note that:

  • The following procedures are required if the type of SSL being established is server-auth, and they are not required in any other case (no-auth or client-auth).

  • If the flags specified in the procedures below are used in a multi-application environment, then the trust store must be shared by all those applications.

Setting Up the WebLogic Server in Case of a Java EE Application

The difference in the following procedures is because the identity store service and the OPSS security store service use different socket factories.

To establish a one-way SSL connection between the server and the identity store, proceed as follows (if applicable, the trust CA is assumed exported):

  1. If the CA is known to the Oracle WebLogic server, skip this step; otherwise, use the utility keytool to import the Oracle Internet Directory's CA into the WebLogic trust store.

    The following invocation, which outputs the file myKeys.jks, illustrates the use of this command to import the file serverTrust.cert:

    >keytool -import -v -trustcacerts -alias trust -file serverTrust.cert -keystore myKeys.jks -storepass keyStorePassword
    
  2. Modify the script (typically startWebLogic.sh) that starts the server to include a line like the following, and then restart the server:

    -Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>
    

To establish a one-way SSL connection between the server and the OPSS security store, proceed as follows (if applicable, the trust CA is assumed exported):

  1. Use the utility keytool to import trust CA to the trust key store, as illustrated in the following invocation:

    >keytool -import -v -trustcacerts -alias trust -file serverTrust.cert -keystore myKeys.jks -storepass keyStorePassword
    
  2. Modify the script (typically startWebLogic.sh) that starts the server to include a line like the following, and then restart the server:

    -Dweblogic.security.SSL.trustedCAKeyStore=<absolute path name to file myKeys.jks>
    
  3. If the OID server uses a wild card in the SSL certificate, then add the following line to the script that starts the WebLogic server:

    -Dweblogic.security.SSL.ignoreHostnameVerification=true
    

Setting Up the WebLogic Server in Case of a Java SE Application

The setting up in the case of Java SE applications is the identical for both the identity store and the OPSS security store.

  1. If the CA is known to the Oracle WebLogic server, skip this step; otherwise, use the utility keytool to import the Oracle Internet Directory's CA into the WebLogic trust store.

    The following invocation, which outputs the file myKeys.jks, illustrates the use of this command to import the file serverTrust.cert:

    >keytool -import -v -trustcacerts -alias trust -file serverTrust.cert -keystore myKeys.jks -storepass keyStorePassword
    
  2. Modify the script that starts the JMV to include a line like the following:

    -Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>
    

9.3 Using a DB-Based OPSS Security Store

A DB-based security store is typically used in production environments. The only supported DB-based security store in production environments is Oracle RDBMS (releases 11.1.0.7 or later; and releases 11.2.0.3 or later).


Note:

In development environments only, the OPSS security store can be Oracle RDBMS Express, Oracle RDBMS Standard Edition, and Oracle RDBMS Standard Edition One.

To use a DB-based OPSS security store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or WLST commands. In case any checks are needed before the server completes its initialization, see Section J.3.6, "Permission Failure Before Server Starts." The OPSS schema supports Edition-Based Redefinition (EBR).

For a list of properties that can be configured, see Appendix F, "OPSS Configuration Properties."

This section contains the following topics:

9.3.1 Prerequisites to Using a DB-Based Security Store

To use a database repository for the OPSS security store, one must first use Oracle Fusion Middleware Repository Creation Utility (RCU) to create the required schema and to seed some initial data.

For details about this task, see appendix A, Understanding Repository Creation Utility Screens, in Creating Schemas with the Repository Creation Utility. To create the OPSS schema, select the following schemas:

  • <prefix>_OPSS

  • <prefix>_IAU

  • <prefix>_IAU_APPEND

  • <prefix>_IAU_VIEWER

9.3.2 Maintaining a DB-Based Security Store

This section describes a few tasks that an administrator can follow to maintain a DB-based security store.

A DB-based security store maintains a change log that should be periodically purged. To purge it, an administrator can use the provided SQL script opss_purge_changelog.sql, which will purge change logs older than 24 hours, or connect to the database and run SQL delete (with the appropriate arguments) as illustrated in the following lines:

SQL>delete from jps_changelog where createdate < (select(max(createdate) - 1) from jps_changelog);
SQL>Commit;

If the OPSS management API performs slowly while accessing the DB-based security store, run the DBMS_STATS package to gather statistics about the physical storage of a DB table, index, of cluster. This information is stored in the data dictionary and can be used to optimize the execution plan for SQL statements accessing analyzed objects.

When loading large amount of data into a DB-based security store, such as when creating thousands of new application roles, it is recommended that DBMS_STATS be run within short periods and concurrently with the loading activity. Otherwise, when the loading activity is small, DBMS_STATS needs to be run just once and according to your needs.

The following sample illustrates the use of DBMS_STATS:

EXEC DBMS_STATS.GATHER_SCHEMA_STATS('DEV_OPSS', DBMS_STATS.AUTO_SAMPLE_SIZE, no_invalidate=>FALSE);

where DEV_OPSS denotes the name of the DB schema created withRCU. For details about the DBMS_STATS package, see the Oracle Database Administrator's Guide.

To run DBMS_STATS periodically, use a shell script or an SQL script, as described next.

The following sample script runs the command DBMS_STATS every 10 minutes:

#!/bin/sh
i=1
while [ $i -le 1000 ]
do
echo $i
sqlplus dev_opss/welcome1@inst1 @opssstats.sql
sleep 600
i=`expr $i + 1`
done

where opssstats.sql contains the following text:

EXEC DBMS_STATS.gather_schema_stats('DEV_OPSS',DBMS_STATS.AUTO_SAMPLE_SIZE, no_invalidate=>FALSE);
QUIT;

The following sample SQL script also runs the command DBMS_STATS every 10 minutes:

variable jobno number;
BEGIN
DBMS_JOB.submit
(job => :jobno,
what => 'DBMS_STATS.gather_schema_stats(''DEV_OPSS'',DBMS_STATS.AUTO_SAMPLE_SIZE,no_invalidate=>FALSE);',
interval => 'SYSDATE+(10/24/60)');
COMMIT;
END;
/

To stop the periodic invocation of DBMS_STATS by the above SQL script, first find out its job number by issuing the following commands:

sqlplus '/as sysdba'
SELECT job FROM dba_jobs WHERE schema_user = 'DEV_OPSS' AND what = 'DBMS_STATS.gather_schema_stats(''DEV_OPSS'',DBMS_STATS.AUTO_SAMPLE_SIZE, no_invalidate=>FALSE);';

Then issue a command like the following, in which it is assumed that the query above returned the job number 31:

EXEC DBMS_JOB.remove(31);

9.3.3 Setting Up an SSL Connection to the DB

Establishing a one- or two-way SSL connection to a DB-Based OPSS security store is optional and explained in section Configuring SSL for the Database in Administering Oracle Fusion Middleware.

For additional information about SSL-related topics see the following document:

9.4 Configuring the OPSS Security Store

For examples of store configurations for Java SE applications, see Section 20.1, "Policy and Credential Stores in Java SE Applications."

For examples of store configurations for Java EE applications, see Example 1.

For details about configuring other artifacts, see Configuring Services Providers with Fusion Middleware Control.

9.5 Reassociating the OPSS Security Store

Reassociating the OPSS security store is the process of relocating security artifacts from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The only type of LDAP target supported is Oracle Internet Directory; the only type of DB target supported is Oracle database.

Reassociation changes the repository while preserving the integrity of the data stored. All security artifacts are migrated from the existing security store to the new target store. This operation can take place at any time after the domain has been created, and it is carried out using either Fusion Middleware Control or reassociateSecurityStore as explained in the following sections:

9.5.1 Reassociating with Fusion Middleware Control

Reassociation migrates the OPSS security store (policies, credentials, keys, and audit metadata) from one repository to another and reconfigures the appropriate security store providers. This section explains how to perform reassociation with Fusion Middleware Control pages.

For information about other uses of the Security Provider Configuration page, see Configuring Services Providers with Fusion Middleware Control.

Important Points

To reassociate the OPSS security store with Fusion Middleware Control, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration, to display the Security Provider Configuration page, partially illustrated in the following graphic:

    Surrounding text describes emsecprovconf.gif.

    The table in the area Security Stores shows the characteristics of the current provider configured in the domain.

  2. Click the button Change Association to display the Set Security Provider page, and choose the Store Type from the pull-down list. The text displayed on this page depends on the store type selected. The following graphic partially illustrates this page when Oracle Internet Directory is selected.

    Surrounding text describes emsetsecprvdr.gif.
  3. If you have selected Database, enter the name of the data source in the Datasource Name box. This should be the name of the JDBC data source entered when the data source was created. If needed, click Select to obtain a list of configured data source names.

  4. If you have selected Oracle Internet Directory, in the LDAP Server Details area, specify details and connection information about the target LDAP server:

    1. Enter the host name and port number of your target Oracle Internet Directory LDAP server.

    2. Optionally, check the box Use SSL to Connect to establish an anonymous SSL transmission to the LDAP server.

      When checking this box, keep in mind the following points:

      The port of the target LDAP server must be configured to handle an anonymous SSL transmission; this port is distinct from the default (non-secure) LDAP server port.

      If the reassociation is to use a one-way SSL to a target LDAP store, be sure to follow the instructions in Setting Up a One- Way SSL Connection to the LDAP before completing this step. Among other things, that setup identifies the port to support a one-way SSL channel, and it is that port that should be specified in this step. Reassociation through a two-way SSL channel is not supported in this release.

      Fusion Middleware Control modifies the file weblogic.policy by adding the necessary grant to support the anonymous SSL connection.

    3. In the text box Connect DN, enter the full distinguished name, a string containing between 1 and 256 characters. For example, cn=orcladmin,dc=us,dc=oracle,dc=com.

    4. In the box Password, enter the user password, also a string containing between 1 and 256 characters.

    5. To verify that the connection to the LDAP server using the entered data works, click the button Test LDAP Authentication. If you run into any connection problem, see Section J.5.5, "Failure to Establish an Anonymous SSL Connection."

  5. In the Root Node Details area, enter the root DN in the box Root DN, which identifies the top of the tree that contains the data in the LDAP repository. The Domain Name defaults to the name of the selected domain.

    To solve most common errors arising from the specifications in these two fields, see Section J.2.1, "Reassociation Failure."

  6. Optionally, in the Policy Store Properties and Credential Store Properties areas, enter service instance properties, such as Enable Lazy Load and Role Member Cache Size.

    To add a new property: click Add to display the Add New Property dialog; in this dialog, enter strings for Property Name and Value; click OK. The added property-value pair is displayed in the table Custom Properties.

    These properties are typically used to initialize the instance when it is created.

    A property-value pair you enter modifies the domain configuration file jps-config.xml by adding a <property> element in the configuration of the LDAP service instance.

    To illustrate how a service instance is modified, suppose you enter the property name foo and value bar; then the configuration for the LDAP service instance changes to contain a <property> element as illustrated in the following excerpt:

    <serviceInstance name="myNewLDAPprovider" provider="someProvider"
      ...
      <property name="foo" value="bar"/>
      ...
    </serviceInstance>
    
  7. When finished entering your data, click OK to return to the Security Provider Configuration page. The system displays a dialog notifying the status of the reassociation. The table in the Security Stores area is modified to reflect the provider you have specified.

  8. Restart the application server. Changes do not take effect until it has been restarted.

Reassociation modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml: it deletes any configuration for the old store provider, inserts a configuration for the new store provider, and moves the policy and credential information from the source to the destination store.

If the destination store is LDAP-based, the information is stored under the domain DN according to the following format:

cn=<domain_name>,cn=JpsContext,<JPS ROOT DN>

As long as the configuration of the installation relies upon the above domain DN, that node should not be deleted from the LDAP Server.

9.5.1.1 Securing Access to Oracle Internet Directory Nodes

The procedure explained in this section is optional and performed only to enhance the security to access an Oracle Internet Directory.

An access control list (ACL) is a list that specifies who can access information and what operations are allowed on the Oracle Internet Directory directory objects. The control list is specified at a node, and its restrictions apply to all entries in the subtree under that node.

ACL can be used to control the access to policy and credential data stored in an LDAP Oracle Internet Directory repository, and it is, typically, specified at the top, root node of the store.

To specify an ACL at a node in an Oracle Internet Directory repository, proceed as follows:

  1. Create an LDIF file with a content that specifies the ACL:

    dn: <storeRootDN>
    changetype: modify
    add: orclACI
    access to entry by dn="<userDN>" (browse,add,delete) by * (none)
    access to attr=(*) by dn="<userDN>" (search,read,write,compare) by * (none)
    

    where storeRootDN stands for a node (typically the root node of the store), and userDN stands for the DN of the administrator data (the same userDN that was entered to perform reassociation).

  2. Use the Oracle Internet Directory utility ldapmodify to apply these specifications to the Oracle Internet Directory.

Here is an example of an LDIF file specifying an ACL:

dn: cn=jpsRootNode
changetype: modify
add: orclACI
access to entry by dn="cn=myAdmin,cn=users,dc=us,dc=oracle,dc=com" (browse,add,delete) by * ( none )
access to attr=(*) by dn="cn=myAdmin,cn=users,dc=us,dc=oracle,dc=com" (search,read,write,compare) by * (none)

For more information about access control lists and the command ldapmodify, see chapter 18 in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

9.5.2 Reassociating with the Script reassociateSecurityStore

The OPSS store can be reassociated with the WLST command reassociateSecurityStore. For details, see Section 10.3.1, "reassociateSecurityStore."

9.6 Migrating the OPSS Security Store

A domain includes one and only one security store. Applications can specify their own policies, and these are stored as application policies in the appropriate stripe in the security store when the application is deployed to a server. All applications deployed or redeployed to a domain use a common security store, the domain security store. This store is logically partitioned in stripes, one for each application name specified in the file $DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml under the element <applications>.

Migrating the OPSS security store is the process that relocates the policies, credentials, audit metadata, and keys from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The OPSS binaries and the target OPSS security store must have compatible versions; for details, see Section J.8.1, "Incompatible Versions of Binaries and Policy Store."

During application development, an application specifies its own policies, and these can be migrated to the OPSS security store when the application is deployed with Fusion Middleware Control. Policies can also be migrated manually; in addition, each application component can specify the use of anonymous user and role, authenticated role, and JAAS mode.

The configuration of the OPSS security store is performed by an administrator.

These topics are explained in the following sections:


Note:

Use the system property jps.deployment.handler.disabled to disable the migration of application policies and credentials for applications deployed on a WebLogic Server.

When this system property is set to TRUE, the migration of policies and credentials at deployment is disabled for all applications regardless of the particular application settings in the application file weblogic-application.xml.


9.6.1 Migrating with Fusion Middleware Control

Application policies are specified in the application file jazn-data.xml and can be migrated to the OPSS security store when the application is deployed to a server in the WebLogic environment with Fusion Middleware Control; they can also be removed from the OPSS security store when the application is undeployed or be updated when the application is redeployed.

All three operations, the migration, the removal, and the updating of application policies, can take place regardless of the type of policy repository, but they do require particular configurations.

For details, see procedure in Section 6.6.2, "Migrating Policies and Credentials."

9.6.2 Migrating with the Script migrateSecurityStore

Application-specific policies, system policies, and credentials can be migrated manually from a source repository to a target repository using the WLST command migrateSecurityStore.

This script is offline, that is, it does not require a connection to a running server to operate; therefore, the configuration file passed to the argument configFile need not be an actual domain configuration file, but it can be assembled just to specify the source and destination repositories of the migration.


Note:

Since the script migrateSecurityStore recreates GUIDs and takes a long time to migrate large volume of data, you may want to consider migrating stores with an alternate procedure that uses Oracle Internet Directory bulk operations. For details, see Section 6.6.2.3, "Migrating Large Volume Policy and Credential Stores.".

For platform-specific requirements to run an WLST command, see note in Section 10.3, "Managing Application Policies with WLST commands." For usage details, see Examples of Use.

To migrate all policies (system and application-specific, for all applications) on WebLogic use the script (first) or interactive (second) syntax (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type policyStore
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext
migrateSecurityStore(type="policyStore", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")
                     

The meanings of the arguments (all required) are as follows:

  • configFile specifies the location of a configuration file relative to the directory where the script is run. This configuration file should be specially assembled and must contain the following elements:

    • a context specifying the source store

    • a context specifying the destination store

    • a context specifying the bootstrap credentials

    The bootstrap context refers to the location of a cwallet.sso file where the keys needed to access the source and destination stores, and to decrypt and encrypt security data in them are expected to be.

    For information about extracting keys used by a domain, see exportEncryptionKey; for information about storing a key into a wallet, see importEncryptionKey.

    For information about creating a wallet, see section Common Wallet Operations in Administering Oracle Fusion Middleware.

  • src specifies the name of a jps-context in the configuration file passed to the argument configFile. The case of the string passed must match the case of the context in the configuration file.

  • dst specifies the name of another jps-context in the configuration file passed to the argument configFile. The case of the string passed must match the case of the context in the configuration file.

The contexts passed to src and dst must be defined in the passed configuration file and must have distinct names. From these two contexts, the script determines the locations of the source and the target repositories involved in the migration.

To migrate just system policies on WebLogic, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type globalPolicies
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext
migrateSecurityStore(type="globalPolicies", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")

The meanings of the arguments (all required) are identical to the previous case.

To migrate just application-specific policies on WebLogic, for one application, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type appPolicies
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext
                        -srcApp srcAppName
                       [-dstApp dstAppName]
                       [-overWrite trueOrfalse]
                       [migrateIdStoreMapping trueOrfalse]
                                       [mode laxOrstrict]
migrateSecurityStore(type="appPolicies", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext", srcApp="srcAppName", [dstApp="dstAppName"], [overWrite="trueOrfalse"], [migrateIdStoreMapping="trueOrfalse"], [mode="strict"])

The meanings of the arguments configFile, src, and dst are identical to the previous cases. The meaning of other five arguments is as follows:

  • srcApp specifies the name of the source application, that is, the application whose policies are being migrated.

  • dstApp specifies the name of the target application, that is, the application whose policies are being written. If unspecified, it defaults to the name of the source application.

  • migrateIdStoreMapping specifies whether enterprise policies should be migrated. The default value is True. To filter out enterprise policies from the migration, that is, to migrate just application policies, set it to False.

  • overWrite specifies whether a target policy matching a source policy should be overwritten by or merged with the source policy. Set to true to overwrite the target policy; set to false to merge matching policies. Optional. If unspecified, defaults to false.

  • mode specifies whether the migration should stop and signal an error upon encountering a duplicate principal or a duplicate permission in an application policy. Either do not specify or set to lax to allow the migration to continue upon encountering duplicate items, to migrate just one of the duplicated items, and to log a warning to this effect.

If the input does not follow the syntax requirements above, the script execution fails and returns an error. In particular, the input must satisfy the following requisites: (a) the file jps-config.xml is found in the passed location; (b) the file jps-config.xml includes the passed jps-contexts; and (c) the source and the destination context names are distinct.

To migrate all credentials use either of the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type credStore
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext

migrateSecurityStore(type="credStore", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")

The meanings of the arguments configFile, src, and dst are identical to the previous case.

To migrate just one credential map, use either of the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type folderCred
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext
                        [-srcFolder map1]
                        [-dstFolder map2]
                        [-srcConfigFile alternConfigFileLocation]
                        [-overWrite trueOrFalse]

migrateSecurityStore(type="folderCred", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext", [srcFolder="map1"], 
[dstFolder="map2"], [srcConfigFile="alternConfigFileLocation"], [overWrite="trueOrFalse"])

The meanings of the arguments configFile, src, and dst are identical to the previous case. The meanings of the last four arguments (all optional) are as follows:

  • srcFolder specifies the name of the map containing the credentials to be migrated. Optional. If unspecified, the credential store is assumed to have only one map and the value of this argument defaults to the name of that map.

  • dstFolder specifies the map where the source credentials are migrated. Optional; if unspecified, it defaults to the map passed to srcFolder.

  • srcConfigFile specifies the location of an alternate configuration file, and it is used in the special case in which credentials are not configured in the file passed to configFile. Optional; if unspecified, it defaults to the value passed to configFile; if specified, the value passed to configFile is ignored.

  • overWrite specifies whether a target credential matching a source credential should be overwritten by or merged with the source credential. Set to true to overwrite target credentials; set to false to merge matching credentials. Optional. If not specified, defaults to false. When set to false, if a matching is detected, the source credential is disregarded and a warning is logged.

9.6.2.1 Migrating Audit Metadata

You can use the script migrateSecurityStore to migrate audit metadata into a domain security store, or migrate audit metadata into an XML file.

See Section 6.6.3 for details.

9.7 Configuring Services Providers with Fusion Middleware Control

This section explains how to use Fusion Middleware Control to configure several service providers in the following sections:


Note:

The area of the Security Provider Configuration page labeled Web Services Manager Authentication Providers pertains to the configuration of Login Modules and the Keystore for Web Services Manager only and is not relevant to ADF or Java EE applications.

To configure policies, credentials, keys, and audit, see the following sections:

9.7.1 Configuring the Identity Store Provider

To configure the parameters used by the User and Role API that interact with the identity store, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. Expand, if necessary, the area Identity Store Provider, and click Configure to display the page Identity Store Configuration.

  3. Manage custom properties, as appropriate, using the buttons Add and Delete.

  4. When finished, click OK to save your settings and to return to the Security Provider Configuration page.

9.7.2 Configuring the Single Sign-On Provider

To configure the SSO provider used by a domain, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. In that page, click the Configure in the Single Sign-On Provider area to display the Single Sign-On Provider page.

  3. In that page, check the box Configure Single Sign-On, to allow entering data for the provider. All boxes are grayed out until this box is checked.

  4. Select the Store Type from the pull-down list, and enter the corresponding data for the selected provider (the data required changes with the type selected).

  5. Enter the Login URL, Autologin URL, and Logout URL in the text boxes.

  6. Select the Authentication Level from the pull-down list.

  7. Optionally, manage the provider Custom Properties using the buttons Add, Edit, and Delete, at the bottom of the page.

  8. When finished, click OK to save the entered data.

9.7.3 Configuring the Trust Service Provider

To configure the trust service provider used by a domain, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. In that page, the Trust Service Provider area shows whether the service is configured; to configure the service, click the Configure to display the Trust Service Provider page.

  3. That page contains the following areas:

    • Provider, where the name of the chosen provider is displayed.

    • Trust Store, where you select a stripe and a trust store, from the available ones.

    • Keystore and Alias, where you select a certificate by picking a stripe and a keystore, and an alias from the list of available trust aliases. The read-only entries at the bottom of the area (Issuer Name and Expiration Date) give information about the certificate selected.

    • Trust Service Configuration, where you enter the following values:

      • Clock Skew, the number of seconds that the clocks of the two systems (involved in the use of the trust service) may differ; the default is 60.

      • Token Validity Period, the number of seconds that the token is valid; the default is 1800.

      • Include Certificate, a boolean stating whether the certificate should be included in the token.

    • Codesource Permission, specifying the URL of the client code (that will access the trust store); no default value provided; this information translates into a codesource permission granted to the specified code.

  4. Click OK to save the entered data and to return to the Security Provider Configuration page; the values you entered are saved in the file $DOMAIN_HOME/config/fmwconfig/jps-config.xml.

9.7.4 Configuring Properties and Property Sets

A property set is collection of properties typically used to define the properties of a service instance or generic properties of the domain.

For a list of OPSS configuration properties, see Appendix F, "OPSS Configuration Properties."

The elements <property> and <properySet> in the file $DOMAIN_HOME/config/fmwconfig/jps-config.xml are used to define property and property sets. Property sets can be referenced by the element <propertySetRef>.

To define a property or a property set, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. Expand, if necessary, the area Advanced Properties, and click Configure to display the Advanced Properties page.

  3. To enter a property, click Add in the Properties area to display the dialog Add New Property, and enter a property name and value. When finished, click OK. The entered property appears on the Properties table.

  4. To enter a property set, click Add Property Set in the Property Sets area to display the dialog Add Property Set, and enter the property set name.

  5. To enter a property in a property set, select a property set from the existing ones, then click Add Property to display the dialog Add New Property, and then enter a property name and value. The entered property is added to the list of properties in the selected property set.

  6. Use the button Delete to remove a selected item from any table. When finished entering or editing properties and property sets, click OK.

  7. Restart the Oracle WebLogic Server. Changes do not take effect until the server has been restarted.

The addition or deletion of property sets modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml; the changes do not take effect until the server is restarted.

The elements <property> and <propertySet> added by the previous procedure are inserted directly under the element <jpsConfig>.

PKYD5PK].FOEBPS/devuserole.htm Developing with the User and Role API

22 Developing with the User and Role API

This chapter explains how to access identity information with the User and Role API.

This chapter includes the following sections:


Note:

The User and Role API is deprecated and may be withdrawn in a future release. Your new applications should be developed on the Identity Governance Framework. Plan to migrate existing applications to the Identity Governance Framework in a future release.

For details, see the Developer's Guide for Identity Governance Framework.


22.1 Introduction to the User and Role API Framework

The User and Role API framework allows applications to access identity information (users and roles) in a uniform and portable manner regardless of the particular underlying identity repository. The repository could be an LDAP directory server such as Oracle Internet Directory, Active Directory (from Microsoft), or Oracle Directory Server Enterprise Edition, or could be a database, flat file, or some other custom repository.

This API framework provides a convenient way to access repositories programmatically in a portable way, freeing the application developer from the potentially difficult task of accounting for the intricacies of particular identity sources. The framework allows an application to work against different repositories seamlessly. An application can switch between various identity repositories without any code changes being required.

Supported operations include creating, updating, or deleting users and roles, or searching users and roles for attributes or information of interest. For example, you may want to search for the e-mail addresses of all users in a certain role.


Note:

These APIs are not meant for authentication or authorization functions, but for maintaining identity information.

You can use a basic usage model (without container integration) or a usage model with container integration that allows your code to be portable.

When the application is intended to run in the context of an Oracle WebLogic Server container, the principal class should be cast to weblogic.security.principal.WLSUserImpl.


Note:

The following are required to invoke the User and Role API in context of an Oracle WebLogic Server container:
  • The identity store is LDAP-based

  • The domain administration server is up and running


A Note about Using the User and Role API

As a general rule of thumb, authentication should only be performed by authentication providers, not through the User and Role API.

Additionally, it is recommended that authentication providers be configured with the connect DN of a user that does not have write privileges.

22.1.1 User and Role API and the Oracle WebLogic Server Authenticators

The User and Role API is automatically configured to use the first Oracle WebLogic Server authenticator and does not require any special configuration.

Note, however, that configuration is required if the User and Role API is going against other authenticators.

The API can access data only from the first LDAP authenticator listed in an Oracle WebLogic Server domain. When more than one authenticator is present, the precedence is determined by their control flag priority. If both have the same priority, the first one is picked. Any LDAP authenticators below the first one on the list are not accessed.

About Concurrent Use of WebLogic APIs

Your application should not try to use both the User and Role API and the WebLogic LDAPAuthenticator API (such as EmbeddedLDAPAuthenticator, OracleInternetDirectoryAuthenticator, OracleVirturalDirectoryAuthenticator) to work on entries in the same LDAP server concurrently. To understand why, consider two LDAP clients, both with caching enabled, that access the same LDAP server; one is deleting entries, and the other tries to use the deleted entries.

The conflict caused by the two clients cannot be resolved unless caching capability is disabled, and the LDAP operations are coordinated among the clients.

22.2 Summary of Roles and Classes

Table 22-1 lists the classes and interfaces of the User and Role API.

Table 22-1 Classes and Interfaces in the User and Role API

NameTypeDescription

AuthenticationException

Class

This exception is thrown when an authentication error occurs while accessing the identity store. An authentication error can happen, for example, when the credentials supplied by the user program is invalid or otherwise fails to authenticate the user to the identity store.

AuthenticationWarningException

Class

This class extends IMException (see below).

ComplexSearchFilter

Interface

A complex search filter represents a complex logical expression that can be used to filter results from underlying identity repository. Complex search filter combines multiple SearchFilter instances together with a single logical operator (AND/OR). Each of these component SearchFilter can itself be a complex filter, enabling you to form a complex nested search filter.

See the Javadoc (Section 22.9, "The User and Role API Reference") for an example of creating a complex search filter.

ConfigurationException

Class

This exception is thrown when there is a configuration problem. This can arise when configuration information required to access the service provider is malformed or missing.

Identity

Interface

This interface represents a basic identity in the identity repository.

IdentityStore

Interface

IdentityStore represents a handle to actual identity repository. This handle can be used to search, create, drop, and modify identities in the repository.

IdentityStoreFactory

Interface

IdentityStoreFactory is a programmatic representation of underlying identity repository. Actual handle to the identity repository can be obtained by calling getIdentityStoreInstance(Hashtable) on this object.

IdentityStoreFactoryBuilder

Class

This class builds the identity store factory.

IMException

Class

This exception is the superclass of all the exceptions thrown by ADF identity management APIs. The nature of failure is described by the name of the subclass.

See the Javadoc (Section 22.9, "The User and Role API Reference") for a list of the direct known subclasses.

ModProperty

Class

This class represents the modification of a property object. ModProperty is called with property name, modified value(s) and type of modification. Modification type can be one of ADD, REMOVE, or REPLACE.

NoPermissionException

Class

This exception is thrown when attempting to perform an operation for which the API caller has no permission. The access control/permission model is dictated by the underlying identity store.

ObjectExistsException

Class

This exception is thrown when an identity with given name is already present in the underlying identity store. For example this exception is thrown when create user API call tries to create a user with the name of an existing user.

ObjectNotFoundException

Class

This exception is thrown when a specified identity does not exist in the identity store.

OperationFailureException

Class

This exception is thrown when an operation fails during execution in the underlying identity store.

OperationNotSupportedException

Class

This exception is thrown by an service provider if it does not support an operation. For example this can be thrown by the service provider, in IdentityStore.getUserManager() call, if it does not provide support for UserManager.

PasswordPolicyException

Class

This class extends IMException (see above).

Property

Class

Property contains name-value information.

PropertySet

Class

A collection of property name and value pairs. Property class is used to represent the property name and value(s) pair. PropertySet guarantees that no two properties have same name.

Role

Interface

This interface represents a role in the identity store.

RoleManager

Interface

This interface represents a role manager that manages execution of various operations, involving roles, in the identity repository.

RoleProfile

Interface

This interface represents the detailed profile of a role.

SearchFilter

Interface

This interface represents a search filter to be used in searching the identity repository.

SearchParameters

Class

This class represents search parameters that need to be specified while performing searches on the identity store. These search parameters are:

  • Search filter,

  • Search identity type,

  • page size,

  • time limit, and

  • count limit.

SearchResponse

Interface

This interface represents search results obtained after searching the identity store. Its implementation is service provider-specific.

SimpleSearchFilter

Interface

This interface represents a simple search filter to be used while searching the identity repository. Each simple search filter is a logical expression consisting of a search attribute/property, evaluation operator and value. This logical expression will be applied to the underlying identity repository while searching and matching results will be filtered out.

See the Javadoc (Section 22.9, "The User and Role API Reference") for an example of a simple search filter.

StoreConfiguration

Interface

StoreConfiguration holds the configuration properties for a given IdentityStore instance. The behavior of this IdentityStore instance can be controlled by changing the properties in this configuration object. The actual configuration properties and their values are specific to the service provider. Some service providers may not support any configuration property at all.

SubjectParser

Interface

This interface provides utility methods for extracting out the user and role principals from the given Subject. Service provider needs to provide the implementation for this interface.

User

Interface

This interface represents a user in the identity store.

UserManager

Interface

This interface represents a user manager that manages execution of various operations, involving users, in the identity repository.

UserProfile

Interface

This interface represents the detailed profile of a user. It allows for user properties to be accessed in a generic manner.

You can read or modify any property of user with these APIs:

  • getProperty(java.lang.String)

  • getProperties(java.lang.String[])

  • setProperty(oracle.security.idm.ModProperty)

  • setProperties(oracle.security.idm.ModProperty[])


22.3 Working with Service Providers

In this section we describe basic provider concepts and lifecycle, and explain how to set up, configure, and use the provider to work with user repositories in an Oracle Platform Security Services environment.

After ensuring the environment is properly set up, implementing the provider involves:

  • identifying the underlying repository and selecting the provider factory class appropriate to that repository

  • creating instances of the provider factory and the identity store

  • configuring the provider

This section contains these topics:

22.3.1 Understanding Service Providers

Although the User and Role API is called for user and role management, the API does not directly interact with the underlying identity repository. Instead, security applications make use of providers which carry out the actual communication with the underlying repository. This offers flexibility since the same code can be used with various underlying repositories simply by modifying the provider/connection information.

22.3.2 Setting Up the Environment

This section describes how to configure the environment for the User and Role API.

22.3.2.1 Jar Configuration

Several jars must be present in your environment:

  • the provider jar file, which implements the desired underlying identity repository

  • the User and Role API jars

  • other component jars which the provider may need, including Toplink, jdbc, xdb, and so on

Ensure that your application classpath includes the relevant jars.

22.3.2.2 User Classes in jps-config.xml (Oracle Virtual Directory only)


Note:

Make this change only for the Oracle Virtual Directory authenticator.

For efficiency when fetching user attributes, add the following entry in jps-config.xml to specify the user object classes for the search:

.
.
     <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
            <property name="idstore.config.provider"
value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"/
>
            <property name="CONNECTION_POOL_CLASS"
value="oracle.security.idm.providers.stdldap.JNDIPool"/>
          <extendedProperty>
            <name>user.object.classes</name>
            <values>
               <value>top</value>
               <value>person</value>
               <value>inetorgperson</value>
               <value>organizationalperson</value>
               <value>otherActiveDirectorySpecificClasses</value>
               ...
            </values>
          </extendedProperty>
.
.

22.3.2.3 Read Privileges for Provider User (Oracle Internet Directory Only)

For the Oracle Internet Directory provider, the configured user should have privileges to read the "cn=common,cn=products,cn=oraclecontext" container at the root level.

22.3.3 Selecting the Provider

Oracle Platform Security Services support a range of user repositories, including the following LDAP directories:

  • Microsoft Active Directory

  • Novell eDirectory

  • Oracle Directory Server Enterprise Edition

  • Oracle Internet Directory

  • Oracle Virtual Directory

  • OpenLDAP

  • Oracle WebLogic Server Embedded LDAP Directory

  • Microsoft ADAM

  • IBM Tivoli

The choice of identity repository dictates the provider class to use with the provider. The provider class must implement the interface specified by the User and Role API framework. Table 22-2 shows the available provider classes:

Table 22-2 LDAP Identity Provider Classes

ProviderFactory Name

Microsoft Active Directory

oracle.security.idm.providers.ad.ADIdentityStoreFactory

Novell eDirectory

oracle.security.idm.providers.edir.EDIdentityStoreFactory

Oracle Directory Server Enterprise Edition

oracle.security.idm.providers.iplanet.IPIdentityStoreFactory

Oracle Internet Directory


oracle.security.idm.providers.oid.OIDIdentityStoreFactory

OpenLDAP

oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory

Oracle WebLogic Server Embedded LDAP Directory

oracle.security.idm.providers.wlsldap.WLSLDAPIdentityStoreFactory

Oracle Virtual Directory


oracle.security.idm.providers.ovd.OVDIdentityStoreFactory

Microsoft ADAM

oracle.security.idm.providers.ad.ADIdentityStoreFactory

IBM Tivoli

oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory


22.3.4 Creating the Provider Instance

Once the provider's class name is identified, take these steps to create the provider:

  1. Use the getIdentityStoreFactory method of the IdentityStoreFactoryBuilder class to build a factory instance. The builder class API accepts:

    • the provider class name

    • the necessary environment properties from a hash table

  2. Use the getIdentityStoreInstance method of the IdentityStoreFactory class to create a store instance

The following example creates a factory instance for the Oracle Internet Directory store:

IdentityStoreFactoryBuilder builder = new 
   IdentityStoreFactoryBuilder ();
 
IdentityStoreFactory oidFactory = builder.getIdentityStoreFactory(
   ”oracle.security.idm.providers.oid.OIDIdentityStoreFactory", factEnv); 

Now obtain the store reference, which is the actual handle to the identity store:

oidStore = oidFactory.getIdentityStoreInstance(storeEnv);

Note that two hash-table objects are supplied in these examples:

  • the factEnv hash table provides the factory instance environment

  • the storeEnv hash table provides the store instance environment

To learn more about these hash tables see the example in Section 22.7.1.

22.3.5 Properties for Provider Configuration

Configuration is dependent on the identity store provider being used.

You can fine-tune the behavior of all types of LDAP-based identity store providers by configuring a number of properties for the factory instance and the store instance. The following properties are relevant for LDAP-based providers only:

  • URL

  • the port at which the repository runs

  • the user and password to use in accessing the repository

For a list of supported LDAP-based providers, see Section 22.3.3, "Selecting the Provider".

This section explains the following provider configuration topics:

22.3.5.1 Start-time and Run-time Configuration

The properties that can be configured fall into two categories:

  • Start-time configuration - the naming convention uses property names starting with ST_.

  • Run-time configuration - the naming convention uses property names starting with RT_.

Start-time Configuration Properties

Start-time configuration is performed only once, and once set, the configuration settings persist for the duration of the provider's lifetime.

With the exception of ST_SUBSCRIBER_NAME, the start-time properties are specified when creating the provider factory instance; ST_SUBSCRIBER_NAME is set when creating the store instance.

Table 22-3 lists the start-time configuration properties:

Table 22-3 Start-time Identity Provider Configuration Properties

Property NameDescription

ST_BINARY_ATTRIBUTES

An array of Array of String objects containing the names of binary attributes stored in the underlying LDAP server. The provider will treat these attributes as binary while sending data to and receiving it from the LDAP server.

ST_CONNECTION_POOL

External connection pool, an instance of class oracle.idm.connection.ConnectionPool. If set, the provider uses this pool to acquire connections to the LDAP server, and the properties ST_SECURITY_PRINCIPAL, ST_SECURITY_CREDENTIALS, and ST_LDAP_URL are ignored.

ST_USER_NAME_ATTR

The attribute used to determine the username of the user in the identity repository.

ST_GROUP_NAME_ATTR

The attribute used to determine the role name in the identity repository.

ST_USER_LOGIN_ATTR

The attribute used to determine the login ID of the user in the identity repository.

ST_SECURITY_PRINCIPAL

The user (principal).

ST_SECURITY_CREDENTIALS

The credentials necessary to log in to the identity repository.

ST_LDAP_URL

The URL of the identity repository.

ST_MAX_SEARCHFILTER_LENGTH

The maximum length of the search filter allowed by the LDAP server.

ST_LOGGER

The logger object that is to be used by the API.

ST_SUBSCRIBER_NAME

The base DN of operations in the LDAP server. This property is specified while creating the IdentityStore instance and is used to determine default values for remaining properties. This property must be specified while creating the IdentityStore instance; however, subsequent changes to its value have no effect on IdentityStore behavior.

ST_CONNECTION_POOL_CLASS

The fully-qualified Connection Pool implementation class name.

ST_INITIAL_CONTEXT_FACTORY

The fully-qualified class name of the initial context factory that will create the initial context.


Run-time Configuration Properties

Properties set at runtime affect all subsequent operations executed by the provider and control the behavior of the IdentityStore instance of the provider.

Runtime properties are configured by specifying the appropriate parameters and values for the StoreConfiguration object obtained from the IdentityStore instance. All runtime properties have default values when the IdentityStore instance is created, and can be subsequently changed.

Table 22-4 lists the run-time configuration properties:

Table 22-4 Runtime Identity Provider Configuration Properties

Property NameDescription

RT_USER_OBJECT_CLASSES

array of object classes required to create a user in the LDAP server

RT_USER_MANDATORY_ATTRS

attribute names that must be specified while creating a user

RT_USER_CREATE_BASES

Base DNs in the LDAP server where a new user can be created

RT_USER_SEARCH_BASES


RT_USER_SEARCH_BASES

the base DNs in the LDAP server that can be searched for users

RT_USER_FILTER_OBJECT_CLASSES

array of object classes to use when searching for a user in the LDAP server

RT_GROUP_OBJECT_CLASSES

array of object classes required to create a role in the LDAP server

RT_GROUP_MANDATORY_ATTRS

attribute names that must be specified when creating a role

RT_GROUP_CREATE_BASES

the base DNs in the LDAP server where a new role can be created

RT_GROUP_SEARCH_BASES

the base DNs in the LDAP server that can be searched for a role

RT_GROUP_MEMBER_ATTRS

An array of member attribute(s) in a role. All members of a role have value(s) for the attribute(s).

RT_GROUP_FILTER_OBJECT_CLASSES

an array of object classes to use when searching for a role in the LDAP server

RT_USER_SELECTED_CREATE_BASE

The currently selected user create base. The user will be created in this base DN upon execution of the createUser() call. If the selected create base is null and the ST_SUBSCRIBER_NAME is not specified, the first supplied value of the RT_USER_CREATE_BASE is used. If the ST_SUBSCRIBER_NAME is specified, the default value is relative to the subscriber name based on the identity store type.

RT_GROUP_SELECTED_CREATE_BASE

The currently selected role create base. This role will be created in this base DN upon execution of the createRole() call. If the selected create base is null and the ST_SUBSCRIBER_NAME is not specified, the first supplied value of the RT_GROUP_CREATE_BASE is used. If the ST_SUBSCRIBER_NAME is specified, the default value is relative to the subscriber name based on the identity store type.

RT_GROUP_GENERIC_SEARCH_BASE

A generic role search base to use in searching the roles related to a given identity. For example while searching all granted roles for a user, or all managed roles for a user, we need a search base under which all the required groups would reside; this helps in optimizing the searches. This search base is usually a common parent. By default, in all LDAP providers this value is set to the subscriber name if provider, else it uses the first group search base.

RT_SEARCH_TYPE

determines whether a search on the LDAP server should be of type SIMPLE, PAGED, or VIRTUAL_LIST_VIEW


22.3.5.2 ECID Propagation

By default, ECID support is disabled in the User and Role API.

When initializing the API, set the ST_ECID_ENABLED property to true for ECID support, as illustrated in the following example:

factEnv.put(OVDIdentityStoreFactory.ST_ECID_ENABLED, "true");

Note:

This action is necessary only if either Oracle Internet Directory or Oracle Virtual Directory is used as the back-end identity store. It is not necessary if using other repositories such as Microsoft Active Directory or Novell eDirectory.

22.3.5.3 When to Pass Configuration Values

You can specify configuration data:

22.3.6 Configuring the Provider when Creating a Factory Instance

This section contains topics related to configuring the provider during factory instance creation.

Configuration at this stage affects the entire factory object as well as objects created using this specific factory instance. Many start-time properties are set at this time, including these common properties:

  • ST_LDAP_URL - the URL of the LDAP repository

  • ST_SECURITY_PRINCIPAL - the user name

  • ST_SECURITY_CREDENTIAL - the user credentials required to connect to the repository

22.3.6.1 Oracle Internet Directory Provider

In this example, the provider is configured when setting up an Oracle Internet Directory (OID) factory:

IdentityStoreFactoryBuilder builder = new 
   IdentityStoreFactoryBuilder();
IdentityStoreFactory oidFactory = null;
Hashtable factEnv = new Hashtable();

// Creating the factory instance
factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_PRINCIPAL,
   "<User DN>");
factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_CREDENTIALS,
   "<User password>");
factEnv.put(OIDIdentityStoreFactory.ST_LDAP_URL,
   "ldap://ldaphost:port/");
oidFactory = builder.getIdentityStoreFactory(
   "oracle.security.idm.providers.oid.
   OIDIdentityStoreFactory", factEnv);

Note:

The values in italics must be replaced with appropriate values prior to execution.

22.3.6.2 Using Existing Logger Objects

You can supply named logger objects to the User and Role API. The API uses the specified logger to log messages. You must supply the external logger's name as an environment variable during the factory creation.

Here is an example:

Logger mylogr = Logger.getLogger("mylogger.abc.com");
FileHandler fh = new FileHandler("userroleapi.log");
mylogr.addHandler(fh);
 
…
 
factEnv.put(OIDIdentityStoreFactory.ST_LOGGER_NAME, 
"mylogger.abc.com");
oidFactory = builder.getIdentityStoreFactory(
   "oracle.security.idm.providers.oid.
   OIDIdentityStoreFactory", factEnv);

This code directs that all the log messages should be redirected to the log file named userroleapi.log.

22.3.6.3 Supplying Constant Values

You can overwrite constants or pre-supply values for missing constants by supplying the map in the ST_PROPERTY_ATTRIBUTE_MAPPING property during factory creation.

This example code sets the mapping of RoleProfile.OWNER to the "myowner" attribute. In this way, all operations related to the owner, such as getOwners(), getOwnedRoles(), and so on, are performed using this attribute.

factEnv.put
   (IPIdentityStoreFactory.ST_SECURITY_PRINCIPAL, "<User DN>");
factEnv.put
   (IPIdentityStoreFactory.ST_SECURITY_CREDENTIALS, "<User password>");
factEnv.put(IPIdentityStoreFactory.ST_LDAP_URL,
   "ldap://ldaphost:port/");
      
Map m = new Hashtable();
m.put(RoleProfile.OWNER, "myowner");
 
factEnv.put
   (IPIdentityStoreFactory.ST_PROPERTY_ATTRIBUTE_MAPPING, m);
 
ipFactory = builder.getIdentityStoreFactory(
   "oracle.security.idm.providers.iplanet.IPIdentityStoreFactory",
   factEnv);

22.3.6.4 Configuring Connection Parameters

You can configure the connection pool parameters for minimum/maximum connections using ST_CONNECTION_POOL_MIN_CONNECTIONS and ST_CONNECTION_POOL_MAX_CONNECTIONS respectively. By default, the values for these parameters are "0" and "10" respectively. There is an additional restriction that:

(ST_CONNECTION_POOL_MAX_CONNECTIONS  - ST_CONNECTION_POOL_MIN_CONNECTIONS) >= 10

Here is an example:

factEnv.put
   (LDIdentityStoreFactory.ST_CONNECTION_POOL_MIN_CONNECTIONS,  "3");
 
factEnv.put
   (LDIdentityStoreFactory.ST_CONNECTION_POOL_MAX_CONNECTIONS, "16");

22.3.6.5 Configuring a Custom Connection Pool Class

To use a custom connection pool, you must provide the fully qualified class name of the custom connection pool class, as follows:

factEnv.put(OIDIdentityStoreFactory.ST_CONNECTION_POOL_CLASS,
"oracle.security.idm.providers.stdldap.JNDIPool");

For related information, see Section J.5.1, "Failure to Connect to the Embedded LDAP Authenticator."

22.3.7 Configuring the Provider when Creating a Store Instance

The IdentityStore configuration affects the store object and all objects that are created using this store instance. A configuration parameter commonly used with the store is ST_SUBSCRIBER_NAME, which is the only start-time property accepted here. (All the runtime properties can be supplied during identity store creation.)

Continuing with the earlier example in Section 22.3.6, "Configuring the Provider when Creating a Factory Instance" which created a factory instance, this code creates a handle instance to the store.

IdentityStore oidStore = null;
Hashtable storeEnv = new Hashtable();
 
// Creating the store instance
storeEnv.put(OIDIdentityStoreFactory.ST_SUBSCRIBER_NAME,
   "dc=us,dc=oracle,dc=com");
oidStore = oidFactory.getIdentityStoreInstance(storeEnv);

Note:

Directories require that you supply a valid subscriber name. For Oracle Internet Directory, you can supply the STsubscriber name as either a proper DN or as the nickname of the realm.

22.3.8 Runtime Configuration

Earlier, in Section 22.3.6, "Configuring the Provider when Creating a Factory Instance" and Section 22.3.7, "Configuring the Provider when Creating a Store Instance", we demonstrated how to perform configuration when creating an instance. To facilitate adding and modifying properties at runtime, the User and Role APIs also provide a Configuration class.

The Configuration instance can be obtained from the store instance using the IdentityStore.getStoreConfiguration() API call. Properties can be modified using the configuration object.

Only runtime properties can be modified using this approach, and the effect is visible only at runtime.

This example sets the RT_USER_SEARCH_BASES property:

StoreConfiguration conf = oidStore.getStoreConfiguration();
conf.setProperty(”RT_USER_SEARCH_BASES”, ”dc=us,dc=oracle,dc=com”);

22.3.9 Programming Considerations

This section contains tips for working with providers and provider artifacts.

22.3.9.1 Provider Portability Considerations

To ensure that your application is portable when switching providers (say, from OpenLDAP provider to Oracle Internet Directory provider or the converse), follow these guidelines when working with the User and Role API:

  1. Use only the corresponding oracle.security.idm.UserProfile constants to refer to user properties. Avoid using native names which are not portable across identity repositories. For example, if the application needs to obtain a user's login name, fetch it using the UserProfile.USER_NAME constant:

    Property prop = usrprofile.getProperty(UserProfile.USER_NAME);
    
  2. For obvious reasons, UserProfile constants are provided for most standard user properties but not for all possible properties. If the application needs to obtain all the properties of a user generically, use the following code:

    UserProfile upf = null;
     
    // Obtain the user profile from user object. User object can be obtained using search 
    
    // get the properties supported for given user in currently configured repository
    List proplst = store.getUserPropertyNames();
    
    String[] proparr = (String[]) proplst.toArray(new String[proplst.size()]);
    
    // get all properties of the user
    PropertySet pset = upf.getProperties(proparr);
    
  3. When creating search filters, do not use native wild card characters directly in your search filter string. Instead, use the SimpleSearchFilter.getWildCardChar() method. This will fetch the correct wild character based upon the underlying provider. For example, the API will return % for a database provider and return * for the Oracle Internet Directory provider.

    SmpleSearchFilter sf = m_identityStore.getSimpleSearchFilter(
       attrName, SimpleSearchFilter.TYPE_EQUAL, null); 
    
    sf.setValue( filterStringWithoutWildcard+sf.getWildCardChar());
    
  4. If your application accepts user-supplied filter strings with a predefined wild card character, apply the following conversion on the filter while generating the User and Role API filter:

    //User supplied filter which assumes ”%” as the wildcard character
    
    String userDefinedFilter = .................
    
    SmpleSearchFilter sf = m_identityStore.getSimpleSearchFilter(
       attrName, SimpleSearchFilter.TYPE_EQUAL, null);
    
    userDefinedFilter = 
       userDefinedFilter.replaceall("%", sf.getWildCardChar());
    
    sf.setValue(userDefinedFilter); 
    

    The line in bold converts the user-supplied filter to the generic User and Role API filter format.

22.3.9.2 Considerations when Using IdentityStore Objects

Keep the following considerations in mind when coding your applications.

Thread Safety

The current IdentityStore implementations are not thread-safe. The User and Role API assumes that the store instances are not generally shared among threads. If the store instance is shared among threads, the application code must take care to handle any required thread safety issues.

There are trade-offs between thread safety and performance. Use cases that need to implement thread safety must be willing to consider the performance implications of doing so.

One Store Instance per Session

In applications such as Delegated Administration Server, each session (corresponding to one logged-in user) can change its own create/search bases and various other runtime settings; these are defined as runtime properties in the User and Role API. The IdentityStore object encapsulates all these settings and changes its runtime behavior accordingly. For this reason, the rule of one IdentityStore instance per session is enforced.

22.3.10 Provider Lifecycle

A given provider exists for the lifetime of the factory instance created for that provider. The life of a factory instance ends whenever the close() API is called on that instance. When the provider instance ends, all the objects that were created using that instance become invalid, and subsequent API calls on those objects return unanticipated output.

Similar considerations apply to IdentityStore instances.


Note:

  • Factory instances are thread-safe while this is not the case with IdentityStore instances.

  • It is best practice to cascade close server connections and explicitly delete objects and instances no longer in use.


22.4 Searching the Repository

The User and Role API provides two types of query functions:

  • functions that return a single identity

  • functions that return a list of identities

This section describes searches and related tasks you can accomplish with the API, and provides details on specifying search parameters:

22.4.1 Searching for a Specific Identity

You can query the identity store directly for a specific user or role using the searchUser and searchRole APIs:

IdentityStore.searchUser(String name);
 
IdentityStore.searchUser(Principal principal);
 
IdentityStore.searchUser(int searchType, String name); 
 

where searchType can be:

  • SEARCH_BY_NAME

  • SEARCH_BY_UNIQUE_NAME

IdentityStore.searchRole(int searchType, String value);

These functions facilitate simple queries where a particular user/role identity is known to exist in the store, and you simply need the object reference to that identity. The functions are minimal in that:

  • they accept only string values

  • they do not support regular expressions

The functions raise an exception if multiple entities with the same value exist in the store.

22.4.2 Searching for Multiple Identities

The User and Role APIs contain several functions that can perform searches to return multiple identities:

IdentityStore.search(SearchParams params);
IdentityStore.searchUsers(SearchParams params);
IdentityStore.searchRoles(int searchType, SearchParams params);
IdentityStore.searchProfiles(SearchParams params);

Each function accepts a search object and returns a search response object.

22.4.3 Specifying Search Parameters

The SearchParams Object

The SearchParams object contains the following information:

  • Search Filter - this is discussed in Section 22.4.4, "Using Search Filters"

  • Search Identity of type - you can search identities of type Roles or Users

  • Page Size - By default the paging option is turned off. If the query needs paging, set the page size to a relevant positive value.

  • Timeout limit – timeout is specified in seconds

  • Count Limit – limits the number of results returned by the query

The SearchResponse Object

SearchResponse is a data structure used when retrieving multiple identities. Your code can iterate through the identities contained in this structure using these functions:

  • hasNext() - returns true if more elements are present, false otherwise

  • next() – returns the next element if it is available, an exception otherwise

22.4.4 Using Search Filters

The User and Role API includes different types of search filters to facilitate a variety of search operations. This section explains key facts about the use of search filters:

22.4.4.1 Operators in Search Filters

Observe these rules when using search filter operators.

Supported Operators

The standard LDAP store accepts only "=" (equals operator), "<" (less-than operator), ">" (greater-than operator), "&" (AND operator), "|" (OR operator) and "!" (NOT operator). IdentityStore provides two more operators to simplify usage, namely "<=" (less than or equal to) and ">=" (greater than or equal to).

The operators "=", "<",">", "<=" and ">=" are used to create simple search filters while the "&" and "|" operators are used to combine two or more search strings to make a complex search filter.

NOT Operator

You can use the NOT operator in both the simple search filter and complex search filters. This operator is used to negate the state of the filter, that is, the state of the filter is changed to accept the entities which were earlier rejected by the filter, or to reject entities that were earlier accepted.

The NOT operator is accessible using the following SearchFilter API:

  • void negate();

  • boolean isNegated();

22.4.4.2 Handling Special Characters when Using Search Filters

According to RFC-2254 (String Representation of LDAP Search Filters), "*", "(", ")","\" and NULL characters are to be handled separately. The User and Role API handles "(", ")" and "\" operators but does not handle the "*" operator, which is also a wild-card character for LDAP stores. The API user is not required to separately handle these characters as the User and Role API framework handles these characters.

22.4.4.3 Search Filter for Logged-In User

Applications commonly need to retrieve the identity of the logged-in user and the user's group name.

The Oracle WebLogic Server authenticator uses two attributes related to users: user.login.attr and groupname.attr. Upon login, the authenticator uses user.login.attr to store the user and groupname.attr for the group.

Your application should use UserProfile.getUserName() (which maps to user.login.attr) to obtain the identity of the logged-in user. To obtain the role (group) name, it should use RoleProfile.getProperty(RoleProfile.NAME) (which maps to groupname.attr).

Sample calls showing how to obtain the logged-in user and role are shown in Example 22-6 and Example 22-7, respectively.

22.4.4.4 Examples of Using Search Filters

Several usage examples are presented in this section.

Example 22-1 Simple Filter to Retrieve Users by Name

The implementation of the simple search filter depends on the underlying store; you can obtain an instance of the search filter through the store instance.

In this example, the filter allows all entries with a non-null value for the "name" field:

SimpleSearchFilter sf = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME, 
   SimpleSearchFilter.TYPE_EQUAL, null);
sf.setValue(sf.getWildCardChar());

Example 22-2 Simple Filter to Find Users by Language Preference

This example retrieves users whose preferred language is not English:

SimpleSearchFilter sf = 
   oidStore.getSimpleSearchFilter(
      UserProfile.PREFERRED_LANGUAGE,          
      SimpleSearchFilter.TYPE_EQUAL,
      "english");
sf.negate();

Example 22-3 Complex Filter for Names by Starting Letter

This complex filter combines multiple search filters with operators "&" or "|". It searches for users whose name starts with a letter between "a" and "j":

SimpleSearchFilter sf1 = 
   oidStore.getSimpleSearchFilter(
      UserProfile.NAME,
      SimpleSearchFilter.TYPE_GREATER,
      null);
 
sf1.setValue("a"+sf1.getWildCardChar());
SimpleSearchFilter sf2 = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME, 
      SimpleSearchFilter.TYPE_LESS, null);
sf2.setValue("j"+sf2.getWildCardChar());
SimpleSearchFilter sfArray[] = new SimpleSearchFilter[] {sf1, sf2};
ComplexSearchFilter cf1 = 
store.getComplexSearchFilter(sfArray, ComplexSearchFilter.TYPE_AND); 

Example 22-4 Complex Filter with Restrictions on Starting Letter

In this example, complex filters are nested to enable a search for users whose name starts with a letter between "a" and "j" but not with the letter "i":

[continue from Example 3]

SimpleSearchFilter sf3 = 
   oidStore.getSimpleSearchFilter(
      UserProfile.NAME,                                  
      SimpleSearchFilter.TYPE_EQUAL, 
      null);
 
sf3.setValue(”i”+sf3.getWildCardChar());
sf3.negate();
 
SearchFilter sfArray2[] = new SearchFilter[] {cf1, sf3};
ComplexSearchFilter cf2 = 
   store.getComplexSearchFilter(sfArray2, ComplexSearchFilter.TYPE_AND); 

Example 22-5 Complete Search with Output

This example filters names starting with the letter "a" and outputs the return values:

// search filter (cn=a*)
SimpleSearchFilter sf = oidStore.getSimpleSearchFilter(
      UserProfile.NAME, 
      SimpleSearchFilter.TYPE_EQUAL, 
      null);
sf.setValue("a"+sf.getWildCardChar());
      
SearchParameters params = new SearchParameters();
params.setFilter(sf);
 
// Searching for users
SearchResponse resp = oidStore.searchUsers(params);
System.out.println("Searched users are:");
while (resp.hasNext()) {
   Identity idy = resp.next();
   System.out.println("Unique name: "+idy.getUniqueName());
}

Example 22-6 Obtaining the Identity of the Logged-in User

This example shows how to retrieve the logged-in user:

SimpleSearchFilter sf = oidStore.getSimpleSearchFilter(
      UserProfile.USER_NAME,  SimpleSearchFilter.TYPE_EQUAL, "sampleUserName");
   SearchParameters ssp = new SearchParameters(sf, SearchParameters.SEARCH_USERS_ONLY);
 
   // Searching for users
   SearchResponse resp = oidStore.searchUsers(ssp);
   System.out.println("Searched users are:");
   while (resp.hasNext()) {
       Identity idy = resp.next();
       String foundUserName = ((User)idy).getUserProfile().getUserName();
       System.out.println("Found user name: "+ foundUserName );
   }

Note:

The name returned by ((User)idy).getName is derived from the RDN, which might be different from the login name.

Example 22-7 Obtaining the Role/Group Name

This example shows how to retrieve the role (group) name:

Role aRole = idStore.searchRole(IdentityStore.SEARCH_BY_NAME, "sampleRoleName");
    Property prop = aRole.getRoleProfile().getProperty(RoleProfile.NAME);
   
    List roleList = prop.getValues();
    Iterator itr = roleList.iterator(); 
   System.out.println("Searched roles are:");
    while (itr.hasNext()) {
        String foundRoleName = (String)itr.next();
        System.out.println("Found role name: "+ foundRoleName );
    }

22.4.5 Searching by GUID

In this example, GUID values obtained from the User and Role API can be directly used in the search:

// up = user.getUserProfile();
String guid = up.getGUID();
SimpleSearchFilter sf1 = oidStore.getSimpleSearchFilter(
   UserProfile.GUID, 
   SimpleSearchFilter.TYPE_EQUAL, guid);
SearchParameters params = new SearchParameters();
params.setFilter(sf1);
SearchResponse resp = oidStore.search(params);
while (resp.hasNext())
   System.out.println("user for guid : " + guid + ","+ resp.next());

22.5 User Authentication

For verification purposes, you can use the User and Role API for password-based authentication of users. (As mentioned earlier, the API is not meant for authentication and authorization.)

The authenticateUser API accepts a user login name and attempts to authenticate the user with the specified password. If authentication is successful, it returns the user object.

Here is an example of password-based authentication:

store.getUserManager().authenticateUser(”testuser”,”password”);

22.6 Creating and Modifying Entries in the Identity Store

The User and Role API facilitates adding new identities to the identity store and modifying identities in the store. The UserManager and RoleManager classes address the user- and role-specific data creation, modification and deletion operations.

UserManager and RoleManager instances can be obtained from the store instance as follows:

UserManager um = oidStore.getUserManager();
RoleManager rm = oidStore.getRoleManager();

Topics in this section include:

22.6.1 Handling Special Characters when Creating Identities

RFC-2253 defines the string representation of Distinguished Names for LDAP v3. This means that all the characters specified in the RFC are handled. The User and Role API user does not need to escape/de-escape those special characters; attempting to do so will cause erroneous results.

There could be a problem when creating identities with empty properties. In this case, the "RDN name" is used to fill in the values of various mandatory attributes. Some of these attributes could have stricter validation rules. In this case, the creation of the identity fails and an exception is raised.

22.6.2 Creating an Identity

Two functions in the UserManager class facilitate creating a user:

  • createUser(java.lang.String name, char[] password)
    

    creates a user with the specified name and password in the underlying repository.

    When the identity store designates that some attributes are mandatory, all such fields will be populated with the "name" value.

  • createUser(java.lang.String name, char[] password, PropertySet suppliedProps)
    

    Properties are set using the supplied property values. If any mandatory attribute values are not supplied, the missing attributes will use the "name" value as the default.

Likewise, RoleManager APIs are used to create roles.

Roles are organized into two categories:

  • application scope

  • enterprise scope

When you invoke RoleManager to create a role, by default the role is created in the enterprise scope unless you specify otherwise.

RoleManager APIs supporting role creation are:

createRole(String roleName);
createRole(String roleName, int roleScope);

The procedure for creating a role is similar to that for creating a user, and all mandatory attributes must be supplied with roleName.

22.6.3 Modifying an Identity

To modify an identity, you need a reference to the identity. The User, UserProfile, Role, and RoleProfile classes provide the following APIs to facilitate modifying identities:

user.setProperty(ModProperty prop);
 
user.setProperties(ModProperty [] props);

ModProperty structure consists of:

  • the field name

  • its new value(s)

  • the modifying operator

Valid operators are:

ModProperty.ADD
ModProperty.REMOVE
ModProperty.REPLACE

In this example, a display name is replaced:

UserProfile usrprofile = usr.getUserProfile();
 
ModProperty mprop = new ModProperty(UserProfile.DISPLAY_NAME,
   "modified display name",
   ModProperty.REPLACE);
 
usrprofile.setProperty(mprop);

Modifying a particular value in a multi-valued attribute is a two-step process; first remove the value, then add the new value.

22.6.4 Deleting an Identity

You drop an identity with the dropUser and dropRole APIs.

You need both user and role references in your code when dropping an identity. Here is an example:

User usr;
Role role;
…
…
usrmanager.dropUser(usr);
rolemanager.dropRole(role);

22.7 Examples of User and Role API Usage

This section contains some examples illustrating practical applications of the User and Role API:

22.7.1 Example 1: Searching for Users

In this example the identity store is Oracle Internet Directory, and a simple search filter is set up to search for users:

import oracle.security.idm.*;
import oracle.security.idm.providers.oid.*;
import java.util.*;
import java.io.*;
 
public class SearchUsersOID
{
  public static void main(String args[])
  {
    IdentityStoreFactoryBuilder builder = new    
IdentityStoreFactoryBuilder();
    IdentityStoreFactory oidFactory = null;
    IdentityStore oidStore = null;
 
    try
    {
 
      Hashtable factEnv = new Hashtable();
      Hashtable storeEnv = new Hashtable();
 
      // creating the factory instance
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_PRINCIPAL,
                   "<User DN>");
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_CREDENTIALS, 
                   "<User password>");
      factEnv.put(OIDIdentityStoreFactory.ST_LDAP_URL,
                  "ldap://ldaphost:port/");
oidFactory =  builder.getIdentityStoreFactory(
              "oracle.security.idm.providers.oid.OIDIdentityStoreFactory", 
              factEnv);
      
      // creating the store instance
         storeEnv.put(OIDIdentityStoreFactory.RT_SUBSCRIBER_NAME,
         "<Subscriber name>");
      oidStore = oidFactory.getIdentityStoreInstance(storeEnv);
 
      // search filter (cn=a*)
      SimpleSearchFilter sf = oidStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null);
      sf.setValue("a"+sf.getWildCardChar());
// sf2 search filter (!(cn=*a)) 
SimpleSearchFilter sf2 = oidStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null);
sf2.setValue(sf2.getWildCardChar()+"a");
sf2.negate();
      
SimpleSearchFilter sfArray[] = new SimpleSearchFilter[] {sf,sf2};
ComplexSearchFilter cf1 = oidStore.getComplexSearchFilter(sfArray,
ComplexSearchFilter.TYPE_AND);
     
SearchParameters params = new SearchParameters();
params.setFilter(cf1);
 
 // Searching for users
SearchResponse resp = oidStore.searchUsers(params);
System.out.println("Searched users are:");
while (resp.hasNext()) {
    Identity idy = resp.next();
    System.out.println("Unique name: "+idy.getUniqueName());
}
    }catch (IMException e)
    {
      e.printStackTrace();
    }
  }
}

Searching for Users and Searching for Groups

When searching for users, you invoke UserProfile, as in the above example with SimpleSearchFilter. When searching for groups, however, you use RoleProfile instead.

22.7.2 Example 2: User Management in an Oracle Internet Directory Store

In this example several user management tasks such as creating, modifying, and dropping an identity are performed in an Oracle Internet Directory store:

  • creating a user

  • modifying the user's display name

  • dropping the user

public class CreateModifyDeleteUser
{
  public static void main(String args[])
  {
    IdentityStoreFactoryBuilder builder = new 
IdentityStoreFactoryBuilder();
    IdentityStoreFactory oidFactory = null;
    IdentityStore oidStore = null;
 
    try
    {
 
      Hashtable factEnv = new Hashtable();
      Hashtable storeEnv = new Hashtable();
 
      // creating the factory instance
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_PRINCIPAL,
                   "<User DN>");
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_CREDENTIALS, 
                   "<User password>");
      factEnv.put(OIDIdentityStoreFactory.ST_LDAP_URL,
                  "ldap://ldaphost:port/");
      oidFactory =  builder.getIdentityStoreFactory(
                  "oracle.security.idm.providers.oid.
OIDIdentityStoreFactory", 
               factEnv);
      
      // creating the store instance
      storeEnv.put(OIDIdentityStoreFactory.RT_SUBSCRIBER_NAME, 
                   "dc=us,dc=oracle,dc=com");
      oidStore = oidFactory.getIdentityStoreInstance(storeEnv);
 
      //get UserManager
      UserManager usrmanager = oidStore.getUserManager();
 
      // create user
      String usrname = "testuser";
      // delete user if already exists
      try
      {
        User usr = oidStore.searchUser(usrname);
        usrmanager.dropUser(usr);
      }catch(IMException ime){}
 
      System.out.println("creating user "+usrname);
      User usr = 
usrmanager.createUser(usrname,"passwd1".toCharArray());
      System.out.println("user (" +usr.getUniqueName() + ") created");
 
      // modifying user properties
      System.out.println("modifying property 
UserProfile.DISPLAY_NAME");
      UserProfile usrprofile = usr.getUserProfile();
      ModProperty mprop = new ModProperty(
UserProfile.DISPLAY_NAME,
                        "modified display name",
                        ModProperty.REPLACE);
 
      usrprofile.setProperty(mprop);
      
      System.out.println("get property values 
UserProfile.DISPLAY_NAME");
      Property prop = usrprofile.getProperty(UserProfile.DISPLAY_NAME);
      List values = prop.getValues();
      Iterator itr = values.iterator();
      while(itr.hasNext()) {
        System.out.println(UserProfile.DISPLAY_NAME+": "+ itr.next());
      }
      System.out.println();
 
      // drop user
      System.out.println("Now dropping user "+usrname);
      usrmanager.dropUser(usr);
      System.out.println("user dropped");
 
    }catch (IMException e)
    {
      e.printStackTrace();
    }
  }
}

22.7.3 Example 3: User Management in a Microsoft Active Directory Store

In this example several user management tasks such as creating, modifying, and dropping an identity are performed in a Microsoft Active Directory store:

  • creating a user

  • modifying the user's display name

  • dropping the user

package oracle.security.idm.samples;
 
import oracle.security.idm.*;
import oracle.security.idm.providers.ad.*;
import java.util.*;
import java.io.*;
 
public class CreateModifyDeleteUserAD
{
  public static void main(String args[])
  {
    IdentityStoreFactoryBuilder builder = new IdentityStoreFactoryBuilder();
    IdentityStoreFactory adFactory = null;
    IdentityStore adStore = null;
 
    try
    {
 
      Hashtable factEnv = new Hashtable();
      Hashtable storeEnv = new Hashtable();
 
      String keystore = "/home/bhusingh/client_keystore.jks";
      System.setProperty("javax.net.ssl.trustStore",keystore);
      System.setProperty("javax.net.ssl.trustStorePassword","welcome1");
 
      // creating the factory instance
      factEnv.put(ADIdentityStoreFactory.ST_SECURITY_PRINCIPAL,
                  "sramaset@xyzt.com");
      factEnv.put(ADIdentityStoreFactory.ST_SECURITY_CREDENTIALS, 
                   "ntrtntrt");
      factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
                  "ldaps://mynode.us.mycorp.com:123/");
      factEnv.put("java.naming.security.protocol","SSL");
      
 
      adFactory =  builder.getIdentityStoreFactory(
                    "oracle.security.idm.providers.ad.ADIdentityStoreFactory",
                    factEnv);
 
      // creating the store instance
      storeEnv.put(ADIdentityStoreFactory.ST_SUBSCRIBER_NAME, 
                   "dc=upad,dc=us,dc=oracle,dc=com");
      adStore = adFactory.getIdentityStoreInstance(storeEnv);
 
      //get UserManager
      UserManager usrmanager = adStore.getUserManager();
 
      // create user
      String usrname = "amyd";
      // delete user if already exists
      try
      {
        User usr = adStore.searchUser(usrname);
        usrmanager.dropUser(usr);
      }catch(IMException ime){}
 
      System.out.println("creating user "+usrname);
      char[] password = {'w', 'e', 'l', 'c', 'o', 'm','e','3'};
      User usr = usrmanager.createUser(usrname, password);
      System.out.println("user (" +usr.getUniqueName() + ") created with guid="+usr.getGUID());
      System.out.println("user name = "+usr.getName() );
 
      // modifying user properties
      System.out.println("DISPLAY_NAME="+usr.getDisplayName());
      System.out.println("modifying property UserProfile.DISPLAY_NAME");
      UserProfile usrprofile = usr.getUserProfile();
      ModProperty mprop = new ModProperty(UserProfile.DISPLAY_NAME,
                                          "modified display name",
                                          ModProperty.REPLACE);
      usrprofile.setProperty(mprop);
      
      System.out.println("get property values UserProfile.DISPLAY_NAME");
      Property prop = usrprofile.getProperty(UserProfile.DISPLAY_NAME);
      List values = prop.getValues();
      Iterator itr = values.iterator();
      while(itr.hasNext())
      {
        System.out.println(UserProfile.DISPLAY_NAME+": "+ itr.next());
      }
      System.out.println();
 
      System.out.println("now verifying the password");
      boolean pass = false;
      try
      {
        usrmanager.authenticateUser(usrname, password);
        pass= true;
      }catch (oracle.security.idm.AuthenticationException e) 
      {
        System.out.println(e);
        e.printStackTrace();
      }
      if (pass)
        System.out.println("password verification SUCCESS !!");
      else
        System.out.println("password verification FAILED !!");
 
      SimpleSearchFilter sf = adStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, usrname);
      
      SearchParameters params = new SearchParameters();
      params.setFilter(sf);
 
      // Searching for users
      SearchResponse resp = adStore.searchUsers(params);
      System.out.println("Searched users are:");
      while (resp.hasNext())
      {
        Identity idy = resp.next();
        System.out.println("name: "+idy.getName()+"\tUnique name: "+idy.getUniqueName());
      }
 
 
      // drop user
      System.out.println("Now dropping user "+usrname);
      usrmanager.dropUser(usr);
      System.out.println("user dropped");
 
    }catch (Exception e)
    {
      e.printStackTrace();
    }
  }
}

22.8 SSL Configuration for LDAP-based User and Role API Providers

This section describes SSL support for the User and Role API. It contains these topics:

22.8.1 Out-of-the-box Support for SSL

LDAP-based providers for the User and Role API rely on the Sun Java Secure Sockets Extension (JSSE) to provide secure SSL communication with LDAP-based identity stores. JSSE is part of JDK 1.4 and higher.

These LDAP providers are:

  • Microsoft Active Directory

  • Novell eDirectory

  • Oracle Directory Server Enterprise Edition

  • Oracle Internet Directory

  • OpenLDAP

  • Oracle WebLogic Server Embedded LDAP Directory

22.8.1.1 System Properties

To support SSL you must provide the following information in the form of system properties:

javax.net.ssl.keyStore
 
javax.net.ssl.keyStorePassword
 
javax.net.ssl.trustStore
 
javax.net.ssl.trustStorePassword

See the Java Secure Socket Extension (JSSE) Reference Guide (http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html) for complete information on JSSE.

22.8.1.2 SSL configuration

You need to provide SSL configuration details during User and Role API configuration.

Provide your keystore location and password as system properties to the JVM:

String keystore = "<key store location>";
String keypasswd = "<key store password>";
System.setProperty("javax.net.ssl.trustStore",keystore);
System.setProperty("javax.net.ssl.trustStorePassword", keypasswd);

Specify following properties in the environment when creating the IdentityStoreFactory instance:

  1. Set the SSL URL of the LDAP server, as in this example:

    factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
     "ldaps://ldaphost:sslport/");
    
  2. Set the security protocol to SSL:

    factEnv.put("java.naming.security.protocol","SSL");
    

22.8.2 Customizing SSL Support for the User and Role API

You can customize SSL support by providing a customized SSLSocketFactory to the User and Role API provider.

22.8.2.1 SSL configuration

Specify the following properties when creating the IdentityStoreFactory instance:

  1. Specify the custom SSL socket factory name:

    factEnv.put("java.naming.ldap.factory.socket", 
    "fully qualified custom socket factory name");
    
  2. Set the SSL URL of the LDAP server, as in this example:

    factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
     "ldaps://ldaphost:sslport/");
    
  3. Set the security protocol to SSL:

    factEnv.put("java.naming.security.protocol","SSL");
    

22.9 The User and Role API Reference

The User and Role API reference (Javadoc) is available at:

Oracle Fusion Middleware User and Role Java API Reference for Oracle Platform Security Services

22.10 Developing Custom User and Role Providers

This section explains how to develop custom providers that security developers can use to manage identities (users and roles). It contains these topics:

22.10.1 SPI Overview

The User and Role API is accompanied by a service provider interface (SPI) that makes it possible to develop custom user/role providers. You can use the service provider interface to develop a custom provider for any identity data repository.

The SPI is bundled as the oracle.security.idm.spi package, which is a set of abstract classes. Custom User and Role providers are created by extending this SPI to fit your requirements.

22.10.2 Types of User and Role Providers

The User and Role API offers functions for both search and Create/Read/Update/Delete (CRUD) operations. A User and Role provider based on read-only functions supports only search operations. A full-featured provider supports both search operations and CRUD operations. In other words, the full-featured provider is a superset of a read-only provider.

As a developer you have the choice of creating either read-only or full-functionality providers depending upon the requirements.

It is reasonable to develop a read-only provider in the following situations:

  • if the underlying identity repository operates in read-only mode

  • if applications consuming the User and Role API do not make any CRUD API calls

For example, it makes sense to develop a read-only provider for use with the SOA identity service.

22.10.3 Developing a Read-Only Provider

This section describes the classes used to implement a provider. Topics include:

22.10.3.1 SPI Classes Requiring Extension

Table 22-5 shows that SPI classes that must be extended to implement a read-only provider:


Note:

All abstract methods must be implemented.

Table 22-5 SPI Classes to Extend for Custom Provider

ClassUsage Notes

oracle.security.idm.spi.AbstractIdentityStoreFactory

The extending class must include a default constructor and a constructor accepting a java.util.Hashtable object.

oracle.security.idm.spi.AbstractIdentityStore


oracle.security.idm.spi.AbstractRoleManager


oracle.security.idm.spi.AbstractUserManager


oracle.security.idm.spi.AbstractRoleProfile


oracle.security.idm.spi.AbstractUserProfile


oracle.security.idm.spi.AbstractSimpleSearchFilter

The constructor of the extending class must call the constructor of the abstract (super) class.

oracle.security.idm.spi.AbstractComplexSearchFilter

The constructor of the extending class must call the constructor of the abstract (super) class.

oracle.security.idm.spi.AbstractSearchResponse



Additional requirements and notes for each class are provided below.

22.10.3.2 oracle.security.idm.spi.AbstractIdentityStoreFactory

The class extending this SPI class must have following constructors:

  1. The default constructor (one which has no arguments).

  2. A constructor that accepts a java.util.Hashtable object as an argument. You can use the hash table to accept any configuration properties required by the provider.

    The configuration properties are passed to this constructor during the user and role configuration phase. The properties are key-value pairs passed in the Hashtable argument:

    • The key must be java.lang.String.

    • The value can be java.lang.Object.

It is recommended that the value be of type String. This guarantees that the property can be specified in jps-config.xml, which is a text file.


See Also:

"The User and Role SPI Reference" for details about the methods that need to be implemented in this class. All listed methods must be implemented.

22.10.3.3 oracle.security.idm.spi.AbstractIdentityStore

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Note that:

  • Method getStoreConfiguration() is optional and can throw OperationNotSupportedException.

  • Method getSubjectParser() can return null.

When there are no search results to be returned, all search APIs should throw:

oracle.security.idm.ObjectNotFoundException 

Never return an empty SearchResponse.

22.10.3.4 oracle.security.idm.spi.AbstractRoleManager

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Note that only the following methods need concrete/actual implementations:

  • getGrantedRoles()

  • getOwnedRoles()

  • getManagedRoles()

  • isGranted()

  • isManagedBy()

  • isOwnedBy()

  • isDropRoleSupported() – should always return false

  • isCreateRoleSupported() – should always return false

  • isModifyRoleSupported() – should always return false

The remaining methods must throw the following in their respective implementations:

oracle.security.idm.OperationNotSupportedException 

22.10.3.5 oracle.security.idm.spi.AbstractUserManager

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Only the following methods need concrete/actual implementations:

  • authenticateUser(User, char[])

  • authenticateUser(String, char[])

  • isDropUserSupported() – should always return false

  • isCreateUserSupported() – should always return false

  • isModifyUserSupported() – should always return false

The remaining methods must throw the following in their respective implementations:

oracle.security.idm.OperationNotSupportedException 

22.10.3.6 oracle.security.idm.spi.AbstractRoleProfile

oracle.security.idm.spi.AbstractRoleProfile is an abstract class that can be used to return a detailed role profile.

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Only the following methods need concrete/actual implementations:

  • getDisplayName()

  • getGUID()

  • getName()

  • getUniqueName()

  • getPrincipal()

  • getDescription()

  • getGrantees()

  • getManagers()

  • getOwners()

  • getProperty() - If requested property is not set/valid for corresponding role then null should be returned as value.

  • isApplicationRole() - must always return false

  • isEnterpriseRole() - must always return false

  • isSeeded() - must always return false

  • getRoleProfile() – should return reference to current object.

The remaining methods must throw the following in their respective implementations:

oracle.security.idm.OperationNotSupportedException 

22.10.3.7 oracle.security.idm.spi.AbstractUserProfile

oracle.security.idm.spi.AbstractUserProfile is an abstract class that can be used to return a detailed user profile.

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Only the following methods need concrete/actual implementations:

  • getDisplayName()

  • getGUID()

  • getName()

  • getUniqueName()

  • getPrincipal()

  • getProperty() - If the requested property is not set/valid for corresponding role then a null value must be returned.

  • getProperties() – If the requested property is not set/valid for the corresponding user, then a null value must be returned.

  • getAllUserProperties() – Only the properties set for the corresponding user should be returned.

  • getReportees()

  • getManagementChain()

  • getUserProfile() – must return reference to current object.

These two methods:

  • setProperty()

  • setProperties()

must throw the following in their implementation:

oracle.security.idm.OperationNotSupportedException 

22.10.3.8 oracle.security.idm.spi.AbstractSimpleSearchFilter

oracle.security.idm.spi.AbstractSimpleSearchFilter is an abstract class that can be extended to implement a simple search filter.

The implementing class must have a constructor that calls the constructor of the abstract class:

AbstractSimpleSearchFilter (
   String attrname, int type, Object value)

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Only the following methods need concrete/actual implementations:

  • getNativeRepresentation() – convert filter into the native representation to be used with the underlying identity repository.

  • getWildCardChar() – wild card character, for example "*", to be used in searches. The specific character depends on the underlying identity repository.

22.10.3.9 oracle.security.idm.spi.AbstractComplexSearchFilter

oracle.security.idm.spi.AbstractComplexSearchFilter is an abstract class that can be extended to implement a search filter of any complexity.

The implementing class must have a constructor that calls the constructor of the abstract class:

AbstractComplexSearchFilter (
   oracle.security.idm.SearchFilter[] filters, int oper_type)

"The User and Role SPI Reference" provides details about the methods that need to be implemented in this class. Only the following methods need concrete/actual implementations:

  • getNativeRepresentation() – convert the filter into the native representation to be used with the underlying identity repository.

22.10.3.10 oracle.security.idm.spi.AbstractSearchResponse

The SearchResponse object contains search results being returned from a repository. Each result entry corresponds to one user or role in the underlying identity repository, represented by the corresponding UserProfile/RoleProfile class implementation.

The SearchResponse object must return one or more results. This means that the hasNext() method must return TRUE at least once.

Do not use if there are zero results to return. When no results are to be returned, the corresponding search API should throw the following exception:

oracle.security.idm.ObjectNotFoundException

22.10.4 Developing a Full-Featured Provider

The full-featured provider implements all the functionality supported by a read-only provider, and additionally supports CRUD operations. This requires that the CRUD APIs be implemented in the SPI implementation classes.

In the read-only provider, these APIs were implemented simply by throwing an OperationNotSupportedException (see the class descriptions in Section 22.10.3, "Developing a Read-Only Provider").

For a full-featured provider, this needs to be replaced by concrete/actual implementation of the corresponding CRUD operations.

22.10.5 Development Guidelines

This section provides some guidelines for developing providers.

Mapping of Names

Be aware of the usage of naming constants such as UserProfile.NAME, UNIQUE_NAME, UserProfile.USER_NAME, UserProfile.USER_ID.

  • NAME – name of the user or role in the underlying repository.

  • UNIQUE_NAME – Complete name with which the user or role is represented in the underlying repository.

  • USER_NAME – login ID of the user in the underlying repository.

  • USER_ID – always same as USER_NAME constant mapping.

Depending on the identity repository, these constants might map to the same underlying identity repository attribute or they might map to different attributes. If the underlying repository is an LDAP v3 server, the mappings are as follows:

  • NAME – mapped to naming attribute of user/group entry, for example "cn"

  • UNIQUE_NAME - mapped to "DN" of user/group entry

  • USER_NAME/USER_ID – mapped to login attribute, for example "uid" or "mail"

Thread Safety

The following objects are likely to be shared among multiple threads:

  • IdentityStoreFactory,

  • IdentityStore,

  • UserManager,

  • RoleManager

You should ensure that there are no thread safety-related issues in the corresponding implementation classes of your provider.

22.10.6 Testing and Verification

The User and Role API ships with a test suite to enable you to test the basic operations of providers that you develop.

The test suite can be used to test both read-only and full-featured providers.

Usage

java oracle.security.idm.tests.SPITest propertiesfile

where propertiesfile contains the provider class name and any configuration data for the provider. It also contains information about the tests to be run. You need to edit this file and update it with correct information before running the tests; the file contents are self-explanatory. One such file (ffprovider.properties) is available with the sample provider discussed in Section 22.10.7.1, "About the Sample Provider".

Results

The test will produce the results on-screen. All providers that you develop must pass the "Lookup tests", "Role membership tests" and "Profile tests" in the test suite. Full-featured providers must pass all the tests in the suite including Create/Drop tests.

The log of test results will be output to the file results.out in current working directory.

22.10.7 Example: Implementing an Identity Provider

The distribution includes a sample identity provider that you can use to understand how custom providers are built.

This section describes how to access the sample provider, and explains the steps needed to implement a custom provider. The steps rely on the sample for illustration.

22.10.7.1 About the Sample Provider

To help you develop providers, a sample provider is available from Oracle Technology Network. To work with this provider:

  1. Navigate to the sample content page at:

    http://www.oracle.com/technetwork/testcontent/index.html

  2. In the Search box, search for sampleprovider-157582.zip.

  3. Download and unzip the file. It will generate the following strucrtture:

    sampleprovider/
          build.xml - ant build file
          ffprovider.properties - properties file required for testing
          jlib - provider jar file location
          out -  location of generated class files
          samples - Folder for samples
          src - provider source code
    
  4. Run ant help for instructions on building and testing this provider.

The provider relies on an ad-hoc identity repository for fetching identity information and has been tested with Oracle SOA Suite. It is not intended for production use without appropriate testing for your environment.

22.10.7.2 Overview of Implementation

The sample identity provider used in this example is a custom Identity/Authentication provider that uses an RDBMS as the underlying store. It can be used as both an identity provider and an authentication provider.


Note:

The sample provider is intended solely for demonstration purposes, and it is not advisable to use this provider in production without exhaustive testing.

These steps are required to set up the sample provider:

  1. Implement the User and Role APIs to access the database repository serving as the identity store. This involves:

    1. Building the sample provider. Run ant help for instructions.

    2. Creating the identity store schema in the database.

  2. Configure the sample provider as the identity store, as shown in Section 22.10.7.3, "Configure jps-config.xml to use the Sample Identity Provider".

  3. Set up Weblogic Authenticator to use this provider as SQLAuthenticator, as explained in Section 22.10.7.4, "Configure Oracle WebLogic Server".

22.10.7.3 Configure jps-config.xml to use the Sample Identity Provider

Configure jps-config.xml as follows to enable the sample identity provider to be used as the identity store:

  1. Add a new provider in the service providers list:

    <serviceProviders>
          ............
         <serviceProvider type="IDENTITY_STORE" name="custom.provider"  class="oracle.security.jps.internal.idstore.generic.GenericIdentityStoreProvider">
              <description>Custom IdStore Provider</description>
        </serviceProvider>
    </serviceProviders>
    
  2. Add the service instance:

    <serviceInstances>
    ........
        <serviceInstance name="idstore.custom" provider="custom.provider"           location="dumb">
           <description>Custom Identity Store Service Instance</description>
           <property name="idstore.type" value="CUSTOM"/>
           <property name="ADF_IM_FACTORY_CLASS" 
             value="custom_provider_identityStoreFactoryClassName"/>
           <property name="DB_SERVER_NAME" value="db_server_name"/>                     <property name="DB_SERVER_PORT" value="db_port"/>
           <property name="DB_DATABASE_NAME" value="db_service_name"/>
           <property name="ST_SECURITY_PRINCIPAL" value="user_name"/> 
           <property name="ST_SECURITY_CREDENTIALS" value="password"/> 
       </serviceInstance>
    ........
    <serviceInstances>
    

    Note:

    custom_provider_identityStoreFactoryClassName for the sample provider is org.sample.providers.db.DBIdentityStoreFactory

  3. Ensure that the default jpsContext points to the identity store service instance added in Step 2 above:

    <jpsContext name="default">
        <serviceInstanceRef ref="credstore"/>
        <serviceInstanceRef ref="keystore"/>
        <serviceInstanceRef ref="policystore.xml"/>
        <serviceInstanceRef ref="audit"/>
        <serviceInstanceRef ref="idstore.custom"/>
    </jpsContext>
    
  4. Add the path of the custom provider jar to the classpath.

  5. Restart the server.

22.10.7.4 Configure Oracle WebLogic Server

The final task is to configure Oracle WebLogic Server to use SQLAuthenticator. The steps are as follows:

  1. Log in to the Oracle WebLogic Server console. Select Security Realms, then myrealm, then Providers. Click New to add a new provider.

  2. Enter a name for the provider and select SQLAuthenticator as the authenticator type.

  3. On the Providers page, click on the newly created authenticator.

  4. Set the Control Flag to SUFFICIENT. Click Save.

  5. Set the control flag to sufficient for all authenticators in the list.

  6. Click on the "Provider Specific" tab to enter the details for the authenticator server. Enter the DataSource name that was used to create the schema for the provider. Click Save.

  7. Return to the Providers tab and reorder the providers so that SQLAuthenticator is at the top of the list.

The User and Role SPI Reference

This section contains the User and Role SPI reference (Javadoc), describing each abstract class in the SPI with package name oracle.security.idm.spi. The classes are:

oracle.security.idm.spi.AbstractUserProfile

This class represents a detailed user profile and enables you to set or obtain attributes of the user profile.

Constructors

public AbstractUserProfile() 

Methods

public void setPassword(        char[] oldPasswd,         char[] newPasswd) 
public byte[] getUserCertificate() 
public void setUserCertificate( byte[] cert) 
public java.lang.String getEmployeeNumber() 
public void setEmployeeNumber(  String employeeNumber) 
public java.lang.String getBusinessPostalAddr() 
public void setBusinessPostalAddr(      String addr) 
public java.lang.String getBusinessPOBox() 
public void setBusinessPOBox(   String pobox) 
public byte[] getJPEGPhoto() 
public void setJPEGPhoto(       String imgpath) 
public java.lang.String getTimeZone() 
public void setTimeZone(        String zone) 
public java.lang.String getDescription() 
public void setDescription(     String desc) 
public java.lang.String getDepartmentNumber() 
public void setDepartmentNumber(        String departmentnumber) 
public java.lang.String getGivenName() 
public void setGivenName(       String givenname) 
public java.lang.String getBusinessEmail() 
public void setBusinessEmail(   String email) 
public java.lang.String getBusinessPager() 
public void setBusinessPager(   String pager) 
public java.lang.String getOrganization() 
public void setOrganization(    String org) 
public void setName(    String name) 
public java.lang.String getBusinessCity() 
public void setBusinessCity(    String city) 
public java.lang.String getMaidenName() 
public void setMaidenName(      String maidenname) 
public java.lang.String getDepartment() 
public void setDepartment(      String dept) 
public java.lang.String getBusinessFax() 
public void setBusinessFax(     String fax) 
public java.lang.String getUserName() 
public void setUserName(        String uname) 
public java.lang.String getBusinessMobile() 
public void setBusinessMobile(  String mobile) 
public java.lang.String getDateofHire() 
public void setDateofHire(      String hiredate) 
public java.lang.String getTitle() 
public void setTitle(   String title) 
public java.lang.String getNameSuffix() 
public void setNameSuffix(      String suffix) 
public java.lang.String getMiddleName() 
public void setMiddleName(      String middlename) 
public java.lang.String getHomePhone() 
public void setHomePhone(       String homephone) 
public void setDisplayName(     String dispname) 
public java.lang.String getEmployeeType() 
public void setEmployeeType(    String emptype) 
public java.lang.String getLastName() 
public void setLastName(        String lastname) 
public java.lang.String getDateofBirth() 
public void setDateofBirth(     String dob) 
public java.lang.String getManager() 
public void setManager( String manager) 
public java.lang.String getBusinessState() 
public void setBusinessState(   String state) 
public java.lang.String getHomeAddress() 
public void setHomeAddress(     String homeaddr) 
public java.lang.String getBusinessStreet() 
public void setBusinessStreet(  String street) 
public java.lang.String getBusinessPostalCode() 
public void setBusinessPostalCode(      String postalcode) 
public java.lang.String getInitials() 
public void setInitials(        String initials) 
public java.lang.String getUserID() 
public void setUserID(  String userid) 
public java.lang.String getFirstName() 
public void setFirstName(       String firstname) 
public java.lang.String getDefaultGroup() 
public void setDefaultGroup(    String defgroup) 
public java.lang.String getOrganiztionalUnit() 
public void setOrganizationalUnit(      String ouUnit) 
public java.lang.String getWirelessAcctNumber() 
public void setWirelessAcctNumber(      String wirelessacct) 
public java.lang.String getBusinessPhone() 
public void setBusinessPhone(   String phone) 
public java.lang.String getBusinessCountry() 
public void setBusinessCountry( String country) 
public java.lang.String getPreferredLanguage() 
public void setPreferredLanguage(       String language) 
public java.lang.String getUIAccessMode() 
public void setUIAccessMode(    String accessMode) 
public java.lang.Object getPropertyVal( String prop) 
public oracle.security.idm.SearchResponse getReportees( boolean direct) 
public java.util.List getManagementChain(       int max,        String upToManagerName,         String upToTitle) 
public oracle.security.idm.PropertySet getAllUserProperties() 


oracle.security.idm.spi.AbstractUserManager

This class represents a user manager and includes basic authentication methods.

Constructors

public AbstractUserManager() 

Methods

public oracle.security.idm.User authenticateUser(
   String user_id, String authProperty, char[] passwd)
 
public oracle.security.idm.User authenticateUser(
   User user, char[] passwd) 

oracle.security.idm.spi.AbstractUser

This class represents a user.

Constructors

public AbstractUser() 

Methods

None.

oracle.security.idm.spi.AbstractSubjectParser

This abstract class provides a constructor for a subject parser.

Constructors

public AbstractSubjectParser() 

Methods

None

oracle.security.idm.spi.AbstractStoreConfiguration

This abstract class provides a constructor for identity store configuration.

Constructors

public AbstractStoreConfiguration() 

Methods

None

oracle.security.idm.spi. AbstractSimpleSearchFilter

This abstract class represents a simple search filter that can be used to search the identity store. Each simple filter consists of a search attribute, matching operator type, and value. Search results are filtered based on this condition. This class is abstract as its actual underlying representation (provided by method @link #getNativeRepresentation()) is implementation-specific. A service provider can extend this class by setting up a specific implementation of that method.

Constructors

public AbstractSimpleSearchFilter(
   String attrname, int type, Object value) 

Methods

Table 22-6 lists the methods of AbstractSimpleSearchFilter.

Table 22-6 Methods of AbstractSimpleSearchFilter

MethodDescription
public void setAttribute(       String name) 

Set attribute name. .

public void setType(int type) 

Set filter type.

public void setValue(Object value) 

Set attribute value.

public java.lang.String getAttributeName() 

Retrieve attribute name.

public java.lang.Object getValue() 

Retrieve attribute value.

public int getType() 

Retrieve filter type.

public void setNegate() 

Negate the current NOT state of the search filter. Behaves like a toggle switch.

public void negate() 

Negate the current NOT state of the search filter. Behaves like a toggle switch.

public boolean isNegated() 

Return the current NOT state of the search filter. Returns true if the NOT operator is set; false otherwise.


oracle.security.idm.spi.AbstractSearchResponse

This is an abstract class that represents search response results.

Constructors

public AbstractSearchResponse() 

Methods

None.

oracle.security.idm.spi.AbstractRoleProfile

This class represents the detailed profile of a role.

Constructors

public AbstractRoleProfile() 

Methods

public oracle.security.idm.SearchResponse getManagers(
   SearchFilter filter,    boolean direct) 

public oracle.security.idm.SearchResponse getManagers(
   SearchFilter filter) 

public oracle.security.idm.SearchResponse getOwners(
   SearchFilter filter, boolean direct) 

public oracle.security.idm.SearchResponse getOwners(
   SearchFilter filter) 

public void addManager(
   Principal principal) 

public void removeManager(
   Principal principal) 

public void addOwner(
   Principal principal) 

public void removeOwner(
   Principal principal) 

public boolean isOwnedBy(
   Principal principal) 

public boolean isManagedBy(
   Principal principal) 

public void addOwner(
   User user) 

public void removeOwner(
   User user) 

public void setDisplayName(
   String displayName) 

public void setDescription(
   String discription) 

public java.lang.String getDescription() 

public oracle.security.idm.Property getProperty(
   String propName) 

oracle.security.idm.spi.AbstractRoleManager

This class is an abstract representation of a role manager.

Constructors

public AbstractRoleManager() 

Methods

public boolean isOwnedBy(
   Role role, Principal principal) 

public boolean isManagedBy(
   Role role, Principal principal) 

public oracle.security.idm.SearchResponse getOwnedRoles(
   Principal principal, boolean direct) 

public oracle.security.idm.SearchResponse getManagedRoles(
   Principal principal, boolean direct)

oracle.security.idm.spi.AbstractRole

This class provides a constructor for a role.

Constructors

public AbstractRole() 

Methods

None

oracle.security.idm.spi.AbstractIdentityStoreFactory

This class represents an identity store factory.


See Also:

"IdentityStoreFactory" in Table 22-1.

Constructors

public AbstractIdentityStoreFactory() 

Methods

public oracle.security.idm.IdentityStore getIdentityStoreInstance() 

oracle.security.idm.spi.AbstractIdentityStore

This abstract class represents an identity store.

Constructors

public AbstractIdentityStore() 

Methods

public oracle.security.idm.RoleManager getRoleManager() public oracle.security.idm.UserManager getUserManager() public java.util.List getMandatoryUserPropertyNames() public java.util.List getUserPropertySchema() 

oracle.security.idm.spi.AbstractComplexSearchFilter

This class represents a complex search filter. This type of search filter is used to combine multiple SearchFilter instances with a single boolean AND or OR operator. Each of the component search filters can itself be a complex filter, enabling you to form nested search filters with a high degree of complexity.

This class is abstract in that its actual underlying representation, provided by the @link #getNativeRepresentation() method, is implementation-specific.

A service provider can extend this class by creating a specific implementation of this method.

Constructors

public AbstractComplexSearchFilter(     SearchFilter[] filters,   int oper_type) 

Methods

Table 22-7 Methods of Complex Search Filter

MethodDescription

public void addFilterComponent( SearchFilter filter)

Add the SearchFilter component to this complex filter's list.

public void setNegate()

Negate the current NOT state of the search filter. Behaves like a toggle switch.

public void negate()

Negate the current NOT state of the search filter. Behaves like a toggle switch.

public boolean isNegated()

Return the current NOT state of the search filter. Returns true if the NOT operator is set; false otherwise.

public int getOperatorType()

Logical operator type which binds together the SearchFilter components.


PK]trtPK].FOEBPS/introroles.htm Understanding Users and Roles

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 23, "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, "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, "The Anonymous User and Role." For details about the authenticated role, see Section 2.3, "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 18.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.

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 Role Mapping

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

RolePermission GrantedActual 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 18.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 18.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:

  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 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 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 WebLogic Server Administration Console Online Help, and 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 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 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.

PK!PK].F OEBPS/lof.htm List of Figures PKPK].FOEBPS/part_uad.htm Understanding Security Concepts PKPK].FOEBPS/part_gs.htm Basic OPSS Administration

Part II

Basic OPSS Administration

This part describes basic OPSS administration features in the following chapters:

PKȔPK].FOEBPS/content.opf= Oracle® Fusion Middleware Securing Applications with Oracle Platform Security Services, 12c (12.1.2) en-US E39179-04 Oracle Corporation Oracle Corporation Oracle® Fusion Middleware Securing Applications with Oracle Platform Security Services, 12c (12.1.2) 2015-06-16T07:58:02Z Describes features, administration, and development of application security with Oracle Platform Security Services. PK3 ==PK].FOEBPS/aptrouble.htm Troubleshooting OPSS

J Troubleshooting OPSS

This appendix describes common problems that you may encounter when configuring and using OPSS, and explains how to solve them.

It contains the following sections:

J.1 Diagnosing Security Errors

This section describes the tools available to diagnose and solve a variety of security errors. It contains the following sections:

The logging support with Fusion Middleware Control is explicitly stated when the tool can help managing, isolating, or interpreting faults.

J.1.1 Log Files and OPSS Loggers

This section describes the various log files and OPSS loggers supported by Oracle WebLogic Server; it also explains how to configure, set logger levels, and locate and view log files with Fusion Middleware Control and WLST commands, in the following sections:

J.1.1.1 Diagnostic Log Files

Each server instance in a domain writes all OPSS-based exceptions raised by its subsystems and applications to a server log file in the file system of the local host computer.

By default, this log file is located in the logs directory below the server instance root directory. The names of these log files have the following format: ServerName-diagnostic.logxxxxx, where xxxxx denotes an integer between 1 and 99999.

Here are some examples of diagnostic file full names: DomainName/servers/AdminServer/logs/AdminServer-diagnostic.log00001 (administration server log), DomainName/servers/soa/logs/soa-diagnostic.log00013 (managed server log).

All server instances output security-related errors to diagnostic files. Server-related security errors, such as exceptions raised by issues with a subject or principal, and errors that may occur while migrating or reassociating domain security data, get written in the administration server diagnostic log. Application-related security errors, such as exceptions raised by application-specific policies or credentials, get written in the corresponding managed server diagnostic log.

J.1.1.2 Generic Log Files

In addition to diagnostic log files, Oracle WebLogic Server supports other log files for each server in a domain and for each domain in a topology.

By default and similar to diagnostic log files, server log files are located in the logs directory below the server instance root directory. Domain log files are located in the logs directory below the administration server root directory. The names of these log files have the format ServerName.logxxxxx and domain.logxxxxx, where xxxxx denotes an integer between 1 and 99999.

Here are some examples of server and domain log files full names: DomainName/servers/AdminServer/logs/AdminServer.log00001, DomainName/servers/AdminServer/logs/domain1.log00033.

Server and domain logs are files where one should look for generic errors, such as exception raised by authenticators or other domain service providers.

The domain logs duplicate some messages written to server logs (for servers in the domain), and they help determine the server on which a fault has occurred in a domain that contains a large number of servers.


Note:

The generation of a new log file is determined by its rotation policy; typically, the rotation is determined by file size, so when a log file exceeds a specified size, the system generates a new one with a name whose integer suffix is increased by 1.

For details about particular loggers, see Authorization Loggers and Audit Loggers.

Related Documentation

For information about server log files and domain log files, see section Server Log Files and Domain Log Files in Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server.

For information about the Oracle WebLogic Framework, see Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

For additional information about logging services, see Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.

For complete details about logging in Oracle Fusion Middleware, see chapter Managing Log Files and Diagnostic Data in Administering Oracle Fusion Middleware.

J.1.1.3 Authorization Loggers

OPSS provides two loggers that help troubleshooting runtime authorization failures:

These two loggers, as any other OPSS logger, can be enabled and disabled dynamically, that is, without having to stop and restart the Oracle WebLogic Application Server; for details about setting the properties of a logger, see Managing Loggers with Fusion Middleware Control. Typically, the level of loggers is set to TRACE:32.

For information about additional loggers, see Other OPSS Loggers.

J.1.1.3.1 oracle.security.jps.util.JpsAuth

The logger oracle.security.jps.util.JpsAuth logs the start and return of the method checkPermission; the following snippets of a log file illustrate the entry and exit demarcations to this method in the log file:

[SRC_CLASS: oracle.security.jps.util.JpsAuth] [APP: JeeScenarioApp] 
[SRC_METHOD: Entering checkPermission] ENTRY
(oracle.security.jps.ResourcePermission
resourceType=TaskFlowResourceType,resourceName=ResourceNameX read)
 
[SRC_CLASS: oracle.security.jps.util.JpsAuth] [APP: JeeScenarioApp] 
[SRC_METHOD: Exiting checkPermission] RETURN 
java.security.AccessControlException: access denied (oracle.security.jps.ResourcePermission
resourceType=TaskFlowResourceType,resourceName=ResourceNameX read)

The following snippet illustrates a successful authorization log:

[JpsAuth] Check Permission
PolicyContext: [JeeScenarioApp]
Resource/Target: [getSubjectFromDomainCombiner]
Action:[null]
Permission Class: [javax.security.auth.AuthPermission]
       Result:               [SUCCEEDED]
       Subject:              [null]
       Evaluator:            [SM]

The following snippet illustrates an unsuccessful authorization log:

[JpsAuth] Check Permission
PolicyContext: [JeeScenarioApp]
Resource/Target: [resourceType=TaskFlowResourceType,resourceName=ResourceNameX]
Action:[read]
Permission Class: [oracle.security.jps.ResourcePermission]
       Result:               [FAILED]
       Evaluator:            [ACC]
       Failed
J.1.1.3.2 oracle.security.jps.trace.logger

The logger oracle.security.jps.trace.logger logs information about application roles, permissions, targets, principals, and granted and denied policies. Since enabling this logger can lead to a large output, it is recommended that it be used to debug a single use case only. Specifically, this logger records:

  • The following information about an authorization request: the application roles granted to an enterprise role, all deny's and grant's, the permission class names, the permission targets, and the principal names.

  • Member cache updates, such as when a principal is added to a role; keywords: "Principal:", "Inserted Roles:".

  • Role managing information; keywords: "In App:", "Query Store for Principal:", "Number of direct app roles:".

  • Calls to the method getPermissions.

J.1.1.4 Offline WLST Commands Loggers

When using an offline WLST commands, such as migrateSecurityStore, OPSS loggers can be enabled by starting the JVM with the following system properties:

-Dwlst.offline.log
-Dwlst.offline.log.priority 

Set these properties as follows:

  • wlst.offiline.log can have one of the following values: <filename>, stdout, sterr, or disable. If this property is not set explicitly, the log files get created, by default, in the directory $MW_HOME/logs.

  • wlst.offline.log.priority can have one of the following values: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, debug, info, warn, error, fatal.

J.1.1.5 Other OPSS Loggers

In addition to authorization loggers, OPSS provides the following loggers:

oracle.jps.common enables diagnosing issues with the OPSS JpsFilter and the OPSS JpsInterceptor.

oracle.jps.deployment enables diagnosing issues with OPSS artifacts packed with the application, when the application is deployed; keyword:"migration".

oracle.jps.openaz enables diagnosing issues with PEP API calls. Setting oracle.jps.openaz.level to FINEST, logs information about submitted requests - identity, resource, action, context - and authorization results.

J.1.1.6 User and Role API Logger

To trace OPSS User and Role API calls, set the logger oracle.idm.userroleapi to TRACE:32.

J.1.1.7 Audit Loggers

There are several run-time components in the Fusion Middleware Audit Framework. This section helps you navigate the diagnostic log files for these components and explains how to interpret diagnostic messages.

The log files are located at:

DomainName/servers/$SERVER_NAME/logs/$SERVER_NAME-diagnostic.log

Table J-1 lists the various diagnostic log files.

Table J-1 Log Files for Audit Diagnostics

ComponentLog LocationConfiguring Loggers

Java EE Components using Audit APIs

DomainName/servers/$SERVER_NAME/logs/$SERVER_NAME-diagnostic.log

oracle.security.audit.logger (See instructions below)

OPMN Components Using Audit APIs

See Section J.1.1.7.3.

See Section J.1.1.7.3.

Startup Class Audit Loader

DomainName/servers/$SERVER_NAME/logs/$SERVER_NAME-diagnostic.log

oracle.security.audit.logger (See instructions following this table)

OPMN Audit Loader

$ORACLE_INSTANCE/diagnostics/logs/OPMN/opmn/rmd.out

java.util.logging.config.file system property can be set to the file that contains the log level for OPMN Audit Loader

Config/Proxy Mbeans

DomainName/servers/$SERVER_NAME/logs/$SERVER_NAME-diagnostic.log

oracle.security.audit.logger (See instructions below)

Audit Schema Support

RCU log location (Default is $ORACLE_HOME/rcu/log/)RCU_LOG_LOCATION can be set to change this location

RCU log level (Default is ERROR) RCU_LOG_LEVEL - [SEVERE; ERROR; NOTIFICATION; TRACE


J.1.1.7.1 Configuring the Audit Loggers

You can configure oracle.security.audit.logger using Fusion Middleware Control.

oracle.security.audit.logger can take any log level from ERROR to TRACE allowing control over the amount of information that gets logged.

You can also view these diagnostic files with Fusion Middleware Control.


See Also:

For more information about the following topics, see chapter 10, Managing Log Files and Diagnostic Data, in Administering Oracle Fusion Middleware:
  • instructions for configuring the loggers

  • details on viewing logs from domain, server, and each application


J.1.1.7.2 Interpreting Audit Diagnostics

The Audit diagnostic messages can be categorized into two types - errors and trace messages.

All error messages are numbered IAU-XXX. These messages are found in the Error Message Guide with a proper cause and an action that can be taken to rectify the error.

The trace messages, however, are meant to provide more information about the running components. Depending on its nature, a message may require some action on your part.

J.1.1.7.3 Configuring Audit Logging for OPMN Components

You can configure audit logging for system components managed with OPMN.

Using the auditconfig.xml configuration file, you can specify the log directory location to which the component's audit logs should be written. Use the LogsDirectory element to specify the audit log location. In the following example, the log is located at /tmp/audit/auditlogs:

<LogsDirectory>
   <MaxFileSize></MaxFileSize>
   <Location>/tmp/audit/auditlogs</Location>
</LogsDirectory>

J.1.1.8 Managing Loggers with Fusion Middleware Control

Fusion Middleware Control provides several pages to manage log information. Using this tool you can:

  • Configure several attributes of a log file, including the log level and rotation.

  • Search the contents of all log files in a domain and group the results of a query by message ID or type.

  • Correlate a given error with others by context or time span.

  • Download a portion of a log file or the results of a query in one of several formats.

This section explains briefly how to configure a log file. The other functions above are explained, also briefly, in section Section J.1.3, "Solving Security Errors."

For full details about these topics, see section Managing Log Files and Diagnostic Data, in the Administering Oracle Fusion Middleware.

To configure a log file with Fusion Middleware Control, proceed as follows:

  1. Navigate to Server > Logs > Log Configuration, to display the Log Configuration page for the selected server. This page allows you to configure the log level for both persistent loggers and active run-time loggers.

  2. Click the Log File entry for the desired logger, to display the page showing the current parameter settings for that file.

  3. In this page, select a row and then click the button Edit Configuration, to display the Edit Log File dialog, where you can set various parameters, including the log level and the rotation policy; typically, the logger level is set to TRACE:32.

To specify a logger not visible in Fusion Middleware Control, proceed as follows:

  1. Navigate to Server > Logs > Log Configuration, to display the Log Configuration page for the selected server.

  2. In the Log Levels tab and from the pull-down View, select Loggers With Persistent Log Level State.

  3. In the area Specify Loggers at the bottom of the page, enter the logger name and select a level for it from the pull-down Oracle Diagnostic Logging Level (Java Level).

J.1.1.9 Managing Loggers with a Script

You can manage loggers using the script setLoggerLevel as illustrated in the following invocation:

setLogLevel(logger="oracle.idm.userroleapi", level="TRACE:32", addLogger=1, persist=1)

J.1.2 System Properties

To increase the debug output, set the following system properties in the script that starts your Oracle WebLogic Server and restart the server:

To get debug output during the authorization process, set any of the system properties described in section Debugging the Authorization Process.

Two other system properties that can be passed at server start and that can help debugging security issues are the following:

  • -DDebugOPSSPolicyLoading, a flag that monitors the progress and setting of the OPSS policy provider.

  • -Djava.security.debug=policy, the standard Java security debug flag that produces print information about policy files as they are parsed, including their location in the file system, the permissions they grant, and the certificates they use for signed code.


Note:

A consequence of setting a high logging output is that many threads may be reported in a stuck state, specially when file loading takes place. To avoid this situation, change the time out value that Oracle WebLogic Server uses to mark a thread as stuck to a higher value.

A system property cannot be set without restarting the server. In order to set a system property the administrator must edit the setDomainEnv.sh shell script and add the property to the environment variable EXTRA_JAVA_PROPERTIES in that script.


J.1.2.1 jps.auth.debug

Assume that just this system property is set to true:

-Djps.auth.debug=true 

Then, a permission check that fails generates an output with details illustrated in the following sample:

[JpsAuth] Check Permission
          PolicyContext:        [jps-wls-Demo]
          Resource/Target:      [app.monitor]
          Action:               [read,write]
          Permission Class:     [java.util.PropertyPermission]
          Evaluator:            [ACC]
          Result:               [FAILED] 
Failed ProtectionDomain:ClassLoader=weblogic.servlet.jsp.JspClassLoader@fb111c finder: weblogic.utils.classloaders.CodeGenClassFinder@106bb21 annotation:
CodeSource=file:/C:/MyOracle/domains/base_domain/servers/AdminServer/tmp/_WL_user/jps-wls-Demo/kebqfo/jsp_servlet/test.class
Principals=total 5 of principals(
 1. weblogic.security.principal.WLSUserImpl "duane"
 2. weblogic.security.principal.WLSGroupImpl "employee"
 3. JpsPrincipal: oracle.security.jps.principals.JpsAuthenticatedRoleImpl "authenticated-role"
 4. JpsPrincipal: oracle.security.jps.principals.JpsAnonymousRoleImpl "anonymous-role"
 5. JpsPrincipal: oracle.security.jps.service.policystore.ApplicationRole "appRoleEmployee")
 Permissions=(
 (java.util.PropertyPermission line.separator read)
 ...
 (oracle.security.jps.service.credstore.CredentialAccessPermission context=SYSTEM,mapName=default,keyName=* read,write))

A permission check that succeeds generates no output. To disable permission check messages, set this property to false; by default, it is set to true. Disabling persmission check messages is not recommended in production environments.

J.1.2.2 jps.auth.debug.verbose

Assume that jps.auth.debug and jps.auth.debug.verbose are both set to true:

-Djps.auth.debug=true 
-Djps.auth.debug.verbose=true

Then, a permission check that succeeds generates an output with details illustrated in the following sample:

[JpsAuth] Check Permission
          PolicyContext:        [jps-wls-Demo]
          Resource/Target:      [app.monitor]
          Action:               [read,write]
          Permission Class:     [java.util.PropertyPermission]
          Result:               [SUCCEEDED]
          Subject:              [total 5 of principals(
 1. weblogic.security.principal.WLSGroupImpl "manager"
 2. weblogic.security.principal.WLSUserImpl "shawn"
 3. JpsPrincipal: oracle.security.jps.internal.core.principals.JpsAuthenticatedRoleImpl "authenticated-role" GUID=null DN=null
 4. JpsPrincipal: oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl "anonymous-role" GUID=null DN=null
 5. JpsPrincipal: oracle.security.jps.service.policystore.ApplicationRole "appRoleManager" GUID=null DN=null)]
          Evaluator:            [ACC] 

A permission check that fails generates an output with details illustrated in the following sample:

JpsAuth] Check Permission
          PolicyContext:        [jps-wls-Demo]
          Resource/Target:      [app.monitor]
          Action:               [read,write]
          Permission Class:     [java.util.PropertyPermission]
          Evaluator:            [ACC]
          Result:               [FAILED]
          Failed ProtectionDomain:ClassLoader=weblogic.servlet.jsp.JspClassLoader@1b7682d finder: weblogic.utils.classloaders.CodeGenClassFinder@7d32cf annotation:
CodeSource=file:/C:/Mydom/domains/domain/servers/AdminServer/jspservlet/test.class
 Principals=total 5 of principals(
 1. weblogic.security.principal.WLSUserImpl "duane"
 2. weblogic.security.principal.WLSGroupImpl "employee"
 3. JpsPrincipal: oracle.security.principals.JpsAuthenticatedRoleImpl "authenticated-role" GUID=null DN=null
 4. JpsPrincipal: oracle.security.principals.JpsAnonymousRoleImpl "anonymous-role" GUID=null DN=null
 5. JpsPrincipal: oracle.security.jps.service.policystore.ApplicationRole "appRoleEmployee" GUID=null DN=null)
 Permissions=(
 (java.util.PropertyPermission line.separator read)
 ... 
 (java.lang.RuntimePermission stopThread))
 Call Stack: java.security.AccessControlException: access denied (java.util.PropertyPermission app.monitor read,write)
 java.security.AccessControlContext.checkPermission(AccessControlContext.java:323)
 ...
 weblogic.work.ExecuteThread.run(ExecuteThread.java:173)
          ProtectionDomains for class stack:
 Class[0]: class oracle.security.jps.util.JpsAuth$Diagnostic$SMSupport
 ProtectionDomain: ClassLoader=sun.misc.Launcher$AppClassLoader@360be0
 CodeSource=file:/C:/MyOracle/jdeveloper/modules/oracle.jps_11.1.1/jps-api.jar
 Principals=total 0 of principals<no principals>
 Permissions=(
 (java.io.FilePermission \C:\MyOracle\jdeveloper\modules\jps-api.jar read)
 ...
 )
 Class[1]: class oracle.security.jps.util.JpsAuth$Diagnostic$SMSupport 

To disable permission check messages, set both jps.auth.debug and jps.auth.debug.verbose to false; by default, jps.auth.debug.vebose is set to false.

J.1.2.3 Debugging the Authorization Process

This section describes the use of several other system properties that help debugging the authorization process based on several criteria. Specifically, the following system properties:

oracle.security.jps.log.for.approle.substring
oracle.security.jps.log.for.permeffect
oracle.security.jps.log.for.permclassname
oracle.security.jps.log.for.permtarget.substring
oracle.security.jps.log.for.enterprise.principalname

generate logging messages during the following authorization phases:

  • Phase 1 - The application roles that were granted to an enterprise user or to an enterprise role during the OPSS Subject computation.

  • Phase 2 - The permission instances that were granted to a grantee.

  • Phase 3 - The outcome of a permission check, that is, whether the grant was granted or denied.

Each of the above properties and the phases they apply are described next.

oracle.security.jps.log.for.approle.substring - During phases 1, 2, and 3, it logs the name of an application role that contains a specified substring; if the substring to match is unspecified, it logs all application role names.

oracle.security.jps.log.for.permeffect - During phase 3 and according to a specified value, it logs a grant that was granted or denied; if the value is unspecified, it logs all grants (regardless whether they were granted or denied).

oracle.security.jps.log.for.permclassname - During phases 2 and 3, it logs the name of the permission class that matches exactly a specified name; if the name to match is unspecified, it logs all permission class names.

oracle.security.jps.log.for.permtarget.substring - During phases 2 and 3, it logs the name of a permission target that contains a specified substring; if the substring to match is unspecified, it logs all permission targets.

oracle.security.jps.log.for.enterprise.principalname - During phases 1, 2, and 3, it logs the name of the principal (enterprise user or enterprise role) that matches exactly a specified name; if the name to match is unspecified, it logs all principal names.

The following characteristics apply to all of the above system properties:

  • They are optional.

  • They can be set at most once.

  • The matchings (where they apply) are case insensitive

To enable the logging of any of the above system properties, proceed as follows:

  1. Set the desired system properties.

  2. Stop the JVM.

  3. Restart the JVM.

  4. Set the logger oracle.security.jps.dbg.logger to TRACE:32. For details on how to set a logger, see Managing Loggers with Fusion Middleware Control.

  5. Run the scenario to be debugged.

  6. Examine the log output; to locate the messages output by the settings of any of the above properties, search the log file for the key word [oracle.security.jps.dbg.logger].

J.1.2.3.1 Examples of Use

The following examples illustrate typical settings of the above system properties.

  • To log all application role names that contain the substring myAppRole, include the following setting:

    -Doracle.security.jps.log.for.approle.substring=myAppRole
    
  • To log all denied permission checks, include the following setting:

    -Doracle.security.jps.log.for.permeffect=deny
    
  • To log all granted permission checks, include the following setting:

    -Doracle.security.jps.log.for.permeffect=grant
    
  • To log all granted or denied permission checks, do not set oracle.security.jps.log.for.permeffect.

  • To log all permission checks that match exactly the class name java.util.PropertyPermission, include the following setting:

    -Doracle.security.jps.log.for.permclassname=java.util.PropertyPermission
    
  • To log all target names that contain the substring p.mon, include the following setting:

    -Doracle.security.jps.log.for.permtarget.substring=p.mon
    
  • To log all authorizations involving the principal name manager, include the following setting:

    -Doracle.security.jps.log.for.enterprise.principalname=manager
    
  • To log application role names that match a substring or principal names that match a string, set both oracle.security.jps.log.for.approle.substring and oracle.security.jps.log.for.enterprise.principalname as indicated above.

  • To log all application roles names and all principal names, set neither oracle.security.jps.log.for.approle.substring nor oracle.security.jps.log.for.enterprise.principalname.

J.1.3 Solving Security Errors

There is no generic way to resolve errors when they occur. One must search for hints and frequently follow multiple hypotheses until, hopefully, the source of the error is isolated and understood. To this end, this section describes how to search and interpret log information to resolve most common security errors. These topics are addressed in the following sections:

J.1.3.1 Understanding Sample Log Entries

Understanding log error output is crucial to isolate and solve an error. Let's take a closer look at a diagnostic log file to describe the information you find for an error logged in such a file. This description is best illustrated with a real-life example.

The following is an excerpt of an error in the file AdminServer-diagnostic.log:

[2009-01-07T09:15:02.393-08:00] [AdminServer] [ERROR] [JPS-00004] [oracle.jps.admin] 
[tid: [ACTIVE].ExecuteThread: '3' for queue: 'weblogic.kernel.Default
(self-tuning)'] [userId: weblogic] [ecid: 0000Hum5kxw7MAn54nU4Ui19PD8S000005,0]
Unable to add principal to the application role. Reason: Principal
"abc.xxx@myComp.com" is already a member of the application role
"BPMWorkflowAdmin"[[
java.security.PrivilegedActionException:
oracle.security.jps.service.policystore.PolicyObjectAlreadyExistsException:
Unable to add principal to the application role. Reason: Principal "abc.xxx@myComp.com" is already a member of the application role
"BPMWorkflowAdmin"
        at java.security.AccessController.doPrivileged(Native Method)
        at oracle.security.jps.mas.mgmt.jmx.policy.JpsApplicationPolicyStoreImpl.
addRemoveMembersToRole(JpsApplicationPolicyStoreImpl.java:408)
        at oracle.security.jps.mas.mgmt.jmx.policy.JpsApplicationPolicyStoreImpl.
addMembersToApplicationRole(JpsApplicationPolicyStoreImpl.java:385)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
…

The meaning of the fields in the preceding message is as follows:

  • [2009-01-07T09:15:02.393-08:00]

    Identifies the date and time when the error was logged.

  • [AdminServer]

    Identifies the name of the server where the error occurred.

  • [JPS-00004]

    Identifies the error code and hints to the kind of error that occurred. For a complete list of JPS error codes, see chapter 41 in Error Messages.

  • [oracle.jps.admin]

    Identifies the logger category. The subcategories of oracle.jps (such as admin above) indicate the kind of error that occurred. They include the following:

    • common - generic errors.

    • upgrade - upgrade errors.

    • config - configuration errors.

    • deployment - deployment errors.

    • authentication - login module errors in Java SE applications only.

    • idmgmt - identity store errors.

    • credstore - credential store errors.

    • authorization - policy store errors at run time.

    • policymgmt - policy store management errors.

    • admin - JMX and WLST errors.

  • [tid: [ACTIVE].ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)']

    Identifies the thread where the error occurred.

  • [userId: weblogic]

    Identifies the user that performed the operation that generated the error.

  • [ecid: 0000Hum5kxw7MAn54nU4Ui19PD8S000005,0]

    Identifies the execution context id. Typically used to correlate and trace sequence of events. Ecids provide information about the flow across processes, such as, from a request, to the WebLogic server, to an Oracle Internet Directory server.

  • Unable to add principal to the application role. Reason: Principal abc.xxx@myComp.com is already a member of the application role BPMWorkflowAdmin

    Identifies the reason why the error was logged.

  • java.security.PrivilegedActionException: oracle.security.jps.service.policystore.PolicyObjectAlreadyExistsException: Unable to add principal to the application role. Reason: Principal abc.xxx@myComp.com is already a member of the application role BPMWorkflowAdmin

    Identifies the exception that was raised and the reason for it.

J.1.3.2 Searching Logs with Fusion Middleware Control

To initiate a search in the contents of all log files in a domain, select Domain > Logs > View Log Messages, to display the Log Messages page.

In this page you have several parameters that you can choose from to specify your search query; specifically, you can:

  • Choose a time interval in which a message was issue, by selecting the appropriate Date Range.

  • Display messages with a given severity error, by checking any of the Message Types boxes.

  • Display messages satisfying further constrains, by choosing an item from the menu Message and entering a string in the box next to it. For example, you could query for just messages that contain the string exception in it.

  • Add extra query fields, by clicking the button Add Fields and checking any of the available choices. For example, you could add the field Host, and then enter the appropriate query, such as starts with a particular string.

Once these parameters are set, click Search and the result of the query is displayed in the page. The result of a query can be further redisplayed by message type, message ID, or simple list of messages, by selecting an item from the menu Show. Moreover, the result can be automatically refreshed by choosing an item from the menu at the top right of the page (by default set to Manual Refresh).

To broaden a search to log files beyond a domain, use the button Broaden Target Scope at the top right of the page.

J.1.3.3 Identifying a Message Context with Fusion Middleware Control

In some situations, it is necessary to know the context in which a message has occurred. For example, it may be useful to know messages that have preceded or followed a given error message by, say, 2 minutes.

The tab View Related Messages provides this functionality, and you can use it as follows:

  1. Display the results of a query with Show set to Messages.

  2. Select a message within the result table. Note that the tabs View Related Messages and Export Messages to File become then available. Let's assume, for example, that the selected message has the time stamp Jan 21, 2009 4:05:00 PM PST.

  3. Select Time Interval from the Date Range menu, and enter a Start Date and an End Date. For example, you could enter Jan 21, 2009 4:02:00 PM, as a start date, and Jan 21, 2009 4:07:00 PM.

  4. Select by Time from the menu View Related Messages, to display the page with all the messages related to the selected one in the specified time span.

  5. In the Related Messages by Time page, you can modify the time window around the time of the selected message by choosing an item from the menu Scope, at the right of the page.

J.1.3.4 Generating Error Listing Files with Fusion Middleware Control

In some situations, you may want to download the list of errors displayed into a separate file to forward it, for example, to a support center, or just to keep it for your records.

Whenever available, the tab Export Messages allows you to generate a file containing just the displayed results by choosing an item from the menu. The format of the generated file can be plain text, XML, or CSV.

The following sample, showing only the first of 29 messages, is an excerpt of a text file generated this way:

#
#Search Criteria
#        Start Time: 2009-01-21T16:34:41.381-08:00
#        End Time:  2009-01-21T16:39:41.381-08:00
#        Message Types: ERROR, WARNING
 
#Selected Targets List
#        /Farm_base_domain/base_domain/AdminServer:Oracle WebLogic Server
#        /Farm_base_domain/base_domain/AdminServer/DMS Application(11.1.1.1.0):Application Deployment
#        /Farm_base_domain/base_domain/AdminServer/em:Application Deployment
#        /Farm_base_domain/base_domain/AdminServer/wsil-wls:Application Deployment
#        /Farm_base_domain/base_domain/AdminServer/wsm-pm:Application Deployment
#
[2009-01-21T16:34:54.045-08:00] [AdminServer] [WARNING] [] [org.apache.myfaces.trinidad.bean.PropertyKey] [host: stacz39] [nwaddr: 140.87.5.40] [tid: 13] [userId: <anonymous>] [ecid: 0000HvvkgjVE^MT6uBj8EH19TvXj000008,0] [APP: em] [Target: /Farm_base_domain/base_domain/AdminServer/em] [Target Type: Application Deployment] Unserializable value:oracle.sysman.core.view.tgtctls.common.DefaultTreeModel@1fcadd2 for key:UINodePropertyKey[value,17]
…
#
#Number of messages exported: 29
#

J.2 Troubleshooting Reassociation and Migration

This section describes the following issues:

J.2.1 Reassociation Failure

Policy and credential reassociation from a file-based store to an LDAP-based store may fail for several reasons. This section explains three reasons why this operation may fail.

Symptom 1- Error Code 32

Reassociation fails and an error like the following is logged in the administration server diagnostic file serverName.diagnostic.log:

[LDAP: error code 32 - No Such Object]
Authentication to LDAP server ldap://myServer.com:3060 is unsuccessful. 

Diagnosis 1

The error above identifies a problem with the target node in the LDAP server, namely, that the node specified does not exist.

It is required that the root node specified in the text box JPS Root DN (of the page Set Security Provider) be present in the LDAP directory before invoking the reassociation.

Solution 1

Verify that the data you enter in the box JPS Root DN matches the name of a node in the target LDAP directory, and then rerun the reassociation.

Symptom 2- Error Code 68

Reassociation fails and an error like the following is logged in the administration server diagnostic file serverName.diagnostic.log:

Authentication to LDAP server ldap://myServer.com:3060 is successful.
Starting to migrate policy store...
Set up security provider reassociation successfully.
Checked and seeded security store schema successfully.
null
[LDAP: error code 68 - Object already exists]:cn=SystemPolicy,cn=domain1,cn=JPSContext,cn=nb_policy
Error occurred while migrating LDAP based policy store. 

Diagnosis 2

The error above indicates that the name specified in the box WebLogic Domain Name is a descendant (more precisely, a grandchild) of the JPS Root DN node in the target LDAP directory.

It is required that the domain specified do not be a descendant of the root node.

Solution 2

Verify that the name you enter in the box WebLogic Domain Name does not match the name of a grandchild of the specified JPS Root DN node, and rerun the reassociation.

Symptom 3

Reassociation, carried out with Fusion Middleware Control, fails and an error like the following is logged in the administration server diagnostic file serverName.diagnostic.log:

[2009-01-21T10:09:24.326-08:00] [AdminServer] [ERROR] [] [oracle.jps.admin] [tid
: [ACTIVE].ExecuteThread: '15' for queue: 'weblogic.kernel.Default (self-tuning)
'] [userId: weblogic] [ecid: 0000HvuOTpe7q2T6uBADUH19Tpyb000006,0] Unable to rem
ove the principal from the application role. Reason: Principal "Managers" is not
a member of the application role "test-role"[[
java.security.PrivilegedActionException: oracle.security.jps.service.policystore
.PolicyObjectNotFoundException: Unable to remove the principal from the applicat
ion role. Reason: Principal "Managers" is not a member of the application role "
test-role"
       at oracle.security.jps.mas.mgmt.jmx.policy.JpsApplicationPolicyStoreImpl
.addRemoveMembersToRole(JpsApplicationPolicyStoreImpl.java:408)... 

Diagnosis 3

The error above points to some problem with the application role test-role, which is, in this case, the root of the problem.

Ensure that when entering data to perform reassociation with Fusion Middleware Control, you use the button Test LDAP Authentication immediately after you have completed entering all required values to connect to the target LDAP server. This test catches any problems with those values before reassociation begins.

Solution 3

In our example, a quick inspection of the file system-jazn-data.xml reveals that the application test-role is used by an application policy, but it was not defined. Here is an excerpt of that file illustrating where the required data is missing:

<application>
    <name>myApp</name>
        <app-roles>
 <--! test-role should have been defined here -->
        </app-roles>
        <jazn-policy>
            <grant>
                <grantee>
                    <principals>
                       <principal>
                         <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                         <name>test-role</name>
                         <guid>66368900E7E511DD9F62F9ADA4233FE2</guid>
                       </principal>
                     </principals>...

To solve this particular error, (a) fix system-jazn-data.xml by inserting the definition of the application test-role; (b) revert to file-based domain stores with the fixed file; and (c) rerun the reassociation.

Symptom 4 - Audit Store is Not Reassociated

In Release 11gR1 (11.1.1.6.0), if you reassociated security stores through the Fusion Middleware Control Enterprise Manager (EM) console, most stores (policy store, credential store and so on) moved except for the audit store. This is because the audit store did not support reassociation through the console, only through the WLST command reassociateSecurityStore.

Diagnosis 4

In a situation where the original migration from Release 11gR1 (11.1.1.6.0) to Release 12c (12.1.2) was done through Enterprise Manager, this leaves the audit repository as file-based. You can use the following resolution to move all security store data to LDAP/DB in order to enable audit.

Solution 4

In the original environment, run WLST command reassociateSecurityStore with a different jpsroot node. This effects an OID-to-OID directory reassociation and any existing data also gets migrated to the new node. After you take this action, audit data will no longer be file based and jps-config will have the new node.

J.2.2 Unsupported Schema

This section explains a reason why reassociation to an LDAP server may fail.

Symptom

Reassociating the security store to an LDAP repository fails and the AdminServer log reports an error like the following:

[2011-02-09T07:01:13.884-05:00] [AdminServer] [ERROR] [] [oracle.jps.admin] [tid: [ACTIVE].ExecuteThread: '6' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: weblogic] [ecid: 41050d66ef2ec40b:-4c1fb689:12e06cc7b6c:-8000-00000000000001e1,0] Schema seeding failed, check the server type of the given ldap url.[[
oracle.security.jps.JpsException: Error Modifying JPS Schema,  Record: dn: cn=schema
changetype: modify
delete: objectclasses
objectclasses: ( 2.16.840.1.113894.7.2.2 NAME 'orclContainer' SUP ( top ) MUS
 T ( cn ) MAY ( orclVersion $ orclServiceType ) )
-
: [LDAP: error code 32 - No Such Object]:cn=schema

Diagnosis

The error LDAP: error code 32 indicates that the schema of the reassociation target LDAP repository is not supported, that is, the version of the target LDAP repository is not one of the OPSS supported LDAP stores.

Solution

Update the target LDAP repository to one of the supported LDAP stores and then try reassociating again. The version of an LDAP OID store must be 10.1.4.3 or later. For a list of supported versions, see Section 9.2, "Using an LDAP-Based OPSS Security Store."

J.2.3 Missing Policies in Reassociated Policy Store

Symptom

When a file-based policy store is reassociated to use an LDAP-based Oracle Internet Directory policy store, the reassociation may report that it completed successfully.

At runtime, however, the system does not behave as expected. Codebase policies, that are supposed to be present in the system policy after migration, are missing.

Diagnosis

At runtime, the server reports a stack trace that resembles the following:

<BEA-000000> <JspServlet: initialization complete>
####<May 4, 2009 8:32:50 AM PDT> <Error> <HTTP> <ap626atg> <WLS_Spaces>
<[ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default
(self-tuning)'> <<WLS Kernel>> <> <> <1241451170341> <BEA-101020>
<[ServletContext@20193148[app:webcenter module:/webcenter path:/webcenter
spec-version:2.5]] Servlet failed with Exception
java.security.AccessControlException: access denied
(oracle.security.jps.service.policystore.PolicyStoreAccessPermission
context=APPLICATION,name=webcenter getApplicationPolicy)
        at
java.security.AccessControlContext.checkPermission(AccessControlContext.java:323)
        at
java.security.AccessController.checkPermission(AccessController.java:546)
        at
oracle.security.jps.util.JpsAuth$AuthorizationMechanism$3.checkPermission(JpsAuth.java:348)
        at
oracle.security.jps.util.JpsAuth$Diagnostic.checkPermission(JpsAuth.java:268)
        at
oracle.security.jps.util.JpsAuth$AuthorizationMechanism$6.checkPermission(JpsAuth.java:372)
        at oracle.security.jps.util.JpsAuth.checkPermission(JpsAuth.java:408)
        at oracle.security.jps.util.JpsAuth.checkPermission(JpsAuth.java:431)
        at
oracle.security.jps.internal.policystore.AbstractPolicyStore.checkPolicyStoreAccessPermission(AbstractPolicyStore.java:246)
        at
oracle.security.jps.internal.policystore.ldap.LdapPolicyStore.getApplicationPolicy(LdapPolicyStore.java:281)
        at
oracle.security.jps.internal.policystore.PolicyUtil.getGrantedAppRoles(PolicyUtil.java:898)
        at
oracle.security.jps.internal.policystore.PolicyUtil.getJpsAppRoles(PolicyUtil.java:1354)
        at
oracle.security.jps.wls.JpsWlsSubjectResolver$1.run(JpsWlsSubjectResolver.java:273)
        at
oracle.security.jps.wls.JpsWlsSubjectResolver$1.run(JpsWlsSubjectResolver.java:270)
        at java.security.AccessController.doPrivileged(Native Method)

Here the permission:

oracle.security.jps.service.policystore.PolicyStoreAccessPermission
context=APPLICATION,name=webcenter getApplicationPolicy

is granted to a code base, and the authorization is not allowed since it evaluates to false.

Solution

Check the AdminServer diagnostic logs for messages like these:

AdminServer-diagnostic.log:[2009-05-28T02:27:52.249-07:00] [AdminServer] [NOTIFICATION] [JPS-00072] [oracle.jps.config] [tid: Thread-39] [ecid: 0000I66Z0KH0fplp4sm3Ui1A7_Rl00002s,1:5001] [arg: 11.1.1.1.0] [arg: 11.1.1.0.0] Policy schema upgrade not required. Store Schema version 11.1.1.1.0 is compatible to the seed schema version 11.1.1.0.0
AdminServer-diagnostic.log:[2009-05-28T02:28:58.012-07:00] [AdminServer] [NOTIFICATION] [JPS-00078] [oracle.jps.config] [tid: Thread-39] [ecid: 0000I66Z0KH0fplp4sm3Ui1A7_Rl00002s,1:5001] [arg: 11.1.1.1.0] [arg: 11.1.1.0.0] Credential store schema upgrade not required. Store Schema version 11.1.1.1.0 is compatible to the seed schema version 11.1.1.0.0

A message of this type suggests that the schema was never seeded during the re-association. If the correct schema is not seeded in the Oracle Internet Directory server, the system will not work as expected.

To ensure that the schema is seeded during re-association, proceed as follows:

  1. Remove the cn=OPSS container under the cn=OracleSchemaVersion container in the Oracle Internet Directory server.

  2. Start with a clean working instance of an OPSS policy store using the file-based store.

  3. Re-associate this file-based store to the Oracle Internet Directory server.

Check the AdminServer diagnostic logs to confirm that the OPSS LDAP schema was seeded in the LDAP server by looking for this message:

AdminServer-diagnostic.log:[2009-05-29T07:18:18.002-07:00] [AdminServer] [NOTIFICATION] [JPS-00078] [oracle.jps.config] [tid: Thread-12] [ecid: 0000I61Z0MH0fplp4sm3Ui1A7_Ll00002s,1:5001] [arg: 11.1.1.0.0]  Policy schema version set to 11.1.1.0.0

If re-associating to a Release 11g Oracle Internet Directory server, the schema version should read: 11.1.1.1.0

If re-associating to a Release 10.1.4.3 Oracle Internet Directory server, the schema version should read: 11.1.1.0.0

The Policy Store schema version is set in the Oracle Internet Directory server under this container:

cn=PolicyStore,cn=OPSS,cn=OracleSchemaVersion

Similarly, the Credential Store schema version is set in the Oracle Internet Directory server under this container:

cn=CredentialStore,cn=OPSS,cn=OracleSchemaVersion

J.2.4 Migration Failure

This section describes a reason why the automatic migration of policies at application deployment may fail. Note that the deployment of an application may succeed even though the migration of policies failed.


Note:

The reason why the automatic migration can fail, as explained in this section, can also lead to similar failures when reassociating domain stores.

For a failure also related to migration, see Incompatible Versions of Policy Stores.

Symptom

The application is configured to migrate policies automatically at deployment. The application deployment succeeds, but the diagnostic file corresponding to the server where it has been deployed outputs a message like the following:

[2009-01-21T13:34:48.144-08:00] [server_soa] [NOTIFICATION] []
[oracle.jps.deployment] [tid: [ACTIVE].ExecuteThread: '2' for queue:
'weblogic.kernel.Default (self-tuning)'] [userId: weblogic] 
[ecid: 0000Hvv7U_H7q2T6uBADUH19Tq0B00002I,0] [APP: JpsJdev#V2.0] 
Application [JpsJdev#V2.0] is being deployed, start policy migration.

[2009-01-21T13:34:48.770-08:00] [server_soa] [WARNING] [] 
[oracle.jps.deployment] [tid: [ACTIVE].ExecuteThread: '2' for queue:
'weblogic.kernel.Default (self-tuning)'] [userId: weblogic] 
[ecid: 0000Hvv7U_H7q2T6uBADUH19Tq0B00002I,0] [APP: JpsJdev#V2.0] 
Exception in application policy migration.[[
oracle.security.jps.JpsException: appplication Role: 
test_role not found for the application in the destination policy store
at oracle.utility.destination.apibased.JpsDstPolicy.convertAppPolicyPrincipal
(JpsDstPolicy.java:815)
at oracle.utility.destination.apibased.JpsDstPolicy.clone
(JpsDstPolicy.java:691)...

The above excerpt was extracted from the file server_soa-diagnostic.log, and the application JpsJdev was deployed to the managed server server_soa. Note that the key phrase to look for to locate such error is highlighted in the sample above. In addition, the error describes the artifact that raised the exception, the application role test_role.

Diagnosis

Something is wrong with the definition of this role in the application file jazn-data.xml. In fact, a quick look at this file reveals that the role test_role is referenced in a grantee, as illustrated in the following excerpt:

<grantee>
   <display-name>myPolicy</display-name>
   <principals>
     <principal>
       <class>oracle.security.jps.service.policystore.ApplicationRole</class>
       <name>test_role</name>
     </principal>
   </principals>
</grantee> ...

But the name of what is supposed to be the application role named test_role, however, was inadvertently misspelled to test_rolle:

<application>
   <name>JpsJdev</name>
   <app-roles>
     <app-role>
       <name>test_rolle</name>
       <class>oracle.security.jps.service.policystore.ApplicationRole</class>
        <members> ...

Solution

Ensure that all application roles referenced in application policies have been properly defined in the jazn-data.xml file. If a referenced role name cannot be matched, as in the samples above, the migration fails.

J.3 Troubleshooting Server Starting

This section explains several reasons why the Oracle WebLogic Server may fail to start in the following sections:

J.3.1 Missing Required LDAP Authenticator

This section explains a reason why the Oracle WebLogic Server may fail to start after modifying the list of authenticators in a domain.

Symptom

After modifying the list of authenticator providers in a domain, the Oracle WebLogic Server fails to start, and the error messages output include the following:

java.lang.IllegalArgumentException: null KeyStore name

Diagnosis

One cause of this problem is that the list of authenticators in your domain does not include an LDAP authenticator.


Important:

An LDAP authenticator is required in this list for any domain using OPSS.

Solution

Since the server cannot start and an LDAP authenticator is missing, you must add it manually, as follows:

  1. Open the file DOMAIN_NAME/config/config.xml.

  2. Edit config.xml and include, within the element <realm>, an LDAP authenticator, such as the default authenticator illustrated in the following sample:

    <realm>
     ...
     <sec:authentication-provider xsi:type="wls:default-authenticatorType"> 
     </sec:authentication-provider>
     ...
    </realm>
    
  3. Restart the server.

Once the server is back up and running, you can modify the list of providers to include the provider of your choice using the WebLogic Administration Console, but ensure that at least one of them is an LDAP authenticator provider.

To this end, use the WebLogic Administration Console as follows:

  1. Navigate to the page Create a new Authenticator Provider.

  2. Enter the authenticator name and select an authenticator type, all of which are LDAP-based:

    • ActiveDirectoryAuthenticator

    • DefaultAuthenticator (this is the one inserted manually in the sample above)

    • LDAPAuthenticator

    • LDAPX509IdentityAsserter

    • OpenLDAPAuthenticator

    • OracleInternetDirectoryAuthenticator

    • OracleVirtualDirectoryAuthenticator

J.3.2 Missing Administrator Account

This section explains a reason why the Oracle WebLogic Server may fail to start.

Symptom

After removing the out-of-box default authenticator and adding, say an Oracle Internet Directory authenticator, the server fails to start.

Diagnosis

Most likely, you have forgotten to enter an account member of the Administrators group in your added authenticator. The server requires that such an account be present in one domain authenticator. This account is always present in the default authenticator.

Solution

Since the server cannot start, you must add the deleted one LDAP authenticator manually, as follows:

  1. Open the file DOMAIN_NAME/config/config.xml.

  2. Edit config.xml and include, within the element <realm>, the default authenticator, as illustrated in the following sample:

    <realm>
     ...
     <sec:authentication-provider xsi:type="wls:default-authenticatorType"> 
     </sec:authentication-provider>
     ...
    </realm>
    
  3. Restart the server.

Once the server is back up and running, proceed as follows:

  1. Create an account that is member of the Administrators group in the OID LDAP authenticator.

  2. Set the Oracle Internet Directory authenticator flag to SUFFICIENT.

  3. Restart the server, which it should start without problems, since it is using the account in the Administrators group provided in the default authenticator.

  4. Reset the Oracle Internet Directory authenticator flag to REQUIRED and remove the default authenticator. The server should now start using the account in the Administrators group that you created in the Oracle Internet Directory authenticator.

J.3.3 Missing Permission

This section explains a reason why the Oracle WebLogic Server may fail to start.

Symptom

The server fails to start when it started with security manager is enabled (with the system property -Djava.security.manager).

Diagnosis

One reason why you may run into this issue is the lack of permission grants to PKI APIs in oraclepki.jar when the security manager is enabled at server startup.

Solution

Ensure that a grant like the following is present in the file weblogic.policy, or add it if it is not:

grant codeBase "file:${oracle.home}/modules/oracle.pki_${jrf.version}/*" { 
 permission java.security.AllPermission; 
};

The above grant is provided by default. Note that when security manager is enabled, the access to all system resources requires codebase permission grants.

For complete details about using the Java Security Manager to protect WebLogic resources, see Developing Applications with the WebLogic Security Service.


Note:

Printing Security Manager is a WebLogic server enhancement to the Java Security Manager. Use Printing Security Manager to identify all of the required permissions for a Java application running under Java Security Manager. Unlike the Java Security Manager, which identifies needed permissions one at a time, the Printing Security Manager identifies all the needed permissions without intervention.

J.3.4 Server Fails to Start

This section explains two reasons why the Oracle WebLogic Server will fail to start.

Symptom 1

The domain directory ${domain.home}/config/fmwconfig is on an NFS-mounted partition, and an error message like the following is logged when the server is started:

JPS-01050: Opening of wallet based credential store failed. Reason 
java.io.IOException: PKI-02002: Unable to open the wallet. Check password.

Furthermore, when orapki debugging is turned on and the server is started once again, the following message is logged:

java.io.IOException: No locks available.

Note:

To enable orapki debugging, start the server with the following property set: -Doracle.pki.debug=true.

Diagnosis 1

Since OPSS requires file locking when managing security artifacts in file-based stores, the error message No locks available indicates that the file system on which the domain directory is NFS-mounted does not support file locking.

Solution 1

Perform either of the following and restart the server:

  • Upgrade from NFS v3 to NFS v4.

  • Mount the remote file system with the nolock option enabled.

  • Move files in ${domain.home}/config/fmwconfig to a local storage

Symptom 2

The server fails to start because a wallet operation run into an exception. Furthermore, when orapki debugging is turned on (see note above) and the server is started once again, a file permission error is logged.

Diagnosis 2

Wallet operations create and make use of temporary files in the folder /tmp; all files matching the pattern /tmp/*pki* must be owned by the user that started the server. A file permission error message indicates that some files matching that pattern are not owned by the appropriate user.

Solution 2

Remove any files matching the pattern /tmp/*pki* that are not owned by the user that is starting the server and restart the server.

Symptom 3

This symptom is same as symptom 2 above, but it has a different resolution. The server fails to start because a wallet operation run into an exception. Furthermore, when orapki debugging is turned on (see note above) and the server is started once again, a file permission error is logged.

Diagnosis 3

The server must be started by the same OS user as the one who installed the domain. The server will fail to start even if started by any other member of the OS group to which the installer belongs.

Solution 3

Restart the server using the OS user who installed the domain.

J.3.5 Other Server Start Issues

This section explains several reasons why the Oracle WebLogic Server may fail to start.

Symptom

When attempting to load and set the policy provider, the Oracle WebLogic Server fails to start and logs an exception similar to the one illustrated in the following snippet:

<Mar 30, 2010 3:15:54 PM EDT> <Error> <Security> <BEA-090892> <The dynamic loading of the OPSS java security policy provider class oracle.security.jps.internal.policystore.JavaPolicyProvider failed due to problem inside OPSS java security policy provider. Exception was thrown when loading or setting the JPSS policy provider.
...
<Mar 30, 2010 3:15:54 PM EDT> <Critical> <WebLogicServer> <BEA-000386> <Server subsystem failed. Reason: weblogic.security.SecurityInitializationException: The dynamic loading of the OPSS java security policy provider class oracle.security.jps.internal.policystore.JavaPolicyProvider failed due to problem inside OPSS java security policy provider. Exception was thrown when loading or setting the JPSS policy provider.
...
weblogic.security.SecurityInitializationException: The dynamic loading of the OPSS java security policy provider class oracle.security.jps.internal.policystore.JavaPolicyProvider failed due to problem inside OPSS java security policy provider. Exception was thrown when loading or setting the JPSS policy provider.
...

Diagnosis

The server startup includes loading and setting the policy provider as defined in the configuration file jps-config.xml; if this task is not completed successfully, the Oracle WebLogic Server fails to start. As illustrated in the sample above, this type of failure is identified in the server's log by the string

Exception was thrown when loading or setting the JPSS policy provider.

To determine the root cause of a particular failure server startup, check the server's log file and inspect the logged stack trace. For details about identifying errors, see Diagnosing Security Errors.

Here are some reasons why the server fails to start:

  1. The path to the configuration file is incorrectly specified.

  2. The default context is missing in the configuration file.

  3. The XML parser is not available.

  4. A code source URL is incorrectly specified in a system policy. This situation is identified by a logged exception that includes the string

    java.net.MalformedURLException: unknown protocol.
    

Solution

A solution for each of the above cases above is explained next.

  1. Ensure that the correct path is specified by the system parameter oracle.security.jps.config:

    -Doracle.security.jps.config=<full-path-to-jps-config.xml>
    

    Note that special characters (such as backlashes or white space characters) in the full path specification must be properly escaped. One way to verify correctness is to test using the specified full path in a command line.

  2. The configuration file must include a default context. For an example of a default context configuration, see <jpsContext>.

  3. Make sure that the XML parser is available in your system and that the XML parser JAR file is included in the classpath.

  4. Typical incorrect and corrected code source URLs are illustrated in the following two samples.

    Sample 1 - Incorrect URL
    <grantee>
      <codesource>
         <url>${my.oracle.home}/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
     
    Sample 1 - Corrected URL (in bold)
    <grantee>
      <codesource>
         <url>file:/${my.oracle.home}/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
     
    Sample 2 - Incorrect URL
    <grantee>
      <codesource>
         <url>c:/myfolder/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
     
    Sample 2 - The corrected URL (in bold) is either one of the following three:
    <grantee>
      <codesource>
         <url>file:///c:/myfolder/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
     
    <grantee>
      <codesource>
         <url>file:c:/myfolder/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
     
    <grantee>
      <codesource>
         <url>file:/c:/myfolder/jlib/webcacheua.jar</url> 
       </codesource>
    </grantee>
    

    For details about the syntax of URL specifications in a code source (including the use of system variables), see <url>.

J.3.6 Permission Failure Before Server Starts

This section describes a reason why a permission check may fail before the server has completed its starting phase.

Symptom

An authorization check fails before the server has started. The server has completed its starpup when it outputs the a line like the following:

<WebLogicServer> <BEA-000365> <Server state changed to STARTING>

Diagnosis

A permission check error before the server has changed status to STARTING usually indicates that the authorization service required to check that permission was not fully initialized at the time of the request.

Solution

To workaround this issue, proceed as follows:

  1. Edit the file weblogic.policy to add the appropriate grant(s).

  2. Start the Oracle WebLogic Server with the following two system properties set:

    • java.security.policy set to the location of the weblogic.policy file.

    • jps.policystore.hybrid.mode set to true.

J.4 Troubleshooting Permissions

This section describes the following issues:

J.4.1 Troubleshooting Codesourse Grants

This section explains how to solve codesource grant issues.

Symptom

An application is denied authorization to use a security management operation, and an exception like the following is logged:

java.security.AccessControlException: access denied
(oracle.security.jps.service.credstore.CredentialAccessPermission
context=SYSTEM,mapName=oracle.patching,keyName=FUSION_APPS_PATCH_WLS_ADMIN-KEY read)

The specifics of the logged error would indicate the operation that the application failed to access.

Diagnosis

Grants to codesouce are required when an application code needs to access any of the following operations:

  • Policy management

  • Credential management

  • Key management

  • Audit management


Note:

Codesource grants are system policies and cannot be packaged with the application policies.

Solution

To resolve a runtime time failure like the above, proceed as follows:

  1. Inspect the error to identify the codesource URL that was checked by the runtime system.

    If the URL information is not available, enable the following loggers on the specific managed or administrator server in question to reproduce the failure:

    setLogLevel(target="serverName", logger="oracle.security.jps.util.JpsAuth", level="TRACE:32", persist=1);
     
    setLogLevel(target="serverName", logger="oracle.security.jps.trace.logger", level="TRACE:32", persist=1);
     
    setLogLevel(target="serverName", logger="oracle.security.jps.dbg.logger", level="TRACE:32", persist=1);
     
    setLogLevel(target="serverName", logger="oracle.security.jps.internal.policystore.JavaPolicyProvider", level="TRACE:32", persist=1);
     
    setLogLevel(target="serverName", logger="oracle.jps.common", level="TRACE:32", persist=1);
    

    Note:

    In log files, the codesource is identified with an absolute path of the JAR file, but the URL is specified relative to environment variables.

  2. Once the specific codesource is identified, view the configured grant in the security store and ensure that it is indeed specifying the correct permission, target, and action(s).

    To view a grant, use Fusion Middleware Control as explained in Section 10.2, "Managing Policies with Fusion Middleware Control," or the WSLT online command listCodeSourcePermissions. For details on this command, see Oracle Fusion Middleware Infrastructure Security WLST Command Reference.

  3. If the grant in the security store does not match the data in the runtime error, modify the grant using Fusion Middleware Control or the WSLT online command grantPermission. For details about this command, see Oracle Fusion Middleware Infrastructure Security WLST Command Reference.


Note:

If your code is required to run in a privileged block, make sure that it is doing so.

J.4.2 Failure to Grant or Revoke Permissions - Case Mismatch

This section explains the likely reasons why an enterprise user or role (group) may fail to be granted or revoked permissions.

Symptom

An enterprise user or group, properly entered in a domain authenticator, is not granted or revoked the permissions defined by a grant.

Diagnosis

This problem is likely to occur when there is a case mismatch between the stored name (in a domain authenticator) and the supplied name (either actively entered by a user or obtained programmatically). For example, this mismatch would occur when the stored user name is JdOE and the supplied user name is jdoe.

Solution

There are two ways to resolve this issue.

The first solution involves setting the appropriate property in the authenticator being used in your domain. As long as both strings (the supplied and the stored) contain identical sequence of characters (irrespective of case), this setting guarantees that the user name populated in the Subject matches the user name present in a domain authenticator, even when the corresponding characters differ in case. Thus, when this setting is in place, the user names JdOE and jdoe match.

To set your domain authenticator property, proceed as follows:

  1. Use the Administration Console to navigate to the page where your authenticator is configured. For example, if you are using the default authenticator, navigate to the DefaultAuthenticator page by choosing Realms > myrealm > Providers > DefaultAuthenticator.

  2. Choose the tab Provider Specific.

  3. Set the property userRetrievedUserNameAsPrincipal to true.

  4. Restart the server.

The second solution considers the case where the supplied name is obtained programmatically, that is, where one must produce a principal from a user name.

To obtain the correct user or group name, either pass the name exactly as it is stored in the authenticator or use the sequence of calls illustrated in the following code snippet:

import weblogic.security.principal.WLSGroupImpl;
import weblogic.security.principal.WLSUserImpl;
 
// Set the context
JpsContextFactory ctxFact = JpsContextFactory.getContextFactory();
ServerContextFactory scf = (ServerContextFactory) ctxFact;
JpsContext ctx = scf.getContext(ServerContextFactory.Scope.SYSTEM);
ctx = ctxFact.getContext();

// Set the identity store
IdentityStore identityStore = ctx.getServiceInstance(IdentityStoreService.class).getIdmStore();
 
// In case of a user name, search the user that matches the supplied name
User user = idStore.searchUser(IdentityStore.SEARCH_BY_NAME, suppliedUserName);

// Use the obtained object (user) to obtain the stored user name and create 
// the Principal
String storedUserName = user.getName();
Principal userPrincipal = new WLSUserImpl(storedUserName);
 
// Similarily, in case of a role name, search the role that matches 
// the supplied role name
Role role = identityStore.searchRole(IdentityStore.SEARCH_BY_NAME, suppliedRoleName);
 
// Use the obtained object (role) to obtain the stored role name and create 
// the Principal
String storedRoleName = role.getName();
Principal rolePrincipal = new WLSGroupImpl(storedRoleName);

Important:

When creating a user or role principal, you must use the calls:
Principal userPrincipal = new WLSUserImpl(user.getUserProfile()getName());
Principal rolePrincipal = new WLSGroupImpl(role.getRoleProfile().getName());

Instead of the calls:

Principal userPrincipal = new WLSUserImpl(user.getName());
Principal rolePrincipal = new WLSGroupImpl(role.getName());

J.4.3 Authorization Check Failure

This section explains a reason why an authorization check has failed.

Symptom

An attempt to authorize a user by your application fails, and the system logs an error containing a line like the following:

Servlet failed with Exception oracle.adf.controller.security.AuthorizationException:ADFC-0619:
Authorization check failed: '/StartHere.jspx' 'VIEW'. 

Diagnosis

One reason that can lead to such an authorization failure is a mismatch between the run-time policy context and the policy store stripe that you application is using.

On the one hand, the application stripe (or subset of policies in the policy store) that an application uses is specified in the file web.xml with the parameter application.name within the filter configuring the JpsFilter (for a servlet) or the interceptor configuring the JpsInterceptor (for an EJB). For details and samples, see Application Name (Stripe). If the application stripe is not specified (or left blank), then the system picks up an application stripe based on the application name.

On the other hand, the run-time policies that your application uses are specified in the file system-jazn-data.xml with the element <application.name>.

If those two names do not match or if you have not explicitly specified the stripe to use, then, most likely, your application is accessing the wrong policy stripe and, therefore, not able to authorized your application users as expected.

Solution

Ensure that you specify explicitly your application stripe, and that stripe is the one that your application is supposed to use. In most cases, the two names specified in those two different files (as explained above) match; however, in cases where several applications share the same policy stripe, they may differ.

J.4.4 User Gets Unexpected Permissions

This section explains the likely reasons why a user gets permissions other than those anticipated.

Symptom

A new user or a modified user gets unexpected permissions.

Diagnosis

This issue is likely to come up in cases where a user is added with the name of previously removed user, or an old user gets its name or uid changed. The common reason why the user may get more or less permissions than expected is that the policy store has not been properly updated before a user is removed or a user data is changed.

Solution

Before deleting a user, revoke all permissions, application roles, and enterprise groups that had been granted to the user. If you fail to remove all security artifacts referencing a user to be deleted, they are left dangling and, potentially, inherited if another user with the same name or uid is created at a later time.

Similar considerations apply to when a user name or uid is changed: all policies (grants, permissions, roles) referring to the old data must be updated so that they work as expected with the new data.

J.4.5 Granting Permissions in Java SE Applications

This section describes the correct way to code a grant in Java SE applications. Even though the problem described is not an issue in Java EE applications, for maximum portability, it is recommended that this solution be used in Java EE applications too.

Symptom

The application code includes a fragment like the following, by an application creates a grant:

Permission p = new FilePermission(resourceName, "write");
PrincipalEntry myPrincipal2 = InfoFactory.newPrincipalEntry("weblogic.security.principal.WLSGroupImpl", enterpriseRoleName2);
ap.grant(new Principal[]{myPrincipal2.getPrincipal()}, null, new Permission[]{p});

At runtime, however, the grant is not taking effect as expected.

Diagnosis

A bit of inspection indicates that the policy store repository includes the following attribute:

orcljaznjavaclass=oracle.security.jps.internal.policystore.UnresolvedPrincipal+cn=enterpriseRoleName2

Solution

The lines of code above should be replaced by the following:

Permission p = new FilePermission (resourceName, "write");
PermissionEntry permEntry  = InfoFactory.newPermissionEntry(p.getClassName(), p.getName(),  p.getActions());
ap.grant (new PrincipalEntry[] {myPrincipal2}, null, new PermissionEntry[] {permEntry});

The solution uses the array PrincipalEntry instead of the array Principal and the array PermissionEntry instead of the array Permission.


Note:

This same issue applies to the method revoke, which also has overloaded variants that accept Principal[] or PrincipalEntry[]

J.4.6 Application Policies Not Seen in 12c HA Environment

This section describes a sequence that results in application policies not taking effect in a 12c HA (High Availability) domain, and how to work around it.

Symptom

The following sequence throws an exception:

  1. Deploy a custom application (packed with application policies) in a 12c HA environment, either to the domain administration server or to a domain managed server (but not to both).

  2. Undeploy the application.

  3. Redeploy the application to a server different from the one deployed to in step 1.

Step 3 above results in an exception and the application policies do not take effect. This issue is observed in 12c HA domains only.

Diagnosis

This issue is seen because the domain servers do not have their caches synchronized; note that the various servers run in distinct JVM's (Java Virtual Machine).

Suppose, for example, that the HA domain has three servers: server A (the administration server), server B (a managed server), and server C (a managed server). Suppose, further, that the application is first deployed to the domain administration server (server A), and then all three servers are restarted; the caches in servers A, B, and C will then have been initialized (with policies read from the security store) and are synchronized.

If the application is then undeployed (from server A), then the server A's cache will be cleared, but the caches in servers B and C will not. Further, if the application is redeployed, say, to server B, then the caches become out of synch, and an exception is thrown (because policy objects already exist).

Solution

The workaround to this issue is as follows:

After step 2 and before step 3 above, restart all servers in the HA domain. With this additional step, the modified procedure leads to synchronized caches in all servers in the HA domain, and then the application policies are seen as expected.

J.5 Troubleshooting Connections and Access

This section describes the following issues:

J.5.1 Failure to Connect to the Embedded LDAP Authenticator

This section explains the likely reasons why a connection to the embedded LDAP authenticator can fail.

Symptom

The connections that client applications use to request queries to the embedded LDAP authenticator, via the User and Role API, are stored and maintained in a connection pool. By default, and out-of-the-box, this pool is the JNDI pool, as specified in the file jps-config.xml.

If the number of current connections in the pool exceeds the maximum allowed by the LDAP service, client applications will not be able to connect to the service or, even when they are already connected, receive a ”socket closed” exception. The server log would indicate, in this case, that the number of concurrent connections allowed has been exceeded.

Diagnosis

To avoid going over the limit, one needs to adjust the maximum number of concurrent connections allowed by the LDAP service as appropriate to the application's needs. This threshold needs to be finely tuned up: a too small maximum may not be sufficient (and cause the exception mentioned above); a too large maximum may risk a denial of service (DOS) attack. The correct maximum depends on your application and the particular LDAP service the application uses.

Solution

There are two alternative ways that resolve this issue:

  • Increase the maximum number of concurrent connections allowed by the authenticator:

    • If the authenticator your application is using is the WebLogic Embedded LDAP authenticator, then edit the file DomainName/servers/MyServerName/data/ldap/conf/vde.prop, and increase the value of the property vde.quota.max.conpersubject from the default 100 to, for example, 200, or any other value.

    • Otherwise, if your application is using any other authenticator, consult the authenticator's documentation to learn how to modify the maximum.

  • Edit the file DomainName/config/fmwconfig/jps-config.xml and remove the property CONNECTION_POOL_CLASS from the authenticator server instance (by default, this property has the value oracle.security.idm.providers.stdldap.JNDIPool.

Note that (a) these settings do not exclude each other, that is, you can carry out both of them; and (b) in any case, you must restart the server for the changes to take effect.

J.5.2 Failure to Connect to an LDAP Server

This section explains the likely reasons why a connection to an Oracle Internet Directory LDAP server can fail. This failure can also happen during reassociation.

Symptom

The migration of data from a source repository to a target LDAP server repository fails.

Diagnosis

Typically, this kind of problem is due to an incorrect set up of parameters in the target LDAP server.

For further probing into Oracle WebLogic Server log files, search any of the log files in the directories DomainName/servers/AdminServer or DomainName/servers/ManagedServers for the following strings: <Error>, <Critical>, and <Warning>.

For more information about identifying and solving errors, see Section J.1, "Diagnosing Security Errors."

Solution

Verify that all the target server data provided for the migration is valid. You may require the assistance of your LDAP server administrator to perform this validation.


Note:

If you are using Fusion Middleware Control to reassociate to an LDAP server, ensure that you use the button Test LDAP Authorization before initiating the operation. Typically, this test catches incorrect supplied parameters.

J.5.3 Failure to Access Data in the Credential Store

This section explains a likely reason why an application fails to access data in the domain's credential store.

Symptom

An application fails to retrieve credential data from the domain's credential store, and an error message (containing lines like the one illustrated below) is logged (text in between brackets should describe information specific to the particular failure):

07/07/26 18:22:22 [JpsAuth] For permisson ( CredentialAccessPermission [target] [actions]), domain that failed: ProtectionDomain
 cs(file:somePath/aWarFile.war/WEB-INF/classes/), []

Diagnosis

If an application is to access the credential store to perform an operation (such as retrieving a user password, for example), then its code must be granted the appropriate permission to perform the secured operation; otherwise, the application runs into an error like the one described above.

Solution

To grant the permission that an application requires to access the credential store, include the appropriate CredentialAccessPermission in the application's jazn-data.xml; this grant takes effect when the application is deployed or redeployed.

To include a permission using Fusion Middleware Control, see Section 10.2, "Managing Policies with Fusion Middleware Control."

To include a permission using a WLST command, see Section 10.3, "Managing Application Policies with WLST commands."

The following fragment of the file jazn-data.xml illustrates how to grant all code in the application myApp permission to read all credentials in the folder myAlias:

<jazn-data>
    <!--  codebase policy -->
    <jazn-policy>
        <grant>
            <grantee>
                <codesource>
 <!-- This grants applies to all code in the following directory -->
                    <url>${domain.home}/tmp/_WL_user/myApp/-</url>
                </codesource>
            </grantee>
            <permissions>
                <permission>
                    <class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<!-- Allow read permission to all credentials under folder MY_MAP -->
                    <name>context=SYSTEM,mapName=MY_MAP,keyName=*</name>
                    <actions>read</actions>
                </permission>
            </permissions>
        </grant>
    </jazn-policy>
</jazn-data>

J.5.4 Security Access Control Exception

This section explains a reason why your code may run into a security access control exception.

Symptom

At run time, your application outputs an error like the following one (only the first few lines are shown):

<Jan 20, 2009 5:45:33 PM PST> <Error> <HTTP> <BEA-101020>
<[weblogic.servlet.internal.WebAppServletContext@140cf52 
- appName: 'Application2', 
name: 'Application2.war', 
context-path: '/Application2', 
spec-version: '2.5'] 
Servlet failed with Exceptionjava.lang.RuntimeException:java.security.AccessControlException:access denied
...

Diagnosis

The above error means that a call in your code does not have sufficient permissions to execute a secured operation.

Solution

Your code must be granted the appropriate permissions to execute the secured operation. Depending on the scope of the permission you would like to set, you have two alternatives.

The first one is to grant permission to all application code in the application's EAR or WAR files; in this case, the call to the secured operation can be inserted anywhere in the application code.

The second one is to grant permission to just a JAR file; in this case, the call to the secured operation must be inside a privileged block.

Each of these solutions is next illustrated by an application attempting to access the credential store.

The following fragment of an applicationjazn-data.xml illustrates how to set permission to read any key within the map MY_MAP in the credential store to any code within the directory BasicAuth:

<jazn-policy>
   <grant>
       <grantee>
           <codesource>
              <url>file:${domain.home}/servers/_WL_user/BasicAuth/-</url>
           </codesource>
       </grantee>
       <permissions>
           <permission>
             <class>
                 oracle.security.jps.service.credstore.CredentialAccessPermission
             </class>
             <name>context=SYSTEM,mapName=MY_MAP,keyName=*</name>
             <actions>read</actions>
          </permission>
      </permissions>
   </grant>
</jazn-policy>

If the permission is to be granted to the code in a particular EAR or WAR file, the url specification above would have to be changed to one like the following:

<url>file:${domain.home}/servers/_WL_user/jpsBasicAuth/.../BasicAuth.ear</url>

In both above cases, the call to read the credential store can be placed anywhere in the application code.

If, however, the permission is to be granted to just the code in a particular JAR file, the url specification above would have to be changed to one like the following:

<url>file:${domain.home}/servers/_WL_user/jpsBasicAuth/myJars/Foo.jar</url>

In this last case, the code in the file Foo.jar that calls a read operation on the credential store must be placed in an AccessController.doPrivileged block, as illustrated in the following code snippet:

import oracle.security.jps.*;
import oracle.security.jps.service.credstore.*;
 
JpsContextFactory factory = JpsContextFactory.getContextFactory();
JpsContext jpsContext = factory.getContext();
final CredentialStore store = jpsContext.getServiceInstance(CredentialStore.class);
Credential cred = AccessController.doPrivileged(new PrivilegedExceptionAction<PasswordCredential>() {
    public PasswordCredential run() throws JpsException {
        return store.getCredential("MY_MAP", "anyKey");
    }
});
           
PasswordCredential pwdCred = (PasswordCredential)cred;
...

Note that since our sample grant above allows only read permission, none of the set or reset operations work, even inside a privileged block.

J.5.5 Failure to Establish an Anonymous SSL Connection

This section explains the likely reasons why you are not able to establish an anonymous SSL connection while reassociating policies and credentials.

Symptom

A step in the reassociation of file-based policies and credentials to an LDAP-base storage using an Oracle Internet Directory server with Fusion Middleware Control involves testing the anonymous SSL connection to the LDAP server (specifically with the button Test LDAP). This test fails.

Diagnosis

Your target LDAP server must be trusted by the Oracle WebLogic Server and the port number you are using to the LDAP server must be an SSL port.

Solution

Establishing a connection to an LDAP server requires some previous configuration on the LDAP server. For details, see Section 9.2.1, "Prerequisites to Using an LDAP-Based Security Store."

In addition, to use an anonymous SSL connection, you must enter a port that has been set for receiving secure data. If your LDAP server has not been configured with such a port, the connection fails.

Ensure that the supplied LDAP server port is an SSL port configured to listen in anonymous SSL mode, and that the supplied server name reachable. Typically, the setting of this port involves an LDAP server administrator.

J.6 Troubleshooting Oracle Business Intelligence Reporting

This section describes common problems and solutions for Oracle Business Intelligence when used as a reporting tool for Oracle Fusion Middleware security. It contains the following topics:

J.6.1 Audit Templates for Oracle Business Intelligence Publisher

To view Oracle Fusion Middleware Audit Framework reports in Oracle Business Intelligence, you must use the appropriate audit templates.

For details, see Section C.2.

J.6.2 Oracle Business Intelligence Publisher Time Zone

You may see problems with Oracle Fusion Middleware Audit Framework reports if Oracle Business Intelligence Publisher and the database are installed in sites with different time zones.

To avoid this issue, ensure that Oracle Business Intelligence Publisher and the database are installed in the same time zone.

J.7 Troubleshooting Searching

This section describes the following issues:

J.7.1 Search Failure when Matching Attribute in Policy Store

This section describes a reason why cataloging of an attribute is needed.

Symptom

While searching the policy store, an exception similar to the following is encountered:

oracle.security.jps.service.policystore.PolicyStoreOperationNotAllowedException
javax.naming.OperationNotSupportedException:
[LDAP: error code 53 - Function Not Implemented, search filter attribute orcljpsresourcetypename is not indexed/cataloged];
remaining name 'cn=Permissions,cn=JAASPolicy,cn=IDCCS, cn=sprint6_policy_domain,cn=JPSContext,cn=FusionAppsPolicies'

Diagnosis

The error above indicates that the attribute orcljpsresourcetypename must be cataloged before it is used in a filter to search the policy store.

Solution

An Oracle Internet Directory attribute used in a search filter must be indexed and cataloged. Indexing and cataloging are optional operations, in general, but required for OPSS-related attributes. Attribute indexing and cataloging is automatically performed by the WLST command reassociateSecurityStore.

For details about managing attribute catalogs and identifying whether an attribute is indexed, see the following sections in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory:

To catalog attributes manually use the command ldapmodify, as illustrated bellow:

>ldapmodify -h <host> -p <port> -D <bind DN> -w <bind password> -v -f <catalogue modify ldif file name>

To catalog, for example, the attributes createtimestamp and modifytimestamp use an LDIF file like the following:

dn: cn=catalogs
changetype: modify
add: orclindexedattribute
orclindexedattribute: modifytimestamp
orclindexedattribute: createtimestamp

The list of Oracle Internet Directory attributes that must be indexed follows:

OrclJpsAllResourcKeyword
OrclJpsAllResourceActionKeyword
OrclJpsEncodedAttributes
OrclJpsExtensionType
OrclJpsResourceConverter
OrclJpsResourceMatchingAlg
OrclJpsResourceMatchingAlgorithm
OrclJpsResourceNameExpression
OrclJpsRoleType
orcOesAppAttributes
orclASInstanceName
orclFarmName
orclJPSObjGUID
orclJavaApplicationEntityRef
orclJpsPolicyDomainName
orclJpsResourceActionsetMembers
orclJpsResourceExpression
orclJpsResourceLocalityRef
orclJpsResourceMatcherJavaclass
orclJpsResourceName
orclJpsResourceTypeActionAttrs
orclJpsResourceTypeActionNames
orclJpsResourceTypeName
orclJpsResourceTypeProviderName
orclJpsResourceTypeResourceAttrs
orclJpsRoleCategory
orclJpsRoleMemberExpression
orclJpsSuperResourceType
orclOESActCollectionName
orclOESActCollectionRfs
orclOESActionAttributes
orclOESActionConstraint
orclOESAlgorithmJavaClass
orclOESAllResourceType
orclOESAllowAdviceRef
orclOESAllowObligationRef
orclOESAttributeCategory
orclOESAttributeCollectionHandlerFunctionName
orclOESAttributeCollectionHandlerPackageName
orclOESAttributeCollectionHandlerSchemaName
orclOESAttributeCollectionName
orclOESAttributeDataType
orclOESAttributeIssuer
orclOESAttributeNamespace
orclOESAttributeType
orclOESCombinerParameter
orclOESConditionExpression
orclOESDSColumnAttrs
orclOESDSPrimKey
orclOESDataSourceCtrnt
orclOESDataSourceName
orclOESDataSourceType
orclOESDefaultPolSetRef
orclOESDenyAdviceRef
orclOESDenyObligationRef
orclOESDistributionEndTime
orclOESDistributionID
orclOESDistributionIssuer
orclOESDistributionMessage
orclOESDistributionPercentComplete
orclOESDistributionStartTime
orclOESEffect
orclOESEnvAttributes
orclOESEnvConstraint
orclOESExecutionFrequency
orclOESExpression
orclOESFunctionCategory
orclOESFunctionClass
orclOESFunctionParameters
orclOESFunctionReturnType
orclOESIsSensitive
orclOESIsSingleValued
orclOESMatch