4 Creating and Maintaining System Identities

This chapter includes the steps required to configure the application server to run the Oracle Role Manager server and Web application.

This chapter includes the following sections:

About System Identities
Creating System Identities
Updating System Identities
Deleting System Identities
Restoring the Oracle Role Manager System Identity

The procedures in this section assumes that you have already completed the following steps:

A database instance has been created for Oracle Role Manager with the appropriate tablespaces.
The Oracle Role Manager database owner and application user schemas have been created and contain no data.
The database is accessible.
The Oracle Role Manager administrative tools are accessible.
The application server on which Oracle Role Manager is or will be deployed is not running.

Refer to the Oracle Role Manager Installation Guide for more information about these assumptions.

4.1 About System Identities

System Identities are system user objects that are created to access the Oracle Role Manager system. System Identities normally represent external systems, such as a user provisioning system that accesses Oracle Role Manager for role resolution for workflows or access provisioning.

Although System Identities can be created or modified as part of a data load process, the command-line administrative tool described in this chapter is what administrators will use to create and manage System Identity objects.

The command-line tool provides the following functions for System Identities:

Create
Update
Delete

As with the other administrative tools provided with Oracle Role Manager, the System Identity management tool must be run at the command line with the appropriate classpath and access to the Oracle Role Manager libraries.

4.2 Creating System Identities

The System Identity Tool creates System Identities and their attributes on the database that is defined by the combination of the provided database properties (JDBC driver class name and JDBC connection URL) that are identified by the provided username/password.

When creating System Identities, you must provide a file that contains attribute values for the System Identity, such as privilege mapping and permissions. The attributes for System Identity creation are the same as those allowed during data load. For information about what attributes are available, refer to Chapter 3.

Example 4-1 Creating a System Identity for the PeopleSoft System

systemidentity_create appuser peoplesoft peoplesoft.txt

This would create the peoplesoft System Identity with any attribute values as specified in the peoplesoft.txt file, whose contents might resemble:

#Attributes for the Peoplesoft system identity
displayName=Peoplesoft Identity
uniqueName=peoplesoft
status=active
mail=peoplesoft.admin@mycompany.com
description=The System Identity that represents the Peoplesoft system for integration purposes

To create a System Identity:

Create a text file that contains the required and optional attributes to set for the System Identity. (Refer to the preceding example.)
In a command-line window, navigate to the home directory where Oracle Role Manager is installed.
Navigate to <ORM_install>/config, and edit the db.properties file to match your environment:
```
db.driverClass=oracle.jdbc.driver.OracleDriver
db.connection_string=jdbc:oracle:thin:@$HOST$:$PORT$/$SERVICE_NAME$
```
where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE_NAME$ is the database service name on which the Oracle Role Manager users/schemas were created.
In a command window, navigate to <ORM_install>/bin.
Run the following command to create a System Identity:
```
systemidentity_create <ormapp-user> <new-user> <attrfile>
```
where:

<ormapp-user> is the username of the database "application" user/schema for Oracle Role Manager.

<admin-user> is the username to use as the Oracle Role Manager System Administrator.

<attrfile> is the path to the file containing the required attributes for role creation.
At the prompt, type the password of the ORM application user.
At the prompt, type the password for the ORM Administrator account.

4.3 Updating System Identities

The System Identity Tool can also be used to update passwords and other attributes of System Identities already in the system.

When updating System Identities without attribute updates, the attributes file is not required. If the tool doesn't detect any new information, no updates will occur.

Example 4-2 Updating the System Identity for the PeopleSoft System

systemidentity_update appuser peoplesoft newattributes.txt

This would update the peoplesoft System Identity with new attributes.

To update a System Identity:

In a command-line window, navigate to the home directory where Oracle Role Manager is installed.
Navigate to <ORM_install>/config, and edit the db.properties file to match your environment:
```
db.driverClass=oracle.jdbc.driver.OracleDriver
db.connection_string=jdbc:oracle:thin:@$HOST$:$PORT$/$SERVICE_NAME$
```
where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE_NAME$ is the database service name on which the Oracle Role Manager users/schemas were created.
In a command window, navigate to <ORM_install>/bin.
Run the following command to update the System Identity:
```
systemidentity_update <ormapp-user> <admin-user> <attrfile>
```
where:

<ormapp-user> is the username of the database "application" user/schema for Oracle Role Manager.

<admin-user> is the username of the System Identity to update.

<attrfile> is the path to the file containing any changed attributes for the System Identity. This file is optional. If not provided, attributes will not be updated.
At the prompt, type the password of the ORM application user.
To update the password of the System Identity:
1. Type Y at the prompt.
2. Type the new password of System Identity.

4.4 Deleting System Identities

The System Identity Tool can also be used to delete System Identities already in the system.

Note:

Delete System Identities with caution. Only the Oracle Role Manager System Identities are recoverable. If you mistakenly delete a System Identity, you must create it again and regrant any roles that had been granted to the original System Identity.

Example 4-3 Deleting the System Identity for the PeopleSoft System

systemidentity_delete appuser peoplesoft

This would delete the peoplesoft System Identity along with any relationships, role grants and privileges.

To delete a System Identity:

In a command-line window, navigate to the home directory where Oracle Role Manager is installed.
Navigate to <ORM_install>/config, and edit the db.properties file to match your environment:
```
db.driverClass=oracle.jdbc.driver.OracleDriver
db.connection_string=jdbc:oracle:thin:@$HOST$:$PORT$/$SERVICE_NAME$
```
where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE_NAME$ is the database service name on which the Oracle Role Manager users/schemas were created.
In a command window, navigate to <ORM_install>/bin.
Run the following command to delete the Oracle Role Manager System Identity:
```
systemidentity_delete <ormapp-user> userID
```
where:

<ormapp-user> is the username the database "application" user/schema for Oracle Role Manager.
At the prompt, type the password of the ORM application user.

4.5 Restoring the Oracle Role Manager System Identity

The RebootstrapTool can be used for recovering from a system where the role grants or privilege mappings for the System Administrator have been corrupted or removed.

To restore the Oracle Role Manager System Administrator:

Note:

You must stop the server before performing the following steps.

In <ORM_install>/config, update the db.properties file that contains the following two lines:
```
db.driverClass=oracle.jdbc.driver.OracleDriver
db.connection_string=jdbc:oracle:thin:@$HOST$:$PORT$/$SERVICE_NAME$
```
where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE_NAME$ is the database service name on which the Oracle Role Manager users/schemas were created.
In a command window, navigate to <ORM_install>/bin.
Run the following command to recover the Oracle Role Manager System Identities:
```
rebootstrap_tool <ormapp-user> <admin-user>
```
where:

<ormapp-user> is the username of the ORM application user/schema.

<admin-user> is the username of the Oracle Role Manager System Identity you want to restore.
At the prompt, type the password of the ORM application user.
At the prompt, type a password for the System Identity to restore. This can be the original password or a new password.

4.6 Resetting the Failed Login Count

This feature enables you to reset the user's password in case the user account is locked out. A counter is used to record the number of failed attempts performed for each user's account. If the failed attempts exceeds the configurable limit, the user account is locked. Perform one of the following approaches to unlock the account:

Reset the login attempt counter by performing the following steps:
1. Log in to Oracle Role Manager Admin Console.
2. Go to Security and click Reset User. The Reset user's login failure count page is displayed. You can use this screen to reset the failed login attempt counter for both users and system identities and is the only way to reset the counter for users.
3. In the User Type field, select the user type, either person or system identity.
4. In the User Name field, enter the user name whose account has been locked.
5. Click Reset Count. For information about setting the default count, refer to Table 2-1, "Authentication Configuration Values".
If all System Identities are locked making you unable to use the ORM console, then run the following script to unlock the account:
```
systemidentity_update <ormapp-user> <admin-user> <attrfile>
```
where:

<ormapp-user> is the username of the database application user/schema for Oracle Role Manager.

<admin-user> is the username of the System Identity to update.

<attrfile> is the path to the file containing any changed attributes for the System Identity. This file is optional and if not provided, then attributes will not be updated.
If the system identity of the System Administrator is locked, then run the following script to unlock the account:
```
systemidentity_update.bat.sh
```

Note:

You must stop the server before performing the Step 2 and Step 3.