README.md

🚀 Try it for free in the new Phase Two keycloak hosting service. Go to Phase Two for more information.

🐛 This is alpha software

JavaScript SDK for Phase Two API

The Phase Two JavaScript SDK library provides access to the Phase Two API for Node.js and browser applications.

Documentation

See the API Reference and NPM page.

Installation

npm i @p2-inc/js-sdk

Use

The JavaScript SDK assumes the use of the offical keycloak-js library for browser use, or a OpenID Connect library for Node.js use. See the Authentication notes below for example configurations for each.

Examples

import { Configuration } from ".";
import { EventsApi, OrganizationsApi } from "./apis";

// Configure the API connection
const configuration = new Configuration({
  basePath: 'https://my-keycloak-host/auth/realms',
  accessToken: getAccessToken(), //see examples below
});

const realm = 'my-realm';
const orgs = new OrganizationsApi(configuration);

// Create an Organization
const createPromise = orgs.createOrganizationRaw({realm: realm, organizationRepresentation: {name: 'my-org'}});
const orgId = await createPromise.then((resp) => {
  const uri = resp.raw.headers.get("Location");
  return uri.substring(uri.lastIndexOf('/') + 1);
});

// Create an Admin Portal link for the Organization
const portalLinkPromise = orgs.createPortalLink({realm: realm, orgId: orgId});
const portalLink = await portalLinkPromise.then((resp) => {
  return resp.link;
});

// Create and publish an Audit Event
const events = new EventsApi(configuration);
events.createEvent({realm: realm,
  eventRepresentation: {
    type: 'foo.bar',
    organizationId: orgId,
    time: Date.now(),
  }
});

Authentication

Browser

If you are using this in a browser with the official keycloak-js library, you can configure the Phase Two SDK using the access token from the Keycloak instance:

import { Keycloak } from "keycloak-js";

const keycloak = new Keycloak({ url: 'https://my-keycloak-host/auth/', realm: 'my-realm', clientId: 'my-app' });
// do your setup and login

const getAccessToken = () => keycloak.token;

// Configure the API connection
const configuration = new Configuration({
  basePath: 'https://my-keycloak-host/auth/realms',
  accessToken: getAccessToken,
});

Node.js

If you are using this in a server-side Node.js application, we recommend using an OpenID Connect library such as:

• keycloak-nodejs-admin-client The official Keycloak Node.js Admin library. Chances are, you will also be using this with the Phase Two SDK to manage Keycloak-native resources.
• node-openid-client A OpenID Certified™ Relying Party (OpenID Connect/OAuth 2.0 Client) implementation for Node.js. See their quickstart for examples of which flow you are using.

This example uses the Keycloak Node.js Admin library. See their usage documentation for more information on what type of flow you are using (the example is a password grant type):

import KcAdminClient from '@keycloak/keycloak-admin-client';

const kcAdminClient = new KcAdminClient();
await kcAdminClient.auth({
  clientId: 'admin',
  password: 'admin',
  grantType: 'password',
  clientId: 'admin-cli',
});

const getAccessToken = () => kcAdminClient.getAccessToken();

// Configure the API connection
const configuration = new Configuration({
  basePath: 'https://my-keycloak-host/auth/realms',
  accessToken: getAccessToken,
});

Developers

The sources are generated using the OpenAPI typescript-fetch generator.

The generator creates TypeScript/JavaScript client that utilizes Fetch API. The generated Node module can be used in the following environments:

Environment

• Node.js
• Webpack
• Browserify

Language level

• ES5 - you must have a Promises/A+ library installed
• ES6

Module system

• CommonJS
• ES6 module system

It can be used in both TypeScript and JavaScript. In TypeScript, the definition should be automatically resolved via package.json. (Reference)

Building

To build and compile the typescript sources to javascript use:

npm install
npm run build

Publishing

First build the package then run npm publish

Consuming

navigate to the folder of your consuming project and run one of the following commands.

published:

npm install p2-inc/js-sdk@VERSION --save

unPublished (not recommended):

npm install PATH_TO_GENERATED_PACKAGE --save

---

All documentation, source code and other files in this repository are Copyright 2022 Phase Two, Inc.