Enabling the IDM API Explorer with ForgeOps v7.x

Setup
, , , ,
#1

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.

Other Articles by This Author