diff --git a/.env.example b/.env.example
index 4a1fe3943..2afa1b6c5 100644
--- a/.env.example
+++ b/.env.example
@@ -36,6 +36,7 @@ NEXTAUTH_ACL=
# Change this to your deployment public URL (https://next-auth.js.org/configuration/options#nextauth_url)
NEXTAUTH_URL=http://localhost:5225
# Change this to a real secret when deploying to production
+# You can use openssl to generate a secret key: openssl rand -base64 32
NEXTAUTH_SECRET=secret
# Admin credentials (In the format email:password. Comma separated values if you want multiple logins). Alternative to Magic Links.
NEXTAUTH_ADMIN_CREDENTIALS=
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7e0613091..32e3aa236 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,30 @@
# Contributing to Jackson
-We appreciate your interest in contributing to Jackson, and your contributions are integral to enhancing the project. Whether you are addressing a bug, implementing new features, or suggesting improvements, your involvement is highly valued and essential.
+We appreciate your interest in contributing to Jackson, and your contributions are integral to enhancing the project. Whether addressing a bug, implementing new features, or suggesting improvements, your involvement is highly valued and essential.
+
+- [Contributing to Jackson](#contributing-to-jackson)
+ - [Code Style](#code-style)
+ - [Getting Started](#getting-started)
+ - [1. Fork the Repository](#1-fork-the-repository)
+ - [2. Clone the Repository](#2-clone-the-repository)
+ - [3. Setup](#3-setup)
+ - [Contribution](#contribution)
+ - [Creating a New Branch](#creating-a-new-branch)
+ - [Staging Your Changes](#staging-your-changes)
+ - [Committing Your Changes](#committing-your-changes)
+ - [Pushing Your Changes](#pushing-your-changes)
+ - [Create a Pull Request](#create-a-pull-request)
+ - [Review and Feedback](#review-and-feedback)
+ - [Merging](#merging)
+ - [Celebrate!](#celebrate)
+ - [Bug Reports](#bug-reports)
+ - [Feature Requests](#feature-requests)
+ - [Testing](#testing)
+ - [Good First Issues](#good-first-issues)
+ - [Development](#development)
+ - [Code Of Conduct](#code-of-conduct)
+ - [License](#license)
+ - [Additional Tips](#additional-tips)
## Code Style
@@ -24,54 +48,26 @@ git clone https://github.com/your-username/jackson.git
### 3. Setup
-Navigate to the project folder and install the necessary dependencies:
-
-```shell
-cd jackson
-```
-
-#### Install Dependencies
-
-```shell
-npm install
-```
-
-#### Configure Environment Variables
-
-```shell
-cp .env.example .env
-npm run dev
-```
-
-Please update the .env file with your values. Refer to the complete list of [Environment Variables](https://boxyhq.com/docs/jackson/deploy/env-variables) for guidance.
-
-### 4. Build and Run
-
-Ensure that the project is prepared for development:
-
-```shell
-npm run build
-npm run start
-```
-
-Visit [http://localhost:5225](http://localhost:5225) in your browser. If you encounter a sign-in page, you've successfully reached the Admin Portal.
-
-For a comprehensive understanding of the deployment process, consult our documentation [here](https://boxyhq.com/docs/jackson/deploy/).
+See our [README](README.md) for instructions on setting up the project.
## Contribution
### Creating a New Branch
-Begin by creating a new branch where you will work on your changes. You can do this with the following command:
+Begin by creating a new branch where you will work on your changes. You should always aim to start by creating an issue that describes the problem you are solving or the feature you are implementing. This will help ensure that the maintainers are aware of your work and can provide feedback.
+
+Let's say that your issue title is "Support Custom Postgres Schema" and is issue number `#1818`. The ideal format for your branch name would be `1818-support-custom-postgres-schema`.
+
+You can create a new branch with the following command:
```shell
-git checkout -b your-branch-name
+git switch -c 1818-support-custom-postgres-schema
```
-Alternatively, you can create a branch using:
+For older versions of Git, use:
```shell
-git branch your-branch-name
+git checkout -b 1818-support-custom-postgres-schema
```
### Staging Your Changes
@@ -116,7 +112,7 @@ After submitting your pull request, maintainers and other contributors will revi
## Merging
-Once your pull request is approved, it will be merged into the main repository.
+Once your pull request is approved, it will be merged into the main branch of the project.
#### Celebrate!
@@ -155,7 +151,8 @@ Jackson is an open-source project released under the [Apache License 2.0](https:
## Additional Tips
-1. Be responsive to feedback from maintainers.
-2. Don't hesitate to seek help if needed in the discussion forum or any related platform.
+1. Be patient. Your contributions are important, and we will do our best to review them in a timely manner.
+2. Be responsive to feedback from maintainers.
+3. Don't hesitate to seek help if needed in the discussion forum or any related platform.
-#### Happy contributing!
+**Happy contributing!**
diff --git a/README.md b/README.md
index 10eecfb5b..7b87bb713 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,19 @@
-
-
-
-
-
-
-
+# SAML Jackson: Open Source Enterprise SSO And Directory Sync
-
+
+
+
+
+
+
+
+
-# ⭐️ SAML Jackson: Enterprise SSO made simple
+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.
-[]()
-[](https://heroku.com/deploy)
-
-## 🚀 Getting Started with SAML Jackson
-
-Please star ⭐ the repo to support us! 😀
-
-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.
-
-There are two ways to integrate SAML Jackson into an application. Depending on your use case, you can choose either of them.
-
-1. [separate service](https://boxyhq.com/docs/jackson/deploy/#as-a-separate-service) (Next.js application) Admin Portal out of the box for managing SSO and Directory Sync connections.
-2. [NPM library](https://boxyhq.com/docs/jackson/deploy/#as-a-separate-service) as an embedded library in your application.
-
-SAML/OIDC SSO service
-
-Jackson implements the SAML login flow as an OAuth 2.0 or OpenID Connect flow, abstracting away all the complexities of the SAML protocol. Integrate SAML with just a few lines of code. We also now support OpenID Connect providers.
-
-Try our hosted demo showcasing the SAML SP login flow [here](https://saml-demo.boxyhq.com), no SAML configuration required thanks to our [Mock SAML](https://mocksaml.com) service.
-
-## 🎦 Videos
-
-- SSO/OIDC Tutorial [SAML Jackson Enterprise SSO](https://www.youtube.com/watch?v=nvsD4-GQw4A) (split into chapters to easily find what you are looking for)
-- SAML single sign-on login [demo](https://www.youtube.com/watch?v=VBUznQwoEWU)
-
-## ✨ Demo
-
-- SAML IdP login flow showcasing self hosted [Mock SAML](https://mocksaml.com/saml/login)
-- SAML [demo flow](https://saml-demo.boxyhq.com/)
-
-## Here is what deploying SSO looks like with and without BoxyHQ
-
-
-
-
-
-
-
-
-
-## Documentation
-
-For full documentation, visit [boxyhq.com/docs/jackson/overview](https://boxyhq.com/docs/jackson/overview)
+
## Directory Sync
@@ -80,38 +23,126 @@ Directory sync helps organizations automate the provisioning and de-provisioning
For complete documentation, visit [boxyhq.com/docs/directory-sync/overview](https://boxyhq.com/docs/directory-sync/overview)
-## Observability
+## 🌟 Why star this repository?
-We support first-class observability on the back of OpenTelemetry, refer [here](https://boxyhq.com/docs/jackson/observability) for more details.
+If you find this project helpful, please consider supporting us by starring [the repository](https://github.com/boxyhq/jackson) and sharing it with others. This helps others find the project, grow the community and ensure the long-term health of the project. 🙏
-## SBOM Reports (Software Bill Of Materials)
+- [SAML Jackson: Open Source Enterprise SSO And Directory Sync](#saml-jackson-open-source-enterprise-sso-and-directory-sync)
+ - [Directory Sync](#directory-sync)
+ - [🌟 Why star this repository?](#-why-star-this-repository)
+ - [🚀 Getting Started with SAML Jackson](#-getting-started-with-saml-jackson)
+ - [Try A Demo](#try-a-demo)
+ - [Deploying SAML Jackson as a separate service locally](#deploying-saml-jackson-as-a-separate-service-locally)
+ - [Prerequisites](#prerequisites)
+ - [Clone the repository](#clone-the-repository)
+ - [Install dependencies](#install-dependencies)
+ - [Setup environment variables](#setup-environment-variables)
+ - [Database](#database)
+ - [Start the development server](#start-the-development-server)
+ - [Documentation](#documentation)
+ - [Easy Cloud Deployment](#easy-cloud-deployment)
+ - [Videos](#videos)
+ - [End-to-End (E2E) tests](#end-to-end-e2e-tests)
+ - [About BoxyHQ](#about-boxyhq)
+ - [Security And Observability](#security-and-observability)
+ - [Observability](#observability)
+ - [SBOM Reports (Software Bill Of Materials)](#sbom-reports-software-bill-of-materials)
+ - [Container Signing and Verification](#container-signing-and-verification)
+ - [🛡️ Reporting Security Issues](#️-reporting-security-issues)
+ - [Contributing](#contributing)
+ - [💫 Support](#-support)
+ - [📌 License](#-license)
-We support SBOM reports, refer [here](https://boxyhq.com/docs/jackson/sbom) for more details.
+## 🚀 Getting Started with SAML Jackson
-## Container Signing and Verification
+There are two ways to integrate SAML Jackson into an application. Depending on your use case, you can choose either of them.
-We support container image verification using cosign, refer [here](https://boxyhq.com/docs/jackson/container-signing) for more details.
+1. [As a separate service](https://boxyhq.com/docs/jackson/deploy/service) ([Next.js](https://nextjs.org/) application) This includes an admin portal out of the box for managing SSO and Directory Sync connections.
+2. [NPM library](https://boxyhq.com/docs/jackson/deploy/npm-library) as an embedded library in your application.
-### Development Setup
+### Try A Demo
+
+- Try our hosted demo showcasing the SAML service provider (SP) initiated [login flow here](https://saml-demo.boxyhq.com), which uses our [Mock SAML](https://mocksaml.com) IdP service.
+- Try an Identity Provider (IdP) initiated [login flow here](https://mocksaml.com/saml/login).
+
+### Deploying SAML Jackson as a separate service locally
+
+Let's get you to Hello SAML Jackson in no time.
+
+#### Prerequisites
+
+- [Node.js](https://nodejs.org/en) 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](https://github.com/nvm-sh/nvm) or [nvs](https://github.com/jasongin/nvs) on Windows. More [information is available here](https://schalkneethling.com/posts/installing-node-and-managing-versions).
+
+#### Clone the repository
+
+```bash
+git clone https://github.com/boxyhq/jackson.git
+cd jackson
+```
+
+#### Install dependencies
+
+```bash
+npm i
+```
+
+#### Setup environment variables
+
+Create a `.env` from the existing `.env.example` file in the root of the project.
+
+```bash
+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
-To get up and running, we have a [docker-compose setup](_dev/docker-compose.yml) that will spawn all the supported databases. Ensure that the docker daemon is running on your machine and then run: `npm run dev-dbs`. In case you need a fresh start, destroy the docker containers using: `npm run dev-dbs-destroy` and run: `npm run dev-dbs`.
+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/](https://postgresapp.com/).
-#### Development server
+> For other operating systems and alternative options for MacOS, please see the [documentation available on the Prisma website](https://www.prisma.io/dataguide/postgresql/setting-up-a-local-postgresql-database).
-Copy the `.env.example` to `.env.local` and populate the values. Have a look at https://boxyhq.com/docs/jackson/deploy/env-variables for the available environment variables.
+#### Start the development server
-Run the dev 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.
-```zsh
-# Install the packages
-npm install
-# Start the server
+To log in to the admin portal we either need to [configure magic links](https://boxyhq.com/docs/admin-portal/overview#1-magic-links), or [enable username and password](https://boxyhq.com/docs/admin-portal/overview#2-email-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:
+
+```bash
+NEXTAUTH_ADMIN_CREDENTIALS=admin@example.com:password
+```
+
+Now we can start the development server:
+
+```bash
npm run dev
```
-#### End-to-End (E2E) tests
+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](https://boxyhq.com/docs/jackson/overview)
+
+### Easy Cloud Deployment
+
+Deploy SAML Jackson to the cloud with a single click using the following providers:
+
+[]()
+[](https://heroku.com/deploy)
+
+## Videos
+
+- SSO/OIDC Tutorial [SAML Jackson Enterprise SSO](https://www.youtube.com/watch?v=nvsD4-GQw4A) (split into chapters to easily find what you are looking for)
+- SAML single sign-on login [demo](https://www.youtube.com/watch?v=VBUznQwoEWU)
+
+## End-to-End (E2E) tests
Create a `.env.test.local` file and populate the values. To execute the tests run:
@@ -119,33 +150,56 @@ Create a `.env.test.local` file and populate the values. To execute the tests ru
npm run test:e2e
```
-## 🖳 Contributing
+## About BoxyHQ
-Thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody and are appreciated.
+
+
+
+
+
+
+
-Please try to create bug reports that are:
+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.
-- _Reproducible._ Include steps to reproduce the problem.
-- _Specific._ Include as much detail as possible: which version, what environment, etc.
-- _Unique._ Do not duplicate existing opened issues.
-- _Scoped to a Single Bug._ One bug per report.
+
+
+
+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](https://boxyhq.com/docs/jackson/observability) for more details.
+
+### SBOM Reports (Software Bill Of Materials)
+
+We support SBOM reports, refer [here](https://boxyhq.com/docs/jackson/sbom) for more details.
+
+### Container Signing and Verification
+
+We support container image verification using cosign, refer [here](https://boxyhq.com/docs/jackson/container-signing) for more details.
+
+### 🛡️ Reporting Security Issues
+
+[Responsible Disclosure](SECURITY.md)
+
+## 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](CONTRIBUTING.md) for more information.
## 💫 Support
Reach out to the maintainers at one of the following places:
- [GitHub Discussions](https://github.com/boxyhq/jackson/discussions)
-- [GitHub Issues](https://github.com/boxyhq/jackson/issues) (Bug reports, Contributions)
-
-## 🤩 Community
-
-- [Discord](https://discord.gg/uyb7pYt4Pa) (For live discussion with the Open-Source Community and BoxyHQ team)
-- [Twitter](https://twitter.com/BoxyHQ) (Follow us)
-- [Youtube](https://www.youtube.com/@boxyhq) (Watch community events and tutorials)
-
-## 🛡️ Reporting Security Issues
-
-[Responsible Disclosure](SECURITY.md)
+- [GitHub Issues](https://github.com/boxyhq/jackson/issues)
+- [Discord](https://discord.gg/uyb7pYt4Pa)
## 📌 License
diff --git a/samljackson480.gif b/samljackson480.gif
new file mode 100644
index 000000000..e23ce4a8b
Binary files /dev/null and b/samljackson480.gif differ
+
+
+
+
+
+
-# ⭐️ SAML Jackson: Enterprise SSO made simple
+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.
-
