4 Creating and Maintaining System Identities

This chapter includes the following sections:

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

The procedures in this section assume 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 can be used to represent external systems or system administrator logins, for example, the default system administrator. The purpose is to allow entities, not represented as people within Oracle Role Manager to have the ability to login.

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 in the database used by Oracle Role Manager. This database 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. The attributes for System Identity creation are the same as those allowed during data load. For information about what attributes are available, refer to the Oracle Role Manager Developer's Guide.

You will have to load data in a .dar file to grant system roles to the created System Identity. See ORMHome/samples/sample_data/admin_systemrole_privilege_mapping.dar as an example.

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
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_HOME/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_HOME/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 Oracle Role Manager application user.
At the prompt, type the password for the Oracle Role Manager system 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_HOME/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_HOME/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 Oracle Role Manager 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 re-grant any roles that had been granted to the original System Identity. For information about recovering the Oracle Role Manager System Identities, refer "Restoring the Oracle Role Manager System Administrator".

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

To delete a System Identity:

In a command-line window, navigate to the home directory where Oracle Role Manager is installed.
Navigate to ORM_HOME/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_HOME/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 Oracle Role Manager application user.

4.5 Restoring the Oracle Role Manager System Administrator

The RebootstrapTool can be used for recovering from a system where the role grants or entitlement mappings for the system administrator have been corrupted or removed. This tool reinstates the current default configuration stored in the database with the name oracle.iam.rm.bootstrap/default.xml.

If you have deployed configuration_hardened.car, then the configuration file, configuration_hardened.car/config/oracle.iam.rm.bootstrap/default.xml is stored in Oracle Role Manager database. When the rebootstrap tool is run again, this configuration file (configuration_hardened.car/config/oracle.iam.rm.bootstrap/default.xml), is fetched from the database and used, so that it gives the same privileges to the System Administrator.

To restore the Oracle Role Manager System Administrator:

Note:

You must stop the server before performing the following steps.

In ORM_HOME/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_HOME/bin.
Run the following command to recover the Oracle Role Manager system administrator:
```
rebootstrap_tool <ormapp-user> <admin-user>
```
where:

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

<admin-user> is the username of the Oracle Role Manager system administrator you want to restore.
At the prompt, type the password of the Oracle Role Manager application user.
At the prompt, type a password for the system administrator to be restored. 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, then the user account is locked. Perform one of the following procedures 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 Table 2-1, "Authentication Configuration Values".
If all System Identities are locked making you unable to use the Oracle Role Manager console, then run the following script to unlock one of the accounts:
```
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.

Note:

You must stop the server before performing Step 2.