Customizable "Sign In with OpenPass" button

This quickstart helps you create an OpenPass client to integrate with your website and implement single sign-on (SSO) for the open internet. To better fit your branding, you could customize the Sign In with OpenPass button by shape, size, additional width spacing, text option, and theme.

The following is a screenshot of some custom examples of the Sign In with OpenPass button. For more examples of styling options, see Sign-in with OpenPass button samples.

Follow these instructions to install the SDK and customize the Sign In with OpenPass button, then configure your site to reference it.

IMPORTANT: To use the popup flow option, 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.

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 your Sign In with OpenPass button and handles the results of user sign-ins.

To initialize an instance of the OpenPass client, update 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}}" });

If you are using the popup flow, successful handling will include success and failed callbacks in the signInOptions parameter.

When initialization is complete, go to the following step.

3. Render the "Sign In with OpenPass" button

The JavaScript SDK can automatically render a Sign In with OpenPass button with a custom shape, size, additional width spacing, text option, and theme. For examples of styling options, see Sign-in button samples.

TIP: To make the user experience consistent and enjoyable, we've provided OpenPass co-branding guidelines. This page includes a ZIP file with SVG logos and other web assets.

Choose one of the following options for displaying the customizable button at login.

Redirect

The redirect flow uses the OpenPass client method signInWithRedirect() to initiate authentication and redirect the user to a full-page OpenPass sign-in form.

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

For details on customizable options, see HTML API reference.

Html API

The following code example renders the Sign In with OpenPass button 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.

<div 
    id="sign-in-with-openpass-button"
    data-mode="redirect"
    data-text="signin_with"
    data-client-id="CLIENT_ID"
    data-redirect-uri="REDIRECT_URI"
>
</div>

For details on customizable options, see HTML API reference.

After implementing this code, skip to the Handle the authentication response section.

JavaScript API

This API calls the renderSignInButton function with a specified parent-container element ID to house the button.

The following code example renders the Sign In with OpenPass button 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 an error page.

The Sign In with OpenPass button should be rendered using a page load event.

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 openPassClient = new OpenPassClient({
        clientId: "CLIENT_ID"
    });

    openPassClient.renderSignInButton({
        parentContainerElementId: "HTML_ELEMENT_ID",
        authenticationMode: "redirect",
        redirectUrl: "REDIRECT_URI",
        text: "signin_with",
    });

});

For details on customizable options, see JavaScript API reference.

After implementing this code, skip to the Handle the authentication response section.

Popup

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

Html API

The following code example renders the Sign In with OpenPass button in a popup window 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.

<div 
    id="sign-in-with-openpass-button"
    data-mode="popup"
    data-text="signin_with"
    data-client-id="CLIENT_ID"
    data-redirect-uri="REDIRECT_URI"
    data-popup-success-callback="popupSuccessCallback"
    data-popup-failed-callback="popupFailedCallback"
>
</div>

<script>
    window.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;
    }

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

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

For details, see the following:

• User state management implementation, see openPassClient.signInWithPopup(options) ⇒ Promise.
• UID2 implementation, see Unlock greater potential with UID2.
• Customizable options, see HTML API reference.

After implementing this code, skip to the Handle the authentication response section.

JavaScript API

The following code example renders the Sign In with OpenPass button in a popup window 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.

The Sign In with OpenPass button should be rendered using a page load event.

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 openPassClient = new OpenPassClient({
        clientId: "CLIENT_ID"
    });

    openPassClient.renderSignInButton({
        parentContainerElementId: "HTML_ELEMENT_ID",
        authenticationMode: "popup",
        redirectUrl: "REDIRECT_URI",
        text: "signin_with",
        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;
        },
        popupFailedCallback: (error) => {
            // log the error
            console.error(JSON.stringify(error));

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

For details, see the following:

• For user state management implementation, see openPassClient.signInWithPopup(options) ⇒ Promise.
• For UID2 implementation, see Unlock greater potential with UID2.
• For customizable options, see JavaScript API reference.

After implementing this code, go to the following step.

4. Handle the authentication response

NOTE: For the popup flow option, if a redirect flow has been initiated and you want to use the fallback-to-redirect mode, complete this authentication flow.

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 with OpenPass button. 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";
  }
}

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:

• To allow users to experience some of the benefits of OpenPass before verifying their accounts, implement Delayed verification.
• For details on user state management implementation, see openPassClient.signInWithRedirect(options) ⇒ Promise.
• For details on UID2 implementation, see Unlock greater potential with UID2.
• For more information, 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