Monday, February 22, 2021

Standing Up Forgerock Stack On Your Local Machine

 

1.0 Overview


It is quite hard to grok or grasp certain security concepts if you do not have an actual environment to play with, or sometimes you need to raise a Forgerock ticket and you need a vanilla environment to replicate an issue, this article will help you set up the latest version of vanilla Forgerock environment.


The instructions mentioned in this article is about how to stand up the whole Forgerock stack on a Mac machine, if you are using other OSes I would imagine that the . Before continuing you should already have the prerequisite software already set up on your Mac machine. 


2.0 Prerequisite

  • Docker Desktop - Install Docker Desktop for Mac via the download file.

    • Allocating ample resources to your docker 

  • Enable Kubernetes Cluster in your docker



  • K9s - K9s is a kubernetes dash board for browsing and managing deployed kubernetes resources/objects

$ brew install derailed/k9s/k9s


  • kubectx - kubectx is to set the context of current shell so that all subsequent kubectl command would be contextualized to a set cluster

$ brew install kubectx


  • Skaffold - skaffold is a CI/CD tool for kubenetes clusters, here it is used to stand up the forgerock cluster.

$ brew install skaffold


  • kubefwd - kubefwd is a tools to mass forward services ports so that you could access the services from outside the kube cluster, this is important for testing purposes

$ brew install txn2/tap/kubefwd


  • kustomize - kustomize is a tool that allows users to create configuration overlays that could be applied to kubernetes configuration files before they are being deployed into the kube environment, in short it allows for users to surfaced out configuration so that it could be injected by ci/cd pipelines.

$ brew install kustomize


$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.44.0/deploy/static/provider/cloud/deploy.yaml


  • Forgerock Secret Agent -  You will need the forgerock secret agent to curn out passwords and secrets while it is being installed and stood up

$ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml


3.0 Setting Up the Forgerock Stack

The following instructions would allow you to set up the whole Forgerock stack of components in your local mac machine.


3.1 Cloning the ForgeOps Repository

The first step to set up the whole forgerock stack is to clone the ForgeOps Github code. For more information about deployment of Forgerock components in Kubernetes Clusters and how to automate them via CI/CD pipelines you could head on to the ForgeOps documentation. Run the following command to clone the code.


$ git clone https://github.com/ForgeRock/forgeops.git


Now switch the code into a feature branch that is used for deployments to local Kubenetes cluster.

$ cd forgeops
$ git checkout tags/2020.08.07-ZucchiniRicotta.1 -b my-branch


3.2 Setting Up the Right Execution Context

Before you go further you need to set up the kube context. Inorder to check what kubernetes context you are on right now, you could run kubectx without any arguments. The following print screen shows that my current kube context is set the the docker kubernetes cluster, because it is highlighted in yellow.


If the docker kubernetes cluster is not set as context then run the following command.

$ kubectx docker-desktop


In these instructions we are going to use the default namespace in the kube cluster and the default namespace is also called default.

$ kubens default


Now finally we need to set up the right Skaffold context, runt the following command.

$ skaffold config set --kube-context docker-desktop local-cluster true


3.3 Installing the Forgerock Stack

Before you run Skaffold command to inflate the Forgorck stack onto your local kubernetes cluster you need to modify a line of code in the forgeops repository, go to the following file.


./kustomize/overlay/7.0/all/kustomization.yaml


The path provided above is a relative path from inside the forgeops folder. Modify the FQDN to the following.


After modifying the file, please remember to save it. Then run the following command so that the environment specific files would be generated.

$ cd bin; ./config.sh init --profile cdk --version 7.0


Once the configuration files are churned out, go back to the forgeops root directory and run Skaffold.

$ cd ..; skaffold run


After running Skaffold it will start to deploy all the forerock components into your local kubernetes cluster, you need to wait for the deployment to finish and for all the components to come up. 


Inorder to view the statuses of the components run k9s and you will get the following dashboard, here I have listed all pods from all namespaces.

Depending on the color schemes you have configured, once all of them turned blue it would mean that all the Forgerock components are ready and running.

3.4 Setting Up The Network

The following is the kubeforward command, you need to run this in a separate terminal, as it could be run as a long running process to forward ports from services that resides in the listed namespaces. To stop port forwarding just type CTL+D or CTRL+C. 

$ sudo kubefwd services -n default -n ingress-nginx


Once you run the kubefwd command it would create entries of all the forwarded services in your /etc/hosts file like the following.

The highlighted box is an entry we have configured as the FQDN in section 3.3, it is important that you configure this to localhost, because all request to this FQDN will be picked up by the kubernetes ingress controller and inturn will be picked up by the Forgerock ingress configurations and eventually be forwarded to it’s respective components.


3.5 Accessing The Forgerock Stack

The following URL will bring you to the installed forerock stack.



The first log in page you will see is the following.

In order to get the password for amadmin user you need to run the following command from the forgeops directory.


./bin/print-secrets.sh amadmin


You will get something like the following output. The output is the password for the amadmin user.


Once you login you will see the following.

4.0 Conclusion

After running all the set up steps mentioned in the preceding sections you have actually successfully installed the following forgerock components.


  • Directory Service

  • Identity Management Service

  • Access Manager Service


For more details about the mentioned components go to the Forgerock documentation. The set up steps will always install the latest available version of forgerock components into your machine because it is using Forgerock’s own Google Container Registry’s docker images. 


The following is a video instruction based on what is written in this article.