Externally-Hosted Apps#

Externally-Hosted Apps are pre-existing web applications that are registered on Edge and have an application tile, but are hosted elsewhere. They can be displayed as an application tile on Edge, which redirects a user to the app's URL. If a user enters the URL for the app directly in their browser or clicks on the application tile the app will perform authentication with Edge, redirecting them to Edge's login screen if necessary.

Integrating an Externally-Hosted App#

External Applications can integrate with Edge if they support the OAuth2 Authorization Code Flow. The process for integrating an External Application is as follows:

  • Create an Application record in Edge

  • Create an AppVersion record in Edge

  • Register the Application with an redirect URI

  • Provide the client_id and client_secret to the Externally-Hosted App for the Authorization Code Flow

As an example, we will demonstrate how to register a External Application that has been deployed to https://edge-external-app-demo.platform-devops.enthought.com. The source code with OAuth2 integration is available at the Externally-Hosted App Example GitHub repository.

Registering the App#

Registering an External App is very similar to Publishing an App. You will require organization developer access and an API token, as well as an EdgeSession created from the enthought_edge EDM package. There are some notable differences when creating an AppVersion record:

  • The kind parameter must be AppKindEnum.External

  • The link parameter must be the URL of the Externally-Hosted App's deployed location

This is an example of code for creating an AppVersion that differs from creating a Native AppVersion:

version1 = AppVersion(
    app_id="myexternalapp",
    version="1.0.0",
    title="Edge External App Demo, v1.0.0",
    description="Demonstration of an external application",
    icon=ICON,
    kind=AppKindEnum.External,
    link="https://edge-external-demo.platform-devops.enthought.com",
)
edge.applications.add_app_version(version1)

Registering an OAuth2 Client#

When an Externally-Hosted 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 Externally-Hosted App. For the OAuth code and token exchange to occur, the Externally-Hosted 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 with your EdgeSession:

result = edge.applications.register_oauth_client(
    "myexternalapp",
    "https://edge-external-demo.platform-devops.enthought.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-myexternalapp',
 'client_secret': 'RANDOM_CLIENT_SECRET',
 'redirect_uri': 'https://edge-external-app-demo.platform-devops.enthought.com/authorize'}

The authorize endpoint in the Externally-Hosted App demo processes the result of the OAuth2 redirection.

Important

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 Externally-Hosted App will have to be reconfigured with the new client_secret. The previous client_secret is unrecoverable.

Externally-Hosted App Requirements#

Externally-Hosted Apps use the client_id and client_secret along with a few other values to integrate with Edge's authentication. The Externally-Hosted App Example is a Flask application that demonstrates how to implement the OAuth2 Authorization Code Flow. To see details of how to configure the External Application to use these values, view the Externally-Hosted App Example's README.

Important

Edge provides authentication for external applications and guarantees that the ID of a user is genuine. It is up to an External App to determine the authorization for that user to access the External App's resources. For more information, see the README.md file in the Externally-Hosted App Example.

Deploying external-app-example#

There are many ways to deploy an Externally-Hosted App. This example is deployed to edge-external-demo.platform-devops.enthought.com using Terraform. If you wish to use the application code and deployment configuration as a template, you will require a Kubernetes namespace for deployment. You can contact Platform DevOps for access. To configure your deployment, follow the instructions in the Edge External App Demo's deployment README.