search
quickstarts

Integrate Embedded Sign-in

In this QuickStart you’ll:

  • Get access to our sample apps.
  • Integrate authentication into your app using the ForgeRock SDK.
  • Examine how registration and authentication work with ForgeRock samples.


The sample app that you’ll set up is based on the ForgeRock JavaScript SDK. Once configured, you can test the following embedded sign-in experiences:

  • Embedded sign-in experience based on supported Authentication options.
  • A hybrid embedded sign-in sample, based on 2FA.
  • An embedded self-registration sample, as shown here:

alt text


ForgeRock JavaScript SDK

The ForgeRock JavaScript SDK is a toolkit that lets web developers integrate their apps with the ForgeRock Identity Cloud.

The SDK provides:

  • An abstraction for the ForgeRock APIs
  • Recommended implementations

Once installed, you’ll be able to test our authentication processes for yourself. For information, leave this website and go to the ForgeRock SDKs website.

Step 1 : Set Up the SDK

This SDK setup includes Docker containers.

1a. Install the following software:

In some cases, you may need to install and configure these packages as the administrative user.

1b. Clone the ForgeRock JavaScript SDK repository.

alt text

Step 2 : Set Up Your App

To incorporate our code into your apps, you’ll need to find the value of the following properties:

Entry Description
clientId Identifier for your app
scope Rights for protected resources
styled Boolean to inject default styles into the Website DOM
tenant Associated with your environment
tree Authentication tree options: UsernamePassword, PasswordlessWebAuthn, SecondFactor, SecondFactorWebAuthn

Step 3: Generate a Self-Signed Certificate

Modern websites use secure HTTP, so you’ll need to set up a self-signed certificate. The instructions vary by operating system. You’ll need to:

3a. Create a certs/ subdirectory.

3b. Generate a self-signed certificate. For some operating systems, you may need to copy that certificate to a specific directory for your keychain.

3c. Import the certificate to your keychain.

3d. Include the following line to your static name resolution file, such as /etc/hosts:

127.0.0.1 local.forgeblocks.com

Step 4 : Configure Your Environment

4a. Navigate to the directory where you cloned the ForgeRock JavaScript SDK repository.

4b. Set up the DOCKER_HOST environment variable:

content_copy COPY

export DOCKER_HOST=tcp://127.0.0.1:2375

4c. Use the following command to pull Docker containers:

content_copy COPY

docker-compose up -d

If this is the first time you’re importing Docker containers, the process may take a few minutes. Once the command is complete, navigate to any of the following sites:

  • Embedded Sign-in: https://local.forgeblocks.com:9001/simple
  • Hybrid Sign-in: https://local.forgeblocks.com:9001/hybrid1
  • Self-registration: https://local.forgeblocks.com:9001/registration

Step 5 : Try It Out!

The following is what you see when you navigate to https://local.forgeblocks.com:9001/simple. It lets you try the authentication flows for each noted configuration. For details, see Authentication.

alt text

Step 6: Integrate Embedded Sign-in Into Your Website

To integrate Express authentication, substitute your values for these entries:

Entry Description
clientId Identifier for your app
scope Rights for protected resources
styled Boolean to inject default styles into the Website DOM
tenant Associated with your environment
tree Authentication tree options: UsernamePassword, PasswordlessWebAuthn, SecondFactor, SecondFactorWebAuthn

in the following code. Then include the code in your apps.

content_copy COPY

<!-- Create a container for the embedded login -->
<div id="fr-target">Loading...</div>

<!-- Reference the SDK -->
<script src="fr.min.js"></script>

<!-- Integrate the SDK into your site -->
<script>
  // Create the embedded login
  var login = new forgerock.EmbeddedLogin('fr-target', {
    styled: true,
    tenant: 'tenantName',
    tree: 'UsernamePassword',
  });

  // Register callbacks and start the ux
  login
    .addEventListener('step_change', (e) => console.log('step changed', e))
    .addEventListener('login_success', (e) => {
      console.log('login successful', e);
      exchangeToken(e.ssoToken);
    })
    .addEventListener('login_failure', (e) => console.log('login failed', e))
    .start();

  // On login, exchange the SSO token for access and id tokens
  function exchangeToken(ssoToken) {
    var token = new forgerock.Token({
      clientId: 'my-client-id',
      tenant: 'tenantName',
    });
    token.exchangeSsoToken(ssoToken, 'SCOPE').then((t) => {
      console.log('exchanged token', t);
      var target = document.getElementById('fr-target');
      target.innerHTML = `<p>
        SSO Token:<br/>${ssoToken}<br/><br/>
        Access Token:<br/>${t.accessToken}<br/><br/>
        ID Token:<br/>${t.idToken}
        </p>`;
    });
  }
</script>

For questions or feedback, contact us.