Co-branding: Inline 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 the sign-in form directly within a web page using an iframe for a more seamless and integrated user experience. It also offers a better branding experience by placing the publisher's logo and display name at the top of the sign-in form, not next to the OpenPass brand.

The following is a screenshot of the inline sign-in form.

Follow these instructions to install the SDK with an inline sign-in form, then configure your site to reference it.

IMPORTANT: To use the inline sign-in form, 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.
Inline 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 inline sign-in form will be used.

Step Description Notes
1 Install the SDK. You can use a content delivery network (CDN) or node package manager (NPM).
2 Initialize the OpenPass client. N/A
3 Render and configure the inline sign-in form. You can configure its width and height, and select the text for the Sign In with OpenPass button.
4 Implement an authentication flow. To brush up on the differences between flows, see the JavaScript overview.

The following sections detail each step.

1. Install the SDK

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

The OpenPass client in your web application manages the link generation for the inline sign-in form and handles the results of user sign-ins.

To create an instance of the OpenPass client, replace the placeholder values for the clientId parameter with a unique identifier for your application and the URL of the authentication server, respectively. See the following code example.

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

When initialization is complete, go to the following step.

3. Render inline sign-in form

This step renders the sign-in form directly within a web page using an iframe for a more seamless and integrated user experience. It also offers a better branding experience by placing the publisher's logo and display name at the top of the sign-in form, not next to the OpenPass brand.

IMPORTANT: To use the inline sign-in form, 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.
Inline 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 inline sign-in form will be used.

To configure the inline sign-in form, provide your configuration options for the sign-in process. You can customize the sign-in form's appearance and behavior, including enabling dark mode. Additionally, you can store any desired client state to pass to the popupSuccessCallback parameter. For a full list of options, see API reference.

The following sections have code examples for the redirect and popup flows.

Redirect

Here is a code example of configuration options for the redirect flow.

const signInOptions = {
  redirectUrl: window.location.origin + "/redirect-callback",
  parentContainerElementId: "inline-sign-in",
  authenticationMode: "redirect",
  signinButtonTextOption: "signin",
  darkModeEnabled: true
};

openPassClient.renderInlineSignInForm(signInOptions);

Popup

Here is a code example of configuration options for the popup flow.

const popupSuccessCallback = (signInResponse) => {};
const popupFailedCallback = (error) => {};

const signInOptions = {
  redirectUrl: window.location.origin + "/redirect-callback",
  parentContainerElementId: "inline-sign-in",
  authenticationMode: "popup",
  signinButtonTextOption: "signin",
  popupSuccessCallback: popupSuccessCallback,
  popupFailedCallback: popupFailedCallback,
  darkModeEnabled: true
};

openPassClient.renderInlineSignInForm(signInOptions);

The following is a screenshot of the inline sign-in form in dark mode.

Optional DOMContentLoaded event

The inline sign-in form should be rendered using a page load event, but using the load event can delay rendering. We recommend using the DOMContentLoaded event instead. See the following code example.

window.addEventListener("DOMContentLoaded", () => {
  const signInOptions = {
    ...
  };

  openPassClient.renderInlineSignInForm(signInOptions);
});

When completed, go to the following step.

4. Handle the authentication response

Choose the sign-in flow from the following table that works best for your application:

Flow Description
Redirect A full-page redirect to the OpenPass sign-in form. After signing in, it returns you to the redirect URI to finish authentication.
Popup An OpenPass sign-in form launched in a new popup browser window on top of your site. After signing in, the window closes and the flow sends a message to the origin page to finish authentication.

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 the sign-in form. 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 the popup before authenticating):
    window.location = "/login";
  }
}

For details on user state management implementation, see openPassClient.signInWithRedirect(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 popup. 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.

To handle different parts of the workflow, the popup flow uses the following APIs.

API Description
signInWithPopup() This initiates the authentication flow and handles the result.
handleAuthenticationRedirect() As an option, if the fallback to redirect is triggered because the popup fails to open, use the redirect handling method described in the previous section.

To handle the popup authentication response, use the following code example. If the popup window loads successfully, it runs a redirect to the originating page that triggered the sign-in. Otherwise, it redirects to an error page. 

const popupSuccessCallback = (signInResponse) => {
  // 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;
};

const popupFailedCallback = (error) => {
  // log the error
  console.error(JSON.stringify(error));

  // Decide what to do if the sign-in fails (for example, user closes popup):
  window.location = "/login";
};

const signInOptions = {
  redirectUrl: window.location.origin + "/redirect-callback",
  parentContainerElementId: "inline-sign-in",
  authenticationMode: "redirect",
  signinButtonTextOption: "signin",
  popupSuccessCallback: popupSuccessCallback,
  popupFailureCallback: popupFailedCallback,
};

openPassClient.renderInlineSignInForm(signInOptions);

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

Next steps

Here are some suggestions for enhancing OpenPass functionality and the user experience:

Additional resources

For more information, see the following pages: