@forgerock/javascript-sdk

ForgeRock JavaScript SDK

The ForgeRock JavaScript SDK is a toolkit that allows web developers to easily integrate with ForgeRock OpenAM and ForgeRock Identity Cloud.

Installation

To use the SDK:

# Install the SDK as a dependency in your project
npm i -S forgerock-javascript-sdk

To build the SDK and run samples:

# Build the SDK and watch for changes
npm start

# Start the sample webserver
npm run samples

Usage

Express UI Example

The Express UI is the easiest way to log users in using one of the supported Express authentication flows. All required elements will be rendered for you, and you can customize the experience by defining CSS styles to override our defaults.

// Configure the SDK
var clientId = 'my-spa-client';
var redirectUri = 'https://myapp.domain.com/callback';
var scope = 'openid profile';
var tree = 'UsernamePassword';
var serverConfig = { baseUrl: 'https://mytenant.forgeblocks.local/am/' };
var expressServerConfig = { baseUrl: 'https://api-mytenant.forgeblocks.com' };
var options = {
  serverConfig,
  styled: true,
  targetId: 'sdk-target',
  tree,
};

// On log in, request OAuth tokens
function onLogin() {
  var token = new forgerock.Token({ serverConfig });
  token
    .getTokens({ clientId, redirectUri, scope })
    .then(getUser)
    .catch(console.error);
}

// Fetch current user info
function getUser(tokens) {
  var user = new forgerock.User({
    accessToken: tokens.access_token,
    serverConfig: expressServerConfig,
  });
  user
    .getCurrentUser()
    .then(showUser)
    .catch(console.error);
}

// Display the user info
function showUser(user) {
  var json = JSON.stringify(user, null, 2);
  document.getElementById(options.targetId).innerHTML = `<pre>${json}</pre>`;
}

// Invoke the Express UI
var login = new forgerock.ExpressLogin(options);
login.addEventListener('login_success', onLogin);
login.start();

Custom UI Example

When building a custom UI, consume the core Auth service directly. Render your desired DOM based on step type, and then call auth.next(step) to get the next step in the authentication flow.

var serverConfig = { baseUrl: 'https://openam-mytenant.forgeblocks.com/am/' };
var authOptions = { name: 'UsernamePassword', serverConfig };
var auth = new forgerock.Auth(authOptions);

function handleStep(step) {
  // Render UI for this step, e.g. username/password inputs with a
  // submit button that populates `step` and then calls nextStep(step)
}

function nextStep(step) {
  auth
    .next(step)
    .then(handleStep)
    .catch(console.error);
}

nextStep();

Documentation

TBD

To Do

• Unit tests with coverage reporting
• Bundle visualization
• Customize typedocs comments

License

MIT