📘

External Applications

This authentication guide applies to applications hosted outside the congacloud.io domain. Authentication for congacloud.io hosted apps are handled internally by the platform and do not use the authorization code flow described in this document.

About

This guide will walk you through setting up the OAuth 2.0 authorization code flow with PKCE to connect browser-based applications with Conga API services. Your app will be able to get tokens that can be used with the APIs listed in the API reference.

The @azure/msal-angular and @azure/msal-angular package described by the code in this guide wraps the @azure/msal-browser package and uses it as a peer dependency to enable authentication in Single Page web applications without backend servers. This version of the library uses the OAuth 2.0 Authorization Code Flow with PKCE.

Prerequisites

This guide assumes you are building a single-page Application (SPA) using a React framework and you have obtained a client ID from the Conga Authentication Service. Your redirect URI must also be registered with the application.

npm install @azure/msal-browser @azure/msal-react@latest

Initialization of MSAL

Before you start, complete all the prerequisites.

Then, follow these procedures:

• Initializing the PublicClientApplication object
• Choosing an Interaction Type
  • Popup APIs
  • Redirect APIs
• Next Steps

Initializing the PublicClientApplication object

To use MSAL.js, you must instantiate a PublicClientApplication object. You must provide your application's client ID (appId).

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: "***Your Authority URL***",
        redirectUri:  window.location.origin + window.location.pathname,
        knownAuthorities: ['***Your Authority URL***'],
        protocolMode: "OIDC"
    }
};

Choosing an Interaction Type

In the browser, there are two ways to present the login screen to users from your application:

• Present a popup window from the current page
• Redirect the browser window to the login server

Popup APIs

• loginPopup
• acquireTokenPopup

The popup APIs use ES6 Promise objects that resolve when the popup's authentication flow concludes and returns to the specified redirect URI, or reject if there are issues in the code or the popup is blocked.

RedirectUri Considerations

When using popup APIs, we recommend setting redirectUri to a blank page or a page that does not implement MSAL. This prevents potential issues and improves performance. If your application is only using popup and silent APIs you can set this on the PublicClientApplication config. If your application also needs to support redirect APIs, you can set redirectUri on a per-request basis:

msalInstance.loginPopup({
    redirectUri: "http://localhost:3000/blank.html"
});

Redirect APIs

• loginRedirect
• acquireTokenRedirect

Note

If you are using msal-angular or msal-react, redirects are handled differently. See the msal-angular redirect doc and msal-react FAQ for more details.

Redirect APIs are asynchronous (i.e. return a promise) void functions that redirect the browser window after caching some basic info. If you choose to use redirect APIs, be aware that you must call handleRedirectPromise() to handle the API correctly. Use the following function to perform an action when this token exchange is completed:

msalInstance.handleRedirectPromise().then((tokenResponse) => {
    // Check if the tokenResponse is null
    // If the tokenResponse !== null, then you are coming back from a successful authentication redirect. 
    // If the tokenResponse === null, you are not coming back from an auth redirect.
}).catch((error) => {
    // handle error, either in the library or coming back from the server
});

This also allows you to retrieve tokens on page reload.

Do not use both interaction types in a single application.

Note: handleRedirectPromise can accept a hash value to be processed, defaulting to the current value of window.location.hash. This parameter only must be provided when the current value of window.location.hash does not contain the redirect response to be processed. For almost all scenarios, applications do not have to provide this parameter explicitly.

Next Steps

You are ready to use Conga public APIs!