Skip to content

Latest commit

 

History

History
77 lines (53 loc) · 4.97 KB

develop-web-applications-locally-with-managed-authentication.md

File metadata and controls

77 lines (53 loc) · 4.97 KB

Develop Web Applications Locally with Choreo’s Managed Authentication

Choreo’s managed authentication capability provides a set of backend for frontend (BFF) endpoints to facilitate authentication and authorization for web applications. These endpoints are readily available for single-page web applications deployed on Choreo.

As a web application developer, you may need to run the application on your local workstation. Choreo’s local development capability ensures that authentication and authorization during local development work the same way as they do when the application is deployed to Choreo, eliminating the need for code changes.

This guide explains how to configure and use Choreo’s local development capability to streamline your workflow.

How local development works in Choreo

Local development uses a proxy that sits in front of the locally running web application. This proxy intercepts all incoming requests:

  • Requests to /choreo-apis/* and /auth/* are forwarded to Choreo.
  • All other requests are forwarded to the locally running web application.

The proxy runs on HTTPS using a self-signed certificate, which is essential for secure, HTTP-only cookie-based managed authentication. Once the proxy is running, you can access the web application using the proxy's URL and start developing locally. The behavior of the web application, in terms of managed authentication, will mirror its behavior when deployed to Choreo.

Configure local development

Prerequisites

  • Create a single-page application (SPA) with managed authentication enabled. For details, see Secure Web Applications with Managed Authentication.

  • Promote and deploy the application to the environment where you want to enable local development.

    !!! note - The locally running web application will use the same managed authentication configuration as the environment where local development is configured. - Local development is only allowed in non-critical environments.

Apply configurations

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the component you created and deployed.
  3. In the left navigation menu, click Deploy.
  4. Go to the respective environment card and click Local Development.
  5. In the Local Development pane, toggle Local Development to enable it.
  6. (Optional) To update the port on which the local development proxy server runs, expand Advanced Configurations and specify a value for Proxy Port.
  7. Click Apply.

You have now configured local development. The next section explains how to access your web application for local development.

Access your web application locally

Prerequisites

  • Ensure local development is enabled in the desired environment.
  • Ensure your web application is running locally on http://localhost on a specific port.

Access your web application locally

You can use either the Choreo built-in identity provider or an external identity provider to access your web application locally.

=== "Use the Choreo built-in identity provider"

1. Sign in to the Choreo Console.
2. In the **Component Listing** pane, click on the component you created and deployed.
3. In the left navigation menu, click **Deploy**.
4. Go to the respective environment card and click **Local Development**.
5. In the **Local Development** pane, copy the command under **Step 1**.
6. Paste the command in a terminal, replace `[APP_PORT]` with the port on which your application is running locally, and run the command.
7. To access the application, go to the URL provided under **Step 2** in the **Local Development** pane.

    !!! note
        The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.

=== "Use an external identity provider"

1. Sign in to the Choreo Console.
2. In the **Component Listing** pane, click on the component you created and deployed.
3. In the left navigation menu, click **Deploy**.
4. Go to the respective environment card and click **Local Development**.
5. In the **Local Development** pane, copy the redirect URLs under **Step 1**.
6. Go to the settings in the OAuth application in your identity provider and specify the copied URLs as allowed redirect URLs.
7. In the **Local Development** pane, copy the command under **Step 2**.
8. Paste the command in a terminal, replace `[APP_PORT]` with the port on which your application is running locally, and run the command.
9. To access the application, go to the URL provided under **Step 3** in the **Local Development** pane.

    !!! note
        The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.