Skip to main content

Integrating with External Apps

External Apps are traditional web applications that run outside of Edge, but which are registered on Edge and have an application tile on the workbench.

Clicking on the application tile in Edge redirects users to the app's original URL. If a user enters the URL for the app directly in their browser or clicks on the application tile the app will perform login with Edge, redirecting them to Edge's login screen if necessary.

Why integrate external apps with Edge?​

Registering external apps allows you to better centralize and track your R&D workflows, resulting in the following benefits:

  • Provide a single location to access all data, notebooks, and applications on a project. This makes onboarding new team members significantly easier, and team members spend less time hunting down data, documents, and URLs.

  • Track usage for native apps as well as the external apps that run in the Edge Kubernetes namespace. By keeping you on top of your cloud footprint on a single dashboard, you can manage available computational resources and avoid overdrawing from a limited budget.

  • Makes it easier to comply with organizational, institutional, or governmental data policies and prevent loss of data or intellectual property through the use of unsecured data channels or applications.

Add an External App to the Workbench​

Step 1: Create an Application Record​

In the Edge Workbench, access the Settings page via the "gear" icon in the upper right-hand corner:

gear

Then, click "Create Application". You will need to provide a short identifier. This isn't user-visible, so something like my-app-id is appropriate. Finally, click "Save App":

new app

Step 2: Create an Application Version record​

The "Application Version" record is used to locate the app. It has the text and icon that will be displayed on the workbench tile.

Click "Create Version", and fill in basic information on your app. Be sure the "Kind" value is set to "Externally-Hosted App".

new external app

Verify that the tile shows up on the Workbench:

external app tile

tip

Your app will be created with the "In Review" status, which means it's visible only to other developers. When you're ready, ask your organization admin to "Approve" the app, making it visible to everyone.

Use Edge for login (Optional)​

External Applications can integrate with Edge for login if they support the OAuth2 Authorization Code Flow.

This process is somewhat more complicated than adding a "native" app to Edge, so we recommend reviewing the Externally-Hosted App Example in the online examples gallery.

Reminder

Don't forget to add authorization checks to your app, to avoid making it accessible to any Edge user.

Step 1: Set your app up in Edge​

Follow the instructions in the previous section to create the app and add it to the workbench. You will need the app ID for the following steps; in the example above, it is my-app-id.

Step 2: Register an OAuth Client​

When an External App requires a user to login, it can perform an OAuth redirection to Edge's login screen. After the user logs in, they are redirected back to the External App. For the OAuth code and token exchange to occur, the External App requires a client_id and client_secret value. These values are provided by Edge when an Organization Developer registers a redirect_url for the app.

You can perform this task programmatically, using EdgeSession:

from edge.api import EdgeSession

mysession = EdgeSession()

result = mysession.applications.register_oauth_client(
    "my-app-id",
    "https://my-app.example.com/authorize"
)
print(result)

The result of this operation will be a dictionary with the client_id and client_secret:

{'client_id': 'service-edge-app-default-my-app-id',
 'client_secret': '<RANDOM_CLIENT_SECRET>',
 'redirect_uri': 'https://my-app.example.com/authorize'}
info

An application may only have exactly one OAuth client. Registering an OAuth client always invalidates the previous client_secret even if the redirect_uri is the same. This means that the deployed External App will have to be reconfigured with the new client_secret. The previous client_secret is unrecoverable.

Step 3: Configure your end of the OAuth flow.​

External Apps use the client_id and client_secret along with a few other values to integrate with Edge's authentication. As shown in our External App example, the authorize endpoint processes the result of the OAuth redirection.

We recommend inspecting the Externally-Hosted App Example to see all parts of the process. This is a Flask application that demonstrates how to implement the OAuth2 Authorization Code Flow.

Step 4: Add additional authorization checks​

The steps above will allow Edge users to log in to your app. However, without additional checks, all Edge users will be able to log in, which is probably not what you want.

Each app's security model is different. For example, you may want to allow users to sign up and store their emails in a database, or you may wish to maintain a "whitelist" of permitted users. The Externally-Hosted App Example has a stub function you can fill in with such a check.

Please note that "native" Edge applications generally do not require this kind of manual security checking; they have an automatic authorization process which ensures that only the user who launched the app can access it. This process is handled for you if you use the edge-native-base Docker image; contact Enthought for instructions otherwise.

Deployment​

There are many ways to deploy an External App. Our example is deployed using Terraform. If you wish to use the application code and deployment configuration as a template, you will require a Kubernetes namespace for deployment. To configure your deployment, follow the instructions in the Edge External App example's README.