@okta/okta-sdk-nodejs

⚠️ This SDK is NOT intended for end user authentication flows. Please see the auth-js repo instead, it works for both browser and server (Node.js) applications.

• Release status
• Need help?
• Getting started
• Usage guide
• Configuration reference
• TypeScript usage
• Migrating between versions
• Building the SDK
• Contributing

• Create and update users with the Users API
• Add security factors to users with the Factors API
• Manage groups with the Groups API
• Manage applications with the Apps API
• Much more!

• Authentication SDK

Release status

Need help?

• Ask questions on the Okta Developer Forumsdevforum
• Post issuesgithub-issues here on GitHub (for code errors)

npm install @okta/okta-sdk-nodejs

Usage guide

const okta = require('@okta/okta-sdk-nodejs');

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc'    // Obtained from Developer Dashboard
});

OAuth 2.0 Authentication

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  authorizationMode: 'PrivateKey',
  clientId: '{oauth application ID}',
  scopes: ['okta.users.manage'],
  privateKey: '{JWK}', // <-- see notes below
  keyId: 'kidValue'
});

• As a JSON encoded string of a JWK object
• A string in PEM format
• As a JSON object, in JWK format

Note: in case OAuth client app uses multiple JWKs, privateKey should specify kid attribute. When privateKey is passed in PEM format, keyId value should be provided in SDK configuation.

Examples

* [Create a User](#create-a-user)
* [Get a User](#get-a-user)
* [Update a User](#update-a-user)
* [Delete a User](#delete-a-user)
* [List All Org Users](#list-all-org-users)
* [Search for Users](#search-for-users)

* [Create a Group](#create-a-group)
* [Assign a User to a Group](#assign-a-user-to-a-group)

* [Create an Application](#create-an-application)
* [Assign a User to an Application](#assign-a-user-to-an-application)
* [Assign a Group to an Application](#assign-a-group-to-an-application)

* [Get Logs](#get-logs)

• Collection

Users

Create a User

const newUser = {
  profile: {
    firstName: 'Foo',
    lastName: 'Bar',
    email: 'foo@example.com',
    login: 'foo@example.com'
  },
  credentials: {
    password: {
      value: 'PasswordAbc123'
    }
  }
};

const user = await client.userApi.createUser({ body: newUser });
console.log('Created user', user);

Get a User

let user;
user = await client.userApi.getUser({ userId: 'ausmvdt5xg8wRVI1d0g3' });
console.log(user);

user = await client.userApi.getUser({ userId: 'foo@bar.com' });
console.log(user);

Update a User

user.profile.nickName = 'rob';
await client.userApi.updateUser({
  userId: user.id,
  user: user
});

Delete a User

await client.userApi.deactivateUser({ userId: user.id });
await client.userApi.deleteUser({ userId: user.id });

List All Org Users

const collection = await client.userApi.listUsers();
await collection.each(user => {
  console.log(user);
});
console.log('All users have been listed');

const collection = await client.userApi.listUsers();
for await (let user of collection) {
  console.log(user);
}

Search for Users

let collection;
collection = await client.userApi.listUsers({
  q: 'Robert'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});


collection = await client.userApi.listUsers({
  search: 'profile.nickName eq "abc 1234"'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});

collection = await client.userApi.listUsers({
  filter: 'lastUpdated gt "2017-06-05T23:00:00.000Z"'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});

Groups

Create a Group

const newGroup = {
  profile: {
    name: 'Admin Users Group'
  }
};

const group = await client.groupApi.createGroup({ group: newGroup });
console.log('Created group', group);

Assign a User to a Group

await client.groupApi.assignUserToGroup({ groupId: group.id, userId: user.id });
console.log('User has been added to group');

Applications

Create An Application

const application = {
  name: 'template_basic_auth',
  label: 'Sample Basic Auth App',
  signOnMode: 'BASIC_AUTH',
  settings: {
    app: {
      url: 'https://example.com/auth.htm',
      authURL: 'https://example.com/login.html'
    }
  }
};

const createdApplication = await client.applicationApi.createApplication({ application });
console.log('Created application:', createdApplication);

Assign a User to an Application

const appUser = await client.applicationApi.assignUserToApplication({
  appId: createdApplication.id,
  appUser: {
    id: createdUser.id
  }
});
console.log('Assigned user to app, app user instance:', appUser);

Assign a Group to an Application

const assignment = await client.applicationApi.assignGroupToApplication({
  appId: createdApplication.id, 
  groupId: createdGroup.id, 
  applicationGroupAssignment: {}
});
console.log('Assignment:', assignment);

Sessions

Create a Session

const session = await client.sessionApi.createSession({
  createSessionRequest: {
    sessionToken: 'your session token'
  }
});
console.log('Session details:', session);

Get a Session

session = await client.sessionApi.getSession({
  sessionId: session.id
});
console.log('Session details:', session);

Refresh a Session

const refreshedSession = await client.sessionApi.refreshSession({
  sessionId: currentSession.id
});
console.log('Refreshed session expiration:', refreshedSession.expiresAt);

End a Session

await client.sessionApi.revokeSession({
  sessionId: session.id
});
console.log('Session ended');

End all Sessions for a User

await client.userApi.revokeUserSessions({
  userId: user.id
});
console.log('All user sessions have ended');

System Log

Get logs

const collection = await client.systemLogApi.listLogEvents({
  since: new Date('2018-01-25T00:00:00Z') 
});

const collection = await client.systemLogApi.listLogEvents({
  since: new Date('2018-01-24T23:00:00Z')
});

const subscription = collection.subscribe({
  interval: 5000, // Time in ms before fetching new logs when all existing logs are read
  next(logItem) {
    // Do something with the logItem
  },
  error(err) {
    // HTTP/Network Request errors are given here
    // The subscription will continue unless you call subscription.unsubscribe()
  },
  complete() {
    // Triggered when subscription.unsubscribe() is called
  }
});

Call other API Endpoints

const okta = require('@okta/okta-sdk-nodejs');

// Assumes configuration is loaded via yaml or environment variables
const client = new okta.Client();

// https://developer.okta.com/docs/reference/api/apps/#preview-saml-metadata-for-application
const applicationId = '{your custom SAML app id}';
const url = `${client.baseUrl}/api/v1/apps/${applicationId}/sso/saml/metadata`;
const request = {
  method: 'get',
  headers: {
    'Accept': 'application/xml',
    'Content-Type': 'application/json',
  }
};

client.http.http(url, request)
  .then(res => res.text())
  .then(text => {
    console.log(text);
  })
  .catch(err => {
    console.error(err);
  });

Collection

each()

Serial or Parallel Synchronous Work

const collection = await client.userApi.listUsers();
await collection.each(user => {
  console.log(user);
  logUserToRemoteSystem(user);
});
console.log('All users have been visited');

Serial Asynchronous Work

const collection = await client.userApi.listUsers();
await collection.each(user => {
  return new Promise((resolve, reject) => {
    // do work, then resolve or reject the promise
  });
});

Ending Iteration

const collection = await client.userApi.listUsers();
await collection.each(user => {
  console.log(user);
  return false;
});
console.log('Only one user was visited');

const collection = await client.userApi.listUsers();
await collection.each(user => {
  console.log(user);
  return Promise.resolve(false);
});
console.log('Only one user was visited');

const collection = await client.userApi.listUsers();
collection.each(user => {
  console.log(user);
  return Promise.reject('foo error');
})
.catch(err => {
  console.log(err); // 'foo error'
});

subscribe(config)

Simple subscription example

const subscription = collection.subscribe({
  interval: 5000,
  next(item) {
    console.log(item);
  },
  error(err) {
    // handle error
  }
});

// In the future, unsubscribe when you want to stop polling:
subscription.unsubscribe()

Configuration Reference

1. An okta.yaml file in ~/.okta.
2. An okta.yaml file in the current working directory of the node process.
3. Environment variables
4. Properties passed to the client constructor

okta:
  client:
    orgUrl: 'https://dev-1234.oktapreview.com/'
    token: 'xYzabc'

OKTA_CLIENT_ORGURL=https://dev-1234.oktapreview.com/
OKTA_CLIENT_TOKEN=xYzabc

Caching

Storage

const okta = require('@okta/okta-sdk-nodejs');
const MemoryStore = okta.MemoryStore;

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  cacheStore: new MemoryStore({
    keyLimit: 100000,
    expirationPoll: true
  })
});

• keyLimit - Max number of keys stored (default is 100000). The oldest keys are deleted as new keys are set.
• expirationPoll - The time, in milliseconds, between memory scans. If the value is true, a value of 15000 is used. (default is false, no scanning)

Custom Storage

class CustomStore {
  async get(stringKey) {}
  async set(stringKey, stringValue) {}
  async delete(stringKey) {}
}

Middleware

const okta = require('@okta/okta-sdk-nodejs');

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  cacheMiddleware: null
});

Custom Middleware

async function customMiddleware(ctx, next) {
  // do something before the request
  await next();
  // do something after the response
}

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  cacheMiddleware: customMiddleware
});

• req - An object containing details about the request:

const OK = 200;
async function customMiddleware(ctx, next) {
  const text = 'someText';
  ctx.res = {
    status: OK,
    text() { return Promise.resolve(text); }
  };
  await next(); // will skip external request
}

Built-In Retry

Note: in the next major version the default request executor will be automatically added to the client.

Manual Retry

Header parsing example

client.userApi.createUser()
  .catch(err => {
    if (err.status == 429) {
      const retryEpochMs = parseInt(err.headers.get('x-rate-limit-reset'), 10) * 1000;
      const retryDate = new Date(retryEpochMs);
      const nowDate = new Date(err.headers.get('date'));
      const delayMs = retryDate.getTime() - nowDate.getTime() + 1000;
      // Wait until delayMs has passed before retrying the request
    }
  });

Request Executor

Default Request Executor

• maxRetries - The number of times to retry, defaults to 2. Set to 0 if you do not want to limit the number of retries.
• requestTimeout - How long to wait before giving up on the request, regardless of how many retries are made. Defined in milliseconds and defaults to 0, which disables the request timeout.

const customDefaultRequestExecutor = new okta.DefaultRequestExecutor({
  maxRetries: 2,
  requestTimeout: 0 // Specify in milliseconds if needed
})

const client = new okta.Client({
  orgUrl: 'https://dev-1234.okta.com/',
  token: 'xYzabc',    // Obtained from Developer Dashboard
  requestExecutor: customDefaultRequestExecutor
});

defaultRequestExecutor.on('backoff', (request, response, requestId, delayMs) => {
  console.log(`Backoff ${delayMs} ${requestId}, ${request.url}`);
});

defaultRequestExecutor.on('resume', (request, requestId) => {
  console.log(`Resume ${requestId} ${request.url}`);
});

Base Request Executor

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc',    // Obtained from Developer Dashboard
  requestExecutor: new okta.RequestExecutor()
});

const client = new okta.Client({
  // uses the base executor by default
});

client.requestExecutor.on('request', (request) => {
  console.log(`Request ${request.url}`);
});

client.requestExecutor.on('response', (response) => {
  console.log(`Response ${response.status}`);
});

Building a Custom Request Executor

• Extend one of our executors.
• Create a class that implements the fetch method in the same way as RequestExecutor.

class DefaultExecutorWithLogging extends okta.DefaultRequestExecutor {
  fetch(request) {
    const start = new Date();
    console.log(`Begin request for ${request.url}`);
    return super.fetch(request).then(response => {
      const timeMs = new Date() - start;
      console.log(`Request complete for ${request.url} in ${timeMs}ms`);
      return response;
    });
  }
}

const client = new okta.Client({
  requestExecutor: new DefaultExecutorWithLogging()
})

Proxy

const okta = require('@okta/okta-sdk-nodejs');

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  httpsProxy: 'http://proxy.example.net:8080/'
});

User Agent

const okta = require('@okta/okta-sdk-nodejs');

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  userAgent: 'example/1.0'
});

TypeScript usage

4.5.x

import { Client } from '@okta/okta-sdk-nodejs'
import { LogEvent } from '@okta/okta-sdk-nodejs/src/types/models/LogEvent';
const client = new Client({
  orgUrl:'https://dev-org.okta.com',
  token: 'apiToken',
});
const logEvents = client.getLogs({
  since: '2021-03-11'
});
const actors: Set<string> = new Set();
logEvents.each((entry: LogEvent) => {
  actors.add(entry.actor.displayName);
}).then(() => {
  // res.send(JSON.stringify([...actors], null, 4));
};)

import { Application, ApplicationOptions } from '@okta/okta-sdk-nodejs/src/types/models/Application';
import { Client } from '@okta/okta-sdk-nodejs'
import { LogEvent } from '@okta/okta-sdk-nodejs/src/types/models/LogEvent';
const client = new Client({
  orgUrl:'https://dev-org.okta.com',
  token: 'apiToken',
});
const bookmarkAppOptions: ApplicationOptions = {
  "name": "bookmark",
  "label": "Sample Bookmark App",
  "signOnMode": "BOOKMARK",
  "settings": {
    "app": {
      "requestIntegration": false,
      "url": "https://example.com/bookmark.htm"
    }
  }
};
client.createApplication(bookmarkAppOptions).then((createdApp: Application) => {
  console.log(createdApp);
});

>=4.6.x

import { Client, LogEvent } from '@okta/okta-sdk-nodejs';

5.1.0

const oidcApp: OpenIdConnectApplication = client.getApplication<OpenIdConnectApplication>(appId);

const oidcApp: OpenIdConnectApplication = client.getApplication(appId);

const applicationOptions: ApplicationOptions = {
  name: 'bookmark',
  label: 'Bookmark app',
  signOnMode: 'BOOKMARK',
  settings: {
    app: {
      requestIntegration: false,
      url: 'https://example.com/bookmark.htm'
    }
  }
};
const application: BookmarkApplication = client.createApplication(applicationOptions);

7.x.x

const application: BookmarkApplication = {
  name: 'bookmark',
  label: 'Bookmark app',
  signOnMode: 'BOOKMARK',
  settings: {
    app: {
      requestIntegration: false,
      url: 'https://example.com/bookmark.htm'
    }
  }
};
const createdApplication: BookmarkApplication = await client.applicationApi.createApplication({
  application
});

const oidcApp: OpenIdConnectApplication = await client.applicationApi.getApplication({ appId });

Known Issues

const client: Client = new Client({
  orgUrl: 'https://orgname.okta.com',
  token: 'apiToken',
  defaultCacheMiddlewareResponseBufferSize: sizeInBytes
});

Note: this workaround should be used with caution as it relies on node-fetch's internal detail which can change its implementation.

Migrating between versions

From 6.x to 7.0

Breaking changes

- await client.getUser('ausmvdt5xg8wRVI1d0g3')
+ await client.userApi.getUser({ userId: 'ausmvdt5xg8wRVI1d0g3' })

- await user.deactivate()
+ await client.userApi.deactivateUser({ userId: user.id })

From 5.x to 6.0

Breaking changes

From 4.x to 5.0

Breaking changes

• AuthorizationServer

From 3.x to 4.0

• Add stands for newly added factories/models/client methods.
• Change (breaking changes) stands for renamed factories/models/client methods.
• Remove (breaking changes) stands for deprecated factories/models/client methods.

Main breaking changes

• Renamed Factor related factories/models/client methods to UserFactor
• Renamed client.sessionApi.endAllUserSessions to client.sessionApi.clearUserSessions
• Model and Client methods change for User related operations
• Model and Client methods change for Rule related operations

Building the SDK

• Obtain Open API v3 combined spec (management.yaml) and place it under spec dir
• run yarn build:openapi
• run yarn build

Contributing