Secure Web Applications with Managed Authentication¶

The managed authentication capability of Choreo simplifies adding authentication and authorization to a single-page web application.

As a developer, you can easily set up Choreo's managed authentication to seamlessly integrate authentication into your web application. You just need to enable Choreo’s managed authentication, configure the built-in identity provider, and connect to Choreo without having to deal with the complexities of underlying OIDC/OAuth2.0 protocols.

Choreo's managed authentication follows the backend for frontend (BFF) architecture, which is a secure pattern recommended for browser-based applications that utilize OIDC/OAuth2.0 for authentication and authorization. This architecture ensures that OAuth tokens remain secure from browser-side code, making them immune to potential attacks like cross-site scripting (XSS).

Note

Choreo's managed authentication is currently available only for web applications created with React, Angular, or Vue.js buildpacks.

Warning

Managed authentication uses the 'SAMESITE' cookie attribute to prevent CSRF attacks. Therefore, it is recommended to use managed authentication with modern browsers that support the 'SAMESITE' attribute.

Step 1: Set up managed authentication for your web application¶

To secure your web application, you must implement authentication and authorization for it.

To easily set up authentication for your web application with Choreo's managed authentication, follow the steps given below. Before you move on to the next section, see Develop Web Applications Locally with Choreo’s Managed Authentication to ensure a seamless authentication experience when developing your web application on your local machine. You can also refer to the sample React app with managed authentication.

To allow Choreo to manage the sign-in functionality for your web application, you must implement a sign-in button that redirects users to the /auth/login path on click. You can use the following code snippet or any custom button component from a preferred UI component library:

<button onClick={() => {window.location.href="/auth/login"}}>Login</button>

This code snippet works as follows:

When a user clicks sign in on your web application, Choreo will redirect the user to the configured identity provider and handle the authentication process, conforming to the OICD/OAuth2.0 protocols. On successful sign-in, Choreo will set the relevant session cookies and redirect the user to the post-sign-in path (default is /). The user can then invoke any Choreo-deployed APIs depending on the permission granted.

Note

Refer to configure the identity provider section for details on configuring an identity provider for the web application.

Step 1.2: Obtain user information claims¶

Choreo's managed authentication allows you to access user information claims that the identity provider returns post-sign-in, either via a cookie or by invoking a GET resource.

Obtain user information via the `userinfo` cookie

Upon successful sign-in, Choreo's managed authentication establishes a userinfo cookie that is accessible from the post-sign-in path you configured (by default, set to /). This userinfo cookie, provided by the identity provider, contains encoded user information claims.

Note

The userinfo cookie is intentionally set to have a short lifespan of only 2 minutes.
As a developer, you can decide how to utilize the user information that you retrieve. You must securely store the user information because the stored information can also serve as a means to verify the logged-in state of a user.
The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice.

The recommended approach is to retrieve user information from the cookie and subsequently clear the cookie. The following is a sample code snippet that you can include in your post-sign-in path to retrieve user information from the cookie and subsequently clear the cookie:

    import Cookies from 'js-cookie';

    // Read userinfo cookie value.
    const encodedUserInfo = Cookies.get('userinfo')

    // Decode the value. 
    const userInfo = JSON.parse(atob(encodedUserInfo))

    // Store the value in a preferred browser-based storage if needed.

    // Clear the cookie.
    Cookies.remove('userinfo', { path: <post-login-path> })

Obtain user information via a GET endpoint

Choreo's managed authentication provides the GET endpoint /auth/userinfo in addition to the userinfo cookie that it sets after successful sign-in. You can use this endpoint to query information about users who have signed in. It also serves as a mechanism to check the state of a user who has signed in.

The following is an example of a request to this endpoint:

const response = await fetch('/auth/userinfo')

If a user has signed in, the server sends a 200 OK response with the user information in JSON format in the response body. However, if the user is not signed in, the server sends a 401 Unauthorized response.

Step 1.3: Implement the sign-out functionality¶

To allow Choreo to manage the sign-out functionality of your web application, you can implement a sign-out button to redirect users to the /auth/logout path along with the session_hint cookie value on click. You can use the following code snippet or any custom button component from a preferred UI component library:

Note

It is recommended to clear any user information (if stored) at the time of sign-out.
The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice.

<button onClick={async () => {
    window.location.href = `/auth/logout?session_hint=${Cookies.get('session_hint')}`;
}}>Logout</button>`

When a user clicks the sign-out button, Choreo will clear the session cookies and redirect the users to the OIDC logout endpoint of the configured identity provider (if available).

Step 1.4: Invoke APIs¶

To invoke Choreo APIs within the same organization as your web application, you can use the relative path /choreo-apis/<api-suffix>, regardless of whether managed authentication is enabled for the web application or not.

Note

To invoke a Choreo API from a web application, you need to create a Connection from the web application to the Choreo API.

For example, if the API URL is https://2d9ec1f6-2f04-4127-974f-0a3b20e97af5-dev.e1-us-east-azure.choreoapis.dev/rbln/item-service/api-e04/1.0.0, the <api-suffix> would be /rbln/item-service/api-e04/1.0.0. You can invoke the API using the /choreo-apis/rbln/item-service/api-e04/1.0.0 relative path from your single-page application.

Info

To copy the exact service URL of a Connection, you can follow the steps given below: 1. In the Choreo Console, go to the appropriate web application component. 2. In the left navigation menu, click Connections under Dependencies. 3. Click on the required Connection and copy the service URL.

If you enable Choreo's managed authentication, you don't have to manually add any logic to attach an access token to the API call because Choreo APIs accept the cookies set by Choreo's managed authentication. You can directly invoke the API as follows:

    const response = await fetch('/choreo-apis/<api-suffix>')

If Choreo's managed authentication is disabled, you must ensure that your web application attaches a valid access token to the API call.

Step 1.5: Refresh session¶

The logged is user's session expires when the access token provided by the identity provider you have configured expires. After the session expires, the session must be refreshed to successfully call a Choreo-deployed API. For session refresh to function, you must set up the identity provider to issue a refresh token in addition to the access token.

401 Unauthorized response status code for a Choreo API request from a logged in user with the necessary permissions indicates a possible session expiry. To refresh the session, you can make a POST request to the /auth/refresh endpoint.

For example:

const response = await fetch("/auth/refresh", { method: "POST" })

If the refresh token is valid, the session will be refreshed, and the system will respond with a 204 No Content status.

If the refresh token has expired, the session will not be refreshed, and the system will respond with a 401 Unauthorized status.

To automate the session refresh process on receiving a 401 unauthorized response from the Choreo API, you can encapsulate the requests with the refresh logic. The following is an example code snippet that wraps GET requests:

    export const performGetWithRetry = async (url) => {
        try {
            // API call
            return await fetch('/choreo-apis/<api-suffix>');
        } catch (error) {
            if (error instanceof HttpError && error.status === 401) {
                //Received 401 Unauthorized response from API GW. The access token may have expired.

                // Try to refresh the token
                const refreshResponse = await fetch("/auth/refresh", {
                    method: "POST"
                });

                const status = refreshResponse.status;
                if (status === 401) {
                    // Session has expired (i.e., Refresh token has also expired).
                    // Redirect to login page
                    window.location.href = "/auth/login";
                }
                if (status !== 204) {
                    // Tokens cannot be refreshed due to a server error.
                    console.log("Failed to refresh token. Status: " + status);

                    //  Throw the 401 error from API Gateway.
                    throw error;
                }
                // Token refresh successful. Retry the API call.
                return await fetch('/choreo-apis/<api-suffix>');
            } else {
                throw error;
            }
        }
    };

Step 1.6: Set up a custom error page¶

You can set up Choreo's managed authentication to redirect to a customized error page within your web application by defining the error path in the configuration. In the event of an error during a redirection-based process, such as sign in or sign out, Choreo will automatically redirect the user to the designated custom error page.

Note

If you have not configured an error path, Choreo's managed authentication will use its default error page whenever an error occurs.

Choreo's managed authentication will include the following query parameters in the URL when redirecting to the custom error page:

Parameter	Description
code	A short textual error code indicating the error
message	The description of the error

Now have successfully implemented Choreo's managed authentication for your web application. The next step is to enable managed authentication for the component, and subsequently deploy it.

Step 2: Enable managed authentication and configure the paths¶

To ensure that your web application functions seamlessly with managed authentication, it is essential to enable managed authentication for your web application component within Choreo.

You can enable managed authentication for your web application component at the time you deploy the component.

Tip

Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks.

Sign in to the Choreo Console. This opens the project home page.
In the Component Listing pane, click on the web application for which you want to enable managed authentication.
In the left navigation menu, click Deploy.
In the Set Up card, click Configure & Deploy.
Add the necessary configurations for your component if applicable and click Next.
Make sure Managed Authentication with Choreo toggle is enabled.

Specify appropriate values for the following fields:

Field	Description	Default value
Post Login Path	The relative path that the application will be redirected to on successful sign-in. In your code, you must implement the necessary logic to obtain signed-in user's information from the `userinfo` cookie set by managed authentication. See Obtain user information via the `userinfo` cookie section in Obtain user information claims.	/
Post Logout Path	The relative path to which Choreo redirects you on successful sign-out.	/
Error Path	The relative path to which Choreo redirects you when an error occurs during a redirection-based flow (i.e., sign in or sign out). See Set up a custom error page.	Built-in error page
Session Expiry Time	The time in minutes after which the user session expires. For a seamless experience, the session expiry value should match the refresh token expiry time of the OIDC application in your identity provider.	10080 Minutes (7 Days)
Additional Scopes	All additional scopes required by the web application. The `openid`, `profile`, and `email` scopes are added by default together with the scopes required to invoke subscribed APIs.	none

Note

If you need to change these configurations after you deploy the component, you can click Authentication Settings on the Set Up card, make the necessary changes, and deploy the component once again.

Step 3: Configure the identity provider for the web application¶

You can configure your web application to work with the Choreo built-in identity provider, Asgardeo, or any external identity provider which supports OIDC/OAuth2.0 .

Note

The identity provider configured in this step should contain the users for the web application.

Click the respective tab for details depending on which identity provider you need to configure:

Configure Choreo built-in identity providerConfigure AsgardeoConfigure an external identity provider

Follow the steps given below to configure the built-in identity provider by generating authentication keys:

Note

Choreo built-in identity provider is configured by default. Therefore, this step is optional.

In the Choreo Console, go to the component for which you want to manage OAuth keys.
In the left navigation menu, click Settings.
Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
In the Identity Provider list, select Choreo Built-In Identity Provider.
Click Generate Secret.

Note

If the Regenerate Secret button is shown instead of the Generate Secret button, it indicates that OAuth keys are already generated for the component for the selected environment.

Tip

Refer to Configure a User Store with the Built-In Identity Provider for details on adding test users in Choreo built-in identity provider.

Tip

If you need to invoke APIs secured with role-based access control, you can test this within Choreo by creating roles for the application and mapping those roles to relevant permissions (scope) and user groups. For more information, see create roles and assign permissions and assign roles to user groups sections in Test Secure API Access with Choreo Built-In Security Token Service.

Step 3.1: Create and configure an OIDC/OAuth2.0 application in Asgardeo

Sign in to Asgardeo.
In the top navigation menu, click the Organization list and select your organization.
In the Asgardeo Console left navigation menu, click Applications.
Click + New Application.
Click Standard-Based Application.
Specify a name for the application and select OAuth2.0 OpenID Connect as the protocol.
Click Register.
Click the Protocol tab and follow these steps:
1. Select Code and Refresh Token as the Allowed grant types.
2. Specify the following as Authorized redirect URLs:
  - [your-web-application-url]/auth/login/callback
  - [your-web-application-url]/auth/logout/callback
3. Specify your web application URL under Allowed origins.
4. In the Access Token section, select JWT as the Token type.
5. Click Update.
  
  Tip
  
  If you need to invoke APIs secured with role-based access control, you must create roles in the application and map those roles to relevant permissions (scope). Then those roles should be assigned to user groups. For more information, see the Asgardeo API authorization guide.
6. Copy the Client ID and Client Secret of the application. You will need to use these values in the next step to link the OIDC/OAuth2.0 application to your Choreo component.

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo web application component

In the Choreo Console, go to the component for which you want to manage OAuth keys.
In the left navigation menu, click Settings.
Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
In the Identity Provider list, select Asgardeo - [your-org-name].
Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in Asgardeo.
Click Add Keys.

Step 3.1: Create and configure an OIDC/OAuth2.0 application in the external identity provider

Create an OIDC/OAuth2.0 application in your external identity provider.
Configure the OIDC/OAuth2.0 application as follows:
1. Set Code and Refresh Token as allowed grant types.
2. Add the following as authorized redirect URL.
3. Specify the following as authorized redirect URLs:
4. Specify the access token type as JWT.
  
  Tip
  
  If you want to invoke APIs secured with role-based access control, you must ensure that users are assigned a role mapping that grants the necessary permission for API invocation. The approach of mapping application roles to users can vary depending on the identity provider.

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo component

In the Choreo Console, go to the component for which you want to manage OAuth keys.
In the left navigation menu, click Settings.
Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
In the Identity Provider list, select your identity provider.
Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in your external identity provider.
Click Add Keys.

Secure Web Applications with Managed Authentication¶

Step 1: Set up managed authentication for your web application¶

Step 1.1: Implement the sign-in functionality¶

Step 1.2: Obtain user information claims¶

Obtain user information via the userinfo cookie

Obtain user information via a GET endpoint

Step 1.3: Implement the sign-out functionality¶

Step 1.4: Invoke APIs¶

Step 1.5: Refresh session¶

Step 1.6: Set up a custom error page¶

Step 2: Enable managed authentication and configure the paths¶

Step 3: Configure the identity provider for the web application¶

Obtain user information via the `userinfo` cookie