4.2 Installing OSP for Identity Governance

Use the following information to install One SSO Provider (OSP) for Identity Governance. If you are going to use Access Manager as the authentication services, skip the following sections and proceed to Section 4.3, Integrating Access Manager with Identity Governance.

4.2.1 Checklist for Installing One SSO Provider

You must complete the steps in the following checklist to complete the OSP installation:

	Checklist Items
	Decide where to deploy OSP and the required components in relation to your Identity Governance components. For more information, see Section 2.3, Recommended Production Environment Installation Scenarios.
	Decide whether you want to install Identity Governance and the authentication service in a clustered environment. For more information about the requirements, see Section 2.3.4, Ensuring High Availability or Load Balancing for Identity Governance.
	Review the considerations for before installing OSP. For more information, see Considerations for Installing One SSO Provider
	Ensure that Apache Tomcat has been installed on the server where you install OSP. For more information, see Section 3.0, Installing Required Components.
	Ensure that you have an identity service installed and configured. If you are in a production environment ensure that you have configured the identity service for SSL/TLS communication. For more information, see Section 3.8, Securing Connections with TLS/SSL.
	Decide which installation method to use. For more information, see Section 1.2, Understanding the Installation Methods.
	The installation directory for OSP cannot contain any spaces in the name. If it does contain spaces, the installation fails.
	Ensure that you fill out the OSP Installation Worksheet before starting the installation. The worksheet helps you gather the required information to complete the installation. You use the information you gather for the guided, console, and silent installation method. For more information, see Section 4.2.3, OSP Installation Worksheet.
	You must manually extend the schema for eDirectory or Active Directory to allow OSP authentications to work. If you integrate with Identity Manager you can skip this step. For more information, see Section 9.2.3, Extending the Schema for OSP in the Identity Service not Part of Identity Manager.

4.2.2 Considerations for Installing One SSO Provider

Before installing OSP, review the following considerations:

(Conditional) Even if you installed OSP with Identity Manager 4.5 or later, if you want to use OSP as your authentication service, you must install a separate instance of OSP for use with Identity Governance that is supported. For more information, see Section 2.4, Hardware and Software Requirements.
(Conditional) OSP requires trust certificates configured for secure communication for user authentication in a production environment. Depending on your Identity Governance solution, OSP might need to communicate with an identity service, a SAML provider, or one or more Advanced Authentication servers. For more information, see Section 3.2, Understanding the Keystore for the Identity Service.
OSP requires several generated symmetric keys along with public/private key pairs for signing, encryption, and TLS for use during normal operations to generate other key material. The installation program automatically creates the symmetric keys and key pairs and places them in the osp.pkcs12 file.
(Conditional) If you set up multiple instances of OSP for use in a high availability cluster, copy the osp.pkcs12 file from the installed location on the first server to the same location on the other member servers in the cluster. OSP must use the same keys on each member server in the cluster.
(Optional) If you want to enable auditing for OSP, you must configure the audit server to use TLS before beginning the OSP installation so that the OSP installer can connect to the audit server and retrieve the audit server’s certificate to add to the local keystore.

4.2.3 OSP Installation Worksheet

Use the following worksheet to gather the required information to successfully complete the OSP installation. You use the information that you gather with the guided installation, the console installation, and the silent installation. Select one of the installation methods to install OSP and use the worksheet so that you do not have to pause during the installation to find the required information.

Table 4-1 OSP Installation Worksheet

Item	Description	Value
Installation Location	Specify the installation path for OSP. WARNING:Spaces in the names of the directories in the path are not supported. The default location is: Linux: /opt/netiq/idm/apps/osp Windows: C:\netiq\idm\apps\osp
Apache Tomcat Details
Apache Tomcat Home Directory	Specify the path to the Apache Tomcat home directory. WARNING:Spaces in the names of the directories in the path are not supported. The installation process adds some files for OSP to this folder. The default location is: Linux: /opt/netiq/idm/apps/tomcat Windows: c:\netiq\idm\apps\tomcat
Java Home Directory for Apache Tomcat	Specify the path to the Zulu JRE home directory. The Zulu JRE is installed when you install the Zulu OpenJDK. The installation process uses Java for several processes, such as to run commands and create security stores. WARNING:Spaces in the names of the directories in the path are not supported. The default location is: Linux: /opt/netiq/idm/apps/jre Windows: c:\netiq\idm\apps\jre
Application Address for OSP	Specify the address of the application that represents the settings of the URL that users need to connect to OSP. For example, https://myserver.mycompany.com:8443. The installation program creates several symmetric keys and key pairs for signing, encryption, and TLS, which it places in the osp.pkcs12 file. The TLS key pair also specifies the host name as part of its distinguished name.
Application Address for OSP > Protocol	Select if you want the users to access a secure OSP URL for authentication to Identity Governance or not. Select http for an unsecure URL or select https for a secure URL. If you select https, ensure that you have configured Apache Tomcat to use TLS/SSL on the server that runs OSP before starting the OSP installation. For more information, see Section 3.8, Securing Connections with TLS/SSL.
Application Address for OSP > Host Name	WARNING:Use the fully qualified domain name (FQDN) name rather than localhost or an IP address. In a non-clustered environment, specify the DNS name of the Apache Tomcat server for OSP. In a clustered environment, specify the DNS name of the server that hosts the load balancer for OSP. For more information about installing in a clustered environment, see Section 2.3.4, Ensuring High Availability or Load Balancing for Identity Governance.
Application Address for OSP > Port	Specify the port that you want OSP to use for communication with the Identity Governance clients. When installing in a clustered environment, specify the port for the load balancer.
Customize the Login Screen	(Optional) Specify a name that represents the organization name that users see on the login screen. The default value is NetIQ Access. Keep in mind the following points: Allows the ASCII character set (0x20 - 0x7E) Must add escape character for dollar signs (\$) and backslashes (\\) Escaped backslashes do not appear Apostrophes and spaces are converted to pseudo-tags [apos] and [nbsp], respectively To insert a copyright symbol, type (R), which is converted to the pseudo-tag [reg]. To insert a trademark symbol, type (TM), which is converted to the pseudo-tag [tm]. An ampersand is converted to the pseudo-tag [amp]. To insert a line break, type \\r\\n, which is converted to the pseudo-tag [br]. The plus sign is converted to the pseudo-tag [plus].
Expected Setup	Select where Identity Governance and Identity Reporting reside in regard to the OSP installation. The options are external, local, and none. If you select external for Identity Governance or Identity Reporting you must gather the following information that allows OSP to communicate with these two products.
(Conditional) External Identity Governance Details > Protocol	Select whether you want OSP to communicate to Identity Governance securely or not. Select http for unsecure communications or select https for secure communications. If you select https, ensure that you have configured Apache Tomcat to use TLS/SSL on the server that runs Identity Governance before starting the OSP installation. For more information, see Section 3.8, Securing Connections with TLS/SSL.
(Conditional) External Identity Governance Details > Host Name	IMPORTANT:Do not use localhost or the IP address. In a non-clustered environment, specify the DNS name of the Apache Tomcat server for Identity Governance. In a clustered environment, specify the DNS name of the server that hosts the load balancer for Identity Governance. For more information about installing in a clustered environment, see Section 2.3.4, Ensuring High Availability or Load Balancing for Identity Governance.
(Conditional) External Identity Governance Details > Port	Specify the port that you want OSP to use for communication with Identity Governance. When installing in a clustered environment, specify the port for the load balancer.
(Conditional) External Identity Governance Details > Client Password	Specify a client password. The Client Password is the OAuth 2.0 password Identity Reporting uses for the various SSO clients. After the installation, you can change this password for each client through the Identity Governance Configuration Update utility.
(Conditional) External Identity Governance Details > Database Host Name	Specify the DNS name of the database server. WARNING:If you use the IP address of the database server, rather than the DNS name, the installation may not succeed.
(Conditional) External Identity Governance Details > Database Port	Specify the port the database server uses to communicate. The default port is: Microsoft SQL: 1433 Oracle: 1521 PostgreSQL: 5432
(Conditional) External Identity Reporting Details > Protocol	Specify the details for the URL and client password to connect OSP to the Identity Reporting server. These are the Apache Tomcat details that host Identity Reporting.
(Conditional) External Identity Reporting Details > Host Name	IMPORTANT:Do not use localhost or the IP address. In a non-clustered environment, specify the DNS name of the Apache Tomcat server for Identity Reporting. In a clustered environment, specify the DNS name of the server that hosts the load balancer for Identity Reporting. For more information about installing in a clustered environment, see Section 2.3.4, Ensuring High Availability or Load Balancing for Identity Governance.
(Conditional) External Identity Reporting Details > Port	Specify the port that you want OSP to use for communication with Identity Reporting. When installing in a clustered environment, specify the port for the load balancer.
(Conditional) External Identity Reporting Details > Client Password	Specify a client password. The Client Password is the OAuth 2.0 password Identity Governance uses for the various SSO clients. After the installation, you can change this password for each client through the Identity Governance Configuration Update utility.
Bootstrap Administrator Details	Select whether you want to use the file-based bootstrap administrator or the LDAP-based bootstrap administrator. For more information, see Section 4.1.1, Using the Bootstrap Administrator
(Conditional) File-Based Bootstrap Administrator	If you select File-Based Bootstrap Administrator, you must provide a name and a password for the bootstrap administrator. The default name is igadmin. IMPORTANT:If you are using SAML authentication for your users or Access Manager, you must select the LDAP-Based Bootstrap Administrator option. The file-based bootstrap administrator does not work in those scenarios.
(Conditional) LDAP-Based Bootstrap Administrator	If you select LDAP-Based Bootstrap Administrator, you must then provide details about the LDAP identity service so that Identity Governance can access and communicate with this server to authenticate the authorized users. IMPORTANT:If you are using SAML authentication for your users or Access Manager, you must select the LDAP-Based Bootstrap Administrator option. The file-based bootstrap administrator does not work in those scenarios.
Identity Service Details	Specify the information for the Identity Vault (LDAP server). For more information, see Understanding the Identity Service.
LDAP Host	Specify the DNS name of the LDAP identity service that contains the distinguished names of your user accounts. IMPORTANT:Do not use localhost unless you want to specify a CSV file instead of an identity service. (Test environments only)
LDAP Port	Specify the port that you want the LDAP identity service to use for communication with Identity Governance. For example, specify 389 for a non-secure port or 636 for TLS/SSL connections.
Use SSL	Select this option if the LDAP server communicates over TLS/SSL. You must have configured the LDAP server to use TLS/SSL before starting the OSP installation. For more information, see Section 3.8, Securing Connections with TLS/SSL.
Trust Store Secret	Specify the password for the trust store. The trust store is empty unless you select to use SSL for LDAP or audit.
Admin DN	Applies only when installing a new identity service. Specify the distinguished name of the LDAP administrator account that Identity Governance uses to access the LDAP identity service. For example, cn=admin,ou=sa,o=system.
Admin Password	Applies only when installing a new identity service. Specify the password of the LDAP administrator account.
User Container	Applies only when installing a new identity service. Specify the distinguished name of the LDAP container where the user accounts reside. These are the authorized users that can access and use Identity Governance. Identity Governance uses this as the top container when it searches for users. For example, ou=users,o=system.
Admin Container	Applies only when installing a new identity service. Specify the distinguished name of the container where the administrator account resides. If it is the same container where all user accounts resides, specify that name. For example, ou=sa,o=system.
(Conditional) Identity Service	After retrieving the authentication details, the installer uses the gathered information to connect to the LDAP server and attempt to determine whether the server is Active Directory or eDirectory. If this test is unsuccessful, then the installer prompts you to select the LDAP server type. The options are Active Directory or eDirectory.
(Optional) Enable Auditing	Select this option and gather the following information if you want to enable auditing for OSP.
Enable Auditing > Audit Server	IMPORTANT:Do not use localhost or the IP address. Specify the host name of the audit server.
Enabling Auditing > Audit Port	Specify the port to use for communications to the audit server. The default port is 6514.
Enabling Auditing > Audit Cache Location	Specify a local directory on the OSP server for caching of audit events before they are sent to the audit server. The default directory is: Linux: /opt/netiq/idm/apps/audit Windows: c:\netiq\idm\apps\audit
Enable Auditing > Secure Layer	Select this option if you want to communicate securely to the audit server. The OSP installer can test the certificate on the audit server to ensure that secure communication works. For more information, see Section 3.8, Securing Connections with TLS/SSL.
ConfigUpdate Details	Specify the directory where the OSP installer places the files for the Identity Governance Configuration Update utility. The default path is: Linux: /opt/netiq/idm/apps/configupdate Windows: c:\netiq\idm\apps\configudate

4.2.4 Installing One SSO Provider (OSP)

The following procedure describes how to install OSP using the guided installation or the console installation. For information about how to perform a silent installation, see Section 4.2.5, Silently Installing One SSO Provider. Ensure that you meet the prerequisites for OSP before starting the appropriate installation for your environment. For more information, see Section 4.2.2, Considerations for Installing One SSO Provider.

If you are in a clustered environment, all of the nodes of the cluster must contain the same keystore and use the same certificates for secure communication. The OSP installer can do this work for you if you wait to stop Apache Tomcat at the Installation Summary screen of the OSP installer. You must do this for each node in the cluster. If you are not clustering OSP, you must stop Apache Tomcat before the installation starts.

To install OSP:

Ensure that you have completed the OSP Installation Worksheet before starting the installation. For more information, see Section 4.2.3, OSP Installation Worksheet.
Log in as root on a Linux server or as an administrator on a Windows server where you want to install OSP.
Download and extract the OSP installation file. For more information, see Section 2.2, Obtaining Identity Governance, Identity Reporting, Workflow Engine, and OSP.
If you are in a clustered environment, proceed to Step 5, otherwise, stop Apache Tomcat. For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.
From the directory that contains the installation files, complete one of the following actions:
- Linux: Enter the following at a command prompt:
  - Guided: ./osp-install-linux.bin
  - Console: ./osp-install-linux.bin -i console
- Windows: Enter the following from a command prompt:
  - Guided: osp-install-win.exe
  - Console: osp-install-win.exe -i console
NOTE:To execute the file, you might need to use the chmod +x or sh command for Linux to change the permissions on the installer or log in to your Windows server as an administrator.
Complete the installation, using the information you gathered in the OSP Installation Worksheet. For more information, see Section 4.2.3, OSP Installation Worksheet.
Review the pre-installation summary.
(Conditional) If you are in a clustered environment, stop Apache Tomcat at this time. For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.
Start the installation process.
(Conditional) At the end of the installation, if prompted, accept or reject any certificates, and acknowledge any errors.

The installer checks to see if you specified SSL for LDAP or audit. If so, the installer creates the trust store and attempts to retrieve the certificates. Untrusted certificates result in a prompt to accept or reject each certificate chain, with tabs showing extra certificates in the chain. The installer adds accepted certificates to the trust store.

The installer displays errors in the following conditions:
- A single warning about potential future failures for all rejected certificates
- A single warning for any errors when connecting to the secured servers
When the installation process completes, review the OSP_Install.log file to see what the installer did. The default location of the OSP_Install.log file is here:
- Linux: /opt/netiq/idm/apps/osp/logs
- Windows: c:\netiq\idm\apps\osp\logs
Before starting Apache Tomcat again, delete the contents of the following two directories from Apache Tomcat that contain cached files. The directories are:
- Linux: Default installation location:
  - /opt/netiq/idm/apps/tomcat/temp
  - /opt/netiq/idm/apps/tomcat/work/Catalina/localhost
- Windows: Default installation location:
  - c:\netiq\idm\apps\tomcat\temp
  - c:\netiq\idm\apps\tomcat\work\Catalina\localhost
Start Apache Tomcat. For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.

4.2.5 Silently Installing One SSO Provider

A silent (non-interactive) installation does not display a user interface or ask you any questions. The installation files that you download from the Customer Center contain the osp-install-silent.properties. You must edit the osp-install-silent.properties file and add the correct parameters for your environment. Ensure that you have met the prerequisites before starting the silent installation. For more information, see Section 4.2.2, Considerations for Installing One SSO Provider.

Use the following information to properly populate the osp-install-silent.properties file with values from your environment and how to use the osp-install-silent.properties file to silently install OSP.

Creating a Silent Properties File for One SSO Provider

The silent properties file for OSP allows you to perform an installation without any interaction. The osp-install-silent.properties file is in the ZIP file that you download from the Customer Center. You must edit the file to add the appropriate values for your environment. The different properties in the file relate to the questions that you answer during a guided installation or console installation.

You would use the silent installation if you had several instances of OSP to install. We recommend that you install the first instance of OSP using the guided installation or the console installation with the -r parameter and a path where the installer creates a response file for you.

IMPORTANT:To ensure the installation runs correctly, create an empty file in the installation location before starting the installation.

A response file contains the correctly formated properties and values that you must add to the osp-install-silent.properties file for your environment. You can open the response file and copy the values from the response file to the osp-install-silent.properties file to simplify the process of creating the osp-install-silent.properties file.

You can also use the OSP Installation Worksheet to add the proper values to the osp-install-silent.properties file. You open the osp-install-silent.properties file in a text editor and then use the information you gathered in the OSP Installation Worksheet to add the correct values for your environment. For more information, see Section 4.2.3, OSP Installation Worksheet.

To create the osp-install-silent.properties file using the response file:

Download and extract the OSP installation files. For more information, see Section 2.2, Obtaining Identity Governance, Identity Reporting, Workflow Engine, and OSP.
Ensure that you have completed the OSP Installation Worksheet to have the information required to complete the installation. For more information, see Section 4.2.3, OSP Installation Worksheet
Create the response file.
1. From the directory that contains the installation files, complete one of the following actions:
  - Linux: Enter the following at a command prompt:
    
    Guided: ./osp-install-linux.bin -r path-to-response-file
    
    Console: ./osp-install-linux.bin -i console -r path-to-response-file
  - Windows: Enter the following at a command prompt:
    
    Guided:osp-install-win.exe -r path-to-response-file
    
    Console: osp-install-win.exe -i console -r path-to-response-file
  NOTE:To execute the file, you might need to use the chmod +x or sh command for Linux to change the permissions on the installer or log in to your Windows server as an administrator.
2. Use the OSP Installation Worksheet to complete the first guided or console installation of OSP to create the response file. For more information, see Section 4.2.3, OSP Installation Worksheet.
3. Review the OSP_Install.log file to ensure that no errors occurred.
  - Linux: /opt/netiq/idm/apps/osp/logs
  - Windows: c:\netiq\idm\apps\osp\logs
Find and open the response file in a text editor.
Find and open the osp-install-silent.properties in a text editor.
Copy the values from the response file to the osp-install-silent.properties file.

NOTE:If you are deploying on Windows, ensure that you escape the backslashes '\' or the silent properties files does not work.
Close the response file and save the osp-install-silent.properties file.
(Conditional) When installing on a secondary node in a cluster, you can modify the silent properties file using the steps in Creating a Silent Properties File for Installing an Additional Node to Cluster OSP.
Proceed to Running a Silent Installation for One SSO Provider to see how to run the silent installation using the osp-install-silent.properties file for the next installation of OSP.

Creating a Silent Properties File for Installing an Additional Node to Cluster OSP

In a clustered environment, you can use the same silent properties file for each node. However, you might choose to run the guided installation or the console installation on the primary node with the -r parameter to create the response file. You can then silently install on the secondary nodes. You can quickly create a silent properties file from the response file that the guided installation or console installation creates. For more information, see Creating a Silent Properties File for One SSO Provider.

There are additional parameters that you must add to the osp-install-silent.properties file if you are installing secondary nodes in a cluster. Use the following procedure to modify the osp-install-silent.properties file for any secondary nodes in the OSP cluster.

To create an osp-install-silent.properties file for secondary cluster nodes:

After installing OSP on the primary node, locate the response file in the directory you specified. For more information, see Creating a Silent Properties File for One SSO Provider.
Locate the sample osp-install-silent.properties file, by default in the same directory as the installer program for OSP.
Open the files in a text editor.
Copy the parameter values from the response file to their corresponding parameters in the silent properties file.
Change the values that represent true/false settings:

Log file

Silent.properties file

0

false

1

true

Log file	Silent.properties file
0	false
1	true

Change the values for the NetIQ servlet and auditing protocols as specified in the following table:

Log file	Silent.properties file
NETIQ_SERVLET_PROTOCOL_HTTP=1 NETIQ_SERVLET_PROTOCOL_HTTPS=0	NETIQ_SERVLET_PROTOCOL=http
NETIQ_SERVLET_PROTOCOL_HTTP=0 NETIQ_SERVLET_PROTOCOL_HTTPS=1	NETIQ_SERVLET_PROTOCOL=https
NETIQ_OSP_AUDIT_PROTOCOL_TCP=1 NETIQ_OSP_AUDIT_PROTOCOL_TLS=0 NETIQ_OSP_AUDIT_PROTOCOL_UDP=0	NETIQ_OSP_AUDIT_PROTOCOL=tcp
NETIQ_OSP_AUDIT_PROTOCOL_TCP=0 NETIQ_OSP_AUDIT_PROTOCOL_TLS=1 NETIQ_OSP_AUDIT_PROTOCOL_UDP=0	NETIQ_OSP_AUDIT_PROTOCOL=tls
NETIQ_OSP_AUDIT_PROTOCOL_TCP=0 NETIQ_OSP_AUDIT_PROTOCOL_TLS=0 NETIQ_OSP_AUDIT_PROTOCOL_UDP=1	NETIQ_OSP_AUDIT_PROTOCOL=udp

(Optional) Specify any number of certificate files and corresponding aliases to accept into the trust store. For example:
```
NETIQ_CERT_1_FILE=/home/username/Downloads/ldap_cert
NETIQ_CERT_1_ALIAS=osp-ldap
```
NOTE:You can specify the files in any order, and they must exist on the same machine as the OSP installer. The installer starts trusting with 1 and stops with the first missing consecutive number. So if you list files 1, 2, and 4, the installer only trusts certificates 1 and 2.
Save and close the files.
Copy the updated osp-install-silent.properties file to the server that becomes a node in the cluster.
Perform the silent installation on the new node using this modified file. For more information, see Running a Silent Installation for One SSO Provider.

Running a Silent Installation for One SSO Provider

A silent (non-interactive) installation does not display a user interface or ask any questions. Instead, the system uses information from the osp-install-silent.properties file to complete the installation. You would perform this type of installation if you have multiple installations to perform or you are deploying a clustered environment. This file is included with the OSP installation files. You must have the osp-install-silent.properties file populated with the correct values for your environment before you start the silent installation.

To perform a silent installation of OSP:

Ensure that you have created the osp-install-silent.properties file for your environment. For more information, see Creating a Silent Properties File for One SSO Provider.
(Conditional) If this server is an additional node to cluster OSP, ensure that you properly modify the osp-install-silent.properties file for the additional nodes in a cluster. For more information, see Creating a Silent Properties File for Installing an Additional Node to Cluster OSP.
Ensure that this server meets the prerequisites for OSP before starting the installation. For more information, see Section 4.2.2, Considerations for Installing One SSO Provider
Ensure that the OSP installation files are on this server. For more information, see Section 2.2, Obtaining Identity Governance, Identity Reporting, Workflow Engine, and OSP.
Log in as root on Linux server or an administrator on Windows server where you want to install OSP.
Stop Apache Tomcat. For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.
Copy the populated osp-install-silent.properties file to this server.
To run the silent installation, from a command prompt issue the following command:
- Linux: ./osp-install-linux.bin -i silent -f path_to_silent_properties_file
- Windows: osp-install-win.exe -i silent -f path_to_silent_properties_file
NOTE:If the silent properties file is in a different directory from the installation script, you must specify the full path to the file. The script unpacks the necessary files to a temporary directory and then launches the silent installation.
When the console prompt returns, review the log file to ensure that the installation completed successfully. The silent installation does not display any messages on the console.

The log file is located in the following default directory:
- Linux: /opt/netiq/idm/apps/osp/logs/
- Windows: c:\netiq\idm\apps\osp\logs\
When the installation process completes, continue to Section 6.0, Installing Identity Governance.