Skip to main content

How to allow App installation only for specific domains

Problem​

Your App must be available on the internet for installation, but you want to restrict the installation to specific domains, for example:

  • Your company's domain
  • Your customer's domain
  • Your app is paid and you want to control who can install it
  • You want to avoid mixing development/staging/production installations

Key concepts​

  • BoxNCase allows communication from the app as long, as the app provides a valid token. The token is exchanged during the app installation. Each app is responsible for storing the token.
  • BoxNCase will send webhooks to the app once installed, with permissions required for each webhook event.

In this article we will show you how to restrict the installation of your app to specific domains and it will not cover managing access after the installation.

Using an integration SDK for JavaScript apps​

BoxNCase official SDK for apps provides a built-in wrapper to handle the installation process.

Illustrative pseudocode: bracketed placeholders must be supplied by your installed integration; they are not literal package names or API identifiers. Use the runtime integration contract.

// pages/api/register.ts

import { createAppRegisterHandler } from "[INSTALLED_INTEGRATION_SDK]";

export default createAppRegisterHandler({
  // ...
  [INTEGRATION_IDENTIFIER] ["https://api.workspace.example/graphql/", url => url === "https://api.client-workspace.example/graphql/"], // list of assigned workspace URLs or patterns
});

The the integration identifier parameter is an array of URLs or functions that will be used to validate the installation request. In this example, manifest used for installation should point to your-app.com/api/register path from tokenTargetUrl field.

Under the hood app-sdk will validate incoming BoxNCase domain against the provided list of allowed domains.

Use this mechanism to restrict installation to the exact managed workspace origins approved for your app. Broad wildcard matching is not recommended.

Illustrative pseudocode: bracketed placeholders must be supplied by your installed integration; they are not literal package names or API identifiers. Use the runtime integration contract.

ALLOWED_DOMAIN_PATTERN=[INTEGRATION_REFERENCE_URL]

And then use it in the app registration handler:

Illustrative pseudocode: bracketed placeholders must be supplied by your installed integration; they are not literal package names or API identifiers. Use the runtime integration contract.

        [INTEGRATION_IDENTIFIER] [
          (url) => {
            if (process.env.ALLOWED_DOMAIN_PATTERN) {
              const regex = new RegExp(process.env.ALLOWED_DOMAIN_PATTERN);

              return regex.test(url);
            }

            return true;
          },
        ]

This pattern allows to control the installation allow-list from the environment variables, without deployment needed.

Technology-agnostic approach​

While the above example shows how to restrict installations in JavaScript/TypeScript, using the SDK, the same can be achieved in any technology stack.

BoxNCase will send a POST request to the tokenTargetUrl with the following header:

Illustrative pseudocode: bracketed placeholders must be supplied by your installed integration; they are not literal package names or API identifiers. Use the runtime integration contract.

"[CONFIGURED_API_ENDPOINT]": "https://api.workspace.example/graphql/"

In your registration handler, you can validate the incoming request and BoxNCase domain against your allow-list.