QuickAuth sign-in form

This quickstart helps you create an OpenPass client to integrate with your website and implement single sign-on (SSO) for the open internet. It renders a QuickAuth sign-in form directly within a web page using fewer authentication steps than the other OpenPass sign-in methods. With QuickAuth, users who are already signed in to OpenPass on their device can seamlessly authenticate to your website or app with a single click.

The following are screenshots of the QuickAuth sign-in.

Follow these instructions to install the SDK with QuickAuth, then configure your site to reference it.

IMPORTANT: To use QuickAuth, ensure that you have a client ID and your website has a secure origin.
If you're using a localhost origin for development purposes, create a separate application for that purpose. This ensures that localhost is never allowed on your production configurations.
QuickAuth sign-in requires a content security policy that allows embedding the iframe on your site. You must configure the application to include all the origins where the QuickAuth sign-in form will be used.

The following sections detail each step.

TIP: For a better developer experience, you can use the QuickAuth sample apps in GitHub for reference.

1. Install the SDK

IMPORTANT: To properly format the QuickAuth login sign-in form, be sure to use OpenPass JavaScript SDK version 4.2.3 or later.

You can install the SDK on a CDN or use NPM.

Installing using CDN has limitations. Unlike NPM, developers have limited control over the code they can use for shipping when compiling, and they cannot deploy or optimize JavaScript bundles by including dependencies like OpenPass. Also, some developers prefer to fix versions in NPM.

CDN

To install on a CDN, run the following command.

<script src="https://cdn.myopenpass.com/openpass-js-sdk/v4/openpass-js-sdk.min.js"></script>

NPM

To install using NPM, run the following command in your project.

npm install @openpass/openpass-js-sdk

In your code, reference the library. Here is an example:

// ES6 / TypeScript
import { OpenPassClient } from "@openpass/openpass-js-sdk";

When completed, go to the following step.

2. Initialize the OpenPass client

To render QuickAuth, you need to first instantiate the OpenPass client by updating the option parameters in the new OpenPassClient(options) method. The client is created once in your application and referenced in the appropriate places.

const openPassClient = new OpenPassClient({ clientId: "{{clientId}}" });

When initialization is complete, go to the following step.

3. Render QuickAuth

This step renders a QuickAuth sign-in form directly within a web page for a more seamless and integrated user experience. With QuickAuth, users who are already signed in to OpenPass on their device can seamlessly authenticate to your website or app with a single click.

Choose one of the following authentication flow options for displaying QuickAuth.

Redirect flow

The redirect flow uses the OpenPass client method signInWithRedirect() to initiate authentication and redirect the user back to the originating page after sign-in.

For the redirect flow, you can choose from these options:

Html API

The following code example renders QuickAuth using HTML. You must provide a client ID and redirect URI. If the sign-in page loads successfully, it runs a redirect to the originating page that triggered the sign-in. Otherwise, it redirects to an error page.

<main>
  <div>
    <div
      id="openpass-quick-auth"
      data-openpass-quick-auth-client-id="CLIENT_ID"
      data-openpass-quick-auth-mode="redirect"
      data-openpass-quick-auth-redirect-uri="REDIRECT_URI"
      data-openpass-quick-auth-visibility="displayOnInit"
    ></div>
  </div>
</main>;

For details on customizable options, see HTML API reference.

After implementing this code, skip to the Implement the authentication flow section.

JavaScript API

This API renders QuickAuth using JavaScript. You must provide an element ID, client ID, and redirect URI. If the sign-in page loads successfully, it runs a redirect to the originating page that triggered the sign-in. Otherwise, it redirects to the full-page OpenPass sign-in form. Be sure to instantiate the client and pass the correct arguments.

TIP: Using the load event can delay rendering, so we recommend using the DOMContentLoaded event instead. See the following code example.

window.addEventListener("DOMContentLoaded", async () => {
  const authClient = new OpenPassClient({
    clientId: "CLIENT_ID",
  });

  try {
    authClient.renderQuickAuth({
      parentContainerElementId: "HTML_ELEMENT_ID",
      authenticationMode: "redirect", 
      redirectUrl: "REDIRECT_URI",
      visibility: "displayOnInit"
    });
  } catch (e) {
    console.error(e);
  }
});

For details on customizable options, see JavaScript API reference.

After implementing this code, skip to the Implement the authentication flow section.

Popup flow

For the popup flow, you can choose from these options.

Html API

The following code example renders QuickAuth using HTML. You will need to provide a client ID, with an optional redirect URI. If the popup window loads successfully, it runs a redirect to the originating page that triggered the sign-in. If no redirect URI is provided and the popup fails, the user is redirected to an error page.

<main>
  <div>
    <div
      id="openpass-quick-auth"
      data-openpass-quick-auth-client-id="CLIENT_ID"
      data-openpass-quick-auth-mode="popup"
      data-openpass-quick-auth-redirect-uri="REDIRECT_URI"
      data-openpass-quick-auth-visibility="displayOnInit"
      data-openpass-quick-auth-popup-success-callback="popupSuccessCallback"
      data-openpass-quick-auth-popup-failed-callback="popupFailedCallback"
    ></div>
  </div>
  <script>
    function popupSuccessCallback(signInResponse) {
      console.log("Popup flow sign in succeeded, email address: " + signInResponse.idToken.email);
    }

    function popupFailedCallback(error) {
      console.log("Popup flow sign in failed, error: " + error.message);
    }
  </script>
</main>;

For details on customizable options, see HTML API reference.

After implementing this code, skip to the Implement the authentication flow section.

JavaScript API

The following code example renders QuickAuth using JavaScript. You will need to provide an element ID and client ID, with an optional redirect URI. If the popup window loads successfully, it runs a redirect to the originating page that triggered the sign-in. If no redirect URI is provided and the popup fails, the user is redirected to an error page.

TIP: Using the load event can delay rendering, so we recommend using the DOMContentLoaded event instead. See the following code example.

window.addEventListener("DOMContentLoaded", async () => {
  const authClient = new OpenPassClient({
    clientId: "CLIENT_ID",
  });

  try {
    authClient.renderQuickAuth({
      parentContainerElementId: "HTML_ELEMENT_ID",
      authenticationMode: "popup",
      redirectUrl: "REDIRECT_URI",
      popupSuccessCallback,
      popupFailedCallback,
      visibility: "displayOnInit",
    });
  } catch (e) {
    console.error(e);
  }

  function popupSuccessCallback(signInResponse) {
    console.log("Popup flow sign in succeeded, email address: " + signInResponse.idToken.email);
  }

  function popupFailedCallback(error) {
    console.log("Popup flow sign in failed, error: " + error.message);
  }
});

For details on customizable options, see JavaScript API reference.

After implementing this code, go to the following step.

4. Customize visibility

The renderQuickAuth options includes parameters to customize QuickAuth visibility and get notifications when visibility changes. This can help with more advanced scenarios, such as displaying QuickAuth only when an OpenPass session is active in the user's browser.

Visibility

This parameter can be set by either the HTML API or JavaScript API. The following table lists the parameter name for each API.

The following table lists the possible values for the visibility parameter.

TIP: For an improved user experience, use the hideOnInit option. This automatically hides QuickAuth after initialization, preventing the sign-in form from reappearing after a successful login.

Visibility-changed callback

This parameter can be set by either the HTML API or JavaScript API. The following table lists the parameter name for each API.

This parameter points to a function that takes a payload of the form: { visibility: "visible"|"hidden" }

Visibility will change in the following circumstances:

• On initialization - When QuickAuth is initially rendered, depending on the visibility parameter, the visibility-changed callback will be called with visibility set to visible if displayed or hidden if not displayed. If visibility is set to displayOnInitIfSessionActive, then that will be visible when an OpenPass session is active on the user's browser or hidden when there is no active OpenPass session.
• When the user closes QuickAuth.
• When a sign-in flow is complete.

Example

Here is a code example with the visibility set to displayOnInitIfSessionActive.

window.addEventListener("DOMContentLoaded", async () => {
  const authClient = new OpenPassClient({
    clientId: "CLIENT_ID",
  });

  try {
    authClient.renderQuickAuth({
      parentContainerElementId: "HTML_ELEMENT_ID",
      authenticationMode: "popup",
      popupSuccessCallback,
      popupFailedCallback,
      visibility: "displayOnInitIfSessionActive",
      visibilityChangedCallback
    });
  } catch (e) {
    console.error(e);
  }

  function visibilityChangedCallback(data) {
    console.log("QuickAuth visibility changed: " + data.visibility);
  }
});

5. Implement the authentication flow

Choose the sign-in flow from the following table based on your configuration from the previous section.

Redirect

To handle the OpenPass authorization-code redirect and finalize the authentication flow, the redirect flow uses isRedirect() and handleAuthenticationRedirect().

IMPORTANT: Make sure that the redirect URI you provide to the signInWithRedirect() method matches one of the redirect URIs specified in your OpenPass account. You also need to configure the redirect URL in the application settings for your client.

To handle the redirect authentication response, use the following code example to complete the authentication process and handle the redirect from QuickAuth. If the sign-in is successful, you may redirect the user to the originating page that triggered the sign-in. But if there is an exception, you can choose to redirect them to an error page instead.

// Example: on route HTTPS_HANDLE_OP_REDIRECT_URL

// Check if this page was loaded by means of an OpenPass redirect.
if (openPassClient.isAuthenticationRedirect()) {
  try {
    // The following reads the authorization code from the OpenPass redirect request and 
    //exchanges it for an ID token and an access token.
    const signInResponse = await openPassClient.handleAuthenticationRedirect();

    // Access the user's email address and user ID from the response.
    const email = signInResponse.idToken.email; 
    const openpassUserId = signInResponse.idToken.sub;

    // Set up the user's session on your site. This step is controlled by you and depends on your user state management implementation. 
    startUserSession(openpassUserId, email); 

    // Connect the user to UID2.
    setUpUid2Identifier(email);

    // Redirect the user back to the original content.
    window.location = signInResponse.originatingUri;
  } catch (e) {
    // Decide what to do if the sign-in fails (for example, the user closes QuickAuth before authenticating):
    window.location = "/login";
  }
}

For details on user state management implementation, see openpassClient.renderQuickAuth(options) ⇒ Promise. For details on UID2 implementation, see Unlock greater potential with UID2.

Handling the authentication response completes the installation process. To verify the OpenPass ID token, see Verify the ID token. For next steps, see Additional resources.

Popup

This flow initiates OpenPass sign-in in a popup window and can include a fallback to the full-page redirect sign-in if it's not possible to create the iframe. That can happen if the popup is blocked. For the popup window to communicate with the originating window, OpenPass uses the browser's Post Message API.

IMPORTANT: To use the popup flow, ensure that your website has a secure origin. This means that your website should have an HTTPS address.
If you're using a localhost origin for development purposes, create a separate application for that purpose. This ensures that localhost is never allowed on your production configurations.
If you're also using the fallback-to-redirect option for the popup flow, which is used when the popup fails to open, you need to configure a redirect URL.

Handling the authentication response completes the installation process. To verify the OpenPass ID token, see Verify the ID token.

To allow users to experience some of the benefits of OpenPass before verifying their accounts, implement Delayed verification.

For next steps, see Additional resources.

Additional resources

For more information, see the following pages:

• JavaScript API reference
• OpenPass Sample Sites
• UID2
• Integration best practices
• Co-branding guidelines