Deploy a Lightweight Autonomous Identity

Autonomous Identity supports a flexible and scalable microservices architecture that you can deploy in any type of network environment: on-prem, cloud, multi-cloud, or hybrid cloud.

The deployment process is simple. Autonomous Identity provides a deployer script that you launch on a local server or laptop. The deployer pulls down the necessary images from the ForgeRock Google Cloud Repository (gcr.io) to install Autonomous Identity on the target node. From there, you run a few commands to complete the installation.

Important

To download the deployer, you must obtain a registry key to access the ForgeRock Google Cloud Repository. Only ForgeRock Autonomous Identity customers can obtain a registry key. For more information, contact ForgeRock.

For this example, we install a lightweight version of Autonomous Identity in a two-core 8GB virtual machine on a cloud platform, such as Google Cloud Platform (GCP), Amazon Web Services (AWS), Microsoft Azure, or others. The deployment includes the Docker-based microservices component and Apache Cassandra, but not Apache Spark. From there, you populate demo data by importing it into Cassandra and then display it on the Autonomous Identity UI console. This setup provides a way to deploy a system quickly for demonstration purposes.

This installation assumes that you set up the deployer script on a separate machine from the target. This lets you launch a build from a laptop or local server.

A simple diagram is shown below:

Figure 1: A lightweight single-node target deployment.

Autonomous Identity lightweight single node target deployment.

Important

This example setup is only for development or evaluation purposes and should not be used for production deployments.

Let's set up Autonomous Identity on CentOS 7. The following are some prerequisites:

  • Operating System. The target machine requires CentOS 7 and Python 2.6 or later. The deployer machine can use any operating system as long as Docker is installed. For this guide, we use CentOS 7 as its base operating system.

  • Memory Requirements. Make sure you have enough free disk space on the deployer machine before running the deployer.sh commands. We recommend at least a 40GB/partition with 14GB used and 27GB free after running the commands.

  • Registry Requirements. Autonomous Identity provides a Docker image at the ForgeRock Google Cloud Registry (gcr.io). The image creates a deployer.sh script that downloads additional images necessary for the installation. To download the deployment images from the ForgeRock Google Cloud Registry, you need a registry key to log in to the repository. Contact ForgeRock for the key.

Set Up the Target 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. Check your Python version. Autonomous Identity supports Python 2.6 and higher.

    $ python --version
  3. Set the user for the target machine to a username of your choice. For example, autoid.

    # sudo adduser autoid
  4. Set the password for the user you created in the previous step.

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

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

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

    $ su - autoid
  8. 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
  9. 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

Set Up the Deployer Machine

Set up another machine as a deployer node. You can use any OS-based machine for the deployer as long as it has Docker installed. For this example, we use CentOS 7.

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

    $ sudo cat /etc/centos-release
  2. Check your Python version. Autonomous Identity supports Python 2.6 and higher.

    $ python --version
  3. Set the user for the target machine to a username of your choice. For example, autoid.

    # sudo adduser autoid
  4. Set the user password for the user you created in the previous step.

    $ sudo passwd autoid
  5. Configure the user for passwordless sudo. Replace "autoid" with the username for your system.

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

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

    $ su - autoid
  8. 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
  9. 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 machine. We run commands from this machine to install Autonomous Identity on the target machine. In this example, we use CentOS 7.

  1. On the target machine, set up the Docker-CE repository.

    $ sudo yum-config-manager \
         --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  2. Install the latest version of the Docker CE, the command-line interface, and containerd.io, a containerized website.

    $ sudo yum install -y docker-ce docker-ce-cli containerd.io
  3. Enable Docker to start at boot.

    $ sudo systemctl enable docker
  4. Start Docker.

    $ sudo systemctl start docker
  5. Check that Docker is running.

    $ systemctl status docker
  6. Add the user to the Docker group.

    $ sudo usermod -aG docker ${USER}

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 <username>

    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
  4. Copy your public SSH key, id_rsa.pub, to the target machine's ~/.ssh/authorized_keys file.

  5. On the target machine, set the privileges on your ~/.ssh and ~/.ssh/authorized_keys.

    $ chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys
  6. On the deployer machine, test your SSH connection to the target machine. This is a critical step. Make sure the connection works before proceeding with the installation.

    $ ssh -i ~/.ssh/id_rsa autoid@34.70.190.144
    Last login: Sun Jun 14 23:23:36 2020 from 74.125.45.78

Install Autonomous Identity

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

    $ cd ~/autoid-config/
  2. Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. To get the latest Docker image URL, see "Files to Download".

    $ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid/deployer:2020.6.2
  3. Run the create-template command to generate the deployer.sh wrapper. Note that the command sets the configuration directory on the target node to /config. The --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files. To get the latest Docker image, see "Files to Download".

    $ docker run --user=`id -u` -v ~/autoid-config:/config -it gcr.io/forgerock-autoid/deployer:2020.6.2 create-template
  4. Make the script executable.

    $ chmod +x deployer.sh
  5. The create-template command creates a number of configuration files, including ansible.cfg. Open a text editor and edit the 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.

    [defaults]
    host_key_checking = False
    remote_user = autoid
    private_key_file = id_rsa
  6. Open a text editor and enter the target host's public IP addresses in the /autoid-config/hosts file. Make sure to keep the Spark server entries blank as Spark is excluded from the deployment. The following is an example of the /autoid-config/hosts file:

    [docker-managers]
    35.232.107.121
    
    [docker-workers]
    35.232.107.121
    
    [docker:children]
    docker-managers
    docker-workers
    
    [cassandra-seeds]
    35.232.107.121
    
    [cassandra-workers]
    35.232.107.121
    
    [spark-master]
    
    [spark-workers]
    
    [analytics]
  7. If your external IP and internal IP addresses are different, for example, when deploying the target host in a cloud, define a mapping between the external IP address and the private IP address.

    On the target node, add the private_ip_address_mapping property in the /autoid-config/vars.yml file. You can look up the private IP on the cloud console, or run sudo ifconfig on the target host. 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.72.28.214:  "10.128.0.52"
  8. Open a text editor to see the Autonomous Identity passwords, located at /autoid-config/vars.yml.

    configuration_service_vault:
      basic_auth_password: Welcome123
    
    openldap_vault:
      openldap_password: Welcome123
    
    cassandra_vault:
      cassandra_password: Welcome123
      cassandra_admin_password: Welcome123
  9. Encrypt the vault file that stores the Autonomous Identity passwords, located at /autoid-config/vault.yml. Make note of the vault password. You will be asked to enter it when running the encrypt-vault command.

    $ ./deployer.sh encrypt-vault

    The encrypted passwords are saved to /config/.autoid_vault_password. The /config/ mount is internal to the deployer container.

  10. Download the images. This step downloads software dependencies needed for the deployment.

    $ ./deployer.sh download-images
  11. Run the deployer. This step builds the Docker microservices and Cassandra servers.

    $ ./deployer.sh run

Hostname Resolution

  • On the target machine, open a text editor and add an entry in the /etc/hosts file for the Autonomous Identity self-service and UI services.

    For example:

    34.70.190.144  autoid-ui.forgerock.com autoid-selfservice.forgerock.com

Check the System

  1. Open a browser, and point it to https://autoid-ui.forgerock.com/.

  2. Log in as a test user: bob.rodgers@forgerock.com. Enter the password for the user. On the Autonomous Identity UI console, notice that there is no data on the system yet. Logout when done.

  3. Check the status of Apache Cassandra.

    $ /opt/autoid/apache-cassandra-3.11.2/bin/nodetool status

    Datacenter: datacenter1
    =======================
    Status=Up/Down
    |/ State=Normal/Leaving/Joining/Moving
    --  Address      Load       Tokens       Owns (effective)  Host ID                               Rack
    UN  10.128.0.6  624.21 KiB  256          100.0%            0a13aa7f-ea2e-43b2-9323-136bdec915d2  rack1

  4. Enter exit to end your SSH session.

Set Up dbutils

  • On the target machine, run the install-dbutils command. This command creates a dbutils directory in the target instance's Cassandra seed node.

    $ ./deployer.sh install-dbutils

Export Your Data

You may have a need to export your data, for example, from a development server to a QA server or run a quick backup of your data. Autonomous Identity provides a python script to export your data to .csv files and stores them to a folder in your home directory.

For first-time installations, you can skip this step.

  1. On the target machine, change to the dbutils directory.

    $ cd /opt/autoid/dbutils
  2. Export the database.

    $ python dbutils.py export ~/backup

Import the Demo Data

If you are setting up a fresh install using the demo data provided by ForgeRock, follow these steps.

  1. Contact ForgeRock to obtain the demo data.

  2. On the target machine, change to the dbutils directory.

    $ cd /opt/autoid/dbutils
  3. Use the dbutils.py import command to populate the Autonomous Identity keyspace with the demo data.

    $ python dbutils.py import /import-dir

    For example:

    $ python dbutils.py import ~/import/AutoID-data
  4. Open a browser, and point it to https://autoid-ui.forgerock.com/.

  5. Log in as a test user: bob.rodgers@forgerock.com. Enter the password for the user: Welcome123. You should see data populated on the Autonomous Identity UI.

Import the Data into the Autonomous Identity Keyspace

If you are moving your data from another server, for example, from a development server to a QA server, import your data to the target environment using the following steps.

  1. First, create a zoran_user.cql file. This file is used to drop and re-create the Autonomous Identity user and user_history tables. The file should go to the same directory as the other .csv files. Make sure to create this file from the source node, for example, the development server, from where we exported the data.

    Start cqlsh in the source environment, and use the output of these commands to create the zoran_user.cql file:

    $ describe zoran.user;
    $ describe zoran.user_history;

    Make sure the DROP TABLE cql commands precedes the CREATE TABLE commands as shown in the zoran_user.cql example file below:

    USE zoran ;
    
    DROP TABLE IF EXISTS  zoran.user_history ;
    
    DROP TABLE IF EXISTS zoran.user ;
    
    CREATE TABLE zoran.user (
        user text PRIMARY KEY,
        chiefyesno text,
        city text,
        costcenter text,
        isactive text,
        jobcodename text,
        lineofbusiness text,
        lineofbusinesssubgroup text,
        managername text,
        usrdepartmentname text,
        userdisplayname text,
        usremptype text,
        usrmanagerkey text
    ) WITH bloom_filter_fp_chance = 0.01
        AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
        AND comment = ''
        AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
        AND compression = {'chunk_length_in_kb': '64', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
        AND crc_check_chance = 1.0
        AND dclocal_read_repair_chance = 0.1
        AND default_time_to_live = 0
        AND gc_grace_seconds = 864000
        AND max_index_interval = 2048
        AND memtable_flush_period_in_ms = 0
        AND min_index_interval = 128
        AND read_repair_chance = 0.0
        AND speculative_retry = '99PERCENTILE';
    
    CREATE TABLE zoran.user_history (
        user text,
        batch_id int,
        chiefyesno text,
        city text,
        costcenter text,
        isactive text,
        jobcodename text,
        lineofbusiness text,
        lineofbusinesssubgroup text,
        managername text,
        usrdepartmentname text,
        userdisplayname text,
        usremptype text,
        usrmanagerkey text,
        PRIMARY KEY (user, batch_id)
    ) WITH CLUSTERING ORDER BY (batch_id ASC)
        AND bloom_filter_fp_chance = 0.01
        AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
        AND comment = ''
        AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
        AND compression = {'chunk_length_in_kb': '64', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
        AND crc_check_chance = 1.0
        AND dclocal_read_repair_chance = 0.1
        AND default_time_to_live = 0
        AND gc_grace_seconds = 864000
        AND max_index_interval = 2048
        AND memtable_flush_period_in_ms = 0
        AND min_index_interval = 128
        AND read_repair_chance = 0.0
        AND speculative_retry = '99PERCENTILE';
  2. Copy the ui-config.json from the source environment where you ran an analytics pipeline, usually under /data/config, to the same folder where you have your .csv files.

  3. On the target machine, change to the dbutils directory.

    $ cd /opt/autoid/dbutils
  4. Use the dbutils.py import command to populate the Autonomous Identity keyspace with the .csv files, generated from the export command from the source environment using the previous steps. Note that before importing the data, the script truncates the existing tables to remove duplicates. Again, make sure the zoran_user.cql and the ui-config.json are in the /import-dir.

    $ python dbutils.py import /import-dir

    For example:

    $ python dbutils.py import ~/import/AutoID-data
  5. Open a browser, and point it to https://autoid-ui.forgerock.com/.

  6. Log in as a test user: bob.rodgers@forgerock.com. Enter the password for the user: Welcome123. You should see data populated on the Autonomous Identity UI.

Read a different version of :