@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

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.

forgerock.Config.set({
  authServerConfig: { baseUrl: 'https://mytenant.forgeblocks.local/am/' },
  clientId: 'my_client_id',
  redirectUri: 'https://myapp.domain.com/callback',
  scope: 'openid profile me.read',
  tree: 'UsernamePassword',
  userServerConfig: { baseUrl: 'https://api-mytenant.forgeblocks.com' },
});

async function signIn() {
  const ui = new forgerock.ExpressLogin({ targetId: 'sdk-target' });
  const user = await forgerock.FRUser.loginWithUI(ui);
  window.sessionStorage.setItem('user', JSON.stringify(user));
  window.location = 'authenticated.html';
}

async function signOut() {
  await forgerock.FRUser.logout();
  window.location = 'index.html';
}

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();

Custom React UI Example

import { Auth } from '@forgerock/javascript-sdk';
import React from 'react';
import './App.css';

class App extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      error: undefined,
      ssoToken: undefined,
      step: {},
    };

    this.auth = new Auth({
      name: 'UsernamePassword',
      serverConfig: {
        baseUrl: 'https://dev.openam.forgeblocks.local/am/',
      },
    });
  }

  componentDidMount() {
    this.nextStep();
  }

  nextStep = async (step) => {
    step = await this.auth.next(step).catch(this.handleFatalError);
    if (step.tokenId) {
      this.setState({ ssoToken: step.tokenId, step: { stage: 'LoginSuccess' } });
    } else {
      this.setState({ step });
    }
  };

  handleFatalError = (error) => {
    this.setState({ error });
  };

  render() {
    const stage = this.state.step ? this.state.step.stage : 'Loading';
    return (
      <div className="App">
        <header className="App-header">
          <p>ForgeRock SDK + React Demo</p>
          <p style={{ fontSize: '1rem' }}>
            {this.state.error && <span>An error occurred: {this.state.error}</span>}
            {stage === 'Loading' && <span>Loading...</span>}
            {stage === 'LoginSuccess' && <span>SSO token: {this.state.ssoToken}</span>}
            {stage === 'UsernamePassword' && (
              <UsernamePassword step={this.state.step} onSubmit={this.nextStep} />
            )}
            {/* Create components for other stages */}
          </p>
        </header>
      </div>
    );
  }
}

function UsernamePassword(props) {
  const setCallbackValue = (type, value) => {
    props.step.callbacks.find((x) => x.type === type).input[0].value = value;
  };

  const setUsername = (e) => {
    setCallbackValue('NameCallback', e.target.value);
  };

  const setPassword = (e) => {
    setCallbackValue('PasswordCallback', e.target.value);
  };

  const onSubmit = () => {
    props.onSubmit(props.step);
  };

  return (
    <>
      <input type="text" placeholder="Username" onChange={setUsername} />
      <br />
      <input type="password" placeholder="Password" onChange={setPassword} />
      <br />
      <button onClick={onSubmit}>Submit</button>
    </>
  );
}

export default App;

Samples

Prerequisites:

• OpenSSL is installed
• samples/js/config.js is updated to specify your SDK configuration

# Add host
echo '127.0.0.1 www.forgerock-sdk-samples.com' | sudo tee -a /etc/hosts

# Generate self-signed cert
npm run make_cert

# Trust the cert (MacOS)
sudo npm run trust_cert

# Build the SDK and watch for changes
npm start

# Start the sample webserver
npm run samples

Access the samples at https://www.forgerock-sdk-samples.com:3000

E2E Tests

E2E tests are implemented with Puppeteer. They utilize an HTML page that allows configuration of the SDK via querystring parameters at the beginning of each test scenario.

# Start the test web server
npm run e2e_server

# Run test scenarios
npm run e2e_tests

Documentation

TBD

To Do

• Unit tests with coverage reporting
• Expand E2E tests
• Optimizations
• Customize typedocs comments

License

MIT