App-to-App Communication

The App-to-App Communication Runbook is designed for App Administrators and Cluster Administrators to handle configuration and troubleshooting of app communication within a cluster. It covers scenarios related to public and private key management, access control, and caching issues that commonly arise.

Copy link to this section

App communication basics

• Public and Private Keys: Each application has a public key stored at the cluster level, while its private key is stored as an app-level secret in a vault. These keys are essential for secure app-to-app communication.
• Admin Roles:
  • App Admins manage individual app configurations and key associations.
  • Cluster Admins handle cluster-level configurations, including key-related issues.

Note: Refer to the topic on built-in roles for more information about App and Cluster Admin roles.

Copy link to this section

Commonly faced issues

1. Application Login Looping Back to IDP Login Page

   • Possible Cause: Misalignment between public and private keys.
   • Solution:
     • Check if the cached keys for the involved applications are outdated or incorrect. Clear the caches for the c3-c3 application you are trying to login to.
     • Use App.PublicKey.make(<app id>).getConfig() and App.PrivateKey.make(<app id>).getSecret() to fetch key configurations.
     • Verify the keys using JWT.IO with the RS512 algorithm. Ensure the absence of "\n" characters when pasting keys.
     • Do the above check the keys for both c3-c3 and the application you are trying to log into.
     • Regenerate keys if necessary by using App#setupKeys in the C3 AI Console, or manually generating and updating the keys in the config store with RSA512 encryption.

2. Unauthorized Action During App Communication

   • Possible Cause: Incorrect key or insufficient permissions for the caller app.
   • Solution:
     • Verify the caller app's keys.
     • Check the role associated with the caller app using AppIdentity.forId(<caller app id>).
       • Ensure the role is valid and has the necessary permissions by calling Role#allPermissions.
     • Check to see if the role provided is a valid role. Run Role.forId(<role in the AppIdentity for the caller app>)

Copy link to this section

Clearing cached keys

Cached keys can sometimes lead to issues during authentication and authorization. Follow these steps to clear the cache:

1. Use App.PublicKey.clearCacheLocalOnlyAllApps() and App.PrivateKey.clearCacheLocalOnlyAllApps().
2. If unable to access the app directly, use an app from a higher hierarchy to execute the following commands:
   • For example if the app you want to login to is env-app, then go to env-c3 and issue :
     • App.forId("env-app").callJson("App.PublicKey", "clearCacheLocalOnlyAllApps", null, null)
     • App.forId("env-app").callJson("App.PrivateKey", "clearCacheLocalOnlyAllApps", null, null)
3. As a last resort, restart the server by running, Server.restart(), or delete the pod to clear cached values.

Cluster-Wide Cache Clearing Script: To clear the cache on all servers in a cluster, use the following script:

Cluster.apps().forEach((app) => {
    app.nodes.forEach((node) => {
        node.call("App.PublicKey", "clearCacheLocalOnlyAllApps", null, null);
        node.call("App.PrivateKey", "clearCacheLocalOnlyAllApps", null, null);
    });
});

Copy link to this section

Frequently asked questions (FAQ)

Q: Why is my app redirecting to the IDP login page repeatedly? A: This may be due to a misalignment between public and private keys. Clear the caches and verify that both keys match using JWT.IO with the RS512 algorithm. Regenerate keys if necessary.

Q: How can I clear the cache for the App.PublicKey and App.PrivateKey values?
A: Use App.PublicKey.clearCacheLocalOnlyAllApps() and App.PrivateKey.clearCacheLocalOnlyAllApps() commands, or apply the cache clearing script to clear it cluster-wide.

Q: What should I do if an app action is unauthorized?
A: Verify the caller app's key and check the role associated with the caller app. Ensure that it has the appropriate permissions for the action.

Q: How do I manually regenerate a key pair?
A: Use RSA512 encryption with a 2048-bit key length. Make sure to format the key properly with -----BEGIN PUBLIC KEY-----\n and \n-----END PUBLIC KEY----- (similarly for the private key) before updating the configuration.

A sample key pair (using RSA encryption with 2048-bit key length) would look like this:

• Sample public key

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

• Sample private key

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

After updating the keys, the cached value must be cleared from all apps in the cluster. Refer to the section Clear the caches for more details.