Autonomous Identity 2021.8.7

Install a Multi-Node Air-Gapped Deployment

This chapter presents instructions on deploying Autonomous Identity in a multi-node air-gapped or offline target machine that has no external Internet connectivity. ForgeRock provides a deployer script that pulls a Docker image from ForgeRock’s Google Cloud Registry (gcr.io) repository. The image contains the microservices, analytics, and backend databases needed for the system.

The air-gap installation is similar to that of the multi-node deployment, except that the image and deployer script must be stored on a portable drive and copied to the air-gapped target environment.

The deployment example in this section uses the same multi-node deployment as seen in Example Topology.

The deployment depends on how the network is configured. You could have a Docker cluster with multiple Spark nodes and Cassandra or MongoDB nodes. The key is to determine the IP addresses of each node.

Figure 9: A multi-node air-gap deployment.

Autonomous Identity deployed in a multi-node air-gapped deployment

Prerequisites

Let’s deploy Autonomous Identity on a single-node target on CentOS 7. The following are prerequisites:

  • Operating System. The target machine requires CentOS 7. The deployer machine can use any operating system as long as Docker is installed. For this chapter, we use CentOS 7 as its base operating system.

  • Default Shell. The default shell for the autoid user must be bash.

  • Subnet Requirements. We recommend deploying your multi-node machines within the same subnet. Ports must be open for the installation to succeed. Each instance should be able to communicate to the other instances.

    If any hosts used for the Docker cluster (docker-managers, docker-workers) have an IP address in the range of 10.0.x.x, they will conflict with the Swarm network. As a result, the services in the cluster will not connect to the Cassandra database or Elasticsearch backend.

    The Docker cluster hosts must be in a subnet that provides IP addresses 10.10.1.x or higher.

  • Deployment Requirements. Autonomous Identity provides a deployer.sh script that downloads and installs the necessary Docker images. To download the deployment images, you must first obtain a registry key to log into the ForgeRock Google Cloud Registry (gcr.io). The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.

  • Filesystem Requirements. Autonomous Identity requires a shared filesystem accessible from the Spark master, Spark worker, analytics hosts, and application layer. The shared filesystem should be mounted at the same mount directory on all of those hosts. If the mount directory for the shared filesystem is different from the default, /data , update the /autoid-config/vars.yml file to point to the correct directories:

    analytics_data_dir: /data
    analytics_conf_dif: /data/conf
  • Architecture Requirements. Make sure that the Spark master is on a separate node from the Spark workers.

  • Database Requirements. Decide which database you are using: Apache Cassandra or MongoDB. The configuration procedure is slightly different for each database.

  • Docker Required on Air-Gap Machines. When installing the Autonomous Identity binaries on the air-gap machine using a tar file, you must also manually install Docker 20.10.7 onto the machine.

  • IPv4 Forwarding. Many high-security environments run their CentOS-based systems with IPv4 forwarding disabled. However, Docker Swarm does not work with a disabled IPv4 forward setting. In such environments, make sure to enable IPv4 forwarding in the file /etc/sysctl.conf:

    net.ipv4.ip_forward=1
We recommend that your deployer team have someone with Cassandra expertise. This guide is not sufficient to troubleshoot any issues that may arise.

Set Up the Target Nodes

Set up each node as presented in Set Up the Nodes for Non-Airgap.

Make sure you have sufficient storage for your particular deployment. For more information on sizing considerations, see Deployment Planning Guide.

Set Up the Deployer Machine

Set up the deployer on an Internet-connected machine.

  1. The install assumes that you have CentOS 7 as your operating system. Check your CentOS 7 version.

    $ sudo cat /etc/centos-release
  2. Set the user for the target machine to a username of your choice. For example, autoid.

    $ sudo adduser autoid
  3. Set the password for the user you created in the previous step.

    $ sudo passwd autoid
  4. Configure the user for passwordless sudo.

    $ echo "autoid  ALL=(ALL)  NOPASSWD:ALL" | sudo tee /etc/sudoers.d/autoid
  5. Add administrator privileges to the user.

    $ sudo usermod -aG wheel autoid
  6. Change to the user account.

    $ su - autoid
  7. Install yum-utils package on the deployer machine. yum-utils is a utilities manager for the Yum RPM package repository. The repository compresses software packages for Linux distributions.

    $ sudo yum install -y yum-utils
  8. Create the installation directory. Note that you can use any install directory for your system as long as your run the deployer.sh script from there. Also, the disk volume where you have the install directory must have at least 8GB free space for the installation.

    $ mkdir ~/autoid-config

Install Docker on the Deployer Machine

Install Docker on the deployer node as presented in Install Docker for Non-Airgap.

Set Up SSH on the Deployer

  1. On the deployer machine, run ssh-keygen to generate an RSA keypair, and then click Enter. You can use the default filename. Enter a password for protecting your private key.

    $ ssh-keygen -t rsa -C "autoid"

    The public and private rsa key pair is stored in home-directory/.ssh/id_rsa and home-directory/.ssh/id_rsa.pub .

  2. Copy the SSH key to the autoid-config directory.

    $ cp ~/.ssh/id_rsa ~/autoid-config
  3. Change the privileges to the file.

    $ chmod 400 ~/autoid-config/id_rsa

Prepare the Tar File

Run the following steps on an Internet-connected host machine:

  1. On the deployer machine, change to the installation directory.

    $ cd ~/autoid-config/
  2. Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.

    $ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid

    You should see:

    Login Succeeded
  3. Run the create-template command to generate the deployer.sh script wrapper. Note that the command sets the configuration directory on the target node to /config. Note that the --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files.

    $ docker run --user=$(id -u) -v ~/autoid-config:/config -it gcr.io/forgerock-autoid/deployer:2021.8.7 create-template
  4. Open the ~/autoid-config/vars.yml file, set the offline_mode property to true, and then save the file.

    offline_mode: true
  5. Download the Docker images. This step downloads software dependencies needed for the deployment and places them in the autoid-packages directory.

    $ sudo ./deployer.sh download-images
  6. Create a tar file containing all of the Autonomous Identity binaries.

    $ tar czf autoid-packages.tgz deployer.sh autoid-packages/*
  7. Copy the autoid-packages.tgz to a portable hard drive.

Install on the Air-Gapped Target

Before you begin, make sure you have CentOS 7 and Docker installed on your air-gapped target machine.

  1. Create the ~/autoid-config directory if you haven’t already.

    $ mkdir ~/autoid-config
  2. Unpack the tar file.

    $ tar xf autoid-packages.tgz -C ~/autoid-config
  3. On the air-gap host node, copy the SSH key to the ~/autoid-config directory.

    $ cp ~/.ssh/id_rsa ~/autoid-config
  4. Change the privileges to the file.

    $ chmod 400 ~/autoid-config/id_rsa
  5. Change to the configuration directory.

    $ cd ~/autoid-config
  6. Install Docker.

    $ sudo ./deployer.sh install-docker
  7. Log out and back in.

  8. Change to the configuration directory.

    $ cd ~/autoid-config
  9. Import the deployer image.

    $ ./deployer.sh import-deployer
  10. Create the configuration template using he create-template command. This command creates a configuration file, ansible.cfg.

    $ ./deployer.sh create-template
  11. Make the script executable.

    $ chmod +x deployer.sh
  12. To see the list of commands, enter deployer.sh.

    $ ./deployer.sh
    
    Usage: deployer <command>
    
    Commands:
      create-template
      download-images
      import-deployer
      encrypt-vault
      decrypt-vault
      run
      create-tar
      install-docker
      install-dbutils
      upgrade

Configure Autonomous Identity

The create-template command from the previous section creates a number of configuration files, required for the deployment: ansible.cfg, vars.yml, hosts, and vault.yml.

If you are running a deployment for evaluation, you can minimally set the private IP address mapping in the vars.yml file in step 2, edit the hosts file in step 3, jump to step 6 to download the images and then run the deployer in step 7.
For air-gapped deployments, you must set the offline_mode property to true in the ~/autoid-config/vars.yml file in step 2 below. This is a new change in 2021.8.7 from prior releases.
  1. Open a text editor and edit the ~/autoid-config/ansible.cfg to set up the remote user and SSH private key file location on the target node. Make sure that the remote_user exists on the target node and that the deployer machine can ssh to the target node as the user specified in the id_rsa file.

    [defaults]
    host_key_checking = False
    remote_user = autoid
    private_key_file = id_rsa
  2. On the deployer machine, open a text editor and edit the ~/autoid-config/vars.yml file to configure specific settings for your deployment:

    • AI Product. Do not change this property.

      ai_product: auto-id
    • Domain and Target Environment. Set the domain name and target environment specific to your deployment by editing the /autoid-config/vars.xml file. By default, the domain name is set to forgerock.com and the target environment is set to autoid. The default Autonomous Identity URL will be: https://autoid-ui.forgerock.com. For this example, we use the default values.

      domain_name: forgerock.com
      target_environment: autoid

      If you change the domain name and target environment, you need to also change the certificates to reflect the new changes. For more information, see Customize Domains.

    • Analytics Data Directory and Analytics Configuration Direction. For a multi-node Spark deployment, Autonomous Identity requires a shared filesystem accessible from Spark Master, Spark Worker(s), and Analytics hosts. The shared filesystem should be mounted at same mount directory on all of the above hosts. If the mount directory for shared filesystem is different than /data, update the following properties in the vars.yaml file to point to the correct location:

      analytics_data_dir: /data
      analytics_conf_dif: /data/conf
    • Offline Mode. Set the offline_mode to true for air-gapped deployments.

      offline_mode: true
    • Database Type. By default, Apache Cassandra is set as the default database for Autonomous Identity. For MongoDB, set the db_driver_type: to mongo.

      db_driver_type: cassandra
    • Private IP Address Mapping. An air-gap deployment has no external IP addresses, but you may still need to define a mapping if your internal IP address differs from an external IP, say in a virtual air-gapped configuration.

      If the IP addresses are the same, you can skip this step.

      On the target machine, add the private_ip_address_mapping property in the /inventory/vars.yml file. Make sure the values are within double quotes. The key should not be in double quotes and should have two spaces preceding the IP address.

      private_ip_address_mapping:
        external_ip:  "internal_ip"

      For example:

      private_ip_address_mapping:
        34.105.16.198:  "10.128.0.51"
        34.105.16.201:  "10.128.0.54"
        34.105.16.229:  "10.128.0.71"
    • Authentication Option. This property has three possible values:

      • Local. Local indicates that sets up elasticsearch with local accounts and enables the Autonomous Identity UI features: self-service and manage identities. Local auth mode should be enabled for demo environments only.

      • SSO. SSO indicates that single sign-on (SSO) is in use. With SSO only, the Autonomous Identity UI features, self-service and manage identities pages, is not available on the system but is managed by the SSO provider. The login page displays "Sign in using OpenID." For more information, see Set Up SSO.

      • LocalAndSSO. LocalAndSSO indicates that SSO is used and local account features, like self-service and manage identities are available to the user. The login page displays "Sign in using OpenID" and a link "Or sign in via email".

        authentication_option: "Local"
    • Access Log. By default, the access log is enabled. If you want to disable the access log, set the access_log_enabled variable to "false".

    • JWT Expiry and Secret File. Optional. By default, the session JWT is set at 30 minutes. To change this value, set the jwt_expiry property to a different value.

      jwt_expiry: "30 minutes"
      jwt_secret_file: "{{install path}}"/jwt/secret.txt"
      jwt_audience: "http://my.service"
      oidc_jwks_url: "na"
    • Local Auth Mode Password. When authentication_option is set to Local, the local_auth_mode_password sets the password for the login user.

    • SSO. Use these properties to set up SSO. For more information, see Set Up SSO.

    • MongoDB Configuration. For MongoDB clusters, enable replication by uncommenting the mongodb_replication_replset property.

      # uncomment below for mongo with replication enabled. Not needed for single node deployments
      mongodb_replication_replset: mongors

      Also, enable a custom key for inter-machine authentication in the clustered nodes.

      # custom key
      # password for inter-process authentication
      # please regenerate this file on production environment with
      # command 'openssl rand -base64 741'
      mongodb_keyfile_content: |
        8pYcxvCqoe89kcp33KuTtKVf5MoHGEFjTnudrq5BosvWRoIxLowmdjrmUpVfAivh
        CHjqM6w0zVBytAxH1lW+7teMYe6eDn2S/O/1YlRRiW57bWU3zjliW3VdguJar5i
        Z+1a8lI+0S9pWynbv9+Ao0aXFjSJYVxAm/w7DJbVRGcPhsPmExiSBDw8szfQ8PAU
        2hwRl7nqPZZMMR+uQThg/zV9rOzHJmkqZtsO4UJSilG9euLCYrzW2hdoPuCrEDhu
        Vsi5+nwAgYR9dP2oWkmGN1dwRe0ixSIM2UzFgpaXZaMOG6VztmFrlVXh8oFDRGM0
        cGrFHcnGF7oUGfWnI2Cekngk64dHA2qD7WxXPbQ/svn9EfTY5aPw5lXzKA87Ds8p
        KHVFUYvmA6wVsxb/riGLwc+XZlb6M9gqHn1XSpsnYRjF6UzfRcRR2WyCxLZELaqu
        iKxLKB5FYqMBH7Sqg3qBCtE53vZ7T1nefq5RFzmykviYP63Uhu/A2EQatrMnaFPl
        TTG5CaPjob45CBSyMrheYRWKqxdWN93BTgiTW7p0U6RB0/OCUbsVX6IG3I9N8Uqt
        l8Kc+7aOmtUqFkwo8w30prIOjStMrokxNsuK9KTUiPu2cj7gwYQ574vV3hQvQPAr
        hhb9ohKr0zoPQt31iTj0FDkJzPepeuzqeq8F51HB56RZKpXdRTfY8G6OaOT68cV5
        vP1O6T/okFKrl41FQ3CyYN5eRHyRTK99zTytrjoP2EbtIZ18z+bg/angRHYNzbgk
        lc3jpiGzs1ZWHD0nxOmHCMhU4usEcFbV6FlOxzlwrsEhHkeiununlCsNHatiDgzp
        ZWLnP/mXKV992/Jhu0Z577DHlh+3JIYx0PceB9yzACJ8MNARHF7QpBkhtuGMGZpF
        T+c73exupZFxItXs1Bnhe3djgE3MKKyYvxNUIbcTJoe7nhVMrwO/7lBSpVLvC4p3
        wR700U0LDaGGQpslGtiE56SemgoP

      On production deployments, you can regenerate this file by running the following command:

      $ openssl rand -base64 741
    • Elasticsearch Heap Size. Optional. The default heap size for Elasticsearch is 1GB, which may be small for production. For production deployments, uncomment the option and specify 2G or 3G.

      #elastic_heap_size: 1g   # sets the heap size (1g|2g|3g) for the Elastic Servers
    • Java API Service. Optional. Set the Java API Service (JAS) properties for the deployment: authentication, maximum memory, directory for attribute mappings data source entities:

      jas:
          auth_enabled: true
          auth_type: 'jwt'
          signiture_key_id: 'service1-hmac'
          signiture_algorithm: 'hmac-sha256'
          max_memory: 4096M
          mapping_entity_type: /common/mappings
          datasource_entity_type: /common/datasources
  3. Open a text editor and enter the public IP addresses of the target machines in the ~/autoid-config/hosts file. Make sure the target host IP addresses are accessible from the deployer machine. The following is an example of the ~/autoid-config/hosts file:

    Click to See a Host File for Cassandra Deployments

    If you configured Cassandra as your database, the ~/autoid-config/hosts file is as follows for multi-node deployments:

    [docker-managers]
    10.128.0.90
    
    [docker-workers]
    10.128.0.170
    
    [docker:children]
    docker-managers
    docker-workers
    
    [cassandra-seeds]
    10.128.0.175
    10.128.0.34
    
    [spark-master]
    10.128.0.180
    
    [spark-workers]
    10.128.0.176
    10.128.0.177
    
    [spark:children]
    spark-master
    spark-workers
    
    [mongo_master]
    #ip#  mongodb_master=True
    
    [mongo_replicas]
    #ip-1#
    ##ip-2#
    ##…​
    
    [mongo:children]
    mongo_replicas
    mongo_master
    
    # ELastic Nodes
    [odfe-master-node]
    10.128.0.178
    
    [odfe-data-nodes]
    10.128.0.184
    
    [kibana-node]
    10.128.0.184
    
    [notebook]
    #ip#
    
  1. Set the Autonomous Identity passwords, located at ~/autoid-config/vault.yml.

    Despite the presence of special characters in the examples below, do not include special characters, such as & or $, in your production vault.yml passwords as it will result in a failed deployer process.
    configuration_service_vault:
        basic_auth_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
    
    cassandra_vault:
        cassandra_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        cassandra_admin_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        keystore_password: Acc#1234
        truststore_password: Acc#1234
    
    mongo_vault:
        mongo_admin_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        mongo_root_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        keystore_password: Acc#1234
        truststore_password: Acc#1234
    
    elastic_vault:
        elastic_admin_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        elasticsearch_password: ~@C~O>@%^()-_+=|<Y*$$rH&&/m#g{?-o!z/1}2??3=!*&
        keystore_password: Acc#1234
        truststore_password: Acc#1234
  2. Encrypt the vault file that stores the Autonomous Identity passwords, located at ~/autoid-config/vault.yml. The encrypted passwords will be saved to /config/.autoid_vault_password . The /config/ mount is internal to the deployer container.

    $ ./deployer.sh encrypt-vault
  3. Run the deployment.

    $ ./deployer.sh run

Set the Replication Factor

Once Cassandra has been deployed, you need to set the replication factor to match the number of nodes on your system. This ensures that each record is stored in each of the nodes. In the event one node is lost, the remaining node can continue to serve content even if the cluster itself is running with reduced redundancy.

Resolve Hostname

After installing Autonomous Identity, set up the hostname resolution for your deployment.

  1. Configure your DNS servers to access Autonomous Identity dashboard on the target node. The following domain names must resolve to the IP address of the target node:

    <target-environment>-ui.<domain-name>
  2. If DNS cannot resolve target node hostname, edit it locally on the machine that you want to access Autonomous Identity using a browser.

    Open a text editor and add an entry in the /etc/hosts (Linux/Unix) file or C:\Windows\System32\drivers\etc\hosts (Windows) for the target node.

    For multi-node, use the Docker Manager node as your target.

    <Docker Mgr Node Public IP Address>  <target-environment>-ui.<domain-name>

    For example:

    <IP Address>  autoid-ui.forgerock.com
  3. If you set up a custom domain name and target environment, add the entries in /etc/hosts. For example:

    <IP Address>  myid-ui.abc.com

    For more information on customizing your domain name, see Customize Domains.

Access the Dashboard

Access the Autonomous Identity console UI:

  1. Open a browser. If you set up your own url, use it for your login.

  2. Log in as a test user.

    test user: bob.rodgers@forgerock.com
    password: <password>

Start the Analytics

If the previous installation steps all succeeded, you must now prepare your data’s entity definitions, data sources, and attribute mappings prior to running your analytics jobs. These step are required and are critical for a successful analytics process.

For more information, see Set Entity Definitions.

Copyright © 2010-2022 ForgeRock, all rights reserved.