boxyhq/jackson

🔥 Streamline your web application's authentication with Jackson, an SSO service supporting SAML and OpenID Connect protocols. Beyond enterprise-grade Single Sign-On, it also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning. 🤩

SAML Jackson: Open Source Enterprise SSO And Directory Sync

SAML Jackson bridges or proxies a SAML login flow to OAuth 2.0 or OpenID Connect, abstracting away all the complexities of the SAML protocol. It also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning.

We now also support OpenID Connect providers.

Directory Sync

SAML Jackson also supports Directory Sync based on the SCIM 2.0 protocol.

Directory sync helps organizations automate the provisioning and de-provisioning of their users. As a result, it streamlines the user lifecycle management process by saving valuable organizational hours, creating a single truth source of the user identity data, and facilitating them to keep the data secure.

For complete documentation, visit boxyhq.com/docs/directory-sync/overview

🌟 Why star this repository?

If you find this project helpful, please consider supporting us by starring the repository and sharing it with others. This helps others find the project, grow the community and ensure the long-term health of the project. 🙏

• SAML Jackson: Open Source Enterprise SSO And Directory Sync
  • Directory Sync
  • 🌟 Why star this repository?
  • 🚀 Getting Started with SAML Jackson
    • Try A Demo
    • Deploying SAML Jackson as a separate service locally
      • Prerequisites
      • Clone the repository
      • Install dependencies
      • Setup environment variables
      • Database
      • Start the development server
    • Documentation
    • Easy Cloud Deployment
  • Videos
  • End-to-End (E2E) tests
  • About BoxyHQ
  • Security And Observability
    • Observability
    • SBOM Reports (Software Bill Of Materials)
    • Container Signing and Verification
    • 🛡️ Reporting Security Issues
  • Contributing
  • 💫 Support
  • 📌 License

🚀 Getting Started with SAML Jackson

There are two ways to integrate SAML Jackson into an application. Depending on your use case, you can choose either of them.

1. As a separate service (Next.js application) This includes an admin portal out of the box for managing SSO and Directory Sync connections.
2. NPM library as an embedded library in your application.

Try A Demo

• Try our hosted demo showcasing the SAML service provider (SP) initiated login flow here, which uses our Mock SAML IdP service.
• Try an Identity Provider (IdP) initiated login flow here.

Deploying SAML Jackson as a separate service locally

Let's get you to Hello SAML Jackson in no time.

Prerequisites

• Node.js at version 18.14.2 or higher

It is generally a good idea to install and maintain Node.js versions using a version manager like nvm or nvs on Windows. More information is available here.

Clone the repository

git clone https://github.com/boxyhq/jackson.git
cd jackson

Install dependencies

npm i

Setup environment variables

Create a .env from the existing .env.example file in the root of the project.

cp .env.example .env

Environment variable documentation: Have a look at https://boxyhq.com/docs/jackson/deploy/env-variables for all of the available environment variables.

Database

For the rest of the setup, we will use a PostgreSQL database. The easiest way to get PostgreSQL up and running on macOS is by using Postgres.app. You can download it from https://postgresapp.com/.

For other operating systems and alternative options for MacOS, please see the documentation available on the Prisma website.

Start the development server

Now that we have our database running we can start the development server. But before we do, we need a way to log into the admin portal.

To log in to the admin portal we either need to configure magic links, or enable username and password login. The easiest one, and the one we will use, is to enable username and password login.

In your .env find the NEXTAUTH_ADMIN_CREDENTIALS environment variable. We need to provide an email:password combination that we can then use to log in to the admin portal. For example:

[email protected]:password

Now we can start the development server:

npm run dev

Open http://localhost:5225 in your browser and you should be redirected to the login screen.

At the login screen, you can now use the username and password you set in the NEXTAUTH_ADMIN_CREDENTIALS environment variable to log in. Click "Sign In" and you should be logged in and see the SSO Connections page with no configured connections. We have reached Hello SAML Jackson!

Documentation

For the full documentation, visit boxyhq.com/docs/jackson/overview

Easy Cloud Deployment

Deploy SAML Jackson to the cloud with a single click using the following providers:

Videos

• SSO/OIDC Tutorial SAML Jackson Enterprise SSO (split into chapters to easily find what you are looking for)
• SAML single sign-on login demo

End-to-End (E2E) tests

Create a .env.test.local file and populate the values. To execute the tests run:

npm run test:e2e

About BoxyHQ

BoxyHQ is on a mission to democratize enterprise readiness for developers one building block at a time. We are building a suite of security building blocks that are easy to use and integrate into your applications. Our goal is to make being enterprise-ready accessible to all developers, founders, and those responsible for the security of their internal applications regardless of their security expertise.

Community is core to our mission. We are building a community of developers, security enthusiasts, and founders who are passionate about security and building secure applications. We are building in the open and would love for you to join us on this journey.

Join the community on Discord today.

Security And Observability

Observability

We support first-class observability on the back of OpenTelemetry, refer here for more details.

SBOM Reports (Software Bill Of Materials)

We support SBOM reports, refer here for more details.

Container Signing and Verification

We support container image verification using cosign, refer here for more details.

🛡️ Reporting Security Issues

Responsible Disclosure

Contributing

Thank you for your interest in contributing to SAML Jackson! We are excited to welcome contributions from the community. Please refer to our contributing guidelines for more information.

💫 Support

Reach out to the maintainers at one of the following places:

• GitHub Discussions
• GitHub Issues
• Discord

📌 License

Apache 2.0 License

jackson's Issues

Mock IdP SAML provider for testing

Is your proposal related to a problem?

We need a mock service that emulates a SAML Identity Provider. Prototyping has begun here - https://github.com/boxyhq/mock-saml

TypeORM does not reconnect properly if DB goes down

Use a standard HTTP response for the jackson service

Currently we send the response payload back as either json or plaintext. It would be better to standardise the format into JSON with defined structure for error and data. Eg:-
Error

{
 "status": 400 
 "error": {
  msg: "Please provide a defaultRedirectUrl" , 
  description: "Jackson needs the URL to complete the IdP flow"
 }
}

Success

{
"status": 200
"data": {
      client_id: clientID,
      client_secret: clientSecret,
      provider: idpMetadata.provider,
  }
}

Privacy preserving login

Is your proposal related to a problem?

In heavily regulated industries transfer or identification of employee information (even email) outside the boundary of the company leads to heavy compliance burden. If we provide a way to strip all info except the id then this opens up some interesting opportunities.

Describe the solution you'd like

• Document mapping of only the ID skipping everything else
• For any other info that might come via the SAML response we include a flag to strip that out
• Hash the id so it cannot be mapped back in any form, this also caters to the case where some providers send email as the id

SAML for Cal.com - https://github.com/calendso/calendso/pull/1192

OpenTelemetry support

Create an example with next.js and NextAuth.js

Decrease docker image size

Is your proposal related to a problem?

Decrease docker image size by using the new self-hosted feature in next.js

Describe the solution you'd like

https://nextjs.org/blog/next-12-1#self-hosted-nextjs-improvements

Sort css classes in jsx as part of code formatting

Is your proposal related to a problem?

We need to configure a plugin which automatically sorts the classes on save.

Describe the solution you'd like

prettier-plugin-tailwindcss can work well with tailwindcss classes.

Hasura auth with SAML Jackson

Is your proposal related to a problem?

Hasura has a plug-and-play auth interface, set up a demo showcasing auth with SAML.

Describe the solution you'd like

SAML Jackson + Hasura, what a mind-blowing combo.

Generate documentation and spec files for Swagger, Open API, Postman and Hoppscotch

Is your proposal related to a problem?

For our APIs it would be good to generate docs and spec files for the products listed above. Should ideally be in Github Actions if possible.

Deploy Jackson using docker-compose

• Easy to deploy
• Add production deployment guide

OpenTelemetry Tracing

Is your proposal related to a problem?

Add tracing via OpenTelemetry

Delete tokens after use

Read xml metadata from a url when setting the config

Is your proposal related to a problem?

Read XML metadata from a URL if available.

Describe the solution you'd like

We can divide this task into two subtasks:

• Make the required changes to /npm.
• Admin UI: Add an additional text input for Metadata URL to the create/update SSO connection UI. We'll do this after finishing the first one.

Make the required changes to /npm

• You can now create an SSO connection by passing an encoded or raw XML metadata to the createSAMLConnection method. Most of the identity providers also provide the URL to read the metadata. So createSAMLConnection should also allow passing a metadata URL if available.
• We have to add another attribute to the body called metadataUrl to pass the metadata URL.
• Make the required changes to the method createSAMLConnection within the /npm/src/controller/api.ts file.
• The new approach should fetch the raw metadata from the URL and use it as rawMetadata.
• Here are a few additional things you should consider during the implementation.
  • Only accept HTTPS URLs.
  • Set a timeout while fetching the data from the metadata URL and throw an error if the timeout exceeds.
  • Limit the payload size.
• Since no UI is involved, writing unit tests is the best way to test this implementation. You can create new unit test cases to address code changes you will make. You can find all the test cases in /npm/test/sso folder.
• Here is a sample metadata URL you can use to test https://mocksaml.com/api/saml/metadata

Provide a metadata file which will ease configuration with Identity Providers

Is your proposal related to a problem?

Some IdPs allow the uploading of a metadata file that will help populate all the fields when creating a SAML app.

Describe the solution you'd like

We should provide this metadata file with all the required fields at an endpoint so that the user can point their customers to it. This will ease the manual configuration of setting up the SAML app.

Move from express.js to next.js, express.js can be make into an example

Is your proposal related to a problem?

We'll need an admin interface in the future, next.js seems like a good fit.

Describe the solution you'd like

Move service to next.js, deployment is easier too and taps into the Vercel/next.js ecosystem.

Send requested tenant, product in the userinfo profile

Is your proposal related to a problem?

Send back the requested params like product, tenant, clientId and clientSecret in userinfo.

Admin interface for Jackson

Support for API gateways

Is your proposal related to a problem?

Support for API Gateways.

Describe the solution you'd like

We have simple API key auth support but should support the ability to add an API gateway in front. Kong, APISIX and Tyk are a few of the ones we should look at first.

Validate redirect_uri in all steps

Found a bug? Please fill out the sections below. 👍

Issue Summary

redirect_uri should be validated at all steps including code exchange - #26

SAML response user.id is undefined with Google SAML integration

Sample response

{
  audience: 'https://saml.boxyhq.com',
  claims: {
    'user.id': undefined,
    ...
  },
}

How can I use this with MySQL storage?

• What options should I pass?
• Should I create the table beforehand?

Any documentation about how to use this package?

Encode rawMetadata

Issue Summary

Certain gateways might reject the config API request because of rawMetadata, we need to encode it to avoid this.

Steps to Reproduce

Send a config API request to Jackson that is hosted on AWS.

Potential Solution

Add a new attribute, encodedRawMetadata which is a base64 encoding of rawMetadata. This will maintain backwards compatibility.

Supertokens.io integration enhancements

Is your proposal related to a problem?

• Provide tenant and product in userinfo as context or requested params. This will ease things on the frontend during integration - #113.
• Add a recipe to https://github.com/supertokens/supertokens-node which encapsulates the routes needed for SAML config.

Describe the solution you'd like

Improve developer experience by providing the above quality of service improvements.

SAML for Supabase.io, Supertokens, NocoDB, Appflowy

Add x509 data to AuthnRequest

Is your proposal related to a problem?

Currently, AuthnRequest is signed but there's no public cert being added to the signature. This means that the request is not being validated.

Describe the solution you'd like

Send the public cert along with AuthnRequest.

IdP metadata fetch: Swap POST with GET

Is your proposal related to a problem?

Currently, the POST method is used to fetch the IdP metadata. GET would be more apt for the operation.

Describe the solution you'd like

Swap out the POST method with GET and pass the body as a query string in the URL.
Also update the endpoint api/v1/saml/config/get -> /api/v1/saml/config

Support HTTP-POST as fallback (in case HTTP-Redirect is missing or not supported)

DigitalOcean 1-Click App

Fallback to a cookie session to retrieve RelayState if a SAML provider doesn't support RelayState

One click deploy button

Would be nice to have some one click deploy buttons for jackson

Admin UI pagination

Is your proposal related to a problem?

Paginate using offset and limit.

Monorepo for all our examples

Is your proposal related to a problem?

We are starting to have a list of growing examples and integrations. They should be moved to a monorepo, a new one called jackson-examples.

Describe the solution you'd like

Monorepo using Turborepo.

Create a software bill of materials (SBOM) for the project

Is your proposal related to a problem?

With the growing vulnerabilities in the software supply chain (like log4j) it makes a lot of sense to add an SBOM to our project.

Describe the solution you'd like

• We should support all 3 SBOM formats - https://www.settletop.com/insights/understanding-sbom-standards-cyclonedx-spdx-swid.
• We should automate updating of the SBOM when we add more dependencies
• We need it for our npm package, next.js service and docker container

Describe alternatives you've considered

n/a

Additional context

n/a

SAML strategy for remix-auth

Is your proposal related to a problem?

It would be nice to have a way to integrate SAML login with remix applications.

Describe the solution you'd like

Develop a strategy using https://github.com/sergiodxa/remix-auth-strategy-template.

Add Google Tag Manager

Move to TypeScript

Error reporting & Logging

Is your proposal related to a problem?

Support error reporting and logging.

Describe the solution you'd like

Opentelemetry has support for logging event. Pino for nodejs logging. For frontend if there is no library out there that consolidates this like Opentelemetry we should look to create one.

Add an env.example

IdP Config : support delete operation

Is your proposal related to a problem?

Currently, there is no way to delete an IdP config once it is saved in jackson.

Describe the solution you'd like

Expose a deleteConfig function in the API controller and use it in jackson/jackson-next services.

Add provider specific SAML documentation

Is your proposal related to a problem?

Test more SAML providers and add instructions for each provider.

Describe the solution you'd like

Okta, Google and Auth0 have been tested and supported so far. Test the following popular providers and document specific instructions - OneLogin, Duo, Azure, CyberArk, ADFS, JumpCloud, Shibboleth (not an exhaustive list).

Code Exchange: A token is created even if a wrong tenant/product is passed to the request.

curl --request POST \
  --url 'http://localhost:5000/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=<a invalid tenant and product combination>' \
  --data 'client_secret=<some value>' \
  --data 'redirect_uri=<redirect URL>' \
  --data 'code=<code from the query parameter above>'

Issue Summary

The token creation method doesn't evaluate the tenant and product is valid or not. It validates only the code at the moment.

Ensure we have proper OAuth 2.0 error handling (Reference - https://www.oauth.com/oauth2-servers/authorization/the-authorization-response/)

"SAML configuration not found." when using 'preLoadedConfig'

Issue Summary

Got the error "SAML configuration not found." when initiating the SAML request. Note, I'm using the pre-loaded SAML config options.

Steps to Reproduce

1. Created a new express app
2. Added the express routes as per the doc
3. Pre-loaded one Idp metadata (Create 2 files abc.js and abc.xml)
4. Added the correct pre-loaded config path (I can confirm Jackson could access the file)
5. Visited the following URL

http://localhost:3000/sso/oauth/authorize?response_type=code&provider=saml&client_id=abc&redirect_uri=http://localhost:3000/sso/oauth/completed&state=1234

Notes

I think oauth.authorize() method is not considering the preLoadedConfig

Support multiple SAML matches for a tenant + product combination

Pre loaded config import fails with webpack dynamic module parsing

Issue Summary

Using the PRE_LOADED_CONFIG fails to load the config js file.

config api error: Error: Cannot find module '/Users/xxxxx/Code/jackson/_config/boxyhq.js'

Steps to Reproduce

1. Run jackson with PRE_LOADED_CONFIG set to point to a local dir
2. Invoke the GET config
3. Requests fails with above error

Technical details

Summarized nicely at https://stackoverflow.com/a/42804941/3939061

You cannot use a variable as argument to require. Webpack needs to know what files to bundle at compile time. As it does no program flow analysis, it can't know what you pass to the function. In that case it might be obvious, but this could go as far as using user input to decide what module to require, and there is no way webpack can possibly know which modules to include at compile time, so webpack does not allow it.

Support ForceAuthn

Is your proposal related to a problem?

SAML support ForceAuthn to indicate to the provider that they should force an authentication of the user even if already logged in.

Describe the solution you'd like

We need to set a flag on the config and also maybe allow an override on the back of the OAuth 2.0 authorize request through a custom parameter.

Husky pre-commit hooks not running

Issue Summary

The husky pre-commit hook is not running now.

Steps to Reproduce

1. Change a variable declaration to use var instead of const
2. Stage and commit locally
3. Ideally the script runs and fixes the eslint issues.

Technical details

• git commit warning

hint: The '.husky/pre-commit' hook was ignored because it's not set as executable.
hint: You can disable this warning with `git config advice.ignoredHook false`.

• Missing a prepare script in package json to "To automatically have Git hooks enabled after install"
  https://typicode.github.io/husky/#/?id=manual