Skip to main content
Version: v2

Integrate with Auth0

Last updated on

This guide provides information on how to set up Beyond Identity as a passwordless authentication provider in an Auth0 environment.

Here's what you'll do in this guide:

  • Configure Beyond Identity as an Identity provider

  • Provision users when Auth0 is the master directory

info

You can find us in the Auth0 Marketplace.

Prerequisites​

Before continuing, make sure you've met the following prerequisites:

  • Ensure that you have an Auth0 account with admin privileges

  • Access to a Beyond Identity tenant. If you still need to, sign up for a tenant.

Add Beyond Identity as an Identity Provider​

Depending on your Auth0 subscription (license), you can add Beyond Identity as an identity provider using the Enterprise OIDC connection or as a custom social OAuth2.0 connection.

Create an OIDC App in Beyond Identity​

  1. From the Admin Console, under Authentication, select Apps > Add new app.

    Admin Console Apps Add new app

  2. Give your application a name.

    Admin Console Add a new application window

  1. Select Protocol 'OIDC'.

  2. Configure the Redirect URIs as follows:

    https://DOMAIN.auth0.com/login/callback

    where DOMAIN is replaced with your Auth0 domain URL

    Example: 

    https://dev-myauth099.us.auth0.com/login/callback

  3. On the Authenticator Config tab, for Configuration Type select 'Hosted Web'.

  4. Leave all other fields with their default values and click Submit.

  5. Click the newly created OIDC client app and copy and save the following values because you'll need them for the next few steps.

    • Issuer

    • Authorization Endpoint

    • Token Endpoint

    • Client ID

    • Client Secret

Enterprise OIDC Connection​

  1. On the left side menu, click Authentication, and click Enterprise from the expanded menu.

  2. On the Enterprise Connections page, click Open ID Connect.

    enterprise-config

  3. Within the Open ID Connect menu, click Create Connection and enter the following values:

    FieldValue
    Connection NameBeyond-Identity
    Issuer URLIssuer corresponding to Beyond Identity app
    Client IDFrom OIDC client created in Beyond Identity
    Client SecretFrom OIDC client created in Beyond Identity

    new-oidc-config

  4. Click Create.

  5. Scroll up, and click the Login Experience tab.

    experience-customize

  6. Find the Connection button section and do the following:

    1. Select (enable) the Display connection as a button checkbox.

    2. Enter Beyond Identity for the Button display name.

    3. Add the following URL for the Button Logo URL:

      https://byndid-public-assets.s3-us-west-2.amazonaws.com/logos/beyondidentity.png

      display-connection

  7. Scroll down and click Save.

Custom Social OIDC Connection​

  1. On the left side menu, click Authentication, and from the expanded menu, click Social.

  2. On the Social Connections page, click the + Create Connection button in the top right corner, then scroll down and select Create Custom:

    custom-auth

  3. On the new connection form, enter the following values:

    FieldValue
    Connection NameBeyond-Identity
    Authorization URLFrom the Authorization Endpoint for the app created in Beyond Identity
    Token URLFrom the Token Endpoint for the app created in Beyond Identity
    Scopeopenid email
    Client IDFrom the Client ID of the app created in Beyond Identity
    Client SecretFrom the Client Secret of the app created in Beyond Identity

  4. Enter the following code snippet under Fetch User profile Script:

    function(accessToken, ctx, cb) {

    request.get('<BEYOND_IDENTITY_BASE_URL>/userinfo',    {
          headers: {
          'Authorization': 'Bearer' + accessToken
          }
       },
       function(err, r, body) {
          if (err) {
          return cb(err);
          }
          try {
          var profile = JSON.parse(body);
          profile.provider = 'beyond';
          profile.id = profile.sub;
          profile.displayName = profile.display_name;
          profile.email = profile.email;
          cb(null, profile);
          } catch (e) {
          cb(e);
          }
       });
    }

    where <BEYOND_IDENTITY_BASE_URL>/userinfo is replaced with the User Info Endpoint from the app you created in Beyond Identity

  1. Leave the other values as default and click Create.

    The connection is saved, and the Applications tab is displayed. You can now configure which applications should use this connection. Use the toggle switches to enable the connection for the applications you wish to use Beyond Identity.

  2. (Optional) If you use Auth0-hosted pages, you must update the button text and button logo. Auth0 only supports this via the API at the point rather than the UI. You can follow the Auth0 docs to configure this last part:

    recommendation

    We recommend labeling the button Beyond Identity or Passwordless.

  3. If you use your own login form, you can add the button manually and call the authorize endpoint specifying the connection parameter where the connection is the name of the connection you just created:

Confirm Auth0 Callback URL in Beyond Identity​

important

Check that the Auth0 callback URL is correct in the Beyond Identity OIDC integration.

  1. In Auth0, under the Settings tab of the Beyond Identity OIDC connection created above, make a note of the Callback URL as shown below:
    callback)

  1. Navigate to the Beyond Identity Admin portal, Under Authentication click Apps.

  2. Click the Auth0 app you created above.

  3. Ensure that the Redirect URI value matches the value in the Auth0 connection. If the values do not match, update the value with the Callback URL from Auth0 and click Submit.

Configure Auth0 to delegate to Beyond Identity​

This section of the guide describes how to configure Auth0 to delegate requests to Beyond Identity for authentication during an OAuth2 authorization flow.

Integration with Auth0 flow

In this section you will

  • Configure your example app to use Auth0 for authentication, including creating the app in Auth0
  • Configure Auth0 to ensure the authentication requests from the app to Auth0 can use Beyond Identity for authentication

Create the app in Auth0​

In your Auth0 tenant:

  1. On the left side menu, click Applications, and then Applications from the expanded menu.

  2. On the Applications page, click Create Application.

  3. Provide the app a name such as "NextAuth.js App" or similar and select the appropriate app type based on your platform, then click Create

  4. Click the Settings tab

  5. In the Allowed Callback Urls, specify a route in your app that is capable of handling the code that is returned from the authorization call and exchanging it for access and/or refresh tokens. For a web app this will be a URL, or for a native app this will be an App Scheme or Universal URL.

    For example: In a Next.js application using NextAuth, your redirect URI would follow the pattern: http://localhost:3000/api/auth/callback/auth0

  6. Copy the values for Domain, Client ID, and Client Secret

  7. Click Save to save the new app

Enable the app on your Beyond Identity connection in Auth0​

In order for Beyond Identity to show up as an authentication option for your app, you need to enable the Beyond Identity connection for that app in Auth0:

  1. In Auth0, navigate to the Enterprise or Social connection you created above for Beyond Identity.

  2. Within the Enterprise or Social connection, click the Applications tab and toggle the entry for the app you have just created.

Configure Auth0 connection in the NextAuth.js sample app​

Now you will create Auth0 as an OAuth provider in your app:

Prerequisites​

NextAuth.js

This part of the integration guide uses NextAuth for all OAuth/OIDC flows. All code snippets are provided in the context of the NextAuth Example App.

Configuring NextAuth​

Under next-auth-example/pages/api/auth/[...nextauth].ts, add the following Auth0 provider:

import Auth0Provider from "next-auth/providers/auth0";
...
providers: [
  Auth0Provider({
    clientId: <AUTH0_ID>,
    clientSecret: <AUTH0_SECRET>,
    issuer: <AUTH0_ISSUER>
  })
]
...

Note that you'll need to fill in the <AUTH0_ID>, <AUTH0_SECRET>, and <AUTH0_ISSUER> with the values you generated when creating your application in Auth0.


Wiring up embedded.authenticate​

Create a bi-authenticate.tsx page under /next-auth-example/pages. As long as your invoke_url is configured properly, this is the page that will be redirected to during an authorization flow. copy the following code snippet into that page.

import { useEffect, useState } from "react";
import "bootstrap/dist/css/bootstrap.css";
import { Passkey } from "@beyondidentity/bi-sdk-js";

const BIAuthenticate = () => {
  const [biAuthenticateResult, setBiAuthenticateResult] = useState("");

  useEffect(() => {
    // -- 1
    const authenticate = async () => {
      const BeyondIdentityEmbeddedSdk = await import("@beyondidentity/bi-sdk-js");
      let embedded = await BeyondIdentityEmbeddedSdk.Embedded.initialize();
      if (embedded.isAuthenticateUrl(window.location.href)) {
        // Only authenticate if the URL is a "bi-authenticate" URL
        let biAuthenticateUrl = window.location.href;
        // -- 2
        biAuthenticate(biAuthenticateUrl).then(redirectUrl => {
          // -- 4
          window.location.href = redirectUrl;
        }).catch(error => {
          setBiAuthenticateResult(error.toString());
        });
      }
    }
    authenticate().catch(console.error);
  }, []);

  // -- 3
  async function biAuthenticate(url: string): Promise<string> {
    const BeyondIdentityEmbeddedSdk = await import("@beyondidentity/bi-sdk-js");
    let embedded = await BeyondIdentityEmbeddedSdk.Embedded.initialize();

    // Display passkeys so user can select one
    let passkeys = await embedded.getPasskeys();
    let promptText = passkeys.map((passkey, index) => {
      return `${index}: ${passkey.identity.username}`;
    }).join("\n");
    let selectedIndex = parseInt(prompt(promptText, "index")!!);
    if (selectedIndex >= 0 && selectedIndex < passkeys.length) {
      let selectedId = passkeys[selectedIndex].id;
      // Perform authentication using selected id
      let result = await embedded.authenticate(url, selectedId);
      return Promise.resolve(result.redirectUrl);
    } else {
      // This will fail in core as it won't match to any id
      return Promise.resolve("unknown_id");
    }
  }

  return (
    <div
      style={{
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
        height: '100vh',
      }}
    >
      <div className="container">
        <div className="row">
          <div className="d-flex justify-content-center">
            <div className="spinner-border" role="status">
              <span className="sr-only"></span>
            </div>
          </div>
        </div>
        <div className="row">
          {
            biAuthenticateResult.length > 0 &&
            <div className="row row-cols-1 row-cols-md-1 mt-3">
              <div className="col">
                <code>
                  {JSON.stringify(biAuthenticateResult, null, 2)}
                </code>
              </div>
            </div>
          }
        </div>
      </div>
    </div>
  );
};

export default BIAuthenticate;

What's happening here?​

  1. The useEffect is only called once on page load. In this function, we initialize the Beyond Identity SDK and use embedded.isAuthenticateUrl to check if the current page that was redirected to is in fact a valid bi-authenticate URL.
  2. If the URL is valid, we pull the URL using window.location.href and pass that directly into biAuthenticate in step 3.
  3. biAuthenticate calls embedded.authenticate with a valid bi-authenticate URL. This function performs a challenge/response against a passkey bound to your browser. Note that the callback in embedded.authenticate contains logic in order to prompt a user to select a passkey if there is more than one.
  4. Finally, the response of embedded.authenticate contains a redirectUrl. Follow this redirect URL to complete the OAuth/OIDC flow.

What does it look like?​

Upon running the next auth example app and clicking on the sign in button, you'll see the provider you just added as shown in the image below. Clicking on that provider will go through an OAuth/OIDC that will result in fetching an id token that will log you in to the example app.


image