Introduction
When developing your ForgeRock Identity Management (IDM) implementation with ForgeOps, there are times where it would be useful to have access to the in-built API explorer functionality which is disabled by default for v7.x deployments.
While the API explorer functionality has been disabled as a security precaution, it is possible to re-enable it using the following steps.
It is highly recommended that the API explorer is disabled for a Production deployment of IDM.
This post assumes that you have deployed the ForgeRock Identity Platform using the CDK deployment pattern as described in the documentation: Cloud Developer’s Kit.
The CDK is a minimal sample deployment of the ForgeRock Identity Platform on Kubernetes that you can use for demonstration and development purposes.
Step 1: Enable the IDM API descriptor
boot.properties
( ./forgeops/docker/7.0/idm/resolver/boot.properties
) : Update the openidm.apidescriptor.enabled
flag to true
Step 2: Enable the IDM API context
ui.context-api.json
( ./forgeops/docker/7.0/idm/conf
) : Change the enabled
boolean to true
and update the urlContextRoot
to /api
{
"enabled" : true,
"urlContextRoot" : "/api",
"defaultDir" : "&{idm.install.dir}/ui/api/default",
"extensionDir" : "&{idm.install.dir}/ui/api/extension"
}
If the conf directory does not exist, run ./forgeops/bin/config.sh init
to generate it.
Step 3: Enable the API Explorer button on the Admin UI
AppConfiguration.js
( ./forgeops/docker/7.0/idm/ui/admin/extension/config
) : Add the following after Line 143:
"helpLinks": {
"url": "#api",
"icon": "fa fa-question-circle",
"dropdown": true,
"navbarRight": true,
"urls": [{
"url": "#apiExplorer",
"icon": "fa fa-code",
"name": "config.AppConfiguration.Navigation.links.apiExplorer"
}]
}
Remember to correctly terminate the existing curly brace on Line 143 with a comma to avoid JSON parsing issues on deployment
Step 4: Add a route to the Nginx configuration for the API Explorer
In ingress.yaml
( ./forgeops/kustomize/base/ingress
) add the following to the list of backends (Line 30 onwards):
- backend:
service:
name: idm
port:
number: 80
path: /api
pathType: Prefix
Be aware that whitespace is meaningful in YAML so make sure that this entry aligns with the others already in the file.
You can also make this change directly against the ingress controller of a running cluster using:
kubectl edit ingress forgerock
But these changes will be lost if you re-deploy your ingress controller configuration at a later date.
Step 5: Build a new IDM image then re-deploy the ingress controller (Nginx) and IDM
From the command prompt, build a new IDM image with your changes in place:
% bin/cdk build idm
Generating tags...
- idm -> idm:b9d492365-dirty
Checking cache...
- idm: Found Locally
Updated the image_defaulter with your new image for idm: "idm:f83e9b7774d3b221d57a0b3eb120dd127afc11124991d77cadf1124b6d782546"
Delete the running IDM pod from your Kubernetes cluster:
% bin/cdk delete idm
Uninstalling component(s): ['idm']
OK to delete these components? [Y/N] Y
configmap "idm" deleted
configmap "idm-logging-properties" deleted
service "idm" deleted
deployment.apps "idm" deleted
Deploy the new IDM image to the cluster:
% bin/cdk install idm
Checking secret-agent operator and related CRDs: secret-agent CRD found in cluster.
Checking ds-operator and related CRDs: ds-operator CRD found in cluster.
Installing component(s): ['idm']
configmap/idm created
configmap/idm-logging-properties created
service/idm created
deployment.apps/idm created
Enjoy your deployment!
Finally, deploy the updated configuration to the ingress controller using the appropriate fqdn
and namespace
for your environment:
% bin/cdk install --fqdn dev.example.com --namespace forgeops base
Checking secret-agent operator and related CRDs: secret-agent CRD found in cluster.
Checking ds-operator and related CRDs: ds-operator CRD found in cluster.
Installing component(s): ['base']
configmap/dev-utils unchanged
configmap/platform-config unchanged
ingress.networking.k8s.io/end-user-ui unchanged
ingress.networking.k8s.io/forgerock unchanged
ingress.networking.k8s.io/ig-web unchanged
ingress.networking.k8s.io/login-ui unchanged
ingress.networking.k8s.io/platform-ui unchanged
secretagentconfiguration.secret-agent.secrets.forgerock.io/forgerock-sac configured
Waiting for K8s secrets
Waiting for secret: am-env-secrets .done
Waiting for secret: idm-env-secrets .done
Waiting for secret: rcs-agent-env-secrets .done
Waiting for secret: ds-passwords .done
Waiting for secret: ds-env-secrets .done
Relevant passwords:
xxxxx (amadmin user)
xxxxx (openidm-admin user)
xxxxx (rcs-agent IDM secret)
xxxxx (rcs-agent RCS secret)
xxxxx (uid=admin user)
xxxxx (App str svc acct (uid=am-config,ou=admins,ou=am-config))
xxxxx (CTS svc acct (uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens))
xxxxx (ID repo svc acct (uid=am-identity-bind-account,ou=admins,ou=identities))
Relevant URLs:
https://dev.example.com/platform
https://dev.example.com/admin
https://dev.example.com/am
https://dev.example.com/enduser
Enjoy your deployment!
If you now navigate to the IDM Admin UI, you should see the API Explorer icon in the top right and be able to open it successfully.