Subaccount Roles Export

Subaccount Roles Export

Export Neo subaccount application roles, groups, and user assignments for Cloud Foundry migration.

Purpose

This skill exports all application roles, groups, and their user and role assignments from a Neo subaccount using the public Neo Authorization Management REST API. It:

• Lists all deployed applications and fetches their roles
• Fetches user assignments for each role
• Lists all groups and fetches their role and user assignments
• Generates migration notes explaining the Neo → CF authorization model differences
• Saves structured output to $_SUBACCOUNT_DIR/neo-roles.json for downstream skills

This skill is read-only — it does NOT create anything in CF. The companion subaccount-roles-import skill consumes the output.

Neo vs. CF authorization model difference. Neo uses flat per-application roles — you assign users directly to a role on a specific application. CF uses a layered model: XSUAA defines scopes and role-templates per application, which are assembled into role collections at the subaccount level, and role collections are assigned to users. This skill exports the Neo model as-is; the import skill creates role collections as a best-effort mapping. A full redesign using the authentication-xsuaa skill is required per application to define proper XSUAA scopes.

The "Everyone" role is implicit in Neo. Any user authenticated to the subaccount automatically has access via the Everyone role. In CF, all access must be explicitly granted via role collections. This is flagged in the migration summary.

Prerequisites

Before running this skill, ensure:

1. Tools available on PATH:

   • curl (required)
   • jq (recommended)

2. Neo Platform API OAuth client with the following scope:

   • readAuthorizationSettings — to read roles, groups, and assignments

3. Neo subaccount technical name and region host

No dependency on other skills — this skill can run standalone.

Input Resolution

Step 0: Resolve Required Parameters

0a. Determine the migration directory:

# If running inside an app migration copy, use its .migration/ folder.
# Otherwise use a temp directory — subaccount migration is not tied to any single app repo.
if [ -f .migration/cf-migration-config.json ]; then
  MIGRATION_DIR="$(pwd)/.migration"
else
  MIGRATION_DIR="${TMPDIR:-/tmp}/neo-subaccount-migration"
  mkdir -p "$MIGRATION_DIR"
fi
echo "Migration directory: $MIGRATION_DIR"

0b. Check for existing config file:

if [ -f "$MIGRATION_DIR/neo-migration-config.json" ]; then
  cat "$MIGRATION_DIR/neo-migration-config.json"
fi

Read the following fields if present:

• neoSubaccount → subaccount technical name
• neoRegionHost → region host
• auth.method → "clientCredentials" or "bearerToken"
• auth.clientId + auth.clientSecret → if method is clientCredentials
• auth.bearerToken → if method is bearerToken

After reading, export the values explicitly:

export SUBACCOUNT=$(jq -r '.neoSubaccount' "$MIGRATION_DIR/neo-migration-config.json")
export REGION_HOST=$(jq -r '.neoRegionHost' "$MIGRATION_DIR/neo-migration-config.json")

_NEO_MIGRATION_HOME="${XDG_DATA_HOME:-${APPDATA:-$HOME}}/.neo-migration"
_CF_ORG=$(cf target 2>/dev/null | awk '/^org:/{print $2}')
CF_SUBACCOUNT_GUID=$(btp list accounts/subaccount 2>/dev/null | awk -v org="${_CF_ORG}" '
  NR > 2 {
    guid=$1; subdomain=$3
    if (index(org, subdomain) > 0) { print guid; exit }
  }
')
[ -n "${CF_SUBACCOUNT_GUID}" ] || { echo "ERROR: Could not resolve CF_SUBACCOUNT_GUID — check btp login and cf target." >&2; exit 1; }
_SUBACCOUNT_DIR="${_NEO_MIGRATION_HOME}/${SUBACCOUNT}/${CF_SUBACCOUNT_GUID}"
mkdir -p "${_NEO_MIGRATION_HOME}/${SUBACCOUNT}"
mkdir -p "${_SUBACCOUNT_DIR}"

0c. Check the user's prompt for any values provided inline.

0d. If any required value is still missing, invoke the subaccount-migration-orchestrator skill to collect all inputs and write $MIGRATION_DIR/neo-migration-config.json, then return here and continue from Step 1.

Do not ask the user for individual values directly — the orchestrator owns input collection and ensures all three export skills share a consistent config file.

0e. If $MIGRATION_DIR is inside a git repo, ensure it is in .gitignore:

if [[ "$MIGRATION_DIR" != /tmp* ]]; then
  if [ -f .gitignore ]; then
    grep -q '^\\.migration' .gitignore 2>/dev/null || echo '.migration/' >> .gitignore
  else
    echo '.migration/' > .gitignore
  fi
fi

Step 1: Obtain Bearer Token

Base URLs for this skill:

• Token endpoint: https://api.${REGION_HOST}/oauth2/apitoken/v1

If using client credentials:

export MSYS_NO_PATHCONV=1

TOKEN_RESPONSE=$(curl -s -X POST \
  "https://api.${REGION_HOST}/oauth2/apitoken/v1?grant_type=client_credentials" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "${CLIENT_ID}:${CLIENT_SECRET}")

BEARER_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token // empty')

If BEARER_TOKEN is empty, check the response for errors:

If using pre-issued token: Use it directly. Warn about 25-minute expiry.

Step 1b: Setup NEO API (telemetry + functions)

This step is mandatory before any NEO API call. It writes telemetry files, then sources neo-api-setup-template.sh which exports all NEO API URLs and fetch_neo_*() functions.

Resolve telemetry paths:

_NEO_MIGRATION_HOME="${XDG_DATA_HOME:-${APPDATA:-$HOME}}/.neo-migration"
_NEO_CONSENTS_HOME="${XDG_DATA_HOME:-${APPDATA:-$HOME}}/.neo-migration-consents"
if [ -z "${CF_SUBACCOUNT_GUID}" ]; then
  _CF_ORG=$(cf target 2>/dev/null | awk '/^org:/{print $2}')
  CF_SUBACCOUNT_GUID=$(btp list accounts/subaccount 2>/dev/null | awk -v org="${_CF_ORG}" '
    NR > 2 { guid=$1; subdomain=$3; if (index(org, subdomain) > 0) { print guid; exit } }
  ')
  [ -n "${CF_SUBACCOUNT_GUID}" ] || { echo "ERROR: Could not resolve CF_SUBACCOUNT_GUID — check btp login and cf target." >&2; exit 1; }
fi
_SUBACCOUNT_DIR="${_NEO_MIGRATION_HOME}/${SUBACCOUNT}/${CF_SUBACCOUNT_GUID}"
mkdir -p "${_NEO_MIGRATION_HOME}/${SUBACCOUNT}"
mkdir -p "${_SUBACCOUNT_DIR}"
mkdir -p "${_NEO_CONSENTS_HOME}/${SUBACCOUNT}/${CF_SUBACCOUNT_GUID}"
_TELEMETRY_FILE="${_NEO_CONSENTS_HOME}/neo-telemetry-installation.txt"
_CONSENT_FILE="${_NEO_CONSENTS_HOME}/${SUBACCOUNT}/neo-telemetry-consent.txt"
_SESSION_FILE="${_NEO_CONSENTS_HOME}/${SUBACCOUNT}/${CF_SUBACCOUNT_GUID}/neo-telemetry-session.txt"

Note: CF_SUBACCOUNT_GUID is resolved in Step 0b if available; this block re-resolves it as a fallback for standalone runs.

Collect consent (per subaccount — ask only if not already recorded):

STOP — do not run any bash here. Check whether $_CONSENT_FILE exists:

• If it exists and contains a valid consent= line, read the value from there and skip to "Ensure installation_id".
• If it does not exist or consent= is missing, use the AskUserQuestion tool to ask the user: "Enable telemetry? This migration appends two non-PII random UUIDs (neo_cf_migration_installation_id, neo_cf_migration_session_id) as query parameters to every NEO API call for usage tracking. No personal data, subaccount names, or credentials are included. Enable? (yes/no)" Wait for the user's answer before continuing.

if [ ! -f "${_CONSENT_FILE}" ] || ! grep -q "^consent=" "${_CONSENT_FILE}"; then
  _CONSENT="<yes or no from user answer above>"   # replace with actual value
  echo "consent=${_CONSENT}" > "${_CONSENT_FILE}"
fi
_CONSENT=$(grep "^consent=" "${_CONSENT_FILE}" | cut -d= -f2)

if [ "${_CONSENT}" = "yes" ]; then
  # installation_id — once per machine
  if [ ! -f "${_TELEMETRY_FILE}" ] || ! grep -q "^neo_cf_migration_installation_id=" "${_TELEMETRY_FILE}"; then
    _INSTALLATION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
    echo "neo_cf_migration_installation_id=${_INSTALLATION_ID}" > "${_TELEMETRY_FILE}"
  fi

  # session_id — reuse if present (standalone run continues existing session)
  if [ ! -f "${_SESSION_FILE}" ]; then
    _MIGRATION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
    echo "neo_cf_migration_session_id=${_MIGRATION_ID}" > "${_SESSION_FILE}"
    echo "INFO: New migration session started. neo_cf_migration_session_id: ${_MIGRATION_ID}"
  else
    _MIGRATION_ID=$(grep "^neo_cf_migration_session_id=" "${_SESSION_FILE}" | cut -d= -f2)
    echo "INFO: Resuming migration session. neo_cf_migration_session_id: ${_MIGRATION_ID}"
  fi
fi

Source the NEO API setup script:

_NEO_SETUP="$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd ../../shared && pwd)/neo-api-setup-template.sh"
[ -f "${_NEO_SETUP}" ] || _NEO_SETUP="ai-migration/neo-java-migration-skills/shared/neo-api-setup-template.sh"
source "${_NEO_SETUP}" || exit 1

Step 2: Fetch Application List

Use the Neo Lifecycle API to get all deployed applications:

declare -f fetch_neo_apps > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}

export MSYS_NO_PATHCONV=1

APPS_RESPONSE=$(fetch_neo_apps)

HTTP_STATUS=$(echo "$APPS_RESPONSE" | tail -1 | tr -d '\r')
APPS_BODY=$(echo "$APPS_RESPONSE" | sed '$d' | tr -d '\r')

Extract application names:

APP_NAMES=$(echo "$APPS_BODY" | jq -r '.apps[].entity.applicationName // .[].applicationName // .[].name // empty' 2>/dev/null)

Note: If the Lifecycle API is unavailable or returns an empty list, still proceed to fetch groups (Step 4). The roles export will have an empty applications array, which is valid.

Step 3: Fetch Roles and User Assignments per Application

For each application name from Step 2:

3a. Fetch roles for the application:

declare -f fetch_neo_roles > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}
ROLES_RESPONSE=$(fetch_neo_roles "${APP_NAME}")

The response is a JSON object wrapping a roles array:

{
  "roles": [
    { "name": "Admin", "type": "PREDEFINED", "applicationRole": true, "shared": true }
  ]
}

Extract role names: echo "$ROLES_BODY" | jq -r '.roles[].name // .[] .name // empty'

3b. For each role, fetch its user assignments:

declare -f fetch_neo_role_users > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}
USERS_RESPONSE=$(fetch_neo_role_users "${APP_NAME}" "${ROLE_NAME}")

The response is a JSON object wrapping a users array. The user identifier field is name:

{
  "users": [
    { "name": "p000000" }
  ]
}

Extract user names: echo "$USERS_BODY" | jq -r '.users[].name // .[].userId // .[].name // empty'

Extract user IDs into an array for the role.

Error handling per role fetch: If any individual role or user fetch returns a non-200 status, log a warning and continue — do not stop the entire export.

Step 4: Fetch Groups and Their Assignments

4a. Fetch all groups:

declare -f fetch_neo_groups > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}
GROUPS_RESPONSE=$(fetch_neo_groups)

Response: JSON object wrapping a groups array:

{
  "groups": [
    { "name": "managers" },
    { "name": "viewers" }
  ]
}

Extract group names: echo "$GROUPS_BODY" | jq -r '.groups[].name // empty'

4b. For each group, fetch role assignments:

declare -f fetch_neo_group_roles > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}
GROUP_ROLES_RESPONSE=$(fetch_neo_group_roles "${GROUP_NAME}")

Response: JSON object wrapping a roles array:

{
  "roles": [
    { "name": "Admin", "applicationName": "myapp", "providerAccount": "myaccount" }
  ]
}

4c. For each group, fetch user assignments:

declare -f fetch_neo_group_users > /dev/null 2>&1 || {
  echo "ERROR: NEO API functions not loaded — collect telemetry consent and source neo-api-setup-template.sh before making any NEO API calls." >&2
  exit 1
}
GROUP_USERS_RESPONSE=$(fetch_neo_group_users "${GROUP_NAME}")

Response: JSON object wrapping a users array (same schema as role users — field is name):

{
  "users": [
    { "name": "p000000" }
  ]
}

Step 5: Build and Save Output

Construct the output JSON and save to $_SUBACCOUNT_DIR/neo-roles.json using the Write tool:

{
  "sourceSubaccount": "<subaccount technical name>",
  "sourceRegion": "<region host>",
  "exportTimestamp": "<ISO 8601 timestamp>",
  "applications": [
    {
      "name": "myapp",
      "roles": [
        {
          "name": "Admin",
          "applicationRole": true,
          "shared": false,
          "userAssignments": ["user1@example.com", "user2@example.com"]
        },
        {
          "name": "Viewer",
          "applicationRole": true,
          "shared": false,
          "userAssignments": []
        }
      ]
    }
  ],
  "groups": [
    {
      "name": "managers",
      "roleAssignments": [
        { "applicationName": "myapp", "roleName": "Admin" }
      ],
      "userAssignments": ["user3@example.com"]
    }
  ],
  "migrationSummary": {
    "totalApplications": 0,
    "totalRoles": 0,
    "totalGroups": 0,
    "totalUserRoleAssignments": 0,
    "totalGroupRoleAssignments": 0,
    "totalGroupUserAssignments": 0,
    "requiresManualSteps": true,
    "manualSteps": [
      "Neo uses flat per-application roles. CF requires scopes + role-templates + role-collections. Run authentication-xsuaa skill per application to define proper XSUAA scopes, then add roles to the collections created by subaccount-roles-import.",
      "The implicit 'Everyone' role in Neo must be explicitly replicated in CF by assigning the appropriate role collections to all authenticated users."
    ]
  }
}

Always include in manualSteps (these are structural limitations, not configuration gaps):

• "Neo uses flat per-application roles. CF requires scopes + role-templates + role-collections. Run the authentication-xsuaa skill per application to define proper XSUAA scopes, then add application roles to the collections created by subaccount-roles-import."
• "The implicit 'Everyone' role in Neo must be explicitly replicated in CF by assigning the appropriate role collections to all authenticated users."

Step 6: Display Summary

Roles Export Complete
=====================
Source: <subaccount> (<region>)

Applications: <count>
  Total roles:              <count>
  Total user-role assigns:  <count>

Groups: <count>
  Total group-role assigns: <count>
  Total group-user assigns: <count>

Note: Neo roles are flat per-application. CF requires a redesign into
      scopes + role-templates + role-collections (done via authentication-xsuaa).
      subaccount-roles-import will create role collections as a best-effort mapping.

Output saved to: $_SUBACCOUNT_DIR/neo-roles.json

Configuration Files

CF Services

None — this skill is read-only.

Verification

1. Verify output file exists:

   ls -la $_SUBACCOUNT_DIR/neo-roles.json
   

2. List all applications and their roles:

   jq '.applications[] | {app: .name, roles: [.roles[].name]}' $_SUBACCOUNT_DIR/neo-roles.json
   

3. List all groups:

   jq '.groups[] | {group: .name, roles: [.roleAssignments[].roleName], users: .userAssignments}' $_SUBACCOUNT_DIR/neo-roles.json
   

4. Check migration summary:

   jq '.migrationSummary' $_SUBACCOUNT_DIR/neo-roles.json
   

Common Issues

Issue: "Authorization API returns 403"

Cause: OAuth client does not have readAuthorizationSettings scope. Solution: In Neo cockpit, edit the Platform API OAuth client and add the readAuthorizationSettings scope.

Issue: "Lifecycle API returns 404 or empty array"

Cause: No applications deployed, or the Lifecycle API endpoint differs for this region. Solution: Verify the subaccount has deployed applications in Neo cockpit. The export will proceed with an empty applications list — groups are still exported.

Issue: "Role fetch returns empty array for an app"

Cause: The application has no custom roles defined (only the implicit Everyone role). Solution: This is normal — the application will appear in the output with an empty roles array. The Everyone role is noted in the migration summary.

Issue: Token expires mid-export (25-minute limit)

Cause: Large subaccounts with many applications can take more than 25 minutes to export. Solution: Use client credentials authentication (not pre-issued token) — the skill can re-fetch the token if it detects a 401 response during iteration.

Issue: curl URL path munging on Windows

Solution: Set export MSYS_NO_PATHCONV=1 before running curl commands (this skill does this automatically).

Next Steps

After completing this skill:

• subaccount-roles-import — reads $_SUBACCOUNT_DIR/neo-roles.json and creates CF role collections with user assignments
• authentication-xsuaa — for each application, define proper XSUAA scopes and role-templates; the role collections created by subaccount-roles-import can then be extended with application scopes
• subaccount-trust-migrator — if not done, migrate IdP trust configuration (group-based access rules may depend on the IdP configuration)