FIX #2356: Normalize Permission Expansion

[delize]

Test Log for Issue #2356 Fix - Admin Custom Role Permission Normalization

Test Environment

• Provider: terraform-provider-okta (local build from fix-2356 branch)
• Terraform Version: 1.12.2
• Test Date: July 12, 2025
• Okta Organization: trial-7001215.okta.com

Issue Summary

Issue #2356: "Okta Workflows custom roles experiencing persistent state drift"

Root Cause: When creating custom roles with workflow permissions (okta.workflows.invoke and okta.workflows.read), the Okta API automatically returns both the original permissions AND expanded versions (okta.workflows.flows.invoke and okta.workflows.flows.read). This caused Terraform to see different permissions on each refresh, leading to continuous state drift.

Fix Implementation: Added permission normalization logic in flattenPermissions() function that preserves user's original intent by mapping expanded permissions back to the configured permissions.

---

Fix Implementation Details

Key Changes in resource_okta_admin_role_custom.go:

1. Modified flattenPermissions() function (lines 194-212):

   • Now calls normalizePermissions() to handle API expansion
   • Converts normalized permissions to schema.Set properly

2. Added normalizePermissions() function (lines 234-289):

   • Maps expanded workflow permissions back to user's original configuration
   • Handles both okta.workflows.read → okta.workflows.flows.read expansion
   • Handles both okta.workflows.invoke → okta.workflows.flows.invoke expansion
   • Preserves all other permissions unchanged

3. Logic:

   • If both original and expanded exist → keep original (user's intent)
   • If only expanded exists → keep expanded
   • All other permissions → pass through unchanged

4. Correct Typos in code:

   • Corrects apparent typos in Okta Code at:
     • Line 100
     • Line 82

---

Test Results

Test 1: Initial Custom Role Creation

Purpose: Create custom role with workflow permissions and verify no initial state drift

resource "okta_admin_role_custom" "workflow_role_test" {
  label       = "WorkflowRoleTest-${random_id.test_suffix.hex}"
  description = "Custom role with workflow permissions for testing issue #2356 state flapping"
  
  permissions = [
    "okta.workflows.read",
    "okta.workflows.invoke",
  ]
}

Result: ✅ SUCCESS

• Role created successfully with ID: cr0t5snz72wYzw11V697
• Permissions properly set: okta.workflows.read, okta.workflows.invoke

Test 2: State Drift Testing - Multiple Plan Operations

Purpose: Verify no state changes are detected across multiple plan operations

terraform plan -var-file=test.tfvars  # Run #1
terraform plan -var-file=test.tfvars  # Run #2  
terraform plan -var-file=test.tfvars  # Run #3

Result: ✅ SUCCESS

• All plans returned: "No changes. Your infrastructure matches the configuration."
• No state drift detected

Test 3: State Drift Testing - Multiple Apply Operations

Purpose: Verify no state changes occur during apply operations (where the original issue manifested)

terraform apply -var-file=test.tfvars -auto-approve  # Apply #1
terraform apply -var-file=test.tfvars -auto-approve  # Apply #2
terraform apply -var-file=test.tfvars -auto-approve  # Apply #3

Result: ✅ SUCCESS

• All applies returned: "No changes. Your infrastructure matches the configuration."
• Consistently showed: "0 added, 0 changed, 0 destroyed"
• Permissions remained stable: ["okta.workflows.invoke", "okta.workflows.read"]

Test 4: Role Update with Additional Permissions

Purpose: Test normalization works correctly during role updates

Configuration Change:

permissions = [
  "okta.workflows.read",
  "okta.workflows.invoke", 
  "okta.users.read",  # Added new permission
]

Result: ✅ SUCCESS

• Update applied successfully showing only the new permission addition
• No unexpected permission changes detected
• After update, multiple applies showed stable state

Test 5: API Permission Expansion Verification

Purpose: Confirm Okta API actually returns expanded permissions

API Call: GET /api/v1/iam/roles/{roleId}/permissions

API Response Showed:

1. okta.users.read
2. okta.workflows.flows.invoke (expanded version)
3. okta.workflows.flows.read (expanded version)
4. okta.workflows.invoke (original permission)
5. okta.workflows.read (original permission)

Analysis: ✅ CONFIRMED

• API returns BOTH original AND expanded permissions
• This validates the root cause described in issue Custom Roles using okta.workflows.* have permanent drift due to undocumented permission changes #2356
• Our normalization fix correctly handles this API behavior

Test 6: Unit Test Validation

Purpose: Verify normalization logic works correctly in isolation

go test -v ./okta/services/idaas -run TestWorkflowPermissionNormalization

Result: ✅ SUCCESS

• All test cases passed:
  • workflow_read_permission_expansion
  • workflow_invoke_permission_expansion
  • both_workflow_permissions_expansion
  • only_expanded_workflow_permissions
  • no_workflow_permissions

---

Summary of Findings

✅ What's Fixed:

1. No more state drift: Multiple apply operations remain stable
2. Correct permission handling: User's original permissions are preserved
3. API expansion handled: Both original and expanded permissions properly normalized
4. Update operations stable: Role modifications work without introducing drift
5. Backward compatibility: Non-workflow permissions unaffected

🔧 How the Fix Works:

1. Before Fix: API returned both okta.workflows.read + okta.workflows.flows.read, causing Terraform to see changing state
2. After Fix: Normalization logic recognizes this pattern and consistently returns user's original okta.workflows.read configuration
3. User Experience: No changes required to existing configurations

✅ Issue #2356 Status: RESOLVED

The persistent state drift issue with Okta Workflows custom roles is completely resolved. Users can now:

• Create custom roles with okta.workflows.read and okta.workflows.invoke permissions
• Apply configurations repeatedly without unexpected changes
• Update roles without triggering state drift
• Maintain stable Terraform state across all operations

---

Provider Build Information

• Source: terraform-provider-okta fix-2356 branch
• Build Command: go build -o terraform-provider-okta
• Installation: Local provider in ~/.terraform.d/plugins/local/okta/okta/5.1.0/darwin_arm64/

This comprehensive test validates that issue #2356 is fully resolved with proper permission normalization while maintaining complete backward compatibility.