add documentation and script to set up PingIdentity env for testing (#…

…1638)

Signed-off-by: Jessica He <[email protected]>

docs/provider-setup/ping-identity-env-setup.md

@@ -0,0 +1,51 @@
+## Ping Identity Application Setup
+
+This script populates the Ping Identity environment with desired users/groups to test the [Ping Identity catalog plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/pingidentity/plugins/catalog-backend-module-pingidentity). This would avoid the need to manually set up the environment each time the Ping Identity trial expires and a new account is required.
+
+This script adds the following users and groups by default, modify the script as needed to test different scenarios. Read more about how the PingOne API for identity management [here](https://apidocs.pingidentity.com/pingone/platform/v1/api/#identity-management).
+
+### Prerequisite: Setting up the environment
+
+#### Create the environment in the PingOne console
+
+1. In the `Environments` tab, press `+` to create a new environment
+2. Select `Customer solution` and fill in the mandatory fields
+
+### Prerequisite: Creating the application
+
+#### Create the application in the PingOne console
+
+1. Navigate to `Applications` > `Application` then press `+` to create a new application
+2. Input the application name
+3. Select the `Worker` application type (this is required to make API calls)
+
+#### Enter the required IDs/secrets
+
+1. Click the newly created application and navigate to the `Configuration` tab. Copy the respective values and paste the `Client ID`, `Client Secret` and `Environment ID` in `ping-identity-secrets.env`.
+2. Ensure the API and Auth path matches the domain of your environment. See [PingOne API Domains](https://apidocs.pingidentity.com/pingone/platform/v1/api/#working-with-pingone-apis) for more information.
+
+### Granting API permissions to the application
+
+#### Obtain and enter the access token to run the script
+
+1. Enable the application using the toggle
+2. Navigate to the Roles tab
+3. Grant the following roles to the application: `Environment Admin` & `Identity Data Admin`
+
+![Ping identity grant application roles](./resources/ping-identity-grant-app-roles.png)
+
+### Running the script
+
+#### The script takes 3 arguments
+
+1. The path to the secrets file (e.g. `ping-identity-secrets.env`) with the required secrets filled out
+2. The number of users to add to the environment
+3. The number of groups to add to the environment
+
+The created users and groups will appear under the `Users` and `Groups` tab in the `Directory`.
+
+Note: the script currently statically establishes user group membership and subgroup relationships. Currently the script adds `tester1` and `tester2` in group1, and `group3` as a subgroup of `group1`.
+
+### Setting up the Ping Identity Plugin in RHDH
+
+Read the documentation [here](https://github.com/backstage/community-plugins/blob/main/workspaces/pingidentity/plugins/catalog-backend-module-pingidentity/README.md) to set up the plugin to ingest the users and groups into the software catalog.

mkdocs.yaml

@@ -13,3 +13,5 @@ nav:
       - Migration Process Overview: application-migration/migration-process-overview.md
       - Migration Process Steps: application-migration/migration-process-steps.md
       - Learning Path for Developers: application-migration/learning-path-for-developers.md
+  - Provider Setup:
+      - Ping Identity Environment Setup: provider-setup/ping-identity-env-setup.md

scripts/ping-identity-setup/ping-identity-secrets.env

@@ -0,0 +1,5 @@
+PING_IDENTITY_API_PATH="https://api.pingone.ca/v1"
+PING_IDENTITY_AUTH_PATH="https://auth.pingone.ca"
+PING_IDENTITY_ENV_ID="your-env-id"
+PING_IDENTITY_CLIENT_ID="your-client-id"
+PING_IDENTITY_CLIENT_SECRET="your-client-secret"

scripts/ping-identity-setup/ping-identity-setup.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# Check for expected args
+if [ "$#" -ne 3 ]; then
+  echo "Usage: $0 <secretsFile> <numUsers> <numGroups>"
+  exit 1
+fi
+
+secretsFile=$1
+numUsers=$2
+numGroups=$3
+
+# Load env vars
+if [ ! -f "$secretsFile" ]; then
+  echo "Secrets file not found."
+  exit 1
+fi
+source "$secretsFile"
+
+# Check if env vars are all set
+if [ -z "$PING_IDENTITY_API_PATH" ] || [ -z "$PING_IDENTITY_AUTH_PATH" ] || [ -z "$PING_IDENTITY_ENV_ID" ] || [ -z "$PING_IDENTITY_CLIENT_ID" ] || [ -z "$PING_IDENTITY_CLIENT_SECRET" ]; then
+  echo "One or more required variables is missing from the secrets file."
+  exit 1
+fi
+
+# Fetch access token
+credentials=$(echo -n "$PING_IDENTITY_CLIENT_ID:$PING_IDENTITY_CLIENT_SECRET" | base64)
+response=$(curl -s --request POST \
+  --url "$PING_IDENTITY_AUTH_PATH/$PING_IDENTITY_ENV_ID/as/token" \
+  --header "Authorization: Basic $credentials" \
+  --header "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "grant_type=client_credentials")
+access_token=$(echo $response | jq -r .access_token)
+
+if [ "$access_token" == "null" ]; then
+  echo "Error retrieving access token: $response"
+  exit 1
+fi
+
+# Delete all existing users and groups
+group_ids=$(curl -s --location --request GET "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/groups" \
+  --header "Authorization: Bearer $access_token" \
+  --header "Content-Type: application/json" | jq -r '._embedded.groups[].id')
+
+for group_id in $group_ids; do
+  if [ -n "$group_id" ]; then
+    curl -s --location --request DELETE "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/groups/$group_id" \
+      --header "Authorization: Bearer $access_token"
+  fi
+done
+
+user_ids=$(curl -s --location --request GET "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/users" \
+  --header "Authorization: Bearer $access_token" \
+  --header "Content-Type: application/json" | jq -r '._embedded.users[].id')
+
+for user_id in $user_ids; do
+  if [ -n "$user_id" ]; then
+    curl -s --location --request DELETE "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/users/$user_id" \
+      --header "Authorization: Bearer $access_token"
+  fi
+done
+
+# Create Users
+echo "Adding $numUsers users..."
+
+user_ids=()
+for i in $(seq 1 $numUsers); do
+  user="tester$i"
+  create_user_response=$(curl -s --request POST \
+    --url "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/users" \
+    --header "Authorization: Bearer $access_token" \
+    --header "Content-Type: application/json" \
+    --data-raw "{
+      \"email\": \"$user@example.com\",
+      \"name\": {
+        \"given\": \"$user\",
+        \"family\": \"User\"
+      },
+      \"username\": \"$user\"
+    }")
+  user_id=$(echo "$create_user_response" | jq -r '.id')
+  user_ids+=("$user_id")
+  echo "Created user: $user, ID: $user_id"
+done
+
+# Create Groups
+echo "Adding $numGroups groups..."
+
+group_ids=()
+for i in $(seq 1 $numGroups); do
+  group="group$i"
+  create_group_response=$(curl -s --request POST \
+    --url "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/groups" \
+    --header "Authorization: Bearer $access_token" \
+    --header "Content-Type: application/json" \
+    --data-raw "{
+      \"name\": \"$group\",
+      \"description\": \"This is $group\"
+    }")
+  group_id=$(echo "$create_group_response" | jq -r '.id')
+  group_ids+=("$group_id")
+  echo "Created group: $group, ID: $group_id"
+done
+
+# Set up group memberships and subgroups - modify as needed for testing
+# Example: Add tester1 and tester2 to group1
+for user_id in "${user_ids[@]:0:2}"; do
+  add_user_to_group_response=$(curl -s --request POST \
+    --url "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/users/$user_id/memberOfGroups" \
+    --header "Authorization: Bearer $access_token" \
+    --header "Content-Type: application/json" \
+    --data-raw "{
+      \"id\": \"${group_ids[0]}\"
+    }")
+  echo "Added user ID: $user_id to group1 (ID: ${group_ids[0]})"
+done
+
+# Example: Set group3 as a subgroup of group1
+nest_group_response=$(curl -s --request POST \
+  --url "$PING_IDENTITY_API_PATH/environments/$PING_IDENTITY_ENV_ID/groups/${group_ids[2]}/memberOfGroups" \
+  --header "Authorization: Bearer $access_token" \
+  --header "Content-Type: application/json" \
+  --data-raw "{
+    \"id\": \"${group_ids[0]}\"
+  }")
+echo "Nested group3 (ID: ${group_ids[2]}) into group1 (ID: ${group_ids[0]})"