Salesforce Platform: Resolve Sandbox Connected App Installation Error

Error Symptoms

1. Error Message:

   • When trying to install a connected app, you may encounter the error:
     “You cannot install a sandbox app outside on a non-sandbox organization.”
   • This indicates that the app is designed for a Salesforce Sandbox (non-production) environment but is being installed in a Production org.

2. OAuth Error:

   • Users without the "Approve Uninstalled Connected Apps" permission may see the error:
     “We can’t authorize you because of an OAuth error. For more information, contact your Salesforce administrator.”
   • The error details may include:
     error=invalid_clienterror_description=app must be installed into org

3. Edge Case in Sandbox:

   • In some Sandbox environments, the "Approve Uninstalled Connected Apps" permission might be missing from profiles and cannot be granted.

Root Cause

1. Environment Mismatch:

   • The app was built specifically for a Sandbox environment and cannot be installed in a Production org. This often happens with sample or demo applications.

2. Missing Permissions:

   • The "Approve Uninstalled Connected Apps" permission is required for users to access uninstalled apps. If this permission is missing, users will face errors.

3. Configuration Issues:

   • In some cases, Sandbox environments may lack proper license matching with Production, leading to permission-related errors.

Resolution Steps

1. Verify the Environment:

   • Confirm whether the app is intended for a Sandbox or Production environment.
   • If the app is for Sandbox, ensure it is installed in a Sandbox org. Similarly, for Production apps, ensure they are installed in a Production org.

2. Check Permissions:

   • Grant the "Approve Uninstalled Connected Apps" permission to the affected users. This can be done by:
     • Navigating to the user’s profile or permission set in Setup.
     • Adding the "Approve Uninstalled Connected Apps" permission.

3. Run the Match Production Licenses Tool:

   • If the "Approve Uninstalled Connected Apps" permission is missing in the Sandbox and cannot be granted:
     • Use the "Match Production Licenses to Sandbox without a Refresh" tool to align Sandbox licenses with Production.
     • This tool ensures that permissions and configurations are consistent between environments.

4. Install Trusted Apps:

   • Navigate to Setup > Connected Apps OAuth Usage.
   • Identify the trusted app and click Install.
   • Follow the prompts to complete the installation.

5. Use Unique Consumer Keys:

   • For Production apps, developers and partners must use unique consumer keys (client IDs) to avoid conflicts.

Prevention Measures

1. Environment-Specific Apps:

   • Always ensure that apps are built and installed in the correct environment (Sandbox or Production).

2. Review Connected Apps Regularly:

   • Use the Connected Apps OAuth Usage section in Setup to monitor and manage connected apps.

3. Grant Necessary Permissions:

   • Ensure that users have the "Approve Uninstalled Connected Apps" permission if they need to access uninstalled apps.

4. Plan for License Matching:

   • Regularly use the "Match Production Licenses to Sandbox without a Refresh" tool to keep Sandbox and Production environments aligned.

5. Use Trusted Apps:

   • Only install apps from trusted sources and ensure they are properly configured for the intended environment.