IBM Security Privileged Identity Manager, Version 2.1.0

Deploying a single node

Deploy a single Privileged Session Gateway node for a simple deployment.

Procedure

  1. Create a copy of the response file,ibm-session-gateway.rsp, and provide a new name.

    For example: gateway1.rsp

  2. Obtain the Privileged Session Gateway activation key.

    Available only from 2.1.0, fix pack 3.

    1. Download the activation key package from Passport Advantage®.
    2. Extract the compressed file and open the text file.
    3. In the Privileged Session Gateway response file, enter the activation key in the activation_key parameter.
  3. With disable_client_authorization set to no, get the Privileged Session Gateway client ID.

    Available only from 2.1.0, fix pack 3.

    For more information about trusted sessions, see disable_client_authorization.

    1. To obtain a Client ID, configure the Privileged Session Gateway location in the virtual appliance. See Managing the Privileged Session Gateway configuration. After the Privileged Session Gateway is configured, the Client ID is displayed in the Privileged Session Gateway configuration page.
    2. In the Privileged Session Gateway response file, for the authorized_clients parameter, enter the client ID and the virtual appliance or load balancer URL in the required format. See Table 1. For example: "123ab-123ab-1234-123AB-123AB,https://pimva.example.local"
  4. Obtain the IBM® Security Privileged Identity Manager virtual appliance root certificate by selecting one of the following approaches:
    To obtain the certificate by Do
    Providing the domain name of the IBM Security Privileged Identity Manager virtual appliance or load balancer.

    In the response file, specify the outbound_certificate_urls parameter. For example: pimva.local:443. See Table 1.
    Exporting the certificate to a directory location.
    1. Export the certificate with a .crt file extension in one of the following supported formats:
      • X.509 Certificate (PEM)
      • Base64 Encoded X.509
      Note: You must export the certificate with a .crt file extension.
      Important: In a tree representation of the certification path, the root certificate is typically represented as the first item in the certification path. For example: PIMVA.

      To deploy a self-signed company certificate or a CA signed certificate, export the certificate to a file in the supported format.

      To obtain the virtual appliance root certificate with a web browser, browse to the IBM Security Privileged Identity Manager URL: https://<ispimva>.

      See your web browser documentation on how to export the certificate for a website to a file.
      Note: In Mozilla Firefox, be sure to save the certificate with a .crt file extension to avoid problems.

      The IBM Security Privileged Identity Manager virtual appliance certificate that you obtain is an outbound certificate for the gateway.

    2. Copy the exported certificate to a directory where the certificate can be retrieved.

      For example:

      ~/session-gateway/certs_out/
  5. Optional: If an enterprise CA signed certificate is required for inbound connections, complete the following steps:
    1. Add the certificate to a PKCS#12 keystore. Example keystore file: custom-root.p12
    2. Place the keystore in the Privileged Session Gateway inbound keystore directory.

      For example: ~/session-gateway/certs_in/

  6. In the new response file, review the required parameters.
    Table 1. Configuration parameters for a single node
    Parameter Importance Description
    gateway_id Required The gateway container ID.

    The ID must consist only of the following characters [a-zA-Z0-9.-].

    It is case-sensitive.

    For example: gateway1

    In a load balanced deployment, each gateway ID in the cluster must be unique.
    activation_key

    Available only from 2.1.0, fix pack 3.

    		 Required The activation key for the Privileged Session Gateway.

    Obtain the activation key from Passport Advantage.
    outbound_certificate_urls

    Available only from 2.1.0, fix pack 3.

    		 Optional

    Domain name where the outbound certificate for the virtual appliance or load balancer can be retrieved.

    Include the port number of the virtual appliance or load balancer that is used for listening to requests.

    Note: Alternatively, you can specify the outbound certificate with the outbound_certificate_directory parameter for the outbound certificates.

    Do not include https:// in the value.

    For example: "pimva.example.local:443"

    The outbound certificates are imported later to the Gateway trust store.
    outbound_certificate_directory Optional Directory where the outbound certificate for the virtual appliance or load balancer that you export can be retrieved. See step 4.
    Note: If you are specifying outbound certificates by providing the URL for outbound_certificate_urls, you do not need to specify a value for outbound_certificate_directory. If both parameters are specified, the certificates that are found with outbound_certificate_urls take precedence.

    For example: ~/session-gateway/certs_out/

    The outbound certificates are imported later by the shell script to the Gateway trust store.
    https Optional The HTTP protocol to use.

    For a single node deployment without a load balancer, only HTTPS is supported.

    Set the value to yes.

    https=yes

    Default value is no.
    port Optional The HTTP or HTTPS port number that is used for listening to requests.

    Default value when HTTP is enabled (https=no): 9080.

    Default value when HTTPS is enabled (https=yes): 9443.
    keystore_path Optional Path to the keystore file that contains the custom inbound certificate.

    Production deployments typically require the use of an organization's own self-signed certificate or an enterprise signed CA certificate. To use these certificates, export and save the signed .p12 certificate to this directory. Ensure that you specify the keystore password for the keystore_password parameter.

    For example: ~/session-gateway/certs_in/custom-root.p12
    keystore_password Optional The password for the keystore file.
    disable_client_authorization

    Available only from 2.1.0, fix pack 3.

    		 Optional

    Toggles whether client authorization restriction is disabled.

    If set to yes, client authorization is disabled.

    Default is no.

    Note: If the IBM Security Privileged Identity Manager virtual appliance is version 2.1.0, and the Privileged Session Gateway is upgraded to 2.1.0 fix pack 3, disable client authorization to avoid disruptions to Privileged Session Gateway access. As soon as the IBM Security Privileged Identity Manager virtual appliance is upgraded to 2.1.0 fix pack 3, enable client authorization, and configure the authorized_clients parameter.
    Important: Avoid disabling client authorization. Client authorization ensures that only trusted clients such as IBM Security Privileged Identity Manager can initiate connections through the Privileged Session Gateway.

    See authorized_clients.
    authorized_clients

    Available only from 2.1.0, fix pack 3.

    		 Optional

    The list of authorized IBM Security Privileged Identity Manager virtual appliance cluster or stand-alone instances that are allowed to connect to the Privileged Session Gateway. The list is specified as a value pair.

    Before you can define this parameter, you must obtain a Client ID. To obtain a Client ID, configure the Privileged Session Gateway location in the virtual appliance. See Managing the Privileged Session Gateway configuration.

    You must enclose the assigned values for the authorized_clients parameter with double quotation marks (" ").

    Syntax:

    "<client_id>,<referrer>"

    client_id
    The client ID that is generated when you configure the Privileged Session Gateway location in the virtual appliance dashboard. To retrieve the client_id, see Managing the Privileged Session Gateway configuration.

    Not case-sensitive.

    referrer
    The IBM Security Privileged Identity Manager virtual appliance or load balancer URL.

    If you are listing multiple clients, separate each value pair with a semi-colon.

    For example: "123AB-123AB-1234b-123AB-123AB,https://referrer1;567a-567a-5678,https://referrer2"

    Note: If this parameter is not specified and client authorization is enabled, connections are not allowed. See disable_client_authorization
    For example:
    # This is an example response file to start the Privileged Session Gateway container.
# Lines that begin with # or * are treated as comments. 
*
* NOTE: Spaces are not allowed between parameter and attribute values.

################ MANDATORY CONFIGURATION ####################

# Identifies the gateway instance uniquely.
gateway_id=gateway1

# Activation key for the Privileged Session Gateway. Obtain the activation key from Passport Advantage.
# For example: 123AB-123AB-123AB-123AB-123AB
activation_key=

################ OPTIONAL CONFIGURATION  ####################

# It is recommended that at least outbound_certificate_directory or 
# outbound_certificate_urls is specified

# Directory that contains outbound certificates which will import to Gateway Trust Store. 
# The certificate file must be PEM(base64) encoded X.509 certificate file, with file extension as ".crt".
# outbound_certificate_directory=~/session-gateway/certs_out/

# List of ; delimited URLs. The Gateway parses these URL, imports the certificate and updates them. 
# Do not provide https:// tag. Example URLs: "pimva.local:443"
outbound_certificate_urls="pimva.example.local:443"

# IBM Session Gateway image name. Default is 'ibm-session-gateway'.
docker_image_name=ibm-session-gateway

# IBM Session Gateway image tagname. Default is 'latest'.
docker_image_tag=latest

# Mounted directory for logs etc. Default is ~/ibm/shared/.
shared_directory=~/ibm/shared/

# If yes, use HTTPS. If no, use HTTP. Default is no.
https=yes

# HTTP or HTTPS port used to access REST APIs and GUI. If HTTP, default is 9080; if HTTPS,
# default is 9443.
port=9443

# Keystore(PKCS12 format) containing the custom inbound root cert (with private key), if not set, the Gateway will generate 
# or use a previously generated certificate.
# NOTICE: The keystore file will be copied to <shared dir>/security/custom_root.p12. If not set, the keystore 
# will be generated at <shared dir>/security/self-root.p12, and the keystore password is 'gateway'.
keystore_path=

# Password for the keystore file.
keystore_password=

# File containing outbound aliases for targets. Default is /etc/hosts.
hosts_file=/etc/hosts

# Recording segment file size (minimum is '1KB', maximum is '10MB'). Format is <integer value><unit(KB/MB)>. Default is '1MB'.
segment_size=1MB

# Number of uploader threads (minimum is 5, maximum is 100). Default is 5.
uploader_threads=5

# Log level for Gateway services. Valid options are: error, warning, info, debug. Default is info.
log_level=info

# If yes, there is no client restriction and the authorized_clients parameter is ignored. Default is no.
# NOT RECOMMENDED FOR USE: use this with caution because disabling client authorization can open the system to probing attacks
disable_client_authorization=no

# Identifies the IBM Security Privileged Identity Manager  virtual appliance instance or  load balancer (clustered deployments) 
# that can connect to the Privileged Session Gateway.
# List of ";" delimited authorized client IDs and referers. The format is  "<client id>,<referer>;<client id>,<referer>".
# If no authorized clients are listed and client authorization is not disabled, no connection order requests  are allowed.
authorized_clients="123a-123a-1234,https://pimva.example.local"
  7. Save the response file to a location on the computer.

    For example: ~/session-gateway/gateway1.rsp

  8. Initialize the Privileged Session Gateway image with the response file as a parameter.

    ./run.sh -f -r gateway1.rsp

    Shared folders are created in ~/ibm/shared/<gateway_id>

    The p12 keystore file is copied to the mounted shared folder ~/ibm/shared/<gateway_id>/security/ as custom-root.p12.

    If the keystore options in the response file are not specified, a self-signed certificate is automatically generated with a Common Name that is equal to the gateway ID as specified in the response file. The self-self certificate is then copied to the mounted shared folder ~/ibm/shared/<gateway id>/security/ as self-root.p12

  9. Verify that the Privileged Session Gateway instance is started.

    docker ps

    Example result:

    CONTAINER ID        IMAGE                          COMMAND                  CREATED             STATUS              PORTS                              NAMES
1052274c7aae        ibm-session-gateway:latest   "/usr/bin/supervisord"   2 hours ago         Up 2 hours          9080/tcp, 0.0.0.0:9443->9443/tcp   gateway1
    Note: Certificate and hosts file changes are only applied once after you initialize the node. To apply the changes, you must restart the node. See Restarting a node.
Parent topic: Privileged Session Gateway installation

Feedback