Installing and Configuring the IdentityIQ Service Code

The IdentityIQ service code is provided by SailPoint. The service code is packaged into platform-specific zip files and is downloaded from Compass. Choose the zip file appropriate for your platform.

The Linux zip file includes an executable file, an env.template file, and a shell script and service script to assist with installing the code as a service.

The Windows zip file contains an executable file and an env.template file.

Once you have downloaded the zip appropriate to your environment, follow these steps:

Extract the zip to the private server dedicated to hosting the service code. See the section on Prerequisites for Integrating Microsoft Teams with IdentityIQ for more information.
The zip file includes a template for configuring your IdentityIQ/Microsoft Teams environment, named env.template. Copy this file and name it .env.

Note: Once the zip file has been extracted, add a BOT_HOME environment variable to the server, set to the directory where your executable file, environment file, and cert directory are located (see steps below for details on the cert directory).

Edit the .env file to set configuration values for your environment. The values you must configure are listed below; some other values can be modified as needed for your environment. The variables in the file are commented, to give you information on their usage.
- PUBLIC_HOSTNAME=<public DNS hostname>: the public domain name of where you host the IdentityIQ service code. This must be a public DNS-resolvable hostname that resolves to the private IP of the server that will run the service code. The traffic can be limited to a specific port, which is customizable. See Prerequisites for Integrating Microsoft Teams with IdentityIQ.
- LOCAL_HOSTNAME=<local private IP address>: this is the private IP to which the PUBLIC_HOSTNAME is routed.
- PUBLIC_PORT and PRIVATE_PORT: the hosting ports for the IdentityIQ service code. The template provides default values which can be replaced with values specific to your installation. See the Connectivity and Security Prerequisites section in Prerequisites for Integrating Microsoft Teams with IdentityIQ.
- TENANT_ID=<Azure tenant ID>: your Azure tenant ID.
- APP_ID=<teams app ID>: the Application (client) ID value that was set as part of configuring the Microsoft Teams app. You can find this value on the Overview page of the Microsoft Teams app. See Creating a Microsoft Teams Application for IdentityIQ in Azure
- APP_NAME=<teams app name>: the name of your Microsoft Teams app. See Creating a Microsoft Teams Application for IdentityIQ in Azure
- APP_SECRET=<encrypted teams app secret>: IMPORTANT: this value is required but will be set later, in a secondary step. See step 5 below for more information.
- SSO_CONNECTION_NAME=<sso connection associated with azure bot>: this value was set in the Add OAuth Connection Settings when you configured the Azure bot. See Creating an Azure Bot for IdentityIQ's Microsoft Teams Notifications.
- ENCRYPTION_SECRET=<provide strong value>: provide an 8-character encryption secret. This can be any value you like, but if this value changes, any items encrypted must be re-encrypted
- IIQ_URL: the full URL to your installation of IdentityIQ. Use this format:
  
  https://<host/ip>:<port>/<identityiq_home>
  
  where <identityiq_home> is the directory in which you extracted the identityiq.war file during the IdentityIQ installation procedure. If you are using a load balancer to manage multiple IdentityIQ hosts, put the load balancer URL here.
Install valid certificate files in the cert directory contained in the root location where your extracted service code and .env file are. The certificate must be named bot.cert and the key must be named bot.key.

The service code can work on encrypted or raw certificates, but for security reasons, it is recommended to encrypt them. For convenience, an encrypt endpoint has been provided with the service code. Follow these guidelines for creating encrypted bot.cert and bot.key :
- Convert the raw certificate and key to single lines by replacing end of line characters with \n
- POST the single-line certificate and key to the encryption endpoint.
- Paste the responses to the POST operation into new files called bot.cert and bot.key and save them. After creating the files, verify that an end of line character was not inserted by the editor; remove the end of line character if there is one.
- Make sure the cert directory, the bot.cert and the bot.key items are set with rw permission for owner only.
- For more information on certificates, see Prerequisites for Integrating Microsoft Teams with IdentityIQ.
Encrypt and add your client secret to the environment file. For convenience, the IdentityIQ service code provides an encryption endpoint.
1. Make sure rest of the .env file has been configured and saved before encrypting and adding the client secret.
2. Start the bot (for example, by running the identityiqbot.sh script). Note that because the secret has not yet been encrypted, you may see an error when initially starting the bot. You can continue past this error to complete the process for encrypting the secret.
3. Use the following private POST endpoint to encrypt messages such as bot secret, certificate, and private key. Provide a JSON object as the payload and a JSON object will be returned with the encrypted value.
```
https://<private IP>:<private port>/util/encrypt
```
```
Input: {“message” : “some message to be encrypted”}
```
```
Output: { “status” : “success”, “encrypted_message” : “……..”}
```
4. Copy the returned value into the APP_SECRET=<encrypted teams app secret> field of the .env file.
5. Restart the bot.

Allowing Microsoft Teams Users to Disable Notifications

The ALLOW_USER_TO_DISABLE_NOTIFICATIONS property in the .env file allows Microsoft Teams users to disable notifications, by entering the command nonotifications in their Microsoft Teams environment. This option is disabled by default; if you want to allow users to disable notifications, set this value to true.


	You are here: