SSOReady-Typescript

ssoready is a Typescript/Node.js SDK for the SSOReady API.

SSOReady is a set of open-source dev tools for implementing Enterprise SSO. You can use SSOReady to add SAML support to your product this afternoon, for free, forever. You can think of us as an open source alternative to products like Auth0 or WorkOS.

Reference

A full reference of the SDK is available here.

Installation

npm install --save ssoready
# or
yarn add ssoready

Usage

For full documentation, check out https://ssoready.com/docs.

At a super high level, all it takes to add SAML to your product is to:

1. Sign up on app.ssoready.com for free
2. From your login page, call getSamlRedirectUrl when you want a user to sign in with SAML
3. Your user gets redirected back to a callback page you choose, e.g. your-app.com/ssoready-callback?saml_access_code=.... You call redeemSamlAccessCode with the saml_access_code and log them in.

Import and construct a SSOReady client like this:

import { SSOReadyClient } from 'ssoready';

const ssoready = new SSOReadyClient({
  apiKey: "ssoready_sk_...", // Defaults to process.env.SSOREADY_API_KEY
});

Calling the getSamlRedirectUrl endpoint looks like this:

// this is how you implement a "Sign in with SSO" button
const { redirectUrl } = await ssoready.saml.getSamlRedirectUrl({
  // the ID of the organization/workspace/team (whatever you call it)
  // you want to log the user into
  organizationExternalId: "..."
});

// redirect the user to `redirectUrl`...

And using redeemSamlAccessCode looks like this:

// this goes in your handler for POST /ssoready-callback
const { email, organizationExternalId } = await ssoready.saml.redeemSamlAccessCode({
    samlAccessCode: "saml_access_code_..."
});

// log the user in as `email` inside `organizationExternalId`...

Check out the quickstart for the details spelled out more concretely. The whole point of SSOReady is to make enterprise SSO super obvious and easy.

Request and Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them under the SSOReady namespace:

import { SSOReady } from "ssoready";

const request: SSOReady.RedeemSamlAccessCodeRequest = {
  samlAccessCode: "saml_access_code_..."
};

Contributing

Issues and PRs are more than welcome. Be advised that this library is largely autogenerated from ssoready/fern-config. Most code changes ultimately need to be made there, not on this repo.