This document summarizes common issues that may occur when configuring an integration app, along with troubleshooting steps and security recommendations.
It is designed to help users quickly identify the cause of a problem and resolve it efficiently.
Basic Environment Checklist
Before troubleshooting specific features, first confirm that the following basic settings are correct. These are common root causes behind many issues.
1. App Status
Make sure the integration app is enabled.
2. Trusted Domains
Make sure the domain configured in Trusted Domains exactly matches the actual domain of the service receiving the request.
Enter only the domain name, not the protocol.
For example, entera.example.com, nothttps://a.example.com.A domain does not automatically match its subdomains.
If you need to trust subdomains, add them one by one.
For example,example.comdoes not matcha.example.com.If you need to add multiple domains, separate them with English commas
,and do not add spaces.
Example:a.example.com,b.example.comIf a middleware service is deployed to receive the Jodoo
code, retrieve user information, and redirect to the third-party system. Enter the middleware domain here instead of the third-party system domain.
For example, if the third-party system domain isgetcode.comand the middleware domain issso.code.com, you should entersso.code.com.
3. HTTPS Support
Make sure both the third-party system and the middleware service have valid HTTPS certificates deployed.
Common Issues
This section covers the most common problems and how to troubleshoot them.
Q: After clicking Enter App for the integration app, an error says the request source domain is not in the whitelist
Troubleshooting
This error is usually caused by an incorrect trusted domain configuration.
Please complete the Basic Environment Checklist above.
Q: After clicking Enter App for the integration app, the page fails to redirect or an error appears
Troubleshooting
Complete the Basic Environment Checklist.
Click the edit icon on the integration app card and confirm that the App Home Page URL is correctly configured.
If a middleware service is used to receive the Jodoo
code, retrieve user information, and redirect to the third-party system, the Trusted Domains field should contain the middleware address, not the homepage address of the third-party system.Open the configured URL directly in a browser and confirm that the third-party system or middleware service responds properly.
Q: When accessing the third-party system through single sign-on, the system says the username does not exist or login fails
Troubleshooting
Confirm that the user account is active in the third-party system.
Make sure the account is not disabled, not marked as resigned, and can log in normally.Check the username mapping.
Make sure the Jodoo member ID matches the username in the third-party system one-to-one.
The
usernamefield returned by the Jodoo OAuth API is the member ID in Jodoo.Third-party systems such as FineBI usually log users in with their system username.
Make sure the two values are exactly the same, including letter case.
If they are different, maintain a username mapping table in the middleware service.
Q: When calling the Jodoo API, the system says the code token is invalid or expired
Cause
The code is a one-time credential and becomes invalid immediately after use.
If the middleware service does not call the API immediately after receiving the redirect request, the credential may expire.
Solution
After receiving the redirect request, the middleware service should immediately extract the code and call the API.
Do not store, cache, or reuse the code.
Each time the user clicks Enter App, a new code is generated.
Q: After resetting the Suite Secret, single sign-on to the third-party system no longer works
Cause
After the Suite Secret is reset, the previous Suite Secret becomes invalid immediately.
Solution
Update the new Suite Secret in the integration configuration of the third-party system.
The third-party system can resume normal single sign-on only after the new value is synchronized.
Q: A third-party page embedded in a Jodoo form or dashboard appears blank or fails to load
Troubleshooting
Complete the Basic Environment Checklist.
Check whether clickjacking protection has been disabled so the page can be embedded under the Jodoo domain.
Q: A third-party page embedded in a Jodoo form or dashboard asks the user to log in again
Troubleshooting
Complete the Basic Environment Checklist.
Confirm that the third-party system has been properly configured for OIDC integration or that the single sign-on plugin has been installed.
Confirm that the Suite ID and Suite Secret of the integration app have been correctly entered into the third-party system integration settings.
Security Notes
Security matters here because these credentials directly affect authentication and user access.
Protecting the Suite Secret
The Suite Secret is the only credential used to call Jodoo authentication APIs, so its usage must be strictly restricted.
Use it only on the server side. Never expose it in frontend code or URL parameters.
Do not store or use it in client-side JavaScript, mobile apps, or any environment accessible to users.
After resetting the Suite Secret, immediately synchronize the new value to all dependent server-side services.
HTTPS Is Required
If you need to embed a third-party system page in a Jodoo form or dashboard, the third-party system must be deployed over HTTPS.
The middleware service must also use HTTPS to prevent the code from being intercepted during transmission.
Key Takeaways
For most integration issues, start with these checks:
Whether the integration app is enabled
Whether the trusted domain is configured correctly
Whether the middleware domain is used instead of the third-party system domain when required
Whether HTTPS is properly deployed
Whether the Suite ID, Suite Secret, and username mapping are correct
These checks resolve the majority of common integration problems.