SSOReady-Typescript: SAML & SCIM for 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 and SCIM support to your product this afternoon.

For example applications built using SSOReady-TypeScript, check out:

- SSOReady Example App: Node + TypeScript + Express.js with SAML
- SSOReady Example App: Next.js + NextAuth

Reference

A full reference of the SDK is available here.

Installation

``bash
npm install --save ssoready


or


yarn add ssoready
`

Usage

This section provides a high-level overview of how SSOReady works, and how it's
possible to implement SAML and SCIM in just an afternoon. For a more thorough
introduction, visit the SAML
quickstart or the SCIM
quickstart.

The first thing you'll do is create a SSOReady client instance:

`ts
import { SSOReadyClient } from 'ssoready';

const ssoready = new SSOReadyClient(); // reads api key from env var SSOREADY_API_KEY
`

$3

SAML (aka "Enterprise SSO") consists of two steps: an _initiation_ step where
you redirect your users to their corporate identity provider, and a _handling_
step where you log them in once you know who they are.

To initiate logins, you'll use SSOReady's Get SAML Redirect
URL
endpoint:

`ts
// 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...
`

You can use whatever your preferred ID is for organizations (you might call them
"workspaces" or "teams") as your organizationExternalId. You configure those
IDs inside SSOReady, and SSOReady handles keeping track of that organization's
SAML and SCIM settings.

To handle logins, you'll use SSOReady's Redeem SAML Access
Code endpoint:

`ts
// 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...
`

You configure the URL for your /ssoready-callback endpoint in SSOReady.

$3

SCIM (aka "Enterprise directory sync") is basically a way for you to get a list
of your customer's employees offline.

To get a customer's employees, you'll use SSOReady's List SCIM
Users endpoint:

`ts
const { scimUsers, nextPageToken } = await ssoready.scim.listScimUsers({
organizationExternalId: "my_custom_external_id"
});

// create users from each scimUser
for (const { email, deleted, attributes } of scimUsers) {
// ...
}
`

Contributing

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