@workos-inc/node

What is @workos-inc/node?

@workos-inc/node is an SDK for integrating with WorkOS, a platform that provides enterprise-ready features such as Single Sign-On (SSO), Directory Sync, and Audit Logs. This package allows developers to easily integrate these features into their Node.js applications.

What are @workos-inc/node's main functionalities?

Single Sign-On (SSO)

This feature allows you to generate an SSO authorization URL for a specified provider, such as Google OAuth. The code sample demonstrates how to initialize the WorkOS client and generate an SSO URL.

const { WorkOS } = require('@workos-inc/node');
const workos = new WorkOS('your_api_key');

async function getSSOUrl() {
  const ssoUrl = await workos.sso.getAuthorizationURL({
    clientID: 'your_client_id',
    redirectURI: 'your_redirect_uri',
    state: 'optional_state',
    provider: 'GoogleOAuth'
  });
  console.log(ssoUrl);
}

getSSOUrl();

Directory Sync

This feature allows you to list all directories that have been synchronized with WorkOS. The code sample demonstrates how to initialize the WorkOS client and list the directories.

const { WorkOS } = require('@workos-inc/node');
const workos = new WorkOS('your_api_key');

async function listDirectories() {
  const directories = await workos.directorySync.listDirectories();
  console.log(directories);
}

listDirectories();

Audit Logs

This feature allows you to create an audit log event for tracking user actions. The code sample demonstrates how to initialize the WorkOS client and create an audit log event.

const { WorkOS } = require('@workos-inc/node');
const workos = new WorkOS('your_api_key');

async function createAuditLogEvent() {
  const event = await workos.auditLogs.createEvent({
    organization: 'your_organization_id',
    event: {
      action: 'user.login',
      occurred_at: new Date().toISOString(),
      actor: {
        id: 'user_id',
        type: 'user'
      },
      targets: [{
        id: 'target_id',
        type: 'user'
      }],
      context: {
        location: '127.0.0.1',
        user_agent: 'Mozilla/5.0'
      }
    }
  });
  console.log(event);
}

createAuditLogEvent();

Other packages similar to @workos-inc/node

passport

Passport is a popular authentication middleware for Node.js that supports various authentication strategies, including OAuth and SAML. Unlike @workos-inc/node, Passport focuses solely on authentication and does not provide additional enterprise features like Directory Sync or Audit Logs.

auth0

Auth0 is a comprehensive identity management platform that offers features like SSO, user management, and multifactor authentication. It is similar to @workos-inc/node in terms of providing enterprise-ready authentication solutions, but it also includes additional features like user management and multifactor authentication.

okta

Okta is an identity and access management service that provides SSO, multifactor authentication, and user management. It is similar to @workos-inc/node in offering enterprise authentication solutions but also includes extensive user management and security features.

README

workos-node

A WorkOS client for node applications in your organization to control and monitor the access of information within your organization.

Installation

You can install the WorkOS JS client in your local environment by running:

yarn add @workos-inc/node

Configuration

To use the client you must provide an API key located from the WorkOS dashboard either as an environment variable WORKOS_API_KEY:

WORKOS_API_KEY="sk_1234" ./app

Or you can set it on your own before your application starts:

import WorkOS from '@workos-inc/node';

const workos = new WorkOS('sk_1234');

Usage

Creating an Audit Trail event requires a descriptive action name and annotating the event with its CRUD identifier. The action name must contain an action category and an action name separated by a period, for example, user.login.

const event = {
  group: 'organization_1',
  action: 'user.login',
  action_type: 'C',
  actor_name: '[e-mail]',
  actor_id: 'user_1',
  target_name: '[e-mail]',
  target_id: 'user_1',
  location: '1.1.1.1',
  occurred_at: new Date(0),
};

workos.auditTrail.createEvent(event);

The resulting event being sent to WorkOS looks like:

{
  "group": "organization_1",
  "action": "user.login",
  "action_type": "C",
  "actor_name": "[e-mail]",
  "actor_id": "user_1",
  "target_name": "[e-mail]",
  "target_id": "user_1",
  "location": "1.1.1.1",
  "occurred_at": "2019-05-01T01:15:55.619355Z",
  "metadata": {}
}

All events are published to WorkOS asynchronously by default and support await / async behavior.

Adding Metadata To Events

Metadata provides additional context for your Audit Trail events that would be helpful to you or others in the future when looking at an Audit Trail event. Values for your metadata are expected to be primitive types:

• string
• boolean
• number
• Date

You're allowed to have maps with its elements being any one of the primitive types.

You can add metadata directly to events by appending the metadata property.:

const event = {
  group: 'user_1',
  action: 'tweet.update',
  action_type: 'U',
  actor_name: '[e-mail]',
  actor_id: 'user_1',
  target_name: '[e-mail]',
  target_id: 'tweet_5',
  location: '1.1.1.1',
  occurred_at: '2019-05-01T01:15:55.619355Z',
  metadata: {
    body_was: 'What time is the event',
    body: 'What time is the event?',
  },
};

workos.auditTrail.createEvent(event);

Resulting in the following being sent to WorkOS:

{
  "group": "user_1",
  "action": "tweet.update",
  "action_type": "U",
  "actor_name": "[e-mail]",
  "actor_id": "user_1",
  "target_name": "[e-mail]",
  "target_id": "tweet_5",
  "location": "1.1.1.1",
  "occurred_at": "2019-05-01T01:15:55.619355Z",
  "metadata": {
    "body_was": "What time is the event",
    "body": "What time is the event?"
  }
}

By adding supportive metadata when you create the event you can see what the original tweet body was and what the body was updated to. For something like a tweet that could get updated multiple times over the course of time, you can't always depend on the database representation to tell you what the body has always been. Without logging it right when the change occurs, you'll forever lose all the individual changes along the way. Good Audit Trail events attach all supporting information surrounding the event which could be used to inform the reader in the future what exactly happened, how it happened, and when it happened.