快速开始
-帮助用户快速注册使用平台[5个文档]
-SAML Config
+Add SAML Metadata.
+ + + +``` + +Now let's add another route `POST /config` that will store the form data by calling the SAML Jackson config API. + +This step is the equivalent of setting an OAuth 2.0 app and generating a client ID and client secret that will be used in the login flow. + +```javascript +// routes/index.js + +router.post('/config', async (req, res, next) => { + const { rawMetadata, tenant, product } = req.body; + + const defaultRedirectUrl = 'http://localhost:3000/sso/callback'; + const redirectUrl = '["http://localhost:3000/*"]'; + + try { + await apiController.config({ + rawMetadata, + tenant, + product, + defaultRedirectUrl, + redirectUrl, + }); + + res.redirect('/config'); + } catch (err) { + next(err); + } +}); +``` + +There are a few important things to note in the code above. + +`defaultRedirectUrl` holds the redirect URL to use in the IdP login flow. Jackson will call this URL after completing an IdP login flow. + +`redirectUrl` holds an array containing a list of allowed redirect URLs. Jackson will disallow any redirects that are not on this list. + +Next, let's start the express app. The app starts a server and listens on port 3000 (by default) for connections. + +```bash +npm start +``` + +Now, let's visit [http://localhost:3000/config](http://localhost:3000/config), you should see the page with a form. + + + +Here you can add the metadata you've downloaded from Auth0. Fill out the form with a Tenant, Product, and paste the metadata XML content as it is. + +I'll use 'boxyhq.com' for tenant and 'crm' for product. + +The response returns a JSON with `client_id` and `client_secret` that can be stored against your tenant and product for a more secure OAuth 2.0 flow. + +If you do not want to store the `client_id` and `client_secret` you can alternatively use `client_id=tenant=Dashboard
+Only authenticated users should access this page.
+ +Id - <%= profile.id %>
+Email - <%= profile.email %>
+ + +``` + +From the command line, let's restart the express app then visit the authorize the URL [http://localhost:3000/sso/authorize](http://localhost:3000/sso/authorize). + +If you've configured everything okay, it should redirect you to the Auth0 authentication page, then click on the Sign up link and register there + +If the authentication is successful, the app will redirect you to the dashboard and display the `id`, `email` of the user. + + + +## Conclusion + +Congratulations, you should now have a functioning SAML SSO integrated with your express.js app using the SAML Jackson and Auth0. + +## References + +To learn more about SAML Jackson, take a look at the following resources: + +- [SAML Jackson Documentation](https://boxyhq.com/docs/jackson/overview) +- [SAML Jackson GitHub](https://github.com/boxyhq/jackson) +- [Express web app that shows how to use SAML Jackson](https://github.com/boxyhq/jackson-examples/tree/main/apps/express) + +Your feedback and contributions are welcome! diff --git a/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-solution-providers-side.md b/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-solution-providers-side.md new file mode 100644 index 0000000..3739689 --- /dev/null +++ b/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-solution-providers-side.md @@ -0,0 +1,28 @@ +--- +slug: understanding-saml-sso-the-basics-from-the-solution-providers-side +title: Understanding SAML SSO, the basics from the solution provider's side +author: Jay Singh +author_title: Marketing Consultant +author_url: https://www.linkedin.com/in/jaydsingh/ +author_image_url: https://boxyhq.com/img/team/jay.jpg +tags_disabled: [enterprise-readiness, saml, saml-jackson, sso, single-sign on] +image: img/blog/sso/with-boxyhq.png +--- + +This article follows my first article in which I explain the basics of SAML from the users' side. If you haven't read that one already I would recommend reading that one first [here](./2022-06-30-understanding-saml-sso-the-basics-from-the-user-side.md). In this article, we are going to take a look at what SAML authentication and setup look like from the solution providers' perspective. + +If you are a B2B solutions provider and you plan to have enterprise customers they will likely ask that your product supports SAML SSO. This is because the customer will already be using an IDP to manage user access and security to their services. Anything outside this will be a risk and not fit into their user's workflows. + +Most larger solution providers have already invested a lot of time and money into building SAML integrations with IDP providers but this leaves smaller competitors with less time and resources at a disadvantage as they often haven't been able to prioritize enterprise security features over the core product build. + +The main reason why smaller companies don’t implement SAML as part of the standard build is that it traditionally takes a long time as they have to build a custom integration with each IDP provider their customers use. Well, this is now an old issue because we have created BoxyHQ which allows you to connect to our free product with one single integration that then connects to all the IDPs for you! Let's take a look at what the integrations with and without BoxyHQ look like first. + + + +In the diagram above we can see what it looks like when you build a custom SAML integration with each IDP. As you can see for each IDP you have to connect all the instances of your product and build a unique integration. This can take months and take the focus away from your team building your core product. We believe that enterprise readiness should be accessible and easy for businesses of all sizes so we built BoxyHQ. Let's see what that looks like. + + + +As you can see from the image above with BoxyHQ you only have to connect your product with a straightforward integration to BoxyHQ and then we manage and connect you to all the IDPs! It is that simple and you can deploy SAML SSO for your clients in as little as 8 days. We are also open source and free so you don't need to worry about big maintenance bills, we will even offer you custom support during the integration. + +If you are interested in becoming enterprise-ready without the hassle then let's chat! You can [book](https://meetings.hubspot.com/deepakprab/demo) a free consultation call and chat with our CEO about how we can help. Let's start the journey together. diff --git a/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-user-side.md b/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-user-side.md new file mode 100644 index 0000000..67273ce --- /dev/null +++ b/blog/2022-06-30-understanding-saml-sso-the-basics-from-the-user-side.md @@ -0,0 +1,47 @@ +--- +slug: understanding-saml-sso-the-basics-from-the-user-side +title: Understanding SAML SSO, the basics from the user side +author: Jay Singh +author_title: Marketing Consultant +author_url: https://www.linkedin.com/in/jaydsingh/ +author_image_url: https://boxyhq.com/img/team/jay.jpg +tags_disabled: [enterprise-readiness, saml, saml-jackson, sso, single-sign on] +image: img/blog/sso/with-saml.png +--- + +I have always worked in tech, so have always needed to understand the technical nature of the products we are building. This process has always been over-complicated for me so I now always try to write a guide for non-technical people like me. It turns out that once you understand it you can explain it to other non-technical people much easier! So here we go as I try to explain SAML (Security Assertion Markup Language) SSO (single sign-on) and why BoxyHQ makes it so easy to implement. Firstly you have probably heard of not only SAML but OAuth 2.0 and OIDC, these are all protocols that achieve the same result of providing SSO. There are a few nuances but those are out of scope for this article to keep things simple. + +Let's start with what SAML SSO is and what it does. An example of SAML SSO in action would be a user in your company signs into a single dashboard and inside that dashboard, they have all the icons for the external services they use such as their CRM (Hubspot) and accounting software (Xero). The user can now just log in to any of their services by clicking on them rather than logging into each one individually. + +But how does this work? Well, the idea behind SAML SSO is that by centralizing your access to an external system you can better manage access and permission as well as improve security. So in our example, the dashboard that allowed the user to just click an icon and log in was SAML in action. Because the company has connected to its external servicing using SAML it can now let its users access all the services from a single point. This single point of access is known as the IdP (Identity Provider) which authenticates the access to all the other services via SAML. + +The diagrams below show how this access flow would work with and without SAML: + + +In the diagram above we can see that the company is not using SAML so the user has to log into each of the services with an individual username and password. The username and password are managed by the service provider and access is also managed via an admin user on the service provider's side. The user must be given access to each of the services from each of the services and remember the login details for each one. + + + +In the image above we can see that the company is using an IdP such as Okta so the user simply has to log in once and then can access all the external services from a single dashboard. This also means that the company admins can manage access to the different services as they control the access directly from their IdP. + +Now, remember that this is just a high-level overview of SAML and the technical aspects behind the scenes can get a lot more complicated. + +We have been looking at SAML from a company user's perspective but it's also important to remember that these service providers also have to build a SAML integration to enable them to connect to their clients’ IdPs. This can be a very long and time-consuming process for service providers and this is where BoxyHQ comes in. Instead of service providers building a custom integration for each IdP their customers use which can take months, the service providers can use BoxyHQ and have all the connections to IdPs they need with a single integration! You can be SAML-ready in as little as 8 days! To understand how this looks check out my other blog [here](./2022-06-30-understanding-saml-sso-the-basics-from-the-solution-providers-side.md). + +So what are the main benefits of SAML? Here are three of the most important ones I have identified. + +#### Increased Security + +SAML is at its heart a security standard and as it provides a single point of authentication that takes place in a secure environment it adds an extra layer of security to your service that most enterprise customers will ask for. + +#### Improved user experience + +As a user using SAML is very simple and pleasant to use as you only have to log in once and then you can access all your external services on a dashboard with a single click. This saves the user time and makes their overall experience of your product better. + +#### Reduces cost + +Without SAML you have to maintain account information across multiple services but when you use SAML this is all managed by the IdP. + +BoxyHQ is open source and our SAML SSO product, SAML Jackson is just the first product we have built to help companies become enterprise-ready. If you are interested in discussing your authentication strategy or deploying SAML SSO you can book a call with our CEO [here](https://meetings.hubspot.com/deepakprab/demo) to discuss how we can support you. + +I hope you have found this high-level explanation of SAML and its use cases helpful. If you have any questions please don't hesitate to reach out to us on our live chat on our website https://boxyhq.com/ diff --git a/blog/2022-07-19-three-reasons-not-to-build-enterprise-features.md b/blog/2022-07-19-three-reasons-not-to-build-enterprise-features.md new file mode 100644 index 0000000..4bcedcd --- /dev/null +++ b/blog/2022-07-19-three-reasons-not-to-build-enterprise-features.md @@ -0,0 +1,45 @@ +--- +slug: three-reasons-not-to-build-enterprise-features +title: 'Be enterprise-ready: Three reasons not to build enterprise features!' +author: Sama - Carlos Samame +author_title: Co-founder & COO @BoxyHQ +author_url: https://www.linkedin.com/in/samame/ +author_image_url: https://boxyhq.com/img/team/sama.jpg +tags_disabled: + [enterprise-readiness, startups, enterprises, corporates, sales, founder] +image: /img/blog/dontbuild/security-risks-meme.jpeg +--- + +If you are thinking about building features to be enterprise-ready, there are typically two paths that brought you here: + +1. Your team has initially focused on smaller customers and is now looking to expand, or +2. Your team is building a new product and targeting enterprise customers from day 1 + +Either way, you need to be aware that selling to enterprises is super exciting, especially if you like to play golf and you are ok with a long sales cycle - it could easily take you up to three years to close a deal. + +Enterprises can be scared to give startups a chance and startups often lose out to more established businesses. However, there are two great ways to make sure your business doesn't miss out: + +- List of other enterprise customers (“show me more logos, we are not a guinea pig”) +- Compliance requirements (“a checklist to show my boss you are safe”) + + + +But what is enterprise readiness? From a product perspective, [EnterpriseReady.io](https://www.enterpriseready.io) identified common features that set enterprise software apart. You can do a free self-assessment [here](https://www.enterprisegrade.io/). The basics mean that your business meets the standards that enterprises look for in solution providers. + +Now, the good news is that to be enterprise-ready you don’t need to build these common undifferentiated features which can drain your resources and bank account. Here is why: + +1. Customer Obsession – You need to forget about product development and narrow your attention to customer development. You need to talk to potential enterprise customers and understand their current needs, pains, motivations, processes, etc. Remember that they’ve got plenty of software they already depend on that will need to work smoothly with yours. On top of learning how to navigate the enterprise, you need to identify Infosec barriers and consider how to mitigate them; if your solution needs to process internal data, things will be more complex. + +2. Time to market – Instead of spending months building in-house enterprise-grade features, there are off-the-shelf enterprise readiness solutions that you can integrate into your SaaS app with just a few lines of code. There is no need to wait months to build Single Sign-On (SSO), Directory Sync, Audit Logs, Privacy Vault, and other boring stuff that enterprises ask for anymore, now you could plug them within hours. And your team can spend more time building your core product instead of non-core features that won’t add value to your customers’ main needs. + +3. Cut engineering costs – Out-of-the-box solutions will help your company save developers time. If you consider the learning curve, coding, fixing bugs, and all the hassle that your tech team needs to go through, you will realize that people’s time is more expensive than developer tools. And the good news is that there are reliable open source solutions that you could use at no cost. Free and trustworthy? That’s the beauty of open source communities. Self-hosting these solutions will allow your company to maintain a level of control that will simplify things if you need to be certified (SOC2, ISO 27001, HIPAA, etc). + +Here are 3 open-source solutions that could be interesting for you - BoxyHQ (**disclaimer, I'm a Co-Founder here**), [Supertokens](https://supertokens.com), and [Oso](https://www.osohq.com). There are plenty of other solutions that are relevant, we are building a list and would love to learn about other projects you use, please share them with me. + +Let’s be sincere, will your engineers focus on building the best SAML SSO feature or will they just focus on checking the box? Compliance security could be expensive in the long term when working with large enterprises. Especially if things go wrong because being compliant doesn’t mean your SaaS app is unhackable. + +Remember that not all enterprises are the same. But working with a few design partners will help your team to define an efficient product roadmap, build a robust go-to-market strategy, and you will close more enterprise deals. + +Deals, deals, deals! + +If you know anyone that needs to build enterprise features we would love to hear from them and see how could we help, please feel free to share my email: sama@boxyhq.com - Thank you! diff --git a/blog/2022-07-26-developer-first-security-sucks-automate-product-security.md b/blog/2022-07-26-developer-first-security-sucks-automate-product-security.md new file mode 100644 index 0000000..b855e93 --- /dev/null +++ b/blog/2022-07-26-developer-first-security-sucks-automate-product-security.md @@ -0,0 +1,55 @@ +--- +slug: developer-first-security-sucks-automate-product-security +title: 'Developer-first Security sucks! Why is it essential to automate product security?' +author: Sama - Carlos Samame +author_title: Co-founder & COO @BoxyHQ +author_url: https://www.linkedin.com/in/samame/ +author_image_url: https://boxyhq.com/img/team/sama.jpg +tags_disabled: [developer, security, cybersecurity, devsecops, appsec] +image: /img/blog/security-sucks-meme.jpeg +--- + +Let’s start with some facts to understand why it sucks! + +On one hand: + +- Cybercrime went up 600% due to the COVID-19 Pandemic +- Data breaches and cyber attacks in 2021 were 5.1 billion breached records, this is 11% more than in 2020 +- 79% of companies have experienced at least one cloud data breach in the past 18 months +- Software supply chain attacks jumped over 300% in 2021 +- It is estimated that worldwide, cyber crimes will cost $10.5 trillion annually by 2025. + +(Data from Purplesec, IT Governance, VentureBeat) + +On the other hand: + +- 70% of development teams always or frequently skip security steps due to time pressures when completing projects +- Almost 60% of devs are releasing code 2x faster, thanks to DevOps. +- In 2021, only 20% of organizations have fully integrated security into the development +- Security has low priority. 67% of developers surveyed by Secure Code Warrior admitted that they routinely left known vulnerabilities and exploits in their code +- Github expects the number of software developers using its platform (56 million in 2020), to grow to 100 million developers in 2025 + +(Invicti Security, Gitlab, GitHub, VentureBeat) + +**Security vs Developers** + +Security teams focus on planning secure IT environments, but developers are asked to focus on productivity while they are also tasked with implementing these security plans. The main issue is that developers are often left out of security planning processes, creating a strained relationship between these two teams. + +It is important to build a healthy relationship where trust, communication, and collaboration are key to moving toward the organization’s north star. But traditional security teams sometimes see themselves as inspectors of the developer's work. And that attitude needs to change - “when you’re a hammer, everything is a nail”. + +Did you know that in “Gartner's Top Strategic Technology Trends for 2022: Cybersecurity Mesh”, the word "developer" is not included not even once? We were shocked about it; developers need to have a leading role in cybersecurity! + +**It’s “Shift Left Security” time!** + +With shift left security we mean moving security sooner in the development process. +Teams should provide developers with the right tools to do their job securely; this is why it is essential to automate product security. + +But most of the new security solutions are focused on selling to the CISOs and their security teams, maybe because they are the ones with the budget for “security”; but what about developers? Most of their new solutions are oriented toward productivity, which makes sense since we live in an agile world, but what if there were new developer-first security solutions? Well, it is about time; a recent survey from Forrester shows that last year 27% of organizations had their development teams holding the budget for application security tools and that number has increased to 37% this year. + +**Developer-first security Tools** + +While some security tools for developers have started to appear, it is still early days. The ecosystem needs solutions to automate security for developers and most importantly, that is reliable. Our hypothesis is that the most important products will come from the open-source community; they have a genuine interest in supporting and empowering developers. + +We are consolidating a list of reliable open source developer-first security tools for security, if you know of a project we should consider, or if you would like to have access to this list, please send me an email: sama@boxyhq.com or/and help us spread the word! 🙌 + + diff --git a/blog/2022-09-09-understanding-directory-sync.md b/blog/2022-09-09-understanding-directory-sync.md new file mode 100644 index 0000000..89bdbc2 --- /dev/null +++ b/blog/2022-09-09-understanding-directory-sync.md @@ -0,0 +1,87 @@ +--- +slug: understanding-scim-and-directory-sync +title: Understanding SCIM and Directory Sync +author: Kiran K +author_title: Senior Developer @BoxyHQ +author_url: https://twitter.com/tokirankrishnan +author_image_url: https://boxyhq.com/img/team/kiran.jpg +tags_disabled: + [enterprise-readiness, engineering, saml-jackson, directory-sync, scim] +image: /img/blog/directory-sync-flow.png +--- + +This article will walk you through everything you should know about SCIM and Directory Sync. + +## What is SCIM? + +System for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning (Directory Sync). + +SCIM facilitates user identity data communication between Identity Providers (Okta, OneLogin, etc.) and Service Providers (Enterprise SaaS apps). + +## Why should you care about SCIM? + +Many companies manually onboard and offboard users, which consumes many IT resources and time. + +User lifecycle management (ULM) begins when employees start their job and continue until they leave the company. ULM is all about provisioning and de-provisioning users when they join an organization. + +For IT departments, this means creating an account for the new employees in the cloud apps they need to use after starting their job. Also, IT departments must ensure that when those employees leave, they revoke access to those accounts. + +Smaller organizations might address these procedures manually, but the process can become error-prone and time-consuming when done at scale. This is where the SCIM and Directory Sync come to the organization's rescue. + +## What is Directory Sync? + +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. + +## How does the Directory Sync work? + +Directory sync allows programmatic access to the user identity data via a standard protocol (SCIM). + +Directory sync implementation typically involves a client and a server. A client is an identity provider (IDP) with a directory of user identities. A service provider (SP) is an enterprise SaaS app that needs a subset of data from those identities. + +When you make changes to the user identities, the changes are automatically synced to the SP according to the SCIM protocol. SP can now process this data according to the way they want. + +Some common user identity changes include adding new users to the organization, updating existing users, removing users from the organization, adding users to groups, etc. + +Technically, SCIM is a set of APIs that allows you to manipulate the users and group objects and expose these data as JSON through the REST endpoints. + +## How to add Directory Sync to your SaaS app? + +Building Directory sync implementation yourself can be tedious and time-consuming for any engineering team. + +Below are some questions the engineering team should answer before starting building Directory sync. + +- How do we support multiple identity providers? +- How much effort should the team put into support & maintenance? +- Do we have developers with good knowledge of SCIM and its security? +- Is it worth building the Directory sync ourselves? + +In short, building Directory sync yourself is not a good idea. It requires a lot of tedious engineering work and ongoing maintenance. + +The best alternative is an open-source dedicated Directory Sync implementation provider like SAML Jackson from BoxyHQ. + +## Directory Sync from BoxyHQ + +BoxyHQ can help enterprises to add Directory Sync to any SaaS app with just a few lines of code. + +Enterprise SaaS apps can provide a Webhook endpoint to SAML Jackson, and Jackson will notify the Webhook every time a change occurs in the user identity data within the IDP. + + + +In short, Jackson hides all the complexities involved with Directory Sync implementation and makes your integration easier. + +BoxyHQ's Directory Sync implementation supports identity providers such as Okta, OneLogin, Azure AD, and JumpCloud. We're looking forward to adding more identity providers in future releases. + +Here are a few critical aspects that make [BoxyHQ's Directory Sync implementation](/docs/directory-sync/overview) stand out. + +- An open-source solution. +- Allows you to keep control of your data. +- Support multiple identity providers. +- Allows you to listen to six critical SCIM events. + +## Final Thoughts + +Directory Sync is a valuable investment for every organization seeking efficiency and security in their user lifecycle management system. + +If you are interested in becoming enterprise-ready without the hassle, then let's chat! You can book a free consultation call and talk with our CEO about how we can help. So let's start the journey together. diff --git a/blog/2022-09-27-enterprise-ready-saas-starter-kit.md b/blog/2022-09-27-enterprise-ready-saas-starter-kit.md new file mode 100644 index 0000000..df51769 --- /dev/null +++ b/blog/2022-09-27-enterprise-ready-saas-starter-kit.md @@ -0,0 +1,126 @@ +--- +slug: enterprise-ready-saas-starter-kit +title: Enterprise-ready SaaS Starter Kit +author: Kiran K +author_title: Senior Developer @BoxyHQ +author_url: https://twitter.com/tokirankrishnan +author_image_url: https://boxyhq.com/img/team/kiran.jpg +tags_disabled: [enterprise-readiness, nextjs-template, saas-starter-kit] +--- + +Enterprise-ready SaaS Starter Kit is a **Next.js** based SaaS Starter Kit that can save hundreds of development hours while building [enterprise-ready SaaS apps](/blog/enterprise-readiness-made-simple). + +[Kickstart your enterprise app development with Next.js SaaS Starter Kit](https://github.com/boxyhq/saas-starter-kit) + +Check out the [video tutorial](https://youtu.be/oF8QIwQIhyo) that walks through setting up your local environment and running enterprise-ready features the SaaS kit offers. + +## SAML SSO + +SAML stands for Security Assertion Markup Language. It is an XML-based open standard for transferring identity data between an identity provider (IdP) and a service provider (SP). + +[Single Sign On (SSO)](/blog/understanding-saml-sso-the-basics-from-the-solution-providers-side) allows your customers to manage their team's users outside your built-in user table. + +SAML SSO is integrated with the help of [SAML Jackson](https://github.com/boxyhq/jackson) + +## Directory Sync (SCIM) + +[Directory sync](/blog/understanding-scim-and-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. + +Directory Sync is integrated with the help of [SAML Jackson](https://github.com/boxyhq/jackson#directory-sync) + +## Audit Logs + +Provide enterprise customers with the ability to record and search events that happen within your application. With our simple integration, you can become compliant fast and save your team from building complex solutions from scratch. + +Organizations gain the ability to monitor the flow of data and be alerted to any breaches. Audit logs help to pinpoint any misuse of information and ensure that data policies are followed. + +## Webhooks & Events + +Webhooks are a way for systems to notify external applications that a specific event has occurred in your SaaS app without receiving a request. + +Webhooks are a great solution if the client does not know when an event will occur and wants to be notified in real-time. + +Webhook is integrated with the help of [Svix](https://github.com/svix/svix-webhooks) + +## Team Management + +Teams describe the functionality that enables modern software to be coordinated and managed. + +Through Teams, SaaS app users invite others to collaboratively use the application with them by creating an account. + +## Other Features + +Let's also look at other standard features the SaaS kit offers. + +- Create account +- Sign in with Email and Password +- Sign in with Magic Link +- Update account +- Manage team +- Manage team members +- Invite users to the team +- Accept invitation + +## Getting Started + +Please follow these simple steps to get a local copy up and running. + +### 1. Setup + +Clone or fork this GitHub repository + +```bash +git clone https://github.com/boxyhq/saas-starter-kit.git +``` + +### 2. Go to the project folder + +```bash +cd saas-starter-kit +``` + +### 3. Install dependencies + +```bash +npm install +``` + +### 4. Set up your .env file + +Duplicate `.env.example` to `.env`. + +```bash +cp .env.example .env +``` + +### 5. Set up database schema + +```bash +npx prisma db push +``` + +### 6. Start the server + +In a development environment: + +```bash +npm run dev +``` + +### 7. Start the Prisma Studio + +Prisma Studio is a visual editor for the data in your database. + +```bash +npx prisma studio +``` + +## Contributing guide + +Contributions make the open-source community a fantastic place to learn, inspire, and create. Any contributions are greatly appreciated by the whole community. + +We encourage and invite users and community members to contribute to the [saas-starter-kit](https://github.com/boxyhq/saas-starter-kit) repository. + +For more help or if you have a question about getting started building a SaaS app please join our [Community Discord.](https://discord.boxyhq.com) diff --git a/blog/2022-09-30-sso-building-blocks.md b/blog/2022-09-30-sso-building-blocks.md new file mode 100644 index 0000000..f82c3e3 --- /dev/null +++ b/blog/2022-09-30-sso-building-blocks.md @@ -0,0 +1,83 @@ +--- +slug: sso-building-blocks +title: SSO Building blocks - SAML, OAuth 2.0 and OpenID Connect +author: Aswin V +author_title: Senior Developer @BoxyHQ +author_url: https://twitter.com/av__2021 +author_image_url: https://boxyhq.com/img/team/aswin.jpg +tags_disabled: [sso, engineering, saml-jackson, oauth-2.0] +image: /img/sso-flow.png +--- + +We have already covered SAML at a high level from both [user](2022-06-30-understanding-saml-sso-the-basics-from-the-user-side.md) and [application provider](2022-06-30-understanding-saml-sso-the-basics-from-the-solution-providers-side.md) points of view. + +In this post, we'll dive into the technicalities of SAML, OAuth 2.0 and OpenID Connect and how these come together to serve as building blocks for Jackson SSO. + +## SAML + +SAML was designed for traditional web applications in the early 2000s. The goal was to provide a seamless user experience for applications by federating authentication to an IdP. As a result, applications no longer had to maintain identities for users. All they had to do was to redirect the browser to the IdP which would then authenticate the user and return an assertion about the logged-in user. This assertion in effect was a token, asserting to the app that the user authenticated at the IdP and the assertion is valid for the set period contained within it. + +While SAML gave us a solution to the problem of SSO or federated identity, it does not address the issue of authorization. + +The need for authorization arose with the dawn of Single Page Apps (SPA) and native platforms such as mobile. More and more logic started moving from backend to frontend and an ecosystem of apps that could talk to one another (via HTTP(S)) sprung up. For eg:- You could reserve movie tickets and send invitations to your Facebook friends. This meant that applications started acting on behalf of the end-user, requesting data (friend list) from other services (Facebook). One way we could solve it was by sharing our credentials (for services) with the app. Nothing could be more dangerous than this, because now the application can virtually do anything the user could do. This paved the path for standards like OAuth that provides us with a mechanism to grant controlled and limited access to resources on behalf of the user. + +## OAuth 2.0 + +The OAuth 2.0 Authorization framework enables a third-party application/client to obtain limited access to an HTTP service on behalf of the resource owner (or user). In the final step of this process, the client receives a short-lived access token that can be used to access the protected resources. + +The flow starts with the app redirecting the user agent to an intermediary Authorization server (AS). The AS authenticates the user and obtains permission from the user to access resources. Once that's done, AS redirects back to the client with an Authorization code. The Authorization code is a grant or a credential representing the user's authorization to be used by the client. In the final step, the client uses this code to obtain an access token. This flow otherwise called Authorization Code grant is one of 4 grant types that are supported. For sake of simplicity, we can omit the others for now. + +The above-mentioned flow offers a few benefits: + +- The user only authenticates with the authorization server and the credentials are never shared with the app. +- The access token is not transmitted\* via the user agent but directly to the client via an HTTP request. +- The Client can be authenticated by the authorization server by using a client secret. + +**\*** _It's worth mentioning the fact that another grant type 'implicit grant' does return an access token via the user agent in the redirect URL fragment_ + +#### Using OAuth 2.0 for authentication + +Since authentication usually occurs before issuing the access token, it is usually assumed that possession of an access token is proof that authentication happened. The access token is then used to query the Identity API to obtain user details. + +However, this does not fully serve as proof of authentication and has several pitfalls: + +- The access token is opaque to the client and its intended audience is the protected resource server. +- There is no way to know if the user is still around because information about the authentication event is not exposed. +- In situations where clients get an access token directly in the return URL (implicit grant), there is a high chance that an attacker can inject their malicious token. This can be mitigated by using the Authorization code flow as the token is retrieved from the token endpoint directly. +- OAuth does not define a standard set of fields for the Identity API. For eg:- While one IdP could use `user_id` for the user identifier, the same could be `subject` in another one. This requires different handling on the client side from one IdP to another. + +A new standard called 'OpenID Connect' which builds on top of OAuth 2.0 brings new artifacts like ID tokens that can serve as reliable proof of authentication and also standardizes things like `scope` and `claims`. + +## OpenID Connect (OIDC) + +OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It supports 3 flows of which Authorization code and implicit flow are similar to the ones defined in OAuth 2.0. The notable difference here is the return of an ID Token in JWT format (JSON Web Token). The claims in the ID Token help the client reliably confirm the identity of the user. The audience(`aud`) claim will be set to the client id which means the ID token is intended to be consumed by the client alone. Conforming to the OAuth 2.0 spec, an access token is still returned which can be used to obtain information about the user from the "userinfo" endpoint. OIDC also standardizes the claims in the ID Token as well as the "userinfo" response. + +## Assembling the SSO puzzle + +Now that we have all the pieces of the SSO puzzle, bringing it together in Jackson would look something like the one below. + + + +Allow me to explain. + +We need to support two kinds of SSO Identity Providers - SAML and OIDC. For the sake of discussion, consider the scenario of two apps where one (CRM) needs to log in with Azure AD via SAML and another (HRM) needs to log in with Google Workspace via OIDC. + +#### Setup SSO Connection + +The preliminary step (marked by the green arrow above) is to add the SSO Connection to Jackson. For SAML IdP, this would mean saving the XML metadata from the IdP. The metadata would contain the SSO URL to send the SAML request to plus the public key to verify the SAML assertion signature. In the case of OIDC IdP, we need the discovery URL and client credentials (clientID and clientSecret of the registered app). The discovery URL can be used to query metadata about IdP such as authorization and token endpoints while the client credentials will be used to authenticate the Jackson client orchestrating the OIDC flow. + +#### Login flow + +Jackson supports both OAuth 2.0 and OpenID flows. The OAuth 2.0 flow is made secure by supporting Authorization Code flow with PKCE. By including the scope `openid` in the client request Jackson will switch to OpenID flow. + +The login process follows the below steps: + +1. The Client (Browser app) initiates the login by redirecting to Jackson's `authorize` endpoint. Jackson will parse the tenant/product in the request and use it to redirect the user to the configured IdP. +2. Step 2 varies based on the Identity Provider type. For SAML IdP, Jackson would construct the SAML request, sign it and send it to IdP. The IdP validates the request and authenticates the user. For OIDC IdP, Jackson constructs an OpenID Connect request and redirects the user to the OIDC Provider authorization endpoint. +3. Once the user is logged in successfully, the IdP redirects back to Jackson. For SAML, the response contains the user profile. In the case of OIDC, the response contains the authorization code that is used by Jackson to obtain the token and user profile from the OIDC IdP. Jackson generates a short-lived `authorization code` and stores the user profile against it. +4. The `authorization code` generated in the previous step is sent to the client app. +5. The client exchanges the code for the token and uses it to query the userInfo endpoint of Jackson to get the complete user profile. In the case of OpenID flow, ID Token is returned by Jackson and contains the basic user profile. + +## Final thoughts + +So in a nutshell, Jackson acts as a proxy between the client app and the IdP doing the heavy lifting of orchestrating SAML/OIDC flows with the configured IdPs. This way you can quickly scale your app auth to any number of providers allowing you to focus on your core product. diff --git a/blog/2022-10-12-what-is-dev-ops-and-how-has-it-evolved-into-dev-sec-ops.md b/blog/2022-10-12-what-is-dev-ops-and-how-has-it-evolved-into-dev-sec-ops.md new file mode 100644 index 0000000..afcee2e --- /dev/null +++ b/blog/2022-10-12-what-is-dev-ops-and-how-has-it-evolved-into-dev-sec-ops.md @@ -0,0 +1,46 @@ +--- +slug: what-is-dev-ops-and-how-has-it-evolved-into-dev-sec-ops +title: What is DevOps and how has it evolved into DevSecOps +author: Jay Singh +author_title: Marketing Consultant +author_url: https://www.linkedin.com/in/jaydsingh/ +author_image_url: https://boxyhq.com/img/team/jay.jpg +tags_disabled: [devops, devsecops, developer security] +image: /img/blog/devsecops.png +--- + +## What is DevOps + +Let's first take a look at what DevOps (Developer Operations) is so we can better understand why it has now evolved into DevSecOps (Developer Security Operations). DevOps is a combination of philosophies, practices, and tools that increases a business's ability to deliver better development in less time (Higher velocity). This can be applied to building a new product or the process of continuous improvement that applies to most products we see today. + +If we look at the old way of development, typical teams worked on their own and would do their bit and then just pass it on to the next team to do theirs, a bit like an assembly line. This meant that development cycles were very long, communication between teams was limited, handover processes were not in place and if anything went wrong it would take a long time to identify and fix issues. If we compare that to today's agile development process we use DevOps to work in sprints and deliver results in a much faster and more efficient way. This has been made possible by not only the way we look at the development cycle but also by tools and automation. + +DevOps has come a long way already and we have seen it evolve with the agile methodology of working but security, in particular, was always still the last step of the development process and not thought about as a necessity. In some cases when security was only looked at by a specific team at the end of the process. + +## Why has security been integrated into DevOps + +The rise in cybercrime and the sophistication of attacks has made security a crucial part of the development process and not just an afterthought. This has led to security being integrated into the development process at each stage and becoming a shared responsibility. It has also led to security being thought about and planned right from the start of each process rather than at the end. This has resulted in more development velocity, more layers of integrated security and higher collaboration around security as a major aspect of the development cycle. + +The integration of security in the development cycle at each stage from start to finish while also automating some of the security steps is what has led to the evolution of DevOps becoming DevSecOps, a go-to practice today. One of the main reasons the term was adjusted to include security is to make each person in the process think about and take accountability for secure building practices. + +## Benefits of DevSecOps + +Lastly, let's take a quick look at the main benefits of having solid DevSecOps in place + +1. **Security** + + By thinking about and implementing security at each stage of the development process and particularly in the early stages organizations are proactively mitigating cyber threats. This combined with automated security testing means that dev teams can perform security checks and audits without slowing down development cycles. + +2. **Improved Collaboration** + + DevSecOps pushes for development and security and operations teams to collaborate more and especially in the early stages of the process. This increases innovation and leads to better cross-team buy-in. It also makes sure that everyone is responsible for security. + +3. **Streamlines process that limits vulnerabilities** + + Having security in every stage of the development process limits the chance of finding vulnerabilities much later, vulnerabilities which could delay the release. The process of streamlining the process with automated security testing as part of the development process also ensures that possible vulnerabilities are caught at each stage. + +4. **Cost** + + Cost is also always a major benefit and by having a good DevSecOps process in place you will find bugs and issues much faster which will result in less time and cost required to fix them. + + diff --git a/blog/2022-10-25-how-low-code-solutions-are-changing-how-we-build-products-and-workflows.md b/blog/2022-10-25-how-low-code-solutions-are-changing-how-we-build-products-and-workflows.md new file mode 100644 index 0000000..33ba96a --- /dev/null +++ b/blog/2022-10-25-how-low-code-solutions-are-changing-how-we-build-products-and-workflows.md @@ -0,0 +1,42 @@ +--- +slug: how-low-code-solutions-are-changing-how-we-build-products-and-workflows +title: How low-code solutions are changing how we build products and workflows +author: Jay Singh +author_title: Marketing Consultant +author_url: https://www.linkedin.com/in/jaydsingh/ +author_image_url: https://boxyhq.com/img/team/jay.jpg +tags_disabled: [low-code, no-code, speed of development] +image: /img/blog/lowcode-graph.png +--- + +We have all heard the terms low-code or no-code being thrown around as buzzwords over the last few years but what does this mean and how is it changing the way businesses and individuals solve problems? I am going to use our product SAML Jackson to explain how low-code solutions are changing the way we build products. + +Low-code solutions are essentially products that provide you with building blocks so instead of building a solution from scratch you can simply combine the relevant building blocks to make a relevant solution for your business. Let’s take BoxyHQ and our SAML Jackson product as an example. Without the low-code product (SAML Jackson) the alternative for businesses would be to build a custom SAML integration which takes months and a ton of resources. This sounds ridiculous tho right? With the number of businesses who are deploying SAML for their customer, there must be some reusable parts that can be shared to reduce the time it takes each business. This is where low-code products like SAML Jackson come in. By building the SAML integrations as a reusable component, businesses only need to create one simple connection to the SAML Jackson to deploy SAML. + +Still with me? If not, don't worry. Essentially what low-code is taking advantage of is building in a way that can be shared so the amount of custom building is limited (or low) for common use cases. + +## So what is the difference between low-code and no-code? + +Well while a lot of people would still group them together, the obvious difference is that low-code still needs some code to integrate the building blocks, whereas no-code doesn't. If we look at a product like Zapier for example, that requires no code at all and a non-technical person can use visual blocks to connect different data sources and outputs to build workflows. An example of this is as a non-technical person I can take data from forms such as Hubspot forms that are submitted on our website and create notifications for the team on Slack. Doing all of this without code and just using Zapier is what makes this a no-code solution. + +## Why is low-code so important? + +Lastly, let's take a quick look at the main benefits of having solid DevSecOps in place + +1. **Speed speed speed** + + In today's world businesses need to be agile and fast. With competitors springing up every day and customer expectations high the last thing a business wants to do is to have to make specialist hires for each element of their build or spend precious time on auxiliary features that also have their learning curve. The birth of plug-and-play has meant that businesses can operate faster and more efficiently than ever before. Can you imagine if a business had to build all its tools from scratch? No neither can I. + +2. **Cost** + + Cost is always a major element that businesses and individuals look at when finding a solution and in the case of low-code it comes down to the question of build V buy. For larger enterprises who have not fully adopted the trust and efficiency of low-code they might still choose to build their own solution which will cost them a lot more in resources and time but that might be something, they have spare. Smaller businesses who want to focus on their core offerings will always look for reliable plug-and-play solutions such as low-code which allow them to quickly deploy solutions and stay competitive while saving on the large number of resources needed to build from scratch. + + + +## Are there any negatives to using low-code and no-code platforms? + +The only main negative of these solutions I have identified is that because of the ease and speed of the platforms it can create a lack of transparency and some shadow IT as lots of people in the organization can be building solutions and data can be moving around without accountability. However, with the right IT processes and policies in place, this can be easily fixed. + +## Why are we so excited about low-code and no-code? + +We are very excited about low-code solutions because it drives innovation! We at BoxyHQ are building low-code solutions for enterprises to implement the important but standard features they need to be competitive and compliant with ease so they can focus on what they do best which is innovate. We have some great clients already and can’t wait to see what they do next without the hassle of building standard features such as SSO and Directory Sync. diff --git a/blog/2023-01-18-why-does-your-saas-application-need-audit-logs.md b/blog/2023-01-18-why-does-your-saas-application-need-audit-logs.md new file mode 100644 index 0000000..11dfce2 --- /dev/null +++ b/blog/2023-01-18-why-does-your-saas-application-need-audit-logs.md @@ -0,0 +1,40 @@ +--- +slug: why-does-your-saas-application-need-audit-logs +title: Why does your SaaS application need audit logs? +author: Deepak Prabhakara +author_title: Co-founder & CEO @BoxyHQ +author_url: https://github.com/deepakprabhakara +author_image_url: https://boxyhq.com/img/team/deepak.jpg +tags_disabled: [audit-logs, enterprise-readiness] +image: /img/blog/audit-logs-widget.png +--- + +Audit logs are an important tool for keeping track of activity within your SaaS application. These logs provide a detailed record of the actions taken by users and can be used to monitor for potential security breaches, compliance violations, and other issues. Let’s explore some of the key reasons why you need audit logs for your SaaS app. + +1. **Compliance:** Many industries are subject to strict regulations that require organizations to maintain detailed records of their activities. Audit logs can be used to demonstrate compliance with these regulations, and to provide evidence in the event of an audit or investigation. + + The retention period requirements of some well-known compliance frameworks are listed below: + + - ISO 27001: 3 years + - GDPR: Not very specific, as long as necessary + - HIPAA: 6 years + - PCI DSS: 1 year + - NIST: 3 years + - SOX: 7 years + - GLBA: 6 years + +2. **Cyber Insurance:** Obtaining cyber insurance usually comes with requirements around recording and retaining audit logs. These logs help with forensics during insurance claims, otherwise making investigation expensive and time-consuming for both insurers and the affected companies. +3. **Security:** Audit logs can be used to detect and prevent security breaches. By monitoring for suspicious activity, such as repeated failed login attempts or changes to sensitive data, you can quickly identify and respond to potential threats. Additionally, audit logs can be used to reconstruct the events leading up to a security incident, which can help you identify the cause and prevent similar incidents in the future. +4. **Accountability:** Audit logs make it possible to track the actions of individual users, which can be useful for identifying issues such as data breaches, compliance violations, and other problems. This information can be used to hold users accountable for their actions and to help you identify and address any issues that arise. +5. **Troubleshooting:** Audit logs can be used to identify and diagnose issues that occur within your SaaS application. By reviewing the logs, you can see exactly what happened when a problem occurred, which can help you quickly identify the root cause and develop a solution. +6. **Auditing:** Audit logs provide a record of the activities that occur within your SaaS application, which can be useful for internal audits. This information can be used to assess the effectiveness of your security controls and identify areas for improvement. + + + +Audit logs are a powerful tool that can be used to improve the security, compliance, and overall performance of your SaaS application. By keeping detailed records of user activity, you can monitor for potential issues and quickly respond to problems as they arise. If your SaaS app doesn't have audit logs, you should consider implementing them as soon as possible to ensure the safety and security of your data and users. It is also becoming an important part of enterprise readiness. + +## Introducing our Audit Logs product + +We are extremely thrilled to introduce our new Audit Logs product in collaboration with our friends at [Replicated](https://replicated.com). Retraced is a fully open-source audit log service that comes with an embeddable UI that's easily deployed to an infrastructure of your choice. We have spent years building and fine-tuning audit logs systems and think we have finally discovered an optimal solution to this nagging problem. + +It’s yet another important enterprise readiness feature to tick as you scale your offerings to the enterprise segment and complements our Enterprise SSO and Directory Sync products to give you a one-stop solution. Come check out the product at our [GitHub repo](https://github.com/retracedhq/retraced), we’d love to hear your feedback. diff --git a/blog/2023-03-13-exploring-the-open-source-business-model-and-how-companies-monetize-it.md b/blog/2023-03-13-exploring-the-open-source-business-model-and-how-companies-monetize-it.md new file mode 100644 index 0000000..5da6ba3 --- /dev/null +++ b/blog/2023-03-13-exploring-the-open-source-business-model-and-how-companies-monetize-it.md @@ -0,0 +1,66 @@ +--- +slug: exploring-the-open-source-business-model-and-how-companies-monetize-it +title: Exploring the open-source business model and how companies monetize it +author: Deepak Prabhakara +author_title: Co-founder & CEO @BoxyHQ +author_url: https://github.com/deepakprabhakara +author_image_url: https://boxyhq.com/img/team/deepak.jpg +tags_disabled: [open-source] +image: /img/blog/christine-roy-ir5MHI6rPg0-unsplash.jpg +--- + +With the rise of open-source solutions and solution providers, one of the biggest questions asked is, how do businesses monetize while giving away the source code for free? + +## What is an open-source company? + +An open-source company is an organization that develops software but makes the source code freely available to the public. This means that others can copy the code and engine, deploy it themselves, develop it, fix bugs and more. This allows the software not only to be widely accessible for free but also to evolve in a very collaborative way. + +## If everything is free then how can it be monetized? + +We don't have to look very far to find examples of open-source companies that have become unicorns and continue to grow. Some great examples are Elastic ($608 million in revenue, 2021), HashiCorp ($320 million in revenue, 2021), and RedHat ($3.4 billion in revenue, 2021). All these companies operate an open-source business model but have huge revenues and valuations. This is what we are going to look at. + +There are many different ways that open-source companies can monetize - ultimately this comes down to the goals of the business. We are going to explore a few of the options available but keep in mind that these are just some of the ways it can be done and open-source continues to develop and grow at a rapid pace. + +### Donations + +One of the most popular models is to offer the source code and documentation completely free and let its users donate at their discretion. This is normally done for smaller projects and donations can be solicited in various ways, such as a button on the website, a link in a newsletter, a Github donation, or one that I like - buymeacoffee.com. The latter allows you to embed an option into your website or interface and donate at the value of a coffee. Although donations are a great way to monetize some projects, this method is not feasible for bigger companies that have complex solutions and large overheads. + +### Support + +Paid Support or Premium Care, as it’s commonly termed, is a very common business model that has done very well for larger commercial companies. This model allows users to still access the code and deploy it for free but also enables an option for companies/users to pay for additional support. This monetized plan often includes perks such as help deploying the software, customization and ongoing support for general use. Just because the source code of a project is open, it doesn’t mean it's easy to deploy or manage. This is where companies such as Red Hat have been successful and use this particular model to great effect. + +The benefits of this model are, as Red Hat has demonstrated, you can build a revenue-generating company that can be scaled effectively. The drawback is, some companies only make the open-source code available with a paid plan, which goes against the open-source ethos. To truly use this model effectively, companies should offer the source code for free regardless of an option for additional support. + + + +Photo by Christine Roy on Unsplash
+
+### Licensing
+
+Open-source companies can also license their open-source software, which applies rules to how their software can be used, edited, distributed and copied. Some open-source companies will allow individuals and smaller organizations to use their software for free while charging larger companies a fee to deploy it. Normally a license fee comes with additional benefits, such as support and training, etc. There are also two main types of licensing that open-source companies can utilize.
+
+-Copyleft license
+This is a type of license in which, if code is copied and modified it still retains the original license terms
+
+-Permissive license
+This grants licenses based on different needs and is much more diverse.
+
+Licensing and open-source licensing is a huge topic in itself and Snyk has done a fantastic job at explaining this. You can read more about it here.
+
+### Cloud-hosted Services
+
+Finally, the last model we will look at is hosting. While open-source organizations can still offer their code for free, some may offer a hosted version which is much easier to set up and maintain. This means customers can effectively use their product like any other SaaS and they typically charge on a subscription basis.
+
+The hosted model is very popular as it now allows quick deployment but also reduces the level of maintenance and custom work developers need to carry out. The main limitation of offering a hosted model is, it will require the open-source company to offer web hosting and everything that goes along with it. This can require an enormous amount of maintenance and development.
+
+### The open-core model
+
+The open core model is when a company releases the core software for anyone to use but then also controls things such as the roadmap and what commits are accepted into it. By doing this, the company can also charge for extra features which customers may want. Some examples could be functionality features or even security/compliance modules. This model has been very popular with open-source companies and is widely seen as a very fair way to operate. It is also very important to make sure that the open-core has enough value that developers will rally around the product from the get-go. Companies that offer very little value from the free version and charge for additional features, do not see great traction in the open-source community.
+
+## Controversial opinion
+
+I personally believe that OSS is not a business model but a development model. We are debating this internally, so we would love to hear your feedback and opinions on this subject.
+
+## Summary
+
+Although open-source code is widely free and available to use, it has become a popular choice for companies who also want to commercialize. The benefits of open-source are vast and with the variety of business models we discussed you can understand the various options to create a successful, revenue-generating business.
diff --git a/blog/2023-03-22-sbom-explained-an-enterprise-guide-to-security-risk-management.md b/blog/2023-03-22-sbom-explained-an-enterprise-guide-to-security-risk-management.md
new file mode 100644
index 0000000..9e5d8ed
--- /dev/null
+++ b/blog/2023-03-22-sbom-explained-an-enterprise-guide-to-security-risk-management.md
@@ -0,0 +1,51 @@
+---
+slug: sbom-explained-an-enterprise-guide-to-security-risk-management
+title: 'SBOM Explained: An enterprise guide to security risk management'
+author: Nathan Tarbert
+author_title: Community Success Engineer @BoxyHQ
+author_url: https://github.com/NathanTarbert
+author_image_url: https://boxyhq.com/img/team/nathan.jpg
+tags_disabled: [open-source]
+image: /img/blog/security-lock.jpg
+---
+
+In this age of technology, software companies are quickly shifting towards a strict compliance posture. You may ask yourself, why is that and what has changed over the last several years? This can be due to multiple factors but can mainly be boiled down into four categories.
+
+- Security
+- Product Development
+- Compliance
+- Supply Chain & Risk Management
+
+## What is an SBOM or Software Bill of Materials?
+
+You can think of your modern application as a cake you are baking. The list of ingredients you use to bake that cake would be the SBOM (Software Bill of Materials). In the case of software, it's open-source or private dependencies and third-party components. This list can be massive and can range from hundreds to thousands, especially when you factor in transitive dependencies (an indirect dependency of the component it relies on). This list gets very complex and is impossible to manage at scale at the enterprise level. Gone are the days when most enterprises or smaller-scale organizations would write applications from scratch. Rather, most applications are assembled using pre-built software packages, i.e open-source. Over the past decade, this has led to the rise and use of publicly available software components and agile development at an enormous rate.
+
+## Security
+
+More organizations now have security top-of-mind due to cyber attacks on business infrastructure becoming almost a daily occurrence. Companies are faced with major decisions that affect cost, efficiency, and productivity. There is an enormous risk and liability where a company’s code base lives in the cloud. This could be private or public but a good rule of thumb when you think about risk is not if we’re breached, but when. So precautions need to be taken to add layers of protection to software infrastructure.
+
+An SBOM would provide better visibility to companies in identifying and tracking security vulnerabilities that could enable timely patches. Updates in code should prompt a newly generated report (SBOM).
+
+We could go a lot deeper around all the various ways precautions could be taken like scanning your application for vulnerabilities or penetration testing. A [minimum viable secure product](https://mvsp.dev/) is of course recommended for all enterprise-ready organizations. It could be as simple as having [audit logs](https://boxyhq.com/audit-logs) in place to record and search events internally on your application.
+
+## Product Development
+
+SBOMs can improve and help software development processes by providing a comprehensive list of all open-source dependencies and components used in a product. From an organizational standpoint, it is crucial to ensure that all software and related components are up-to-date and licensed correctly. Having this clear understanding is key to risk mitigation when it comes to understanding what is in a product and how it is constructed.
+Therefore, development teams can quickly improve transparency, communication, and collaborative decision-making with a faster time-to-market while ensuring industry compliance standards and regulations.
+
+
+
+
+## Compliance
+
+In 2021 the US Government issued an [executive order](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/) mandating all software companies that do business with the US government must provide a detailed inventory list (software bill of materials or SBOM) of all components related to the software they have produced and sold to any federal agency. The legislation is geared towards transparency with a view to the enhancement of security for our supply chain infrastructure. This has quickly prompted other countries to consider similar legislation.
+
+## Supply Chain & Risk Management
+
+It’s vital to take a proactive approach and have a top-down understanding of all software components that live in a software ecosystem. With that in mind, SBOMs are quickly becoming a standard for software supply chain risk management. With the expansion of sophisticated attacks, it’s more important than ever to take a systematic approach when it comes to the security of your organization.
+
+The ecosystem is growing with tools that help you verify, scan and monitor all your components and manifest files.
+
+If you have an open-source product to sell to enterprises or the public sector, you will need to anticipate compliance and build an SBOM into your product. Especially if you are targeting entities in heavily regulated industries. Taking this into consideration, that’s what we did at BoxyHQ for each of our four products with guides that will help you navigate these decisions (Enterprise Single Sign On, Directory Sync, Audit Logs, and Data Privacy Vault). We chose to build [Cosign](https://www.sigstore.dev/) right into our tool - but many more are available. Here is a [curated list of SBOM-related tools.](https://github.com/awesomeSBOM/awesome-sbom)
+
+Please visit BoxyHQ’s website to learn more about producing an SBOM for your products. E.g. SBOM for our enterprise SSO: [BoxyHQ](https://boxyhq.com/docs/jackson/sbom)
diff --git a/blog/2023-03-30-sso-wall-of-shame-vs-wall-of-fame.md b/blog/2023-03-30-sso-wall-of-shame-vs-wall-of-fame.md
new file mode 100644
index 0000000..8707a43
--- /dev/null
+++ b/blog/2023-03-30-sso-wall-of-shame-vs-wall-of-fame.md
@@ -0,0 +1,39 @@
+---
+slug: sso-wall-of-shame-vs-wall-of-fame
+title: 'SSO "Wall of Shame" vs "Wall of Fame"'
+tags_disabled:
+ [developer, security, cybersecurity, devsecops, appsec, sso, open-source]
+image: /img/blog/shame-vs-fame.png
+authors:
+ - name: Sama - Carlos Samame
+ title: Co-founder & COO @BoxyHQ
+ url: https://www.linkedin.com/in/samame
+ image_url: https://boxyhq.com/img/team/sama.jpg
+ - name: Deepak Prabhakara
+ title: Co-founder & CEO @BoxyHQ
+ url: https://github.com/deepakprabhakara
+ image_url: https://boxyhq.com/img/team/deepak.jpg
+---
+
+Unless you have been living under a rock, you have probably heard of the SSO Wall of Shame. This is a list of vendors that treat single sign-on as a luxury feature, not a core security requirement. There have been numerous complaints regarding the companies that have made it onto this list, and rightfully so. In a downturn economy and in times when security and privacy are critical, many organizations see an opportunity to generate even more revenue.
+
+This is a small example, listed in alphabetical order of some of the most well-known companies that have ended up on the “Wall of Shame” (see the screenshot below). You can find more information and the full list at [sso.tax](https://sso.tax). It is clear that raising prices for enterprise SSO and other security features, such as Audit Logs (to track critical events), is just part of their revenue model.
+
+
+
+But is this the right thing to do? It’s hard to judge from the outside, and clearly companies need to make a profit while showing growth, especially when you are backed by Venture Capital. Having said that, at BoxyHQ we believe that we can all do better (we are also Venture funded). Nonetheless, cybersecurity taxes should stop, and we should all focus on increasing our security posture and making a positive impact. Take for example, Hubspot charging 6300% more for SSO functionality! That is a clear example of how absurd and abusive some companies can be.
+
+Now, we ask ourselves, how about the “Wall of Fame”? This is a separate list of companies that lead by example and don’t take advantage of their customer base. If you do a quick search, you will find some interesting companies listed. Grafana, Cal.com, and Sumo Logic, just to name a few.
+
+To understand why startups normally lean this way, it’s important to consider the enterprise deal process. With RFPs, security questionnaires, and other compliance-related procedures, closing an enterprise deal becomes all-consuming for a startup. This can justify an enterprise pricing tier. Given a startups early evolution of products, , Enterprise SSO becomes an easy candidate to distinguish the pricing tier gap between charging SMBs and what they can charge enterprises. But building and maintaining SSO is expensive and time-consuming. SAML is not necessarily the easiest protocol implementation to get right. And add to this the customer support issues that come with onboarding large enterprise teams onto the product. But as a startup matures the product needs to have enough core enterprise features and not merely depend on undifferentiated features like SSO.
+
+To take it full circle, it would be nice to see a full list of the SSO Wall of Fame. Then we could ensure support for the companies with integrity, who have clearly not been overtaken by greed. Unfortunately because of our bandwidth, we can not commit to full ownership of this initiative, but can offer some practical advice on how companies could start offering SSO pricing tiers for free or at a nominal price increase:
+
+- Charge for other core enterprise features instead of SSO. If your product is not quite to that level of maturity, please read on.
+- Instead of charging for SSO, charge for the security process’s that comes with enterprise deals. If a company wants you to go through its security and compliance process, rather pay a premium to enhance its security posture and reduce compliance risk from its vendors.
+- If that scenario isn’t possible then consider segmenting SSO pricing based on the number of users or seats. SMBs will not have a very large number of seats so this could be a possible way to separate your pricing.
+- If your Enterprise tier is not based on seats, a natural progression is to base pricing on usage.
+
+We are trying to do our part by providing a free open–source enterprise-grade SSO (called SAML Jackson), that any developer, team, or organization can plug into with just a few lines of code. Check out the GitHub repo [here](https://github.com/boxyhq/jackson). Feedback is much appreciated and a star will help us raise security awareness. 🙂
+
+Stay safe, do good, and avoid the dark side of the SSO tax!
diff --git a/blog/2023-5-11-build enterprise-software-with-no-code-thanks-to-bubble-io copy.md b/blog/2023-5-11-build enterprise-software-with-no-code-thanks-to-bubble-io copy.md
new file mode 100644
index 0000000..eb1e487
--- /dev/null
+++ b/blog/2023-5-11-build enterprise-software-with-no-code-thanks-to-bubble-io copy.md
@@ -0,0 +1,63 @@
+---
+slug: build-enterprise-software-with-no-code-thanks-to-bubble-io
+title: 'Build Enterprise Software with No-Code Thanks to Bubble.io'
+author: Nathan Tarbert
+author_title: Community Success Engineer @BoxyHQ
+author_url: https://github.com/NathanTarbert
+author_image_url: https://boxyhq.com/img/team/nathan.jpg
+tags_disabled: [open-source, sso, enterprise-ready]
+image: /img/blog/bubble-small.jpg
+---
+
+Building your enterprise applications on Bubble is now easier than ever with BoxyHQ, a single API to connect to enterprise Single Sign-On (SSO), and multiple security compliance features.
+
+## What is Bubble.io?
+
+Bubble is a visual drag-and-drop programming language. Instead of scripting code, users can leverage a visual interface to build applications - simple or complex. This makes building apps accessible to people (or teams) with a big idea - but no programming skills.
+
+## What is a Bubble.io Plugin?
+
+Plugins are third-party Bubble.io components that are not part of the Bubble core platform functionality. They can be freely provided by the creators or available as a paid plugin.
+
+## Bubble Makes It Simple
+
+One of the benefits of using a no-code platform like Bubble is that not only can you build an application quickly, but you also have the ability to architect complex features. If we look back just a few years, this was not possible. You would have 2 options:
+
+- Hire a developer or development team
+- Delegate to a developer or team
+
+But we live in an era where technology is continually evolving and individuals' or teams' creativity has no limits. We can put ourselves in the shoes of someone who doesn’t write code but wants to build a professional application - with Bubble.io this is now a possibility.
+
+## Top 3 reasons small businesses or enterprises should switch to a no-code platform
+
+_This comes with a caveat that [Bubble does have a learning curve](https://coachingnocodeapps.com/how-long-does-it-take-to-learn-bubble-and-how-much-does-it-cost) but once you get familiar with the platform it’s much easier to build applications._
+
+## 1. Using a no-code solution like Bubble saves money on IT:
+
+Typical app development workflow costs for SMBs (small to medium businesses) from design to implementation can range from $75,000 to $750,000. This can be crippling for startups which opens up a no-code solution as a better alternative. If we are talking about enterprise development, this number can reach up to millions.
+
+## 2. Time to value:
+
+This depends on what type of app you want to build. Some estimations are up to [80% in development time saved](https://medium.com/swlh/could-i-build-my-product-on-bubble-io-75923a41b9b6). Let’s take into consideration there is no need to set time-consuming tasks for a developer such as basic features and environment setup. This is all taken care of for you when building in Bubble’s platform.
+
+## 3. Built-in SEO:
+
+Whether you are a startup or an enterprise team, but inexperienced in the art of Search Engine Optimization (SEO), not to worry, Bubble has built-in [SEO tools](https://manual.bubble.io/help-guides/customizing-an-application/seo#bubbles-seo-tools) that allow you to the ability to modify and customize how your application is seen by search engine crawlers. This would be in the advanced settings and great care should be taken when enabling or modifying these settings because, by default, your application will not be indexed.
+
+This brings a lot of value when you don’t necessarily need a professional marketing division to start with. Right out of the gate, you can build an application that has professional capabilities to successfully reach your target persona.
+
+## Can I add enterprise features on Bubble?
+
+One of the foundational needs of any new business app is the ability for users to securely log in to password-protected areas - like a shopping cart or protected content. If we look at enterprise features like SAML SSO for instance, you may think this is a feature that is out of reach for a no-code platform, but you can simply search within the Bubble marketplace and a list of plugin creators has made this possible. Instantly you get a short list of plugins available for the functionality you would like to implement.
+
+
+
+BoxyHQ is one of those creators. By simply installing the plugin into your Bubble.io app, you can be up and running with little configuration effort. We have written a step-by-step [guide](https://boxyhq.com/guides/jackson/integrations/bubble) to help you properly configure setting up SAML single sign-on for your small to medium business (SMB) or enterprise application.
+
+Once you have BoxyHQ’s plugin properly configured, you now have an application that will handle secure login access to your users using SAML single sign-on that will connect to any IdP (Identity Provider) like Okta, OneLogin, Azure AD, etc.
+
+This is when you can breathe a sigh of relief because there is now no need to remember usernames and passwords. BoxyHQ’s plugin easily provides that solution for you. If you would like to test a [demo application](https://boxyhq-saml-sso.bubbleapps.io/version-test) click here to see the flow and enjoy the seamless experience you will have inside the Bubble platform.
+
+If you are interested in understanding what’s happening on the backend, we have a [guide](https://boxyhq.com/blog/understanding-saml-sso-the-basics-from-the-user-side) available that will walk you through the technical aspects of single sign-on.
+
+SSO can be complicated but BoxyHQ makes it simple to understand.
diff --git a/blog/2023-6-21-ignite-your-saas-journey-with-the-best-free-and-open-source-saas-starter-kit.md b/blog/2023-6-21-ignite-your-saas-journey-with-the-best-free-and-open-source-saas-starter-kit.md
new file mode 100644
index 0000000..c02edb7
--- /dev/null
+++ b/blog/2023-6-21-ignite-your-saas-journey-with-the-best-free-and-open-source-saas-starter-kit.md
@@ -0,0 +1,34 @@
+---
+slug: ignite-your-saas-journey-with-the-best-free-and-open-source-saas-starter-kit
+title: 'Ignite Your SaaS Journey with the Best Free and Open-Source SaaS Starter Kit'
+author: Sama - Carlos Samame
+author_title: Co-founder & COO @BoxyHQ
+author_url: https://www.linkedin.com/in/samame/
+author_image_url: https://boxyhq.com/img/team/sama.jpg
+tags_disabled: [developer, security, saas, devsecops, appsec]
+image: /img/blog/enterprise-ready-saas.jpg
+---
+
+
+
+Discover the Game-Changing Power of an Enterprise-Ready Solution that will help you save thousands of dollars in development costs.
+
+Are you a SaaS founder striving for accelerated success in the highly competitive landscape? Look no further! At BoxyHQ we've curated a revolutionary tool that will supercharge your SaaS journey like never before. Introducing the Best Free and Open-Source SaaS Starter Kit, designed to ignite your growth and transform your startup dreams into reality.
+
+## Enterprise-Ready Powerhouse
+
+We understand that conquering the enterprise market is a key milestone for many SaaS founders. That's why this Starter Kit is not just another ordinary tool—it's an enterprise-ready powerhouse. Equipped with robust security features and compliance readiness, it's tailored to meet the stringent requirements of corporate clients. It includes SAML/OIDC Single Sign-On (SSO), Directory Sync, Audit Logs, and Data Privacy Vault (PII, PCI, PHI compliant) that would cost tens of thousands of dollars in developer time. Empower your startup to take on the biggest players in the industry with confidence.
+
+## Supercharge Your Development Journey
+
+Leave the tedious and time-consuming development tasks behind. The SaaS Starter Kit empowers founders to supercharge their development journey. Its intuitive, no-code capabilities streamline the entire process, enabling you to focus on your unique value proposition. Join the ranks of successful SaaS startups who have harnessed the power of this kit to achieve rapid growth and customer acquisition.
+
+## Get Started Today
+
+Ready to unlock your SaaS potential? Getting started is a breeze. Simply access the Starter Kit's source code and documentation on GitHub, available at [here](https://github.com/boxyhq/saas-starter-kit)
+
+For additional guidance and insider tips, head over to this other [blog post](https://boxyhq.com/blog/enterprise-ready-saas-starter-kit) and watch our [full demo](https://www.youtube.com/watch?v=oF8QIwQIhyo). It's time to embark on your journey toward SaaS greatness.
+
+Don't let your SaaS dreams remain stagnant—ignite them with the best free and OSS enterprise-grade SaaS Starter Kit. This game-changing tool is set to revolutionize the way startups grow and succeed. Seize the opportunity, join our thriving community, and accelerate your path to SaaS stardom. The possibilities are limitless, and your success awaits!
+
+
\ No newline at end of file
diff --git a/careers/2021-08-18-senior-software-engineer.md b/careers/2021-08-18-senior-software-engineer.md
new file mode 100644
index 0000000..f27ab30
--- /dev/null
+++ b/careers/2021-08-18-senior-software-engineer.md
@@ -0,0 +1,41 @@
+---
+slug: senior-software-engineer
+title: Senior Software Engineer - Open Source, Dev Tools
+author: Deepak Prabhakara
+author_title: Co-founder & CEO @ BoxyHQ
+author_url: https://github.com/deepakprabhakara
+author_image_url: https://avatars.githubusercontent.com/u/357991?s=400&v=4
+tags_disabled: [careers, senior-software-engineer, engineering]
+---
+
+#### TLDR
+
+Join our well-funded remote-first team if you love building open source API driven developer tools. We are just getting started so it is a chance to be part of the founding team and influence adoption of our products! Join us on our mission to help startups simplify development of compliance and data security related features in their products. Reach out to us at careers@boxyhq.com.
+
+#### About us
+
+- Open source-first company - your work will be visible and you will be able to influence hundreds of developers!
+- Our team will be distributed remotely worldwide.
+- BoxyHQ is still small - just us 2 founders for now. You will be one of the first employees and can drive major parts of the product.
+- Highly competitive salary and stock options.
+- Experienced founders with strong engineering, commercial and open source experience.
+- Engineering team will be involved in product discussions and planning. We do it openly via GitHub.
+- We encourage and support the team in attending conferences, giving talks, writing blog-posts, and other activities.
+- We believe in constantly iterating and improving; you will get to influence our internal processes as well.
+
+#### About you
+
+- Strong software engineering background. We are language agnostic but will be using Go and Javascript in our initial projects. Excellent coding practises (standards, unit tests, docs, etc) are essential.
+- Remote work self-discipline. A lot of our processes are built on trust - we don't like to micro-manage. You get to take full ownership of the products.
+- Excellent communication skills - clear, constructive, and respectful dialog with other team members, community.
+- Ability to write technical docs, blogs. Team is responsible to keep documentation up to date.
+
+### The Offer
+
+- Competitive salary and stock options
+- Flexible work schedule
+- Choice of Mac, Windows or Linux laptop
+- Stipend for home office set up
+- Stipend for career development and learning
+
+_We’re committed to be the place where a culturally diverse mix of talented people get together to do their best work. We strongly encourage you to apply regardless of your location, background, race, gender, sexual orientation or any other personally defining attribute that make us different._
diff --git a/docs/Bot市场/_category_.json b/docs/Bot市场/_category_.json
deleted file mode 100644
index aa72f8e..0000000
--- a/docs/Bot市场/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "Bot市场",
- "position": 8
-}
diff --git a/docs/Bot市场/bot安装.md b/docs/Bot市场/bot安装.md
deleted file mode 100644
index 887eeef..0000000
--- a/docs/Bot市场/bot安装.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-sidebar_label: 'bot安装'
-sidebar_position: 1
----
-
-# bot安装
-
-Bot安装是进行bot安装和管理控制的重要模块，主要包括bot安装、安装查询、安装管理等功能。
-
-在bot详情页，用户点击“安装此Bot”按钮后，可以看到该bot工作所需的各项权限信息。若用户同意授予bot所需的相关权限即可进行安装。用户可选择将bot安装到所有仓库（用户拥有的所有仓库）中，也可以选择指定的仓库进行安装。
-
-
-
-在个人“设置”或者“仓库设置”中，用户可以看到目前已经安装的Bot情况，点击“配置”按钮可以对bot安装情况进行配置，点击“卸载”按钮可以进行卸载。
-
-
-
-在bot安装配置页中，用户可以掌握该bot的安装位置和工作状态。若用户需要更改bot的工作仓库时，可以进行更改安装位置。bot的工作状态包括激活和挂起，用户可根据需要对bot的状态进行调整，将其挂起或者激活，会影响到bot对仓库数据的访问权限。
-
-
\ No newline at end of file
diff --git a/docs/Bot市场/bot市场.md b/docs/Bot市场/bot市场.md
deleted file mode 100644
index 32cef1d..0000000
--- a/docs/Bot市场/bot市场.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-sidebar_label: 'bot市场'
-sidebar_position: 4
----
-
-# Bot市场
-
-Bot市场是进行Bot分享与复用的重要模块，主要包括bot的搜索发现，详情查看等功能。
-
-Bot市场主页中展示了目前所有已经上架市场的bot简要信息，包括bot的头像，名称，开发者，简介和安装次数等信息，用户可根据这些基本信息初步判断该bot是否符合自己的项目需求。
-
-在bot市场主页中，用户可以选择指定的bot种类，筛选出特定分类的bot，在这个种类范围内进行搜索与选择。
-
-此外，用户通过在搜索栏中输入关键字进行搜索，可检索出内容包含指定关键字的相关bot。
-
-用户可结合种类筛选和关键字搜索缩小范围，在市场中快速找到符合项目相关需求的bot。
-
-
-
-在bot市场页中，用户点击指定的bot卡片即可进入该bot的详情页。Bot的详情页包含bot的头像，名称，开发者，种类和详细介绍等信息，用户可在此掌握该bot的各项介绍，进一步判断是否将其安装到指定仓库中。
-
-
-
-在bot详情页中，若用户认为该bot满足自己的项目需求，可点击“安装此Bot”按钮，了解该bot的权限信息，将其安装到指定的仓库中，关于安装的更多介绍可见“Bot安装”部分。
\ No newline at end of file
diff --git a/docs/Bot市场/bot开发.md b/docs/Bot市场/bot开发.md
deleted file mode 100644
index 036b04c..0000000
--- a/docs/Bot市场/bot开发.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-sidebar_label: 'bot开发'
-sidebar_position: 3
----
-
-# Bot开发
-
-Bot开发是开发者进行bot注册的重要模块。
-
-在个人“设置”中，用户可以看到目前已经注册的bot列表，点击对应bot的“编辑”按钮可以对已注册的bot进行配置；点击“Bot注册”按钮开始注册新的bot。
-
-
-
-在注册页中，开发者需要填写bot注册的相关信息，包括bot的名称、Webhook 地址，详细介绍等，系统将对开发者输入的信息进行合法性校验，确保bot各项信息的完整性和有效性。此外，系统将自动生成bot的唯一标识，同时调用 GitLink 平台的相关接口生成bot的身份凭证信息，包括客户端密钥和私钥等。
-
-开发者需通过这些身份信息结合平台接口进行bot身份认证后，调用相关接口完成bot的相关功能。
-
-平台开发API链接（待完善）：https://www.gitlink.org.cn/docs/api#introduction
-
-
-
-
\ No newline at end of file
diff --git a/docs/Bot市场/bot配置.md b/docs/Bot市场/bot配置.md
deleted file mode 100644
index 0999a33..0000000
--- a/docs/Bot市场/bot配置.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_label: 'bot配置'
-sidebar_position: 2
----
-
-# Bot配置
-
-Bot配置是开发者进行bot维护和配置的重要模块，主要包括bot基本信息维护、权限&订阅事件管理、高级选项配置等功能。
-
-Bot的基本信息维护中，开发者可以看到bot的各项基本信息，并可以根据需要对bot的头像，名称，Webhook地址等进行修改。
-
-
-
-Bot的权限&订阅事件管理中，开发者可根据对仓库资源的访问需要为bot分配不同的权限和等级，比如增加代码库权限，将拉取请求的写权限变为读权限等。开发者还能更改当前bot订阅的事件列表，比如订阅代码库推送，取消拉取请求分配订阅等，以实现bot功能的更新与升级。
-
-
-
-
-Bot高级选项配置中，开发者可以改变bot的公私有状态，从而影响到bot的使用范围。需要注意的是，公开状态下的bot在已有其他仓库安装的情况下不能变成私有。开发者可选择将bot上架到市场，需要填写上架信息，包括市场简介，主要功能，次要功能等各项信息。
-
-开发者还能进行bot的删除和转让操作，发起转让意味着更改bot的所有权，需要输入接受者的用户名。在接受者确定接受后，即可完成bot的所有权变更，拒绝则会取消本次的转让操作。
-
-
diff --git a/docs/DevOps引擎/_category_.json b/docs/DevOps引擎/_category_.json
deleted file mode 100644
index 813fd86..0000000
--- a/docs/DevOps引擎/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "DevOps引擎(Engine)",
- "position": 6
-}
diff --git a/docs/DevOps引擎/代码流水线.md b/docs/DevOps引擎/代码流水线.md
deleted file mode 100644
index 671fcd3..0000000
--- a/docs/DevOps引擎/代码流水线.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-sidebar_label: '代码流水线'
-sidebar_position: 5
----
-# 代码流水线
- 可以通过代码的形式(YAML格式)来配置流水线，首先选择代码流水线和对应的分支：
-
- 
-
- 编辑流水线代码，其流水线名称描述、触发器、全局参数、执行串行/并发和流水线编排等概念同图形流水线，具体描述如下：
-
-
\ No newline at end of file
diff --git a/docs/DevOps引擎/参数配置.md b/docs/DevOps引擎/参数配置.md
deleted file mode 100644
index 493ea0e..0000000
--- a/docs/DevOps引擎/参数配置.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-sidebar_label: '参数配置'
-sidebar_position: 2
----
-
- # 参数配置
-
- 可在流水线中使用，实现动态参数配置；有字符串、数字、布尔三种类型。
-
- 
-
-
-在流水线的配置中通过如下方式获取参数：
-
- 
\ No newline at end of file
diff --git a/docs/DevOps引擎/图形流水线.md b/docs/DevOps引擎/图形流水线.md
deleted file mode 100644
index 1c6cdbe..0000000
--- a/docs/DevOps引擎/图形流水线.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-sidebar_label: '图形流水线'
-sidebar_position: 4
----
-
- # 图形流水线
- ## 基本信息
-可以编辑流水线的名称、描述
-
-同一仓库下的流水线名称不能重复
-
-
-
-## 触发器
-注：流水线编排时，触发器要放在开始节点之前；目前一条流水线仅添加支持一个触发器
-
-* 定时触发器cron：可通过填写cron表达式设置触发的具体时间
-
-
-* 事件触发器GitLink_Webhook：给出了常见的代码变更事件触发，包括推送代码、合并请求、创建标签
-
-
-## 全局参数
-
-添加后可在当前流水线中使用
-
-
-
-使用实例
-
-
-
-## 并发执行
-
-
-
-开启后，同一流水线可同时并发执行n个流水线实例（每触发一次我们得到一个流水线实例）；
-
-
-
-若未开启，则当前流水线实例执行中，后面的实例处于排队状态（最多可排队5个实例）。当前实例执行完成，下一个实例开始执行。
-
-
-
-
-## 流水线编排
-
-每条流水线必须要有一个开始节点、结束节点，至少一个任务节点。支持串行编排和并行编排。
-
-
diff --git a/docs/DevOps引擎/密钥设置.md b/docs/DevOps引擎/密钥设置.md
deleted file mode 100644
index b28b953..0000000
--- a/docs/DevOps引擎/密钥设置.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-sidebar_label: '密钥设置'
-sidebar_position: 3
----
-
- # 密钥设置
-
-将账号密码、密钥、证书等存放到密钥管理里，配置后可直接在流水线中使用，避免因直接填写引起的泄露风险。
-
-
-
-使用示例
-
-注：节点输入参数中，下拉选项为密钥类型，需要提前配置好密钥在流水线中选择使用
-
-
\ No newline at end of file
diff --git a/docs/DevOps引擎/引擎简介.md b/docs/DevOps引擎/引擎简介.md
deleted file mode 100644
index e63549a..0000000
--- a/docs/DevOps引擎/引擎简介.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-sidebar_label: '引擎简介'
-sidebar_position: 1
----
-
- # 引擎
-
-引擎(Engine)是GitLink提供的一款DevOps工具，通过简单的节点编排来构建开发、测试、部署流水线，从而创建自动化的软件交付流程。
-它可以实现持续的代码集成，让开发者能尽早发现质量问题，快速定位修复，提升软件开发效率和质量；自动化的代码扫描、编译打包、单元测试，把研发团队从重复的工作中解放出来，聚焦到更有价值的事情上。
-
-
-
-在引擎页面中，用户可以创建和编辑图形流水线或代码流水线、设置外部参数、管理密钥等操作。
\ No newline at end of file
diff --git a/docs/DevOps引擎/执行记录查询.md b/docs/DevOps引擎/执行记录查询.md
deleted file mode 100644
index 30ca593..0000000
--- a/docs/DevOps引擎/执行记录查询.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-sidebar_label: '执行记录查询'
-sidebar_position: 6
----
-
- # 执行记录查询
-
- 用户可以查看流水线的运行状态
-
- 
\ No newline at end of file
diff --git a/docs/admin-portal/audit-logs.md b/docs/admin-portal/audit-logs.md
new file mode 100644
index 0000000..aa41971
--- /dev/null
+++ b/docs/admin-portal/audit-logs.md
@@ -0,0 +1,91 @@
+---
+title: Manage Audit logs Admin Portal
+sidebar_label: Audit Logs
+---
+
+# Admin Portal
+
+Retraced can be accessed using Admin interface that allows you to manage Projects & Environments via UI. To enable the Admin Portal, make sure you deploy [Retraced with Docker Compose](../retraced/self-host/docker.md)
+
+You can open the Admin Portal on port `5225`.
+
+## Sign into Admin Portal
+
+We use [Magic Links](https://next-auth.js.org/providers/email) to authenticate users to the UI.
+
+You'll need to set the following configuration in the [environment](../jackson/deploy/env-variables.md#admin-ui-configuration):
+
+1. SMTP Server details, so we can send you the email with the magic link.
+2. Access Control List which is an array of emails or glob patterns. Only these users will be allowed access to the Admin Portal. Example: `tonystark@gmail.com,*@marvel.com`.
+
+Follow the below steps to login into the Admin dashboard.
+
+- Visit the path `/api/auth/signin` on your app. The page will display a sign-in page with a text box to enter the email address.
+- Enter the email address that matches the `NEXTAUTH_ACL` and click the button **Sign in with Email**.
+- Open the inbox and you'll see an email from Jackson.
+- Open that email and click the button **Sign in**. Now you've successfully logged into the BoxyHQ Admin Portal.
+- Click on the Audit Logs menu from the sidebar on the left to access the Retraced service.
+
+## Fresh Start
+
+When you are setting up the Audit logs for the first time with Retraced, you won't have any **Projects** in the system or in case you run bootstrap script as a part of your deployment you will have **dev** project.
+
+
+
+## Create Project
+
+Just click on **Create Project** or **Add Project** button to initiate new Project creation.
+You just need to enter the name of the project and click on **Create Project** button.
+
+
+
+## Project Information
+
+You will get see the **Project Information** after the Project is created.
+This page shows,
+
+1. Project ID
+2. Production Token
+3. Staging Token
+4. Publisher API Base URL
+5. POST request URL to ingest your events
+6. Example CURL command to send test events
+
+
+
+## Send test event with CURL
+
+You can copy and paste the curl command in terminal or command prompt.
+After execution of command you should see **id & hash** as output.
+
+
+
+## Project List
+
+Now if you click on Audit Logs you should see newly created Project there.
+
+You can perform following actions:
+
+- You can click on first button under actions the **tools** button to open the **Project Information** page.
+- You can click on second button under actions, the button with **magnifying glass** to see the **logs**.
+
+
+
+## Select Environment & Group
+
+When you create a Project by default following environments are created
+
+- Production
+- Staging
+
+Every Environment can have multiple Tenants.
+
+
+
+## View Logs
+
+Once you select the Environment you will see the Tenants listed in the dropdown.
+For this example you will see **BoxyHQ** listed in the dropdown for **Staging Environment**.
+Once you select the **Tenant** you will the logs listed down on the page.
+
+
diff --git a/docs/admin-portal/directory-sync.md b/docs/admin-portal/directory-sync.md
new file mode 100644
index 0000000..be5d367
--- /dev/null
+++ b/docs/admin-portal/directory-sync.md
@@ -0,0 +1,81 @@
+---
+title: Manage Directory Sync using Admin Portal
+sidebar_label: Directory Sync
+---
+
+# Manage Directories
+
+On the Admin Portal **Directory Sync** menu, you can see the Directory connections.
+
+## Create Directory Sync connection
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. Click **Create New**.
+3. Enter the following information:
+ - Enter **Directory name**
+ - Select the **Directory provider** from the list of [available providers](../directory-sync/providers/).
+ - Add the **Tenant**
+ - Add the **Product**
+ - Enter the **Webhook URL**
+ - Enter the **Webhook secret**
+
+
+
+---
+
+## Update Directory Sync connection
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. From the list of directory sync connections, click edit icon.
+3. You can update the following information:
+ - Enter **Directory name**
+ - Enter the **Webhook URL**
+ - Enter the **Webhook secret**
+ - Toggle **Enable Webhook events logging**
+
+
+
+---
+
+## View directory users
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. From the list of directory sync connections, click database icon.
+3. Click the tab **Users**.
+4. Click the eye icon to view the user raw JSON data.
+
+
+
+---
+
+## View directory groups
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. From the list of directory sync connections, click database icon.
+3. Click the tab **Groups**.
+4. Click the eye icon to view the group raw JSON data.
+
+
+
+---
+
+## View webhook events
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. From the list of directory sync connections, click database icon.
+3. Click the tab **Webhook Events**.
+4. Click the eye icon to view the event raw JSON data.
+
+
+
+Click the button **Clear Events** to delete all events from the database.
+
+---
+
+## Enable webhook events logging
+
+1. From your Admin Portal, go to **Directory Sync**.
+2. From the list of directory sync connections, click edit icon.
+3. You can enable or disable the **Enable Webhook events logging**.
+
+By default, the webhook events are not logged.
diff --git a/docs/admin-portal/enterprise-sso.md b/docs/admin-portal/enterprise-sso.md
new file mode 100644
index 0000000..e8335b0
--- /dev/null
+++ b/docs/admin-portal/enterprise-sso.md
@@ -0,0 +1,90 @@
+---
+title: Manage Enterprise SSO using Admin Portal
+sidebar_label: Enterprise SSO
+---
+
+# Manage SSO Connections
+
+On the Admin Portal **Enterprise SSO** menu, you can see the SSO Connections details.
+
+## Add SAML Connections
+
+Once you've set up the SAML app on your Identity Provider, the Identity Provider will generate a SAML Metadata file.
+
+The SAML metadata file contains information about the various SAML Authorities that can be used in SAML 2.0 protocol message exchanges.
+
+Download the SAML Metadata file from your IdP and follow the below steps for adding the SAML connection.
+
+- Click the button **New Connection**.
+- Choose **SAML** as the type.
+- Give your new connection a **name**.
+- Add your **Tenant** (Eg: boxyhq.com) and **Product** (Eg: flex).
+- Add **Allowed redirect URLs**.
+- Add **Default redirect URL**.
+- Paste the **Raw IdP XML**.
+- If **ForceAuthn** is checked, it means that the user will be forced to re-authenticate at SAML IdP, even if they have an active session.
+- Click the button **Save Changes**.
+
+Now you've successfully added your first SAML connection.
+
+## Add OIDC Connections
+
+Once you've registered the OIDC app on your Identity Provider, the Identity Provider will generate a clientId and clientSecret.
+
+The `clientSecret` will be used to authenticate the oidc client (in this case jackson) and obtain the `access_token`.
+
+Also get the OpenID provider [discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) endpoint (usually ending in `/.well-known/openid-configuration`) and follow the below steps for adding the OIDC connection.
+
+- Click the button **New Connection**.
+- Choose **OIDC** as the type.
+- Give your new connection a **name**.
+- Add your **Tenant** (Eg: boxyhq.com) and **Product** (Eg: flex).
+- Add **Allowed redirect URLs**.
+- Add **Default redirect URL**.
+- Enter the URL for OpenID Provider discovery which exposes the Provider Metadata.
+- Paste the **clientId** and **clientSecret** values into Client ID [OIDC Provider]/Client Secret [OIDC Provider] fields in the UI.
+- Click the button **Save Changes**.
+
+Now you've successfully added your first OIDC connection.
+
+## SAML Federation
+
+SAML Federation is an enterprise feature and you need to have an enterprise license to use this feature.
+
+From the **Admin Portal** go to **Enterprise SSO** > **SAML Federation**.
+
+### Create SAML Federation App
+
+- Click **New App**.
+- Enter the following information:
+ - **Name**
+ - **Tenant**
+ - **Product**
+ - **ACS URL** (ACS URL of the SP)
+ - **Entity ID** (Entity ID of the SP)
+
+
+
+---
+
+### Update SAML Federation App
+
+- From the list of SAML Federation Apps, click on the **Edit** icon of the app you want to update.
+- You can update the following information:
+ - **Name**
+ - **ACS URL** (ACS URL of the SP)
+ - **Entity ID** (Entity ID of the SP)
+
+
+
+---
+
+### View IdP Configuration
+
+Click **View IdP Configuration** button to view the IdP configuration for the SAML Federation App. You need to provide the SP with the following information:
+
+- **SSO URL**
+- **Entity ID / Audience URI / Audience Restriction**
+- **X.509 Certificate**
+
+
diff --git a/docs/admin-portal/overview.md b/docs/admin-portal/overview.md
new file mode 100644
index 0000000..5caff7a
--- /dev/null
+++ b/docs/admin-portal/overview.md
@@ -0,0 +1,77 @@
+---
+title: Get Started with Admin Portal
+sidebar_label: Get Started
+---
+
+# Get Started with Admin Portal
+
+SAML Jackson comes with an Admin Portal that allows you to manage **Enterprise SSO**, **Directory Sync**, **Setup Links**, and **Audit Logs** products via an easy to use web interface.
+
+Our future products (where relevant) will also be available in the Admin Portal.
+
+To enable the Admin Portal, make sure you deploy [Jackson as a service](../jackson/deploy/service).
+
+## Authentication Methods
+
+BoxyHQ SAML Jackson supports multiple authentication methods. You can choose to use any of the following methods to authenticate users to the Admin Portal.
+
+We use [NextAuth](https://next-auth.js.org) to handle authentication. Set the following environment variables to configure the authentication.
+
+- `NEXTAUTH_URL`: The URL of your app.
+- `NEXTAUTH_SECRET`: A secret used to encrypt the session cookie. You can generate one using `openssl rand -base64 32`
+
+### 1. Magic Links
+
+With Magic Links, you can sign in to the Admin Portal without having to enter a password. The app will send you an email with a link to sign in. You'll need **SMTP server credentials** to send emails.
+
+Configure the following environment variables to enable Magic Links.
+
+- `SMTP_HOST`: SMTP server host
+- `SMTP_PORT`: SMTP server port
+- `SMTP_USER`: SMTP server username
+- `SMTP_PASSWORD`: SMTP server password
+- `SMTP_FROM`: From email address to use when sending Magic Link emails
+- `NEXTAUTH_ACL`: An array of emails or glob patterns. Only these users will be allowed access to the Admin Portal. For example: `NEXTAUTH_ACL=tonystark@gmail.com,*@marvel.com`
+
+Follow the below steps to login into the Admin Portal.
+
+- Visit the path `/api/auth/signin` on your app.
+- Enter the email address that matches the `NEXTAUTH_ACL` and click the button **Send Magic Link**.
+- Open the inbox and you'll see an email from SAML Jackson.
+- Open that email and click the button **Sign in**.
+
+### 2. Email and Password
+
+With Email and Password, you can sign in to the Admin Portal using an email address and password. You can use it as an alternative to Magic Links or SAML Single Sign-On. This is the easiest way to get started with the Admin Portal.
+
+Configure the environment variable to enable Email and Password authentication.
+
+- `NEXTAUTH_ADMIN_CREDENTIALS`: A comma separated list of email and password pairs. For example: `david@acme.com:secretpassword,john@acme.com:anotherpassword`
+
+At the moment, set the password as plain text. We'll add support for encrypted passwords soon.
+
+Follow the below steps to login into the Admin Portal.
+
+- Visit the path `/api/auth/signin` on your app.
+- Enter the email address and password that matches the `NEXTAUTH_ADMIN_CREDENTIALS` and click the button **Sign In**.
+
+### 3. SAML/OIDC Single Sign-On
+
+With SAML/OIDC Single Sign-On, you can sign in to the Admin Portal using your Identity Provider. The app will redirect you to your Identity Provider to sign in. Once you've signed in, you'll be redirected back to the Admin Portal.
+
+Configure the following environment variables to enable SAML/OIDC Single Sign-On.
+
+- `ADMIN_PORTAL_SSO_TENANT`: This will be used as the tenant for the SSO connections. Set this to a value that is less likely to conflict with the main Enterprise SSO connections.
+- `ADMIN_PORTAL_SSO_PRODUCT`: This will be used as the product for the SSO connections. Set this to a value that is less likely to conflict with the main Enterprise SSO connections.
+
+If not set, the default values will be used which are `_jackson_boxyhq` and `_jackson_admin_portal`.
+
+To enable SAML/OIDC Single Sign-On, you'll need to access the Admin Portal using either [Magic Links](#1-magic-links) or [Email and Password](#2-email-and-password). Once you've logged in, you can configure SAML/OIDC Single Sign-On from the Admin Portal.
+
+Go to **Settings** > **SSO for Admin Portal** and add a new SSO connection. We support both SAML and OIDC protocols.
+
+Follow the below steps to login into the Admin Portal.
+
+- Visit the path `/api/auth/signin` on your app.
+- Click the button **Login with SSO**.
+- You'll be redirected to your SAML Identity Provider to sign in for the authentication and then redirected back to the Admin Portal.
diff --git a/docs/admin-portal/setup-links/directory-sync.md b/docs/admin-portal/setup-links/directory-sync.md
new file mode 100644
index 0000000..ed03745
--- /dev/null
+++ b/docs/admin-portal/setup-links/directory-sync.md
@@ -0,0 +1,64 @@
+---
+title: Setup Link (Directory-Sync)
+sidebar_label: Directory Sync
+description: Setup Link to create a Directory Sync
+---
+
+# Setup Link (Directory Sync)
+
+The Setup link is used to create a shareable link that can be used to create an Directory Sync without exposing any sensitive information.
+Let's go through the steps to create a new Setup link
+
+## Create Setup Link
+
+You can create a new Setup link for Directory Sync from the Connections page using `New Setup Link` button
+
+
+
+Another way is to go to the `Setup Links` section under `Directory Sync` menu and Click on Create New/New Setup Link button
+
+
+
+The create Setup Link for Directory Sync page looks like below
+
+
+
+Once the link is created you can see the the link info section at the bottom
+
+
+
+You can copy the link by clicking on the `Copy` button
+
+
+
+### Regenerate Link
+
+You can regenerate the link by clicking on `Regenerate` button
+
+
+
+Once you confirm Regenerate action you will see the new setup link in the link info section
+
+
+
+### Actions from Setup Link list page
+
+You can perform `ACTIONS` like `Copy`, `View`, `Regenerate` & `Delete` from this page
+
+
+
+### Setup Link Page
+
+When you open the setup link you will see the following
+
+
+
+### Create Directory Sync Connection
+
+You can open create Directory Sync by clicking on `New Directory` button & filling the correct details
+
+
+
+After creation of the directory sync you will see the info section
+
+
diff --git a/docs/admin-portal/setup-links/index.md b/docs/admin-portal/setup-links/index.md
new file mode 100644
index 0000000..f6b8392
--- /dev/null
+++ b/docs/admin-portal/setup-links/index.md
@@ -0,0 +1,9 @@
+# Setup Link
+
+Admin portal can be used to create setup links for
+
+- [Enterprise SSO](./jackson)
+- [Directory-Sync](./directory-sync)
+
+Setup links can be shared with anyone to let them set up connections for the products.
+These links come in handy for admins to facilitate setup by non-admin users without revealing any sensitive information or giving admin access unnecessarily.
diff --git a/docs/admin-portal/setup-links/jackson.md b/docs/admin-portal/setup-links/jackson.md
new file mode 100644
index 0000000..2b1af6b
--- /dev/null
+++ b/docs/admin-portal/setup-links/jackson.md
@@ -0,0 +1,68 @@
+---
+title: Setup Link (Enterprise SSO)
+sidebar_label: Enterprise SSO
+description: Setup Link to create a SSO Connection
+---
+
+# Setup Link (Enterprise SSO)
+
+The Setup link is used to create a shareable link that can be used to create an SSO Connection without exposing any sensitive information.
+Let's go through the steps to create a new Setup link
+
+## Create Setup Link
+
+You can create a new Setup link for SSO from the Connections page using `New Setup Link` button
+
+
+
+Another way is to go to the `Setup Links` section under `Enterprise SSO` menu and Click on Create New/New Setup Link button
+
+
+
+The create Setup Link for SSO page looks like below
+
+
+
+Once the link is created you can see the the link info section at the bottom
+
+
+
+You can copy the link by clicking on the `Copy` button
+
+
+
+### Regenerate Link
+
+You can regenerate the link by clicking on `Regenerate` button
+
+
+
+Once you confirm Regenerate action you will see the new setup link in the link info section
+
+
+
+### Actions from Setup Link list page
+
+#### You can perform `ACTIONS` like `Copy`, `View`, `Regenerate` & `Delete` from this page
+
+Regenerate
+
+
+
+Delete
+
+
+
+### Setup Link page
+
+When you open the setup link you will be landed on SSO Connection create section as there are no connections to show
+
+
+
+### Create SSO Connection with Setup Link
+
+You can create SSO Connection by filling the correct details
+
+
+
+As you can see that setup link makes it super easy & safe to create SSO Connections.
diff --git a/docs/directory-sync/api-reference.md b/docs/directory-sync/api-reference.md
new file mode 100644
index 0000000..29c2228
--- /dev/null
+++ b/docs/directory-sync/api-reference.md
@@ -0,0 +1,648 @@
+---
+title: Directory Sync API Reference
+sidebar_label: API Reference
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# API Reference
+
+The following guides provide information about the APIs and SDKs that are available for the Directory Sync service.
+
+### Directory
+
+#### Properties
+
+- `name`: The name of the directory
+- `tenant`: The tenant ID of the tenant you want to create the directory for.
+- `product`: The product ID of the product you want to create the directory for.
+- `type`: The directory provider type. See the [Directory Providers](./providers) for more information.
+- `webhook_url`: The webhook URL to which the directory connection will POST the events.
+- `webhook_secret`: The webhook secret used to sign the webhook payload.
+
+:::info
+The `tenant` and `product` should not contain the `:` character since we use it as a delimiter internally.
+:::
+
+### Initialize Directory Sync
+
+```javascript
+const opts = {
+ externalUrl: 'https://my-cool-app.com',
+ db: {
+ engine: 'mongo',
+ url: 'mongodb://localhost:27017/my-cool-app',
+ },
+};
+
+let directorySyncController;
+
+// Please note that the initialization of @boxyhq/saml-jackson is async, you cannot run it at the top level.
+async function init() {
+ const jackson = await require('@boxyhq/saml-jackson').controllers(opts);
+
+ directorySyncController = jackson.directorySyncController;
+}
+```
+
+### Create a new directory
+
+Create a new directory connection.
+
+#### Request
+
+
+
+
+user.created - New user has been assigned to the app.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "user.created", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "038e767b-9bc6-4dbd-975e-fbc38a8e7d82", + "first_name": "Deepak", + "last_name": "Prabhakara", + "email": "deepak@boxyhq.com", + "active": true, + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "deepak@boxyhq.com", + "name": { + "givenName": "Deepak", + "familyName": "Prabhakara" + }, + "emails": [ + { + "primary": true, + "value": "deepak@boxyhq.com", + "type": "work" + } + ], + "title": "CEO", + "displayName": "Deepak Prabhakara", + "locale": "en-US", + "externalId": "00u1ldzzogFkXFmvT5d7", + "groups": [], + "active": true, + "id": "038e767b-9bc6-4dbd-975e-fbc38a8e7d82" + } + } +} +``` + +
+ +
+
+
+user.updated - A user's properties has been updated.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "user.updated", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "first_name": "Kiran", + "last_name": "Krishnan", + "email": "kiran@boxyhq.com", + "active": true, + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "kiran@boxyhq.com", + "name": { + "givenName": "Kiran", + "familyName": "Krishnan" + }, + "emails": [ + { + "primary": true, + "value": "kiran@boxyhq.com", + "type": "work" + } + ], + "displayName": "Kiran Krishnan", + "addresses": [ + { + "primary": true, + "region": "Kerala" + } + ], + "locale": "en-US", + "externalId": "00u3e3cmpdDydXdzV5d7", + "active": true, + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "groups": [] + } + } +} +``` + +
+
+
+
+## Group Events
+
+We'll notify you of the following 5 events related to groups and memberships. Each event will be sent to the webhook URL you've configured in the Directory Sync app.
+
+user.deleted - A user has been removed from the Directory Provider.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "user.deleted", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "first_name": "Kiran", + "last_name": "Krishnan", + "email": "kiran@boxyhq.com", + "active": false, + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "kiran@boxyhq.com", + "name": { + "givenName": "Kiran", + "familyName": "Krishnan" + }, + "emails": [ + { + "primary": true, + "value": "kiran@boxyhq.com", + "type": "work" + } + ], + "displayName": "Kiran Krishnan", + "addresses": [ + { + "primary": true, + "region": "Kerala" + } + ], + "locale": "en-US", + "externalId": "00u3e3cmpdDydXdzV5d7", + "active": false, + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "groups": [] + } + } +} +``` + +
+
+
+
+group.created - New group has been added to the app.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "group.created", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6", + "name": "dev", + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "dev", + "members": [], + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6" + } + } +} +``` + +
+
+
+
+group.updated - A group's properties has been updated.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "group.updated", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6", + "name": "developers", + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "developers", + "members": [], + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6" + } + } +} +``` + +
+
+
+
+group.deleted - A group has been removed from the app.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "group.deleted", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6", + "name": "developers", + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "developers", + "members": [], + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6" + } + } +} +``` + +
+
+
+
+group.user_added - A user has been added to a directory group.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "group.user_added", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "first_name": "Kiran", + "last_name": "Krishnan", + "email": "kiran@boxyhq.com", + "active": true, + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "kiran@boxyhq.com", + "name": { + "givenName": "Kiran", + "familyName": "Krishnan" + }, + "emails": [ + { + "primary": true, + "value": "kiran@boxyhq.com", + "type": "work" + } + ], + "displayName": "Kiran Krishnan", + "addresses": [ + { + "primary": true, + "region": "Kerala" + } + ], + "locale": "en-US", + "externalId": "00u3e3cmpdDydXdzV5d7", + "active": true, + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "title": "Developer", + "groups": [] + }, + "group": { + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6", + "name": "developers", + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "developers", + "members": [], + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6" + } + } + } +} +``` + +
+
+
+
+## Directory Events
+
+We'll notify you of the following 4 events related to the directory connections.
+
+To configure the webhook, you have to set the following environment variables.
+
+- `WEBHOOK_URL` - The URL to which the webhook events will be sent.
+- `WEBHOOK_SECRET` - The secret key used to sign the webhook events.
+
+group.user_removed - A user has been removed from a directory group.
++ +```json +{ + "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "event": "group.user_removed", + "tenant": "boxyhq", + "product": "jackson", + "data": { + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "first_name": "Kiran", + "last_name": "Krishnan", + "email": "kiran@boxyhq.com", + "active": true, + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "kiran@boxyhq.com", + "name": { + "givenName": "Kiran", + "familyName": "Krishnan" + }, + "emails": [ + { + "primary": true, + "value": "kiran@boxyhq.com", + "type": "work" + } + ], + "displayName": "Kiran Krishnan", + "addresses": [ + { + "primary": true, + "region": "Kerala" + } + ], + "locale": "en-US", + "externalId": "00u3e3cmpdDydXdzV5d7", + "active": true, + "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", + "title": "Developer", + "groups": [] + }, + "group": { + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6", + "name": "developers", + "raw": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "developers", + "members": [], + "id": "29e3adde-b4bb-45fc-bf65-2b44f29fd6f6" + } + } + } +} +``` + +
+
+
+
++ dsync.created - New connection has been created. +
++ +```json +{ + "event": "dsync.created", + "tenant": "boxyhq", + "product": "demo", + "data": { + "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44", + "name": "Okta Directory", + "type": "okta-scim-v2" + } +} +``` + +
+
+
+
++ dsync.deactivated - A connection has been deactivated. +
++ +```json +{ + "event": "dsync.deactivated", + "tenant": "boxyhq", + "product": "demo", + "data": { + "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44", + "name": "Okta Directory", + "type": "okta-scim-v2" + } +} +``` + +
+
+
+
++ dsync.activated - A connection has been activated. +
++ +```json +{ + "event": "dsync.activated", + "tenant": "boxyhq", + "product": "demo", + "data": { + "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44", + "name": "Okta Directory", + "type": "okta-scim-v2" + } +} +``` + +
+
+
+
+## Frequently Asked Questions
+
+### How to determine whether a user has been deleted if the Identity Provider does not send a webhook event for user deletion?
+
+To receive notifications when a user is deleted, it's important to note that not all Identity Providers send requests for this. However, you can listen for the `user.updated` event from SAML Jackson and examine the `active` property to determine whether a user has been deleted. In case the user is deleted, the `active` property will be assigned the value `false`.
+
+### Which Identity Providers do not send an event for user deletion?
+
+Following Identity Providers do not send `user.deleted` event:
+
+- Okta
+- Azure AD
+
+### Which SCIM version does SAML Jackson support?
+
+At the moment, SAML Jackson supports SCIM version 2.0.
diff --git a/docs/directory-sync/examples.md b/docs/directory-sync/examples.md
new file mode 100644
index 0000000..584371a
--- /dev/null
+++ b/docs/directory-sync/examples.md
@@ -0,0 +1,16 @@
+---
+title: Examples & Resources (Directory Sync)
+sidebar_label: Examples & Resources
+description: Examples & Resources for our Directory Sync product
+---
+
+# Examples & Resources (Directory Sync)
+
+## Examples
+
+- [Directory Sync with Next.js](https://github.com/boxyhq/jackson-examples/tree/main/apps/directory-sync)
+- [Directory Sync (embedded as a library) with Next.js](https://github.com/boxyhq/jackson-examples/tree/main/apps/directory-sync-embedded)
+
+## Resources
+
+- [SCIM 2.0 Protocol](https://datatracker.ietf.org/doc/html/rfc7644)
diff --git a/docs/directory-sync/getting-started.md b/docs/directory-sync/getting-started.md
new file mode 100644
index 0000000..fdf74ee
--- /dev/null
+++ b/docs/directory-sync/getting-started.md
@@ -0,0 +1,29 @@
+---
+title: Getting Started
+sidebar_label: Getting Started
+---
+
+There are two ways to integrate the Directory Sync within your application.
+
+## As a service
+
+The advantage of running a separate service is that you get all of our UI tooling (like the Admin Portal) with the service. The disadvantage is that you have to manage the operations of a separate service.
+
+**If you are not using Node.js then this is the only option available to you.**
+
+Read more about [how to run the Jackson service](/docs/jackson/deploy/service)
+
+Jackson use webhooks to notify your application any time changes are made to directory users and groups. You can use webhooks to trigger actions in your application, such as creating a new user in your application, or updating a user in your application based on the changes made in the directory.
+
+## As an NPM library
+
+This is available if you are already developing your application using Node.js.
+
+The advantage of embedding Jackson as an NPM library is that you do not have to manage operations of a separate service.
+The disadvantage is that you do not readily get our UI tooling (like the Admin Portal) with this method.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+See the [API Reference](/docs/directory-sync/api-reference) to understand more about the available methods.
diff --git a/docs/directory-sync/overview.md b/docs/directory-sync/overview.md
new file mode 100644
index 0000000..19db417
--- /dev/null
+++ b/docs/directory-sync/overview.md
@@ -0,0 +1,23 @@
+---
+title: Directory Sync Docs
+---
+
+# Directory Sync
+
+Directory sync helps organizations automate the provisioning and de-provisioning of their users. It is based on the System for Cross-domain Identity Management (SCIM) protocol.
+
+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.
+
+Directory Sync is part of our SAML Jackson service (and npm library) from v1.2.1 onwards. Follow the instructions in [SAML Jackson](../jackson/deploy/index.md) for details on deployment. Or check out our [GitHub repo](https://github.com/boxyhq/jackson#directory-sync).
+
+We currently only support SCIM 2.0 protocol because SCIM 1.1 is deprecated and support will be discontinued on December 2nd, 2022. If you still need support for SCIM 1.1 and are unable to move away from it then please contact us.
+
+
+
+## Overview
+
+- [API Reference](api-reference)
+- [Admin Portal](../admin-portal/directory-sync)
+- [Webhook](webhooks)
+- [Events and Types](events)
+- [Directory Sync Providers](providers)
diff --git a/docs/directory-sync/providers/azure.md b/docs/directory-sync/providers/azure.md
new file mode 100644
index 0000000..ec5070e
--- /dev/null
+++ b/docs/directory-sync/providers/azure.md
@@ -0,0 +1,74 @@
+---
+title: Azure AD SCIM v2.0
+sidebar_label: Azure SCIM v2.0
+---
+
+# Azure AD SCIM v2.0
+
+The following guide will walk you through the process of configuring SAML Jackson to use the Azure AD SCIM v2.0 directory provider.
+
+---
+
+### Create Azure Application
+
+Click **Azure Active Directory** from the Microsoft Azure Portal.
+
+
+
+Click **Enterprise Applications** from the left navigation menu.
+
+
+
+If your application is already created, choose it from the list and move to the section [Enable SCIM Provisioning](#enable-azure-scim-provisioning)
+
+If you haven't created your application yet, click **New application** button.
+
+
+
+From the next screen, click **Create your own application**, give your application a **name** and click the **Create** button.
+
+
+
+---
+
+### Enable Azure SCIM Provisioning
+
+Click **Provisioning** from the left navigation menu then click **Get started**.
+
+
+
+Select **Automatic** from the **Provisioning Mode** dropdown and enter the following information under **Admin Credentials** section:
+
+- Tenant URL
+- Secret Token
+
+Next, click the **Test Connection** button to test the connection to see if the credentials are correct, then click **Save** to save the credentials.
+
+
+
+Expand the **Mappings** section and ensure group and user attribute mappings are enabled for your app. The default mapping should work.
+
+
+
+Expand the **Settings** section and make the following changes:
+
+- Select **Sync only assigned users and groups** from the **Scope** dropdown.
+- Confirm the **Provisioning Status** is set to **On**.
+
+
+
+At this stage, you've successfully configured the Azure AD SCIM API integration.
+
+---
+
+### Assign Users
+
+From your application, click the **Users and groups** from the left navigation menu and click **Add user/group**.
+
+
+
+Select **None Selected** under the **Users**.
+
+From the right side of the screen, select the users you want to assign to the app and click the **Select** button, then click **Assign** to those users to the app.
+
+
diff --git a/docs/directory-sync/providers/index.md b/docs/directory-sync/providers/index.md
new file mode 100644
index 0000000..29f4cdf
--- /dev/null
+++ b/docs/directory-sync/providers/index.md
@@ -0,0 +1,8 @@
+# Providers
+
+SAML Jackson supports the following directory providers:
+
+- [Azure SCIM v2.0](./azure)
+- [OneLogin SCIM v2.0](./onelogin)
+- [Okta SCIM v2.0](./okta)
+- [JumpCloud SCIM v2.0](./jumpcloud)
diff --git a/docs/directory-sync/providers/jumpcloud.md b/docs/directory-sync/providers/jumpcloud.md
new file mode 100644
index 0000000..730c05a
--- /dev/null
+++ b/docs/directory-sync/providers/jumpcloud.md
@@ -0,0 +1,60 @@
+---
+title: JumpCloud SCIM v2.0
+sidebar_label: JumpCloud SCIM v2.0
+---
+
+# JumpCloud SCIM v2.0
+
+The following guide will walk you through the process of configuring SAML Jackson to use the JumpCloud SCIM v2.0 directory provider.
+
+---
+
+### Create JumpCloud SAML Application
+
+JumpCloud only support configuring SCIM provisioning in an existing SAML application.
+
+Choose an existing SAML application or create a new one. Click **SSO** from the left navigation menu and select your custom SAML application.
+
+
+
+Click the tab **Identity Management** within your SAML application.
+
+Unde the **SCIM Version**, choose **SCIM 2.0** and enter the following information:
+
+- Base URL
+- Token Key
+- Test User Email
+
+Click **Test Connection** to test the connection to see if the credentials are correct then click **Activate**.
+
+Next click **Save** to save the settings.
+
+
+
+At this stage, you've successfully configured the JumpCloud SCIM app.
+
+---
+
+### Assign Users & Push Groups
+
+
+
+Click the tab **User Groups** within your SAML application.
+
+You can see the all the groups that are available, select the groups you want to sync and click **Save**.
+
+If no existing groups are available, click **User Groups** from the left navigation menu and click plus icon to create a new group.
+
+Give the group a name.
+
+
+
+Select the **Users** tab and choose the users you want to assign to the group.
+
+
+
+Next select the **Applications** tab and choose the app you want to assign the group to.
+
+
+
+At this stage, you've successfully assigned users and pushed the groups.
diff --git a/docs/directory-sync/providers/okta.md b/docs/directory-sync/providers/okta.md
new file mode 100644
index 0000000..0e3e62a
--- /dev/null
+++ b/docs/directory-sync/providers/okta.md
@@ -0,0 +1,81 @@
+---
+title: Okta SCIM v2.0
+sidebar_label: Okta SCIM v2.0
+---
+
+# Okta SCIM v2.0
+
+The following guide will walk you through the process of configuring SAML Jackson to use the Okta as a directory sync provider.
+
+---
+
+### Create Okta Application
+
+Click **Applications** from the left navigation menu and click **Browse App Catalog** button.
+
+
+
+Search for **SCIM 2.0 Test App (Oauth Bearer Token)** from the search box and choose the app called **SCIM 2.0 Test App (Oauth Bearer Token)**.
+
+
+
+From the app page, click the **Add Integration** button.
+
+
+
+Give the app a name and click the **Next** button. Click **Done** to finish the creation of the app.
+
+
+
+---
+
+### Enable Okta SCIM Provisioning
+
+In your application, click the **Provisioning** tab and click **Configure API Integration**.
+
+
+
+Check the **Enable API Integration** checkbox and enter the following information:
+
+- SCIM 2.0 Base URL
+- OAuth Bearer Token
+
+You'll receive these information from Jackson when you create the directory sync connection either via the API or the Admin Portal.
+
+Click **Test API Creditentials** to test the connection to see if the credentials are correct then click the **Save** to save the credentials.
+
+
+
+You'll see a new setting page, click **To App** and enable the following settings:
+
+
+
+At this stage, you've successfully configured the Okta SCIM API integration.
+
+---
+
+### Assign Users
+
+In your application, click the **Assignments** tab and select **Assign to People** from the dropdown **Assign**.
+
+
+
+Select users you want to assign to the app and click the **Assign** button.
+
+
+
+After you click the **Assign** button, you'll see a new popup window with various fields. Confirm the field values and click the **Save and Go Back** button.
+
+
+
+---
+
+### Push Groups
+
+Navigate to the tab **Push Groups** and select **Find group by name** from the dropdown **Push Groups**.
+
+
+
+Find the group you want to assign to the app and click the **Save** button.
+
+
diff --git a/docs/directory-sync/providers/onelogin.md b/docs/directory-sync/providers/onelogin.md
new file mode 100644
index 0000000..d6250b8
--- /dev/null
+++ b/docs/directory-sync/providers/onelogin.md
@@ -0,0 +1,121 @@
+---
+title: OneLogin SCIM v2.0
+sidebar_label: OneLogin SCIM v2.0
+---
+
+# OneLogin SCIM v2.0
+
+The following guide will walk you through the process of configuring SAML Jackson to use the OneLogin SCIM v2.0 directory provider.
+
+---
+
+### Create OneLogin Application
+
+Click **Applications** from the top navigation menu and click **Add App** button.
+
+
+
+Search for **SCIM** from the search box and choose the app called **SCIM Provisioner with SAML (SCIM V2 Enterprise)** from the list of apps.
+
+
+
+Give the app a name and click the **Save** button.
+
+
+
+At this stage, you've successfully created the OneLogin SCIM app.
+
+---
+
+### Enable OneLogin SCIM Provisioning
+
+In your application, click the **Configuration** tab on the left.
+
+Enter the following information:
+
+- SCIM Base URL
+- SCIM Bearer Token
+
+You'll receive these information from Jackson when you create the directory sync connection either via the API or the Admin Portal.
+
+Click the button **Enable** to test the connection to see if the credentials are correct and click the button to **Save** to save the creditentials.
+
+
+
+Next click the **Provisioning** tab and check the **Enable provisioning** checkbox. Click the **Save** button to save the changes.
+
+
+
+Next click the **Parameters** tab and select the row **Groups** from the table.
+
+
+
+In the popup window, check the box **Include in User Provisioning** and click the **Save** button.
+
+
+
+---
+
+### Assign Users
+
+In order to assign users to your app, select **Users** from the top navigation menu and choose the user you want to assign to the app.
+
+From the user page, click the **Application** tab on the left and click the plus sign.
+
+
+
+A popup window will show you the list of apps that you can assign the user to. Select the app you created earlier and click the **Continue** button.
+
+
+
+Click **Save** on the next modal window to confirm the assignment.
+
+
+
+Depending on your configuration, You may have to approve the assignment.
+
+If you see a text **Pending** in the table, click that text. That'll bring up a modal window, click the button **Approve** to approve the assignment.
+
+
+
+At this point, the user will be assigned to the app.
+
+---
+
+### Push Groups
+
+In order to push groups to your app, you've to create a new **Role** in your app.
+
+In the top navigation, select **Users** and then **Roles** from the dropdown.
+
+Click **New Role** to create a new role.
+
+
+
+Enter a name for the role, select the app you created earlier and click the **Save** button.
+
+
+
+Click the **Users** tab for the role and search for the user you want to assign the role to.
+
+Click the button **Add To Role** to assign the user to the role and click the **Save** button.
+
+
+
+Click **Save** in the next modal to confirm the assignment.
+
+
+
+Go back to your app and click the **Rule** tab on the left and click the **Add Rule** button.
+
+Give the rule a name. Under the **Actions**, select the **Set Groups in your-app-name** from the dropdown, then select for each **role** with values that matches **your-app-name**. Click the **Save** button.
+
+
+
+Click the **Users** tab on the left, you may see **Pending** provisions in the table. Click that text to approve the assignment.
+
+
+
+Click **Approve** in the next modal to confirm the assignment.
+
+
diff --git a/docs/directory-sync/webhooks.md b/docs/directory-sync/webhooks.md
new file mode 100644
index 0000000..6accb32
--- /dev/null
+++ b/docs/directory-sync/webhooks.md
@@ -0,0 +1,120 @@
+---
+title: Directory Sync Webhooks
+sidebar_label: Webhooks
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Webhooks
+
+A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system (Eg: your app), often with a payload of data.
+
+SAML Jackson use webhooks to notify your application any time changes are made to directory users and groups. You can use webhooks to trigger actions in your application, such as creating a new user in your application, or updating a user in your application based on the changes made in the directory.
+
+## Configure Webhooks
+
+SAML Jackson allows you to configure a webhook and secret while creating a directory sync connection either in the Admin Portal or the API. You can change the webhook and secret at any time.
+
+- [Admin Portal](../admin-portal/directory-sync)
+- [API Reference](api-reference#create-a-new-directory)
+
+## Receive Events
+
+SAML Jackson will make a POST request to your webhook endpoint when a change is made to a directory user or group. Your webhook endpoint should be able to receive the webhook request and respond with a 200 status code.
+
+You can start receiving events in your app using the below steps:
+
+- Create a webhook endpoint as an HTTP endpoint (URL) on your server.
+- Create a directory sync connection and configure a webhook endpoint.
+- Configure the SCIM app on your Identity Provider.
+- Handle the webhook request and respond with a 200 status code.
+
+To see the full list of events, please see the [Events and Types](events) page.
+
+Here is a sample webhook request look like:
+
+```json
+POST /your-webhook-endpoint
+Content-Type: application/json
+BoxyHQ-Signature: t=xxx,s=xxxx
+
+{
+ "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
+ "event": "user.created",
+ "tenant": "boxyhq",
+ "product": "jackson",
+ "data": {
+ "id": "038e767b-9bc6-4dbd-975e-fbc38a8e7d82",
+ "first_name": "Deepak",
+ "last_name": "Prabhakara",
+ "email": "deepak@boxyhq.com",
+ "active": true,
+ "raw": {...}
+ }
+}
+```
+
+:::caution
+If the webhook request fails, SAML Jackson will not retry the webhook request. A log will be created in the SAML Jackson Admin Portal if the you've enabled the webhook event logging.
+:::
+
+## Secure Webhooks
+
+Use the webhook signature (**BoxyHQ-Signature**) to verify the webhook request is from SAML Jackson. The signature is generated using the **webhook secret** you configured in the directory sync connection.
+
+Signature contains comma separated values of the following:
+
+- **t** The timestamp of the webhook request.
+- **s** The signature of the webhook request.
+
+An example of the webhook signature is below:
+
+```
+BoxyHQ-Signature: t=1545010989801,s=xxxx
+```
+
+## Verify Webhooks Signature
+
+You can verify the webhook signature by using the following steps:
+
+- Extract the **t** and **s** values from the webhook signature.
+- Create the signed payload string by concatenating:
+ - The timestamp (t)
+ - The character `.`
+ - The actual JSON payload
+- Compute the `HMAC-SHA256` hash of the signed payload string using your webhook secret.
+- Compare the signature in the request header with the computed signature.
+
+Once the signature is verified, you can use the webhook payload to perform any action in your application.
+
+```javascript showLineNumbers
+// Your webhook secret
+const secret = 'your-secret-here';
+
+// The signature header from the webhook request.
+const signatureHeader =
+ 't=1657016083300,s=9ece981128a8f2a96f95e3d0be68c37b825d5c15f5b8982e0b7e198a76621866';
+
+// JSON body from the webhook request.
+const body = {...}
+
+const [t, s] = signatureHeader.split(',');
+
+const signature = t.split('=')[1];
+const timestamp = s.split('=')[1];
+
+const signedPayload = `${timestamp}.${JSON.stringify(body)}`;
+
+const expectedSignature = crypto
+ .createHmac('sha256', secret)
+ .update(signedPayload)
+ .digest('hex');
+
+// Compare the expectedSignature to the signature
+if(signature === expectedSignature) {
+ // The webhook request is valid
+} else {
+ // The webhook request is invalid
+}
+```
diff --git a/docs/index.mdx b/docs/index.mdx
new file mode 100644
index 0000000..73d5aa1
--- /dev/null
+++ b/docs/index.mdx
@@ -0,0 +1,80 @@
+---
+title: Docs
+description: Check out our documentation to see how you can deploy our enterprise-ready solutions into your application with ease. Check out our SAML Jackson for Single sign-on.
+hide_table_of_contents: true
+---
+
+import Link from '@docusaurus/Link';
+
+Security Building Blocks for Developers
+
+Reduce Time to Market without sacrificing your security posture! BoxyHQ’s suite of APIs for security and privacy helps engineering teams build and ship compliant cloud applications faster. Integrate Single Sign-On (SSO), Audit Logs, Privacy Vault and Role Based Access in minutes. Open source and free.
+
++ dsync.deleted - A connection has been deleted. +
++ +```json +{ + "event": "dsync.deleted", + "tenant": "boxyhq", + "product": "demo", + "data": { + "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44", + "name": "Okta Directory", + "type": "okta-scim-v2" + } +} +``` + +
+
+
diff --git a/docs/intro.md b/docs/intro.md
deleted file mode 100644
index 5089392..0000000
--- a/docs/intro.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-sidebar_label: "介绍"
-label: "介绍"
-sidebar_position: 1
-slug: /
----
-
-# 关于GitLink
-GitLink（确实开源）是CCF官方指定的开源创新服务平台，旨在以“为开源创新服务”为使命，以“成为开源创新的汇聚地”为愿景，秉承“创新、开放、协作、共享”的价值观，致力于为大规模开源开放协同创新助力赋能，打造创新成果孵化和新工科人才培养的开源创新生态！
-
- 
-
-# 平台功能
-
-- **分布式协作开发**：支持在线文件编辑、分支管理、贡献统计、仓库复刻、合并请求；
-- **一站式过程管理**：支持疑修、里程碑、通知提醒、标签归档、Wiki文档、组织管理；
-- **高效流水线运维**：提供轻量级工作流引擎，并支持自定义配置、静态扫描、制品构建；
-- **多层次代码分析**：支持代码溯源分析、许可证风险分析、开源漏洞检测和加固建议；
-- **多维度用户画像**：支持开发活动统计、贡献日历、能力建模、角色与专业定位分析。
-
-# 帮助文档
-帮助文档有助于您全面了解GitLink平台，让我们一起为开源创新贡献力量！
-
-
+
+
+
+
+
+
+
+ Enterprise SSO
++ A SAML/OIDC SSO service designed as an OAuth 2.0 flow. Integrate SSO + with just a few lines of code. +
+
+
+
+
+
+
+ Directory Sync
++ Directory sync helps organizations automate the provisioning and + de-provisioning of their users. It is based on the SCIM 2.0 + protocol. +
+
+
+
+
+
+
+
+
+ Audit Logs
++ Retraced is the easiest way to integrate a compliant audit log into + your application. It provides a searchable, exportable record of + read/write events. +
+
+
+
+
+
+
+ Admin Portal
++ Manage our Enterprise SSO and Directory Sync products via an easy to + use web interface +
+
-
-
\ No newline at end of file
diff --git a/docs/jackson/container-signing.md b/docs/jackson/container-signing.md
new file mode 100644
index 0000000..ff1801b
--- /dev/null
+++ b/docs/jackson/container-signing.md
@@ -0,0 +1,21 @@
+# Container Signing and Verification
+
+Jackson container images are signed and can be verified using [cosign](https://github.com/sigstore/cosign).
+
+## Fetching our public key
+
+You can use [oras](https://oras.land/docs/category/cli) (or a similar OCI artifacts tool) to fetch our public key or download it from our website [here](https://boxyhq.com/.well-known/cosign.pub).
+
+```bash
+oras pull ghcr.io/boxyhq/cosign.pub:latest
+```
+
+## Container verification
+
+**Note:** This is supported for all versions >=1.6.0
+
+Our container images are hosted on [Docker Hub](https://hub.docker.com/r/boxyhq/jackson/tags). You can verify it by using the following command.
+
+```bash
+cosign verify --key cosign.pub boxyhq/jackson:',
+ state: '',
+});
+```
+
+
+
+
++ sso.created - New connection has been created. +
++ +```json +{ + "event": "sso.created", + "tenant": "boxyhq", + "product": "demo", + "data": { + "name": "SSO Connection", + "description": "SSO Connection for BoxyHQ", + "clientID": "326991705d478f0178fc2b49e35cd166dc771061", + "clientSecret": "15b2db91b2ba4c848b68148f108035e7138d69104d99de89", + "provider": "saml.example.com", + "friendlyProviderName": null + } +} +``` + +
+
+
+
++ sso.deactivated - A connection has been deactivated. +
++ +```json +{ + "event": "sso.deactivated", + "tenant": "boxyhq", + "product": "demo", + "data": { + "name": "SSO Connection", + "description": "SSO Connection for BoxyHQ", + "clientID": "326991705d478f0178fc2b49e35cd166dc771061", + "clientSecret": "15b2db91b2ba4c848b68148f108035e7138d69104d99de89", + "provider": "saml.example.com", + "friendlyProviderName": null + } +} +``` + +
+
+
+
++ sso.activated - A connection has been activated. +
++ +```json +{ + "event": "sso.activated", + "tenant": "boxyhq", + "product": "demo", + "data": { + "name": "SSO Connection", + "description": "SSO Connection for BoxyHQ", + "clientID": "326991705d478f0178fc2b49e35cd166dc771061", + "clientSecret": "15b2db91b2ba4c848b68148f108035e7138d69104d99de89", + "provider": "saml.example.com", + "friendlyProviderName": null + } +} +``` + +
+
+
+
+## Configure Webhook
+
+To configure the webhook, you have to set the following environment variables.
+
+- `WEBHOOK_URL` - The URL to which the webhook events will be sent.
+- `WEBHOOK_SECRET` - The secret key used to sign the webhook events.
diff --git a/docs/jackson/examples.md b/docs/jackson/examples.md
new file mode 100644
index 0000000..81dbeea
--- /dev/null
+++ b/docs/jackson/examples.md
@@ -0,0 +1,27 @@
+---
+title: Examples & Resources (Enterprise SSO)
+sidebar_label: Examples & Resources
+description: Examples & Resources for our Enterprise SSO product
+---
+
+# Examples & Resources (Enterprise SSO)
+
+## Examples
+
+- [Jackson with Next.js and NextAuth.js](https://github.com/boxyhq/jackson-examples/tree/main/apps/next-auth)
+- [Jackson with Remix and remix-auth](https://github.com/boxyhq/jackson-remix-auth)
+- [Jackson with React and client-side OAuth](https://github.com/boxyhq/jackson-examples/tree/main/apps/react)
+- [Jackson with Express.js](https://github.com/boxyhq/jackson-examples/tree/main/apps/express)
+- [Jackson with Supertokens and Express.js](https://github.com/boxyhq/jackson-supertokens-express)
+- [Jackson with Express.js and Auth0](https://github.com/boxyhq/express-jackson-auth0-demo)
+
+## Resources
+
+- [Mock SAML hosted service](https://mocksaml.com)
+- [Mock SAML](https://github.com/boxyhq/mock-saml)
+- [NextAuth.js Provider](https://next-auth.js.org/providers/boxyhq-saml)
+- [Remix Auth Strategy](https://github.com/boxyhq/remix-auth-saml)
+
+## Third-party examples
+
+- [Jackson with Next.js and Supertokens](https://github.com/nadilas/jackson-next-supertokens)
diff --git a/docs/jackson/local-development.md b/docs/jackson/local-development.md
new file mode 100644
index 0000000..7352a40
--- /dev/null
+++ b/docs/jackson/local-development.md
@@ -0,0 +1,57 @@
+# Local Development
+
+This guide will help you to setup and run SAML Jackson in development mode.
+
+## Clone the repo
+
+```bash
+git clone https://github.com/boxyhq/jackson.git
+
+cd jackson
+```
+
+## Install dependencies
+
+Run the following command to install the Node dependencies.
+
+```bash
+npm install
+```
+
+## Setup environment variables
+
+```bash
+cp .env.example .env
+```
+
+Please refer to [environment variables](./deploy/env-variables.md) to read on setting environment variables.
+
+## Setup the database
+
+Run the following command to create database instances for the local development. Make sure you have Docker installed on your machine.
+
+```bash
+npm run dev-dbs
+```
+
+## Start the development server
+
+Start the development server by running the following command.
+
+```bash
+npm run dev
+```
+
+## Testing Jackson in your local environment
+
+The Jackson service can be accessed locally using the following URL
+
+```bash
+http://localhost:5225
+```
+
+You can visit the following URL to see if the Jackson was started successfully!
+
+```bash
+http://localhost:5225/api/hello
+```
diff --git a/docs/jackson/observability.md b/docs/jackson/observability.md
new file mode 100644
index 0000000..d2f31d9
--- /dev/null
+++ b/docs/jackson/observability.md
@@ -0,0 +1,16 @@
+# Observability
+
+Jackson provides first-class observability on the back of OpenTelemetry. Currently we support the following metrics. Traces and logs are coming soon.
+
+Please check the [Environment Variables](./deploy/env-variables.md#opentelemetry-configuration) to configure to enable this feature.
+
+## Metrics
+
+| Name | Description | Type |
+| --------------------------- | ---------------------------------------- | ----- |
+| `jackson.connection.create` | Number of SSO Connection create requests | Count |
+| `jackson.connection.get` | Number of SSO Connection get requests | Count |
+| `jackson.connection.delete` | Number of SSO Connection delete requests | Count |
+| `jackson.oauth.authorize` | Number of oauth authorize requests | Count |
+| `jackson.oauth.token` | Number of oauth token requests | Count |
+| `jackson.oauth.userinfo` | Number of oauth user info requests | Count |
diff --git a/docs/jackson/overview.md b/docs/jackson/overview.md
new file mode 100644
index 0000000..46b850d
--- /dev/null
+++ b/docs/jackson/overview.md
@@ -0,0 +1,48 @@
+---
+title: Enterprise SSO Docs
+---
+
+# Enterprise SSO
+
+Jackson is our Single Sign-On (SSO) service for SAML/OIDC Identity Providers [SSO in a box from BoxyHQ].
+
+Jackson implements SSO as an OAuth 2.0 flow, abstracting away all the complexities of the underlying SAML/OIDC protocol. Check out our [GitHub repo](https://github.com/boxyhq/jackson).
+
+## Architecture
+
+
+
+We have developed Jackson from scratch adopting a modular architecture as shown below. The business logic is separated into controllers which helps us in incremental adoption of features.
+
+
+
+## Key Features
+
+### Own your own data
+
+- An open-source solution that allows you to keep control of your data
+- Supports Bring Your Own Database (BYOD) and can be used with any database
+- Built-in support for MySQL, MariaDB, Postgres, MongoDB, Redis, PlanetScale
+- Works great with databases from popular hosting providers
+
+### Flexible and easy to use
+
+- Designed to work with OAuth 2.0 / OpenID Connect 1.0 flow
+- Integrate with your existing OAuth 2.0 / OpenID Connect 1.0 library
+
+### Support
+
+Reach out to the maintainer at one of the following places:
+
+- [GitHub Discussions](https://github.com/boxyhq/jackson/discussions)
+- [GitHub Issues](https://github.com/boxyhq/jackson/issues)
+- The email which is located [in GitHub profile](https://github.com/deepakprabhakara)
+
+### Community
+
+- [Discord](https://discord.gg/uyb7pYt4Pa)
+- [Twitter](https://twitter.com/boxyhq)
+
+### License
+
+[Apache 2.0 License](https://github.com/boxyhq/jackson/blob/main/LICENSE)
diff --git a/docs/jackson/saml-federation/index.md b/docs/jackson/saml-federation/index.md
new file mode 100644
index 0000000..eb80632
--- /dev/null
+++ b/docs/jackson/saml-federation/index.md
@@ -0,0 +1,25 @@
+---
+title: SAML Federation
+sidebar_label: SAML Federation
+---
+
+# SAML Federation
+
+SAML Federation is an enterprise feature and you need to have an enterprise license to use this feature.
+
+This feature allows you to federate multiple Identity Providers (IdPs) without needing any additional plugins or code changes. Extremely useful in cases where the SAML support is restricted to a single provider and you need to support multiple IdPs. Contact us to find out more.
+
+## SAML Federation Flow
+
+Here is how the SAML Federation flow works if you are using Jackson as a SAML IdP and want to federate with another identity provider (IdP) (Eg: Okta):
+
+- The user accesses the Service Provider's (SP) login page
+- The user clicks on the "Login with SAML" button
+- The SP sends SAML Request to Jackson's SSO endpoint
+- Jackson displays the list of IdP available for the user to choose from (if there is more than one IdP) based on the requested tenant and product combination
+- Jackson redirects the user to the chosen IdP for authentication
+- After successful authentication, IdP sends (POST) SAML Response to Jackson's ACS endpoint
+- Jackson process SAML Response from the IdP and create a new SAML Response to send (POST) back to the SP's ACS endpoint
+- SP process SAML Response from Jackson and create a new session for the user (Depending on the SP's implementation)
+
+Visit [Create SAML Federation App](/docs/admin-portal/enterprise-sso#saml-federation) to learn how to create and configure a SAML Federation App.
diff --git a/docs/jackson/sbom.md b/docs/jackson/sbom.md
new file mode 100644
index 0000000..462868b
--- /dev/null
+++ b/docs/jackson/sbom.md
@@ -0,0 +1,25 @@
+# Software Bill Of Materials (SBOM) Reports
+
+[SBOM](https://en.wikipedia.org/wiki/Software_bill_of_materials) is a list of components in a piece of software. It is like a list of ingredients of a product and is quickly becoming a standard for software supply chain risk management. The ecosystem is growing with tools that help you verify, scan and monitor all your dependencies.
+
+## Report Standards
+
+SBOM reports primarily use [SPDX](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange) & [CycloneDX](https://cyclonedx.org/) standards.
+
+## Reports
+
+**Note:** This is supported for all versions >=0.3.8
+
+You can find the SBOM reports as artifacts in our container registry at the locations below. They are updated every time there is change in the codebase and tagged by the exact version we release.
+
+| Location | Files | Context |
+| ----------------------------------------------- | ----------------------------- | ------------------------------------- |
+| `ghcr.io/boxyhq/jackson/sbom:service-+ sso.deleted - A connection has been deleted. +
++ +```json +{ + "event": "sso.deleted", + "tenant": "boxyhq", + "product": "demo", + "data": { + "name": "SSO Connection", + "description": "SSO Connection for BoxyHQ", + "clientID": "326991705d478f0178fc2b49e35cd166dc771061", + "clientSecret": "15b2db91b2ba4c848b68148f108035e7138d69104d99de89", + "provider": "saml.example.com", + "friendlyProviderName": null + } +} +``` + +
+'
+```
+
+- `grant_type`: `authorization_code` is the only supported flow, for now. We might extend this in the future
+- `client_id`: Use the client_id returned by the SSO connection API or use `tenant=&product=` to use the tenant and product IDs instead. **Note:** Please don't forget to URL encode the query parameters including `client_id`.
+- `client_secret`: Use the client_secret returned by the SAML connection API or any arbitrary value if using the tenant and product in the clientID
+- `redirect_uri`: This is where the user will be taken back once the authorization flow is complete. Use the same redirect_uri as the previous request
+
+If everything goes well you should receive a JSON response that includes the access token. This token is needed for the next step where we fetch the user profile.
+
+```json
+{
+ "access_token": ,
+ "token_type": "bearer",
+ "expires_in": 300
+}
+```
+
+### 3.3 Profile Request
+
+The short-lived access token can now be used to request the user's profile. You'll need to make the following request:
+
+```bash
+curl --request GET \
+ --url 'https://localhost:5225/api/oauth/userinfo' \
+ --header 'authorization: Bearer '
+```
+
+If everything goes well you should receive a JSON response with the user's profile:
+
+```json
+{
+ "id": ,
+ "email": "sjackson@coolstartup.com",
+ "firstName": "SAML",
+ "lastName": "Jackson"
+ "raw": {
+ ...
+ },
+ "requested": {
+ ...
+ }
+}
+```
+
+- `id`: The id of the user as provided by the Identity Provider. (SAML SLO request requires you to pass `id` as `nameId`. Save `id` if you have a plan to implement SLO in the future.)
+- `email`: The email address of the user as provided by the Identity Provider
+- `firstName`: The first name of the user as provided by the Identity Provider
+- `lastName`: The last name of the user as provided by the Identity Provider
+- `raw`: This contains all claims attributes returned by the SAML provider
+- `requested`: This contains the `tenant`, `product`, `client_id` and `state` from the authorize request. It can be used to reconcile context on the client side if needed
+
+## 4. SAML SLO
+
+SLO is a SAML flow that allows an end-user to logout of a single session and be automatically logged out of all linked sessions created during the SSO process.
+
+The SLO flow begins with redirecting your user to the `/api/logout` endpoint.
+
+```bash
+https://localhost:5225/api/logout
+ ?nameId=google-auth0-f92cc1834efc0f73e9c09
+ &tenant=boxyhq.com
+ &product=demo
+ &redirectUrl=http://www.example.com/logout
+```
+
+- `nameId`: Identifies the subject of a SAML assertion (Typically the user who is authenticated)
+- `tenant`: The tentant
+- `product`: The product
+- `redirectUrl`: Post logout redirect URL
+
+IdP will send a response (as a POST operation) to a specific URL (Single Logout URL) for the logout request. You need to register this URL on the IdP `/api/logout/callback` to handle the response.
+
+Jackson will redirect users to `redirectUrl` after the successful logout.
+
+:::info
+You should save the `id` returned by the `userinfo` for an user so that you can use the `id` as `nameId` with SLO request.
+:::
diff --git a/docs/jackson/sso-providers/auth0.md b/docs/jackson/sso-providers/auth0.md
new file mode 100644
index 0000000..2d093ce
--- /dev/null
+++ b/docs/jackson/sso-providers/auth0.md
@@ -0,0 +1,54 @@
+---
+title: Set up your own custom SAML application for Auth0 SAML
+sidebar_label: Auth0 SAML
+---
+
+# Auth0 SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for Auth0 SAML.
+
+## Create Application
+
+From your Auth0 dashboard, click **Applications** from the left navigation menu.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+
+
+If you haven't created a SAML application, click the **Create Application** button to create a new application.
+
+Give your application a **Name** and click **Create**.
+
+
+
+## Configure Application
+
+Click the tab **Addons** and enable **SAML2 WEB APP** addon.
+
+
+
+Enter your **Application Callback URL** on the next screen and click **Enable**.
+
+Replace the values with the ones you have received from SAML Jackson.
+
+
+
+Click the tab **Usage** and download the **Identity Provider Metadata**.
+
+
+
+## Attribute Mapping
+
+No additional attribute mapping is required for Auth0 SAML to work with SAML Jackson.
+
+## Next steps
+
+You've successfully configured your custom SAML application for Auth0 SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Auth0 Doc](https://auth0.com/docs)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/azure.md b/docs/jackson/sso-providers/azure.md
new file mode 100644
index 0000000..74a08c3
--- /dev/null
+++ b/docs/jackson/sso-providers/azure.md
@@ -0,0 +1,80 @@
+---
+title: Set up your own custom SAML application for Azure AD SAML
+sidebar_label: Azure AD SAML
+---
+
+# Azure AD SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for Azure AD SAML.
+
+## Create Application
+
+From your Azure Admin console, click **Enterprise applications** from the left navigation menu.
+
+
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click **New application** from the top to create a new application.
+
+
+
+From the next screen, click **Create your own application**. Give your application a **Name** and click **Create**.
+
+
+
+## Configure Application
+
+Select **Single Sign On** from the **Manage** section of your app and then **SAML**.
+
+
+
+Click **Edit** on the **Basic SAML Configuration** section.
+
+
+
+Enter the following values in the **Basic SAML Configuration** section on the next screen:
+
+- **Identifier (Entity ID)**
+- **Reply URL (Assertion Consumer Service URL)**
+
+Replace the values with the ones you have received from SAML Jackson.
+
+Click **Save** to save your changes.
+
+
+
+## Attribute Mapping
+
+Click **Edit** on the **Attributes & Claims** section.
+
+
+
+You have to configure the following attributes under the **Attributes & Claims** section:
+
+| Name | Value |
+| -------------------------------------------------------------------- | ---------------------- |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | user.mail |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | user.givenname |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | user.userprincipalname |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | user.surname |
+
+See the screenshot below.
+
+
+
+Go to the section **SAML Signing Certificate** section and download the **Federation Metadata XML**.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for Azure AD SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Azure Admin Console](https://portal.azure.com/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/generic-oidc.md b/docs/jackson/sso-providers/generic-oidc.md
new file mode 100644
index 0000000..6ab50a0
--- /dev/null
+++ b/docs/jackson/sso-providers/generic-oidc.md
@@ -0,0 +1,16 @@
+---
+title: Set up app in your OpenID Connect Identity Provider
+sidebar_label: OpenID Connect Provider
+---
+
+# OIDC Provider setup
+
+To allow apps or clients to login using an OIDC Identity Provider, we must register an application with the IdP. The process might slightly vary from one IdP to another (refer your IdP documentation), but there are a few things in common.
+
+- **Callback URL**: This will be the URL where Jackson receives the OIDC Authorization response. Make sure to set the full HTTPS URL obtained by concatenating Jackson endpoint with [oidcPath](../deploy/env-variables.md#oidc_path) env. The default value set for `oidcPath` in Jackson service is `/api/oauth/oidc`.
+- **Client/Application ID**: The OIDC Identity Provider normally will generate a unique identifier for the registered App. Make a note of this to be used later when creating the SSO connection with Jackson.
+- **Client Secret**: Along with the Client ID, the IdP also generates a client secret which is used to authenticate the client while issuing tokens. Make a note of this to be used later when creating the SSO connection with Jackson.
+
+:::info
+Since Jackson acts as a proxy between the app and the OIDC Identity Provider, here the application/client is Jackson.
+:::
diff --git a/docs/jackson/sso-providers/generic-saml.md b/docs/jackson/sso-providers/generic-saml.md
new file mode 100644
index 0000000..f5b9d28
--- /dev/null
+++ b/docs/jackson/sso-providers/generic-saml.md
@@ -0,0 +1,39 @@
+---
+title: Set up your own custom SAML application for a Generic IdP
+sidebar_label: Generic SAML 2.0 Provider
+---
+
+# Generic SAML
+
+This guide explains the settings you’d need to use to configure SAML with your Identity Provider. Once this is set up you should get an XML metadata file that should then be configured using our [API (or calling the API controller connection method if using our NPM)](../sso-flow/index.md#21-add-connection).
+
+> Please do not add a trailing slash at the end of the URLs.
+
+Create them exactly as shown below:
+
+- Assertion consumer service URL / Single Sign-On URL / Destination URL: `http://localhost:5225/api/oauth/saml`
+
+- Entity ID / Identifier / Audience URI / Audience Restriction: `https://saml.boxyhq.com`
+
+- Response: `Signed`
+
+- Assertion Signature: `Signed`
+
+- Signature Algorithm: `RSA-SHA256`
+
+- Assertion Encryption: `Unencrypted`
+
+:::info
+The deployed Jackson service has a Service Provider (SP) endpoint that exposes the above metadata and the same can be accessed at `/.well-known/saml-configuration`.
+:::
+
+## SAML profile/claims/attributes mapping
+
+As outlined in the guide above we try and support 4 attributes in the SAML claims - `id`, `email`, `firstName`, `lastName`. This is how the common SAML attributes map over for most providers, but some providers have custom mappings. Please refer to the documentation on Identity Provider to understand the exact mapping.
+
+| SAML Attribute | Jackson mapping |
+| ---------------------------------------------------------------------- | --------------- |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` | id |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | email |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | firstName |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | lastName |
diff --git a/docs/jackson/sso-providers/google.md b/docs/jackson/sso-providers/google.md
new file mode 100644
index 0000000..0c5b307
--- /dev/null
+++ b/docs/jackson/sso-providers/google.md
@@ -0,0 +1,73 @@
+---
+title: Set up your own custom SAML application for Google SAML
+sidebar_label: Google SAML
+---
+
+# Google SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for Google SAML.
+
+## Create Application
+
+From your Google Admin console, click **Apps** from the sidebar then click **Web and mobile apps** from the list.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click **Add custom SAML app** from the menu.
+
+
+
+Give your application an **App name** and click **Continue**.
+
+
+
+## Configure Application
+
+From the next screen, click **DOWNLOAD METADATA** to download the metadata XML file, then click **Continue**.
+
+
+
+Enter the following values in the **Service provider details** section:
+
+- **ACS URL**
+- **Entity ID**
+
+Replace the values with the ones you have received from SAML Jackson and click **Continue** to save the configuration.
+
+
+
+## Attribute Mapping
+
+Under the **Attributes** section, you have to configure the following attributes:
+
+| App attributes | Google directory attributes |
+| -------------- | --------------------------- |
+| email | Primary email |
+| firstName | First name |
+| lastName | Last name |
+
+See the screenshot below.
+
+After you have configured the attributes, click **Finish** to save the configuration.
+
+
+
+From the next screen, click **User access** to configure the application to allow users to log in.
+
+
+
+Check the **ON for everyone** checkbox and click **Save**.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for Google SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Google Admin Console](https://admin.google.com/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/index.md b/docs/jackson/sso-providers/index.md
new file mode 100644
index 0000000..17d7adb
--- /dev/null
+++ b/docs/jackson/sso-providers/index.md
@@ -0,0 +1,20 @@
+---
+title: SAML SSO Providers
+sidebar_label: SSO Providers
+---
+
+# SAML SSO Providers
+
+SAML Jackson supports the following SSO providers:
+
+- [Generic SAML 2.0 Provider](./generic-saml.md)
+- [Azure](./azure.md)
+- [Microsoft AD FS](./microsoft-adfs.md)
+- [Okta](./okta.md)
+- [Auth0](./auth0.md)
+- [Google](./google.md)
+- [OneLogin](./onelogin.md)
+- [PingOne](./pingone.md)
+- [JumpCloud](./jumpcloud.md)
+- [Rippling](./rippling.md)
+- [OpenID Connect Provider](./generic-oidc.md)
diff --git a/docs/jackson/sso-providers/jumpcloud.md b/docs/jackson/sso-providers/jumpcloud.md
new file mode 100644
index 0000000..e3e1848
--- /dev/null
+++ b/docs/jackson/sso-providers/jumpcloud.md
@@ -0,0 +1,68 @@
+---
+title: Set up your own custom SAML application for JumpCloud SAML
+sidebar_label: JumpCloud SAML
+---
+
+# JumpCloud SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for JumpCloud SAML.
+
+## Create Application
+
+From your JumpCloud Admin console, click **SSO** from the left navigation menu.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click plus icon and then **Custom SAML App** to create a new application
+
+
+
+Give your application a **Display Label**.
+
+
+
+## Configure Application
+
+Next click on the **SSO** tab and enter the following values:
+
+- **IdP Entity ID**
+- **SP Entity ID**
+- **ACS URL**
+
+Replace the values with the ones you have received from SAML Jackson.
+
+
+
+## Attribute Mapping
+
+Under the **Attributes** section, you have to configure the following attributes:
+
+See the screenshot below.
+
+| Service Provider Attribute Name | JumpCloud Attribute Name |
+| ------------------------------- | ------------------------ |
+| email | email |
+| firstName | firstname |
+| lastName | lastname |
+
+Make sure you have checked the **Declare Redirect Endpoint** checkbox.
+
+Finally, click **Activate** to save the application configuration.
+
+
+
+Now go back to the SAML app you just created, click the tab **SSO**, and click the button **Export Metadata** to download the metadata XML file.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for JumpCloud. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [JumpCloud](https://jumpcloud.com/) official website
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/microsoft-adfs.md b/docs/jackson/sso-providers/microsoft-adfs.md
new file mode 100644
index 0000000..c9296b6
--- /dev/null
+++ b/docs/jackson/sso-providers/microsoft-adfs.md
@@ -0,0 +1,51 @@
+---
+title: Set up your own custom SAML application for Microsoft AD FS
+sidebar_label: Microsoft AD FS
+---
+
+# Microsoft AD FS SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for Microsoft AD FS.
+
+In AD FS, a relying party (RP) trust needs to be set up. You can supply our SP metadata file, usually located at `https:///.well-known/sp-metadata` and let AD FS automatically pick up the configuration.
+
+If you are manually entering the details then you'll find the details you need in [this section](./generic-saml.md). The public certificate is needed for Signature verification and is usually located at `https:///.well-known/saml.cer` for Signature verification.
+
+You will also need to map some attributes of the claims so we can fetch the profile information for your user.
+
+## Create a claims aware Relying Party Trust using federation metadata
+
+1. In Server Manager, click Tools, and then select AD FS Management.
+2. Under Actions, click Add Relying Party Trust.
+ 
+3. On the Welcome page, choose Claims aware and click Start.
+ 
+4. On the Select Data Source page, click Import data about the relying party published online or on a local network. In Federation metadata address (host name or URL), type the federation metadata URL or host name for the partner, and then click Next.
+ 
+5. On the Specify Display Name page type a name in Display name, under Notes type a description for this relying party trust, and then click Next.
+6. On the Choose Issuance Authorization Rules page, select either Permit all users to access this relying party or Deny all users access to this relying party, and then click Next.
+7. On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
+8. On the Finish page, click Close. This action automatically displays the Edit Claim Rules dialog box.
+9. **Mapping attributes**:
+ On the Configure Claim Rule screen, enter a Claim Rule Name of your choice, select Active Directory as the Attribute Store, then add the following mapping:
+
+- From the LDAP Attribute column, select `E-Mail-Addresses`. From the Outgoing Claim Type, type `E-Mail Address`.
+- From the LDAP Attribute column, select `Given-Name`. From the Outgoing Claim Type, type `Given Name`.
+- From the LDAP Attribute column, select `Surname`. From the Outgoing Claim Type, type `Surname`.
+- From the LDAP Attribute column, select `User-Principal-Name`. From the Outgoing Claim Type, type `Name ID`.
+
+10. **Transform Rule**: Create a transform rule mapping the incoming `Email-Address` to outgoing `NameID` (of type `Email`), ADFS by default sends `NameID` as `Unspecified` which results in an `InvalidNameIDPolicy` error if this step is missed.
+
+
+
+If you'd rather use Claim rule language then the following rule can be applied:
+
+```sh
+c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
+```
+
+11. Finally open Windows PowerShell as an administrator, then run the following command:
+
+```sh
+ Set-ADFSRelyingPartyTrust -TargetName -SamlResponseSignature "MessageAndAssertion"
+```
diff --git a/docs/jackson/sso-providers/okta.md b/docs/jackson/sso-providers/okta.md
new file mode 100644
index 0000000..b637831
--- /dev/null
+++ b/docs/jackson/sso-providers/okta.md
@@ -0,0 +1,76 @@
+---
+title: Set up your own custom SAML application for Okta SAML
+sidebar_label: Okta SAML
+---
+
+# Okta SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for Okta SAML.
+
+## Create Application
+
+From your Okta account, click **Applications** from the left navigation menu.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click the **Create App Integration** button to create a new application.
+
+
+
+Choose **SAML 2.0** from the next screen and click **Next**.
+
+
+
+Give your application an **App Name** and click **Next**.
+
+
+
+## Configure Application
+
+Enter the following values in the **SAML Settings** section on the next screen:
+
+- **Single sign on URL**
+- **Audience URI (SP Entity ID)**
+- Select **EmailAddress** from the **Name ID format** dropdown.
+
+Replace the values with the ones you have received from SAML Jackson.
+
+
+
+## Attribute Mapping
+
+Under the **Attribute Statements** section, you have to configure the following attributes:
+
+| Name | Value |
+| --------- | -------------- |
+| id | user.id |
+| email | user.email |
+| firstName | user.firstName |
+| lastName | user.lastName |
+
+See the screenshot below.
+
+
+
+On the next screen select **I'm an Okta customer adding an internal app** and click **Finish**.
+
+
+
+From your application, click **Sign On** tab and go to the section **SAML Signing Certificates**
+
+Click the **Actions** dropdown for the correct certificate and click **View IdP metadata**. A separate window will open with the metadata XML file, you can copy it to your clipboard.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for Okta SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Okta](https://www.okta.com/) official website
+- Visit [Okta documentation](https://developer.okta.com/docs/concepts/saml/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/onelogin.md b/docs/jackson/sso-providers/onelogin.md
new file mode 100644
index 0000000..6764cdd
--- /dev/null
+++ b/docs/jackson/sso-providers/onelogin.md
@@ -0,0 +1,91 @@
+---
+title: Set up your own custom SAML application for OneLogin SAML
+sidebar_label: OneLogin SAML
+---
+
+# OneLogin SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for OneLogin SAML.
+
+## Create Application
+
+From your OneLogin account, click **Applications** from the top navigation menu.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click the **Add App** button to create a new application.
+
+
+
+Search for **SAML Test Connector** in the **Find Applications** section. Select **SAML Custom Connector (Advanced)** from the search results.
+
+
+
+Give your application a **Display Name** and click **Save**.
+
+
+
+## Configure Application
+
+From your application, click the **Configuration** tab on the left to configure the application.
+
+You have to enter the following values in the **Application details** section:
+
+- **Audience (Entity ID)**
+- **ACS (Consumer) URL Validator**
+- **ACS (Consumer) URL**
+- Select the **Service Provider** from the **SAML initiator** dropdown.
+
+Replace the values with the ones you have received from SAML Jackson.
+
+Click **Save** to save the configuration.
+
+
+
+
+
+Click the dropdown menu **More Actions** from the top right corner and click **SAML Metadata** to download the metadata XML file.
+
+
+
+## Attribute Mapping
+
+From your application, click the **Parameters** tab on the left.
+
+You have to configure the following attributes:
+
+| SAML Custom Connector Field | Value |
+| --------------------------- | ---------- |
+| id | UUID |
+| email | Email |
+| firstName | First Name |
+| lastName | Last Name |
+
+See the screenshot below.
+
+
+
+See the below screenshot to see how to map the **id** attribute to **UUID**.
+
+Enter **id** in the **Field name** input and check the **Include in SAML assertion** checkbox. Click **Save** to continue.
+
+
+
+On the next screen, select **UUID** from the **Value** dropdown and click **Save**.
+
+
+
+Do the same for the other attributes (email, firstName, lastName).
+
+## Next steps
+
+You've successfully configured your custom SAML application for OneLogin SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [OneLogin](https://www.onelogin.com/) official website
+- Visit [OneLogin documentation](https://developers.onelogin.com/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/pingone.md b/docs/jackson/sso-providers/pingone.md
new file mode 100644
index 0000000..47b76fa
--- /dev/null
+++ b/docs/jackson/sso-providers/pingone.md
@@ -0,0 +1,71 @@
+---
+title: Set up your own custom SAML application for PingOne SAML
+sidebar_label: PingOne SAML
+---
+
+# PingOne SAML SSO
+
+In this section, we will show you how to set up your own custom SAML application for PingOne SAML.
+
+## Create Application
+
+From your PingOne account, click **Connections** > **Applications** from left navigation menu.
+
+If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
+
+If you haven't created a SAML application, click plus button to create a new application.
+
+
+
+Give your application a **Application Name**, choose **SAML Application** from the **Application Type** and click **Configure**.
+
+## Configure Application
+
+
+
+From the next screen, you have to enter the following values in the **SAML Configuration** section:
+
+- **ACS URLs**
+- **Entity ID**
+
+Replace the values with the ones you have received from SAML Jackson.
+
+Click **Save** to save the configuration.
+
+
+
+Click the **Configuration** tab from the top and click **Download Metadata** to download the metadata XML file.
+
+
+
+## Attribute Mapping
+
+Click the **Attribute Mappings** tab from the top and you have to configure the following attributes:
+
+| SAML App | PingOne |
+| --------- | ------------- |
+| id | User ID |
+| email | Email Address |
+| firstName | Given Name |
+| lastName | Family Name |
+
+See the screenshot below.
+
+
+
+Make sure you have enabled your app so that it can be used by the users. You can do this by clicking the **Toggle** button next to your app.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for PingOne SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Ping Identity Website](https://www.pingidentity.com/en.html)
+- [Ping Identity Documentation](https://docs.pingidentity.com/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/sso-providers/rippling.md b/docs/jackson/sso-providers/rippling.md
new file mode 100644
index 0000000..a85fd39
--- /dev/null
+++ b/docs/jackson/sso-providers/rippling.md
@@ -0,0 +1,58 @@
+---
+title: Set up your own custom SAML application for Rippling SAML
+sidebar_label: Rippling SAML
+---
+
+# Rippling SAML SSO
+
+This section will show you how to set up your own custom SAML application for Rippling SAML.
+
+## Create Application
+
+You'll need to create a new **Custom App** from your Rippling account if the app is not already in the Rippling app directory.
+
+Go to **IT Management** > **Custom App** from the left navigation menu.
+
+
+
+Click **Create New App** button to create a new application.
+
+From the next screen, fill in the following fields:
+
+- **App Name**
+- **Select Categories**
+- **Upload Logo**
+- **What type of app would you like to create?** - Make sure you select **Single Sign-On (SAML)** from the list.
+
+
+
+## Configure Application
+
+Copy the **Idp Metadata URL** or **Idp Metadata XML** from the next screen. You'll need this value to configure your SAML connection in SAML Jackson.
+
+
+
+You'll need to enter the **ACS URL** and **Entity ID**. You'll get these values from SAML Jackson.
+
+
+
+Make sure that **Service Provider Entity ID** matches the **SAML Audience (SP Entity ID)** value from SAML Jackson.
+
+From the **Settings** tab of custom app you just created. Go to **Advanced SAML Settings** section and check the box for **Disable InResponseTo field in assertions for IdP initiated SSO**.
+
+This is because Rippling sends dummy values for the **InResponseTo** field and SAML Jackson will try to validate the **InResponseTo** field if it is present.
+
+
+
+## Next steps
+
+You've successfully configured your custom SAML application for Rippling SAML. At this stage, you can assign users to your application and start using it.
+
+## Resources
+
+- [Rippling](https://www.rippling.com/) official website
+- Visit [Rippling documentation](https://developer.rippling.com/)
+
+:::tip
+Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+:::
diff --git a/docs/jackson/upgrade.md b/docs/jackson/upgrade.md
new file mode 100644
index 0000000..7afebfc
--- /dev/null
+++ b/docs/jackson/upgrade.md
@@ -0,0 +1,35 @@
+# Upgrade Guide
+
+## Upgrading to v1.11.0
+
+We have patched the SSO connection (`/api/v1/connections`) DELETE handler to accept payload (client/Secret or tenant/product/strategy) as part of query parameters. Earlier, the payload was expected to be part of the body which is non-standard and is no longer supported in Next.js.
+
+## Upgrading to v1.9.7
+
+We discovered and fixed a database connection leak introduced in v1.9.1, if you are using versions 1.9.1 to 1.9.6 then please upgrade to v1.9.7
+
+## Upgrading to v1.8.0
+
+1. We support bringing your own database (BYOD), this is a very tricky feature to support and we are still iterating on the schema which works as seamlessly as possible across the range of databases we support. Unfortunately, not everything goes smoothly here and we have encountered some length issues on newer versions of MySQL and MariaDB. The best way forward was to change the schema of the keys we use from length 1500 to 250 which is compatible with the newer versions. As a result, this will break your updates if you are using MySQL, MariaDB, or MS SQL Server. If you encounter this please reach out and we'll guide you through the update process. If you haven't gone into production yet then please update to v1.8.0 before you deploy it to production.
+
+## Upgrading to v1.3.10
+
+1. For users of our npm library, `directorySync` has been renamed to `directorySyncController`.
+
+## Upgrading to v1.3.6
+
+1. `samlSPConfig.get()` is now async since we introduced a global certificate instead of per tenant certificate to ease the SAML setup process.
+
+## Upgrading to v1.3.0
+
+1. Landed support for OpenID Identity Providers.
+2. Landed new API (`/api/v1/connections`) to support setting up both SAML/OIDC SSO Connections.
+
+ **Note:** The previous API for SAML configuration `/api/v1/saml/config` has been deprecated, and would be completely removed in a future release.
+
+3. Renamed env variable `PRE_LOADED_CONFIG` to [`PRE_LOADED_CONNECTION`](deploy/env-variables.md#pre_loaded_connection) for Jackson service. In the case of npm `preLoadedConfig` becomes`preLoadedConnection`.
+4. Make sure to set the value for [`oidcPath`](deploy/env-variables.md#oidc_path) in case you are using the npm.
+
+## Backups
+
+Please remember to take backups before upgrading Jackson. We cannot stress how important this step is, although we take precautions to avoid bugs they sometimes do slip by us. Having backups will not only help you recover from these rare events but should be part of your disaster recovery process. If you need any help with this please do not hesitate to reach out to us.
diff --git a/docs/retraced/advanced/automated-audit-events.md b/docs/retraced/advanced/automated-audit-events.md
new file mode 100644
index 0000000..d3ba545
--- /dev/null
+++ b/docs/retraced/advanced/automated-audit-events.md
@@ -0,0 +1,64 @@
+# Automated Audit Events
+
+When an end customer uses a Viewer or Enterprise token to view logs directly from the Retraced API, Retraced will record the read event in your audit log.
+
+You can configure these events with the optional `view_log_action` parameter when you create a new Viewer or Enterprise token through the Publisher API. The default action is "audit.log.view". Viewer tokens also require an `actor_id` parameter at creation time, while Enterprise token audit events generate an `actor.id` from the token.
+
+## Viewer Example
+
+Suppose a viewer token was created with `group_id=example.com`, `actor_id=user@example.com` and `action=viwer.view_logs`. When the token is used, an event like this will be inserted into your audit log:
+
+```json
+{
+ "action": "viewer.view_logs",
+ "crud": "r",
+ "actor": {
+ "id": "user@example.com"
+ },
+ "group": {
+ "id": "example.com"
+ },
+ "description": "GET http://localhost:3000/auditlog/viewer/v1/graphql",
+ "source_ip": "1.1.0.180"
+}
+```
+
+## Enterprise Example
+
+An Enterprise token created with `group_id` "example.com" and no `view_log_action` would generate an event similar to this when used:
+
+```json
+{
+ "action": "audit.log.view",
+ "crud": "r",
+ "actor": {
+ "id": "enterprise:1234567"
+ },
+ "group": {
+ "id": "example.com"
+ },
+ "description": "GET http://localhost:3000/auditlog/enterprise/v1/graphql",
+ "source_ip": "1.1.0.180"
+}
+```
+
+## Viewer Enterprise Token Self-Management
+
+Another instance where Viewers can perform actions bypassing your API is when creating, retrieiving, updating, or deleting their own Enterprise tokens. Retraced will add these events to your audit log on your behalf. Note that Retraced does not insert audit events when Enterprise tokens are managed through the Publisher API, since you have the option of sending your own audit events for these actions.
+
+An example of an event logged when a Viewer creates their own Enterpise token is:
+
+```json
+{
+ "action": "eitapi_token.create",
+ "crud": "c",
+ "actor": {
+ "id": "user@example.com"
+ },
+ "group": {
+ "id": "example.com"
+ },
+ "description": "POST http://localhost:3000/auditlog/viewer/v1/project/02211171900c4172b4a80d23855961c5/eitapi_token",
+ "source_ip": "1.1.0.180"
+}
+```
diff --git a/docs/retraced/advanced/display-templates.md b/docs/retraced/advanced/display-templates.md
new file mode 100644
index 0000000..1ac1fab
--- /dev/null
+++ b/docs/retraced/advanced/display-templates.md
@@ -0,0 +1,86 @@
+# Display Templates
+
+Display templates is an important part of controlling how the events are rendered in the browser, exports or over any other stream.
+
+A display template has the following components:
+
+## Definitions
+
+### Name
+
+The name is internal only to the admin site. This is a place for you to record what the template is attempting to do.
+
+### Rules
+
+The rules field is a collection of rules that will be evaluated by the Retraced rules engine to determine if this template shoud be applied to the event. We'll cover that in detail shortly. But the idea is that you can have multiple rules, and the first one that matches will control how the event is rendered.
+
+### Template
+
+A handlebars-enabled, markdown rendered display template to use when the rules evaluate to true for a particular event. This ultimately is the text that you want to show for the matching events.
+
+## Rules
+
+Rules are processed against the event object. The best example is with actual data: you can click the Raw object in the admin site and see any actual event object. This is the exact context that is sent into the rule engine.
+
+Rules are expressed as an array of comparators. When the _value_ of the _path_ matches the _comparator_, the rule evaluates to true and the template is applied. Retraced supports a large number of comparators, a [full list of comparators is available](/docs/retraced/advanced/template-comparators).
+
+### Examples
+
+This rule matches when the `action` is set to the string "document.edit":
+
+```json
+[
+ {
+ "comparator": "is",
+ "path": "action",
+ "value": "document.edit"
+ }
+]
+```
+
+This rule matches when the `action` is set to the string "document.edit" AND the type of the document is set to "spreadsheet":
+
+```json
+[
+ {
+ "comparator": "is",
+ "path": "action",
+ "value": "document.edit"
+ },
+ {
+ "comparator": "is",
+ "path": "target.type",
+ "value": "spreadsheet"
+ }
+]
+```
+
+## Templates
+
+Templates are a handlebars string that will be used to display the event. The context of the handlebars engine is the event object, and the output is a markdown string.
+
+### Examples
+
+Partial Event:
+
+```json
+{
+ "action": "document.create",
+ "actor": {
+ "name": "Dr. Evil"
+ },
+ "target": {
+ "type": "spreadsheet",
+ "name": "Master Plan For World Domination.xlsx"
+ }
+}
+```
+
+Template:
+
+```
+**{{ actor.name }}** created the document **{{ target.name }}**
+```
+
+Result:
+**Dr. Evil** created the document **Master Plan For World Domination**
diff --git a/docs/retraced/advanced/index.md b/docs/retraced/advanced/index.md
new file mode 100644
index 0000000..929fbc0
--- /dev/null
+++ b/docs/retraced/advanced/index.md
@@ -0,0 +1,14 @@
+---
+title: Retraced Advanced Concepts
+sidebar_label: Overview
+---
+
+# Advanced Concepts
+
+Once you've started sending events into Retraced, it's time to explore some of the advanced functionality.
+
+- [Display templates](/docs/retraced/advanced/display-templates)
+- [Template Comparators](/docs/retraced/advanced/template-comparators)
+
+- [Tracking Application Versions](/docs/retraced/advanced/tracking-application-versions)
+- [Automated Audit Events](/docs/retraced/advanced/automated-audit-events)
diff --git a/docs/retraced/advanced/ssh-streaming.md b/docs/retraced/advanced/ssh-streaming.md
new file mode 100644
index 0000000..a725447
--- /dev/null
+++ b/docs/retraced/advanced/ssh-streaming.md
@@ -0,0 +1,31 @@
+# SSH Event Streaming
+
+SSH Event Streaming allows Enterprise API users to stream events as they occur over ssh using an Enterprise API Token.
+
+## Usage
+
+To use the SSH event streaming feature, you'll need to start by getting an
+[Enterprise API token](/docs/retraced/apis/enterprise-api#getting-an-enterprise-api-token).
+
+To open a stream, connect to `tail.retraced.io` using your Enterprise API token as
+the username:
+
+```
+ssh aeb1c315b9a8ed11a3f998d8e8ff@tail.retraced.io
+```
+
+Once the connection is open, CSV events will begin to stream through stdout,
+and can be piped to a file or other event ingest system.
+
+The same token can be used for multiple concurrent streaming sessions, all sessions
+will receive every event that occurs while they are active.
+
+## Parameters
+
+The streaming APIs support a few parameters that can control the format of events.
+The default output format is CSV, but JSON is also supported via the
+`format` parameter
+
+```sh
+ssh aeb1c315b9a8ed11a3f998d8e8ff?format=json@tail.retraced.io
+```
diff --git a/docs/retraced/advanced/template-comparators.md b/docs/retraced/advanced/template-comparators.md
new file mode 100644
index 0000000..956bd2f
--- /dev/null
+++ b/docs/retraced/advanced/template-comparators.md
@@ -0,0 +1,19 @@
+# Template Comparators
+
+The following values are acceptable for "comparator" field in rules in the Retraced rules engine:
+
+| Comparator | Desscription |
+| --- | --- |
+| `eq` | Matches when the `value` is equal to the event object data at `path`. This compares values only and doesn't compare types. |
+| `is` | The same as `eq` but it also compares types of objects. |
+| `neq` | Matches when the `value` is not equal to the event object data at `path`. This compares values only and doesn't compare types. This is the inverse of `eq`. |
+| `not` | The same as `neq` but it also compares types of objects. This is the inverse of `is`. |
+| `lt` | Matches when the `value` is less than the event object data at `path`. |
+| `lte` | Matches when the `value` is less than or equal to the event object data at `path`. |
+| `gt` | Matches when the `value` is greater than the event object data at `path`. |
+| `gte` | Matches when the `value` is greater than or equal to the event object data at `path`. |
+| `exists` | Matches when the `value` key exists and is not null on the event object data. |
+| `nexists` | Matches when the `value` key does not exists or is null on the event object data. |
+| `contains` | Matches when the event object data at `path` contains `value`. |
+| `ncontains` | Matches when the event object data at `path` does not contain `value`. |
+| `matches` | This rule is a raw regex rule. When the `value` is interpreted as a regular expression and applied to the event object data at `path`, returns the regex match value. |
diff --git a/docs/retraced/advanced/tracking-application-versions.md b/docs/retraced/advanced/tracking-application-versions.md
new file mode 100644
index 0000000..f9e12fd
--- /dev/null
+++ b/docs/retraced/advanced/tracking-application-versions.md
@@ -0,0 +1,89 @@
+# Tracking Event Publisher Versions
+
+When sending events to Retraced, consumers of the [Publisher API](/docs/retraced/apis/publisher-api)
+may send event metadata like the name and version of the vendor component that is
+sending the events. A minimal event payload that includes this metadata might look like
+
+```json
+{
+ "action": "user.login",
+ "crud": "c",
+ "group": {
+ "id": "7890123",
+ "name": "some.customer"
+ },
+ "actor": {
+ "id": "123456",
+ "name": "user@example.com"
+ },
+ "component": "authentication-api",
+ "version": "ae242df"
+}
+```
+
+Where `component` describes a single versioned piece of a architecture like `authentication-api`
+or `spreadsheet-processor` and `version` is usually one of
+
+- A git SHA of the component's source code as in `ae242df`
+- A semantic version for the component as in `1.0.3`
+- A build number of the component as in `129`
+
+Sending this information to Retraced will allow Retraced to give better
+guarantees about time windows during which an event **did not** occur.
+
+## Example
+
+To better understand how this works, consider the following stream of events,
+in which the `password.change` action at 12:35 is the very first `password.change`
+event seen in Retraced, because a recent new release of the vendor app is the first
+to start tracking `password.change` events.
+
+| action | received |
+| ----------------- | ------------------- |
+| `email.change` | 2017-01-01 11:14:00 |
+| `user.login` | 2017-01-01 11:30:00 |
+| `email.change` | 2017-01-01 12:01:00 |
+| `user.login` | 2017-01-01 12:12:00 |
+| `password.change` | 2017-01-01 12:35:00 |
+| `user.login` | 2017-01-01 12:49:00 |
+| `password.change` | 2017-01-01 12:52:00 |
+
+Without any info about app versions, we can still say for certain that
+
+- no `password.change` events occured between 12:35 and 12:52.
+
+We cannot say anything about whether or not any `password.change` events
+occurred before 12:35, because we have to assume that the vendor application
+was not publishing these events until we see the first one at 12:35.
+
+| action | received | component | version |
+| ----------------- | ------------------- | -------------------- | --------- |
+| `email.change` | 2017-01-01 11:14:00 | `authentication-api` | `aeb22f1` |
+| `user.login` | 2017-01-01 11:30:00 | `authentication-api` | `aeb22f1` |
+| `email.change` | 2017-01-01 12:01:00 | `authentication-api` | `fd02eed` |
+| `user.login` | 2017-01-01 12:12:00 | `authentication-api` | `fd02eed` |
+| `password.change` | 2017-01-01 12:35:00 | `authentication-api` | `fd02eed` |
+| `user.login` | 2017-01-01 12:49:00 | `authentication-api` | `fd02eed` |
+| `password.change` | 2017-01-01 12:52:00 | `authentication-api` | `493ef1d` |
+
+Since we know the version of the component sending each event, we can know for sure
+that the app version that sends `password.change` events was sending `email.change` events as
+early as 12:01. In addition to what we knew before, that
+
+- no `password.change` events occured between 12:35 and 12:52
+
+we now can also guarantee that
+
+- no `password.change` events occurred between 12:01 and 12:35.
+
+Note: Being able to make these guarantees relies on an assumption that application
+versions change at the same time, and that there are never multiple versions of
+a single component running in parallel for significant periods of time. If
+Publisher API consumers rely on canary deploys or staged rollouts over several days,
+then component names will need to be rotated during the rollout.
+
+## Using SDKs
+
+If you are using one of the official [Retraced SDKs](/docs/retraced/sdks/available-sdks),
+you can provide the `version` and `component` fields when the client is initialized,
+and they will be sent for every event.
diff --git a/docs/retraced/apis/admin-api.md b/docs/retraced/apis/admin-api.md
new file mode 100644
index 0000000..8273772
--- /dev/null
+++ b/docs/retraced/apis/admin-api.md
@@ -0,0 +1,17 @@
+---
+title: Admin API
+sidebar_label: Admin API
+description: Admin API
+---
+
+# Admin API
+
+### [Swagger JSON](http://localhost:3000/auditlog/admin/v1/swagger.json) | [API Console](https://retraced.readme.io/v1.0/reference)
+
+## Authentication
+
+The Admin API expects a base64-encoded hmac-signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) in an `Authorization` header:
+
+```
+Authorization: WU9VUl9TSUdORURfSldUX1RPS0VOX18K...
+```
diff --git a/docs/retraced/apis/enterprise-api.md b/docs/retraced/apis/enterprise-api.md
new file mode 100644
index 0000000..d6d465b
--- /dev/null
+++ b/docs/retraced/apis/enterprise-api.md
@@ -0,0 +1,32 @@
+---
+title: Enterprise API
+sidebar_label: Enterprise API
+description: Enterprise API
+---
+
+# Enterprise API
+
+### [Swagger JSON](http://localhost:3000/auditlog/enterprise/v1/swagger.json) | [API Console](https://retraced.readme.io/v1.0/reference)
+
+## Overview
+
+The Enterprise API is the API that the end customer (the enterprise IT administrator) will consume to pull their organization events and ingest it into their own internal systems.
+
+## Authentication
+
+The Enterprise API endpoints expect the token to be provided in a header of the form
+
+```
+Authorization: token=YOUR_ENTERPRISE_TOKEN
+```
+
+## Getting an Enterprise API Token
+
+There are currently two ways to manage Enterprise API tokens.
+
+- Most often, end customers create and manage Enterprise IT tokens using the UI in the [Embedded Viewer](/docs/retraced/getting-started/embedded-viewer)
+- There are also endpoints in the [Publisher API](/docs/retraced/apis/publisher-api) that
+ allow a vendor to create, edit, and delete Enterprise API tokens
+
+Note that to allow end customers to manage Enterprise API tokens in the embedded viewer,
+the `is_admin` query parameter must be set to `true` when [requesting a token to initialize the embedded viewer](https://retraced.readme.io/reference#publisherv1projectprojectidviewertoken)
diff --git a/docs/retraced/apis/graphql.md b/docs/retraced/apis/graphql.md
new file mode 100644
index 0000000..205ad78
--- /dev/null
+++ b/docs/retraced/apis/graphql.md
@@ -0,0 +1,803 @@
+# GraphQL Endpoint
+
+The recommended way to search events using an API is to POST your query and variables to the appropriate Retraced GraphQL endpoint.
+
+| API | Endpoint |
+| ---------- | ----------------------------------------------------------------------------------------------- |
+| Publisher | http://localhost:3000/auditlog/publisher/v1/project/{projectId}/graphql |
+| Admin | http://localhost:3000/auditlog/admin/v1/project/{projectId}/environment/{environmentId}/graphql |
+| Enterprise | http://localhost:3000/auditlog/enterprise/v1/graphql |
+| Viewer | http://localhost:3000/auditlog/viewer/v1/graphql |
+
+## Search
+
+The query root provides a search method. A fully-formed query for a subset of event fields would look like this:
+
+```
+{
+ search(query:"action:user.login location:Germany", last:50, before:"opaquecursor") {
+ totalCount
+ pageInfo {
+ hasNextPage
+ }
+ edges {
+ cursor
+ node {
+ action
+ actor {
+ name
+ }
+ created
+ country
+ }
+ }
+ }
+}
+```
+
+### Variables
+
+Use `query`, `last`, and `before` variables to enable reuse of your query templates. If you define a parameterized query like this...
+
+```
+const searchQuery = `query Search($query: String!, $last: Int, $before: String) {
+ search(query:"action:user.login location:Germany", last:50, before:"opaquecursor") {
+ totalCount
+ pageInfo {
+ hasNextPage
+ }
+ edges {
+ cursor
+ node {
+ action
+ actor {
+ name
+ }
+ created
+ country
+ }
+ }
+ }
+}`;
+```
+
+... then you can execute searches like this:
+
+```
+const vars = {
+ query: "action:user.login location:German",
+ last: 50,
+ before: "opaquecursor",
+};
+const res = fetch("http://localhost:3000/auditlog/publisher/v1/project/3hf140713bn302/graphql", {
+ method: "POST",
+ headers: {
+ "Accept": "application/json",
+ "Content-Type": "application/json",
+ "Authorization": "Token token=2ba3059ad7f14071b9befb2a7a2e195e",
+ },
+ body: JSON.stringify({
+ query: searchQuery,
+ variables: vars,
+ }),
+});
+```
+
+# Schema Types
+
+
+ Table of Contents
+
+- [GraphQL Endpoint](#graphql-endpoint)
+ - [Search](#search)
+ - [Variables](#variables)
+- [Schema Types](#schema-types)
+ - [Query](#query)
+ - [Objects](#objects)
+ - [Action](#action)
+ - [Actor](#actor)
+ - [Display](#display)
+ - [Event](#event)
+ - [EventEdge](#eventedge)
+ - [EventsConnection](#eventsconnection)
+ - [Field](#field)
+ - [Group](#group)
+ - [PageInfo](#pageinfo)
+ - [Target](#target)
+ - [Enums](#enums)
+ - [CRUD](#crud)
+ - [Scalars](#scalars)
+ - [Boolean](#boolean)
+ - [ID](#id)
+ - [Int](#int)
+ - [String](#string)
+ - [Interfaces](#interfaces)
+
+
+
+## Query
+
+The root query object of the Retraced GraphQL interface.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+search
+EventsConnection
+
+
+Run an advanced search for events.
+
+
+
+
+query
+String
+
+
+The structured search operators used to filter events.
+
+
+
+
+first
+Int
+
+
+The limit of events to return, sorted from oldest to newest. It can optionally be used with the after argument.
+
+
+
+
+after
+String
+
+
+A cursor returned from a previous query.
+
+
+
+
+last
+Int
+
+
+The limit of events to return, sorted from newest to oldest. It can optionally be used with the before argument.
+
+
+
+
+before
+String
+
+
+A cursor returned from a previous query.
+
+
+
+
+
+
+## Objects
+
+### Action
+
+An action.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+action
+String
+
+
+The action field of an event such as "user.login".
+
+
+
+
+
+
+### Actor
+
+The agent who performed an event.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+id
+ID
+
+
+A unique id representing this actor.
+
+
+
+
+name
+String
+
+
+The name of this actor.
+
+
+
+
+href
+String
+
+
+The URL associated with this actor.
+
+
+
+
+fields
+[Field]
+
+
+The set of fields associated with this actor.
+
+
+
+
+
+
+### Display
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+markdown
+String
+
+
+
+
+### Event
+
+A single record in an audit log.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+id
+ID
+
+
+A unique id representing this event.
+
+
+
+
+action
+String
+
+
+The type of action that was taken to generate this event.
+
+
+
+
+description
+String
+
+
+The description of the event that was taken.
+
+
+
+
+group
+Group
+
+
+The group associated with this event.
+
+
+
+
+actor
+Actor
+
+
+The actor associated with this event.
+
+
+
+
+target
+Target
+
+
+The target associated with this event.
+
+
+
+
+crud
+CRUD
+
+
+The classification of this event as create, read, update, or delete.
+
+
+
+
+display
+Display
+
+
+The display text for this event.
+
+
+
+
+received
+String
+
+
+The time that the Retraced API received this event.
+
+
+
+
+created
+String
+
+
+The time that this event was reported as performed.
+
+
+
+
+canonical_time
+String
+
+
+The created time if specified; else the received time.
+
+
+
+
+is_failure
+Boolean
+
+
+Set to true if the event represents a failed use of permissions.
+
+
+
+
+is_anonymous
+Boolean
+
+
+Set to true if the user was not logged in when performing this action.
+
+
+
+
+source_ip
+String
+
+
+The IP address of the actor when the action was performed.
+
+
+
+
+country
+String
+
+
+The country that the actor was in when the action was performed.
+
+
+
+
+loc_subdiv1
+String
+
+
+The large area of the country the actor was in when the action was performed (State).
+
+
+
+
+loc_subdiv2
+String
+
+
+The granular area of the country the actor was in when the action was performed (City).
+
+
+
+
+component
+String
+
+
+An identifier for the vendor app component that sent the event.
+
+
+
+
+version
+String
+
+
+An identifier for the version of the vendor app that sent the event, usually a git SHA
+
+
+
+
+fields
+[Field]
+
+
+The set of fields associated with this event.
+
+
+
+
+raw
+String
+
+
+The raw event sent to the Retraced API.
+
+
+
+
+
+
+### EventEdge
+
+The event and cursor for a single result.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+node
+Event
+
+
+The event object.
+
+
+
+
+cursor
+String
+
+
+An opaque cursor for paginating from this point in the search results. Use it as the after argument to paginate forward or the before argument to paginate backward.
+
+
+
+
+
+
+### EventsConnection
+
+The results of a search query.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+edges
+[EventEdge]
+
+
+The events and cursors matching the query.
+
+
+
+
+pageInfo
+PageInfo
+
+
+Indications that more search results are available.
+
+
+
+
+totalCount
+Int
+
+
+The total number of search results matched by the query.
+
+
+
+
+
+
+### Field
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+key
+String
+
+
+The key for this field.
+
+
+
+
+value
+String
+
+
+The value for this field.
+
+
+
+
+
+
+### Group
+
+The group this event is associated with.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+id
+ID
+
+
+A unique id representing this group.
+
+
+
+
+name
+String
+
+
+The name of this group.
+
+
+
+
+
+
+### PageInfo
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+hasNextPage
+Boolean
+
+
+When paging forward with first, indicates more results are available.
+
+
+
+
+hasPreviousPage
+Boolean
+
+
+When paging backward with last, indicates more results are available.
+
+
+
+
+
+
+### Target
+
+The object an event is performed on.
+
+
+
+
+Field
+Argument
+Type
+Description
+
+
+
+
+id
+ID
+
+
+A unique id representing this target.
+
+
+
+
+name
+String
+
+
+The name of this target.
+
+
+
+
+href
+String
+
+
+The URL associated with this target.
+
+
+
+
+type
+String
+
+
+The type of this target entity.
+
+
+
+
+fields
+[Field]
+
+
+The set of fields associated with this target.
+
+
+
+
+
+
+## Enums
+
+### CRUD
+
+Create | Read | Update | Delete
+
+
+
+Value
+Description
+
+
+
+c
+
+
+create
+
+
+
+
+r
+
+
+read
+
+
+
+
+u
+
+
+update
+
+
+
+
+d
+
+
+delete
+
+
+
+
+
+
+## Scalars
+
+### Boolean
+
+The `Boolean` scalar type represents `true` or `false`.
+
+### ID
+
+The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.
+
+### Int
+
+The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
+
+### String
+
+The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
+
+## Interfaces
diff --git a/docs/retraced/apis/index.md b/docs/retraced/apis/index.md
new file mode 100644
index 0000000..870ec0f
--- /dev/null
+++ b/docs/retraced/apis/index.md
@@ -0,0 +1,289 @@
+# API Documentation
+Retraced API
+
+## Version: 1.4.6
+
+
+**License:** UNLICENSED
+
+### /enterprise/v1/graphql
+
+#### POST
+##### Description:
+
+Query events with [GraphQL](/docs/retraced/apis/admin-api)
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form Token token= ... | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | OK |
+
+null
+
+### /enterprise/v1/search/active
+
+#### POST
+##### Description:
+
+Initiate an active search. An active search will maintain
+a persistent cursor that can be used at a later date to
+retrieve additional events from the search.
+
+
+Authenticate with an Enterprise API token.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | header of the form token= ... | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+### /enterprise/v1/search/saved
+
+#### POST
+##### Description:
+
+Create a saved search.
+Saved searches have an ID that can be used to initiate an active search.
+
+Authenticate with an Enterprise API token.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | header of the form token= ... | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+### /publisher/v1/project/{projectId}/event
+
+#### POST
+##### Description:
+
+Create an event. Returns the id of the created event, and
+a cryptographic hash of the received event, as described [here](/docs/retraced/architecture/hashing-formula/).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+### /publisher/v1/project/{projectId}/event/bulk
+
+#### POST
+##### Description:
+
+Create one or more events. Returns a list of the ids of the created event and
+a cryptographic hash of each received events, as described [here](/docs/retraced/architecture/hashing-formula/).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+### /publisher/v1/project/{projectId}/viewertoken
+
+#### GET
+##### Description:
+
+Create a token for use with the Retraced embedded viewer as described [here](/docs/retraced/getting-started/embedded-viewer/).
+
+**Note**: At least one of `group_id` or `team_id` is required.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+| actor_id | query | | Yes | string |
+| group_id | query | The group identifier. Same as `team_id`. If both are passed, `group_id` will be used. | No | string |
+| is_admin | query | Whether to display the Enterprise Settings and API Token Management. Set to `true` to show the settings. | No | string |
+| target_id | query | If passed, only events relating to this target will be returned in a viewer that uses the token created | No | string |
+| team_id | query | Same as `group_id`. If both are passed, `group_id` will be used. This field is deprecated. | No | string |
+| view_log_action | query | The action that will be logged when the token is used | No | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+### /publisher/v1/project/{projectId}/group/{groupId}/enterprisetoken
+
+#### POST
+##### Description:
+
+Create a token for use with [Enterprise IT API](/docs/retraced/apis/enterprise-api/
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+| groupId | path | The group identifier. The generated token will be scoped to the specified group. | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 201 | Created |
+
+null
+
+#### GET
+##### Description:
+
+List all [Enterprise IT API](/docs/retraced/apis/enterprise-api/) tokens.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+| groupId | path | The group identifier. | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | OK |
+
+null
+
+### /publisher/v1/project/{projectId}/group/{groupId}/enterprisetoken/{tokenId}
+
+#### GET
+##### Description:
+
+Retrieve an [Enterprise IT API](/docs/retraced/apis/enterprise-api/) token.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | The project id. | Yes | string |
+| groupId | path | The group identifier. | Yes | string |
+| tokenId | path | The token id. | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | OK |
+
+null
+
+#### PUT
+##### Description:
+
+Update an [Enterprise IT API](/docs/retraced/apis/enterprise-api/) token
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+| groupId | path | The group identifier. | Yes | string |
+| tokenId | path | The token to update. | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | OK |
+
+null
+
+#### DELETE
+##### Description:
+
+Delete an [Enterprise IT API](/docs/retraced/apis/enterprise-api/) token
+
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+| groupId | path | The group identifier. | Yes | string |
+| tokenId | path | The token to delete. | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 204 | Deleted |
+
+null
+
+### /publisher/v1/project/{projectId}/graphql
+
+#### POST
+##### Description:
+
+Query events with [GraphQL](/docs/retraced/apis/graphql/)
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| Authorization | header | auth header of the form Token token= ... | Yes | string |
+| projectId | path | the project id | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | OK |
+
+null
diff --git a/docs/retraced/apis/overview.md b/docs/retraced/apis/overview.md
new file mode 100644
index 0000000..fd65ab4
--- /dev/null
+++ b/docs/retraced/apis/overview.md
@@ -0,0 +1,19 @@
+# Retraced APIs Overview
+
+Retraced provides several APIs:
+
+## Publisher API
+
+the [Publisher API](/docs/retraced/apis/publisher-api) is the primary API that an application vendor will use to send events into Retraced. This is the API that the [Retraced SDKs](/docs/retraced/sdks/available-sdks) consume. When getting started, this is the first place to start. Use the Publisher API to start sending events into Retraced.
+
+## Enterprise API
+
+The [Enterprise API](/docs/retraced/apis/enterprise-api) is the API that the end customer (the enterprise IT administrator) will consume to pull their organization events and ingest it into their own internal systems.
+
+## Admin API
+
+The [Admin API](/docs/retraced/apis/admin-api) is an optional API that can be used in place of the Retraced Admin site. The Retraced Admin site uses this API. It's useful to managing your account and API tokens and pulling reports.
+
+## Swagger Documentation
+
+### [Retraced API Console](https://retraced.readme.io) | [Publisher API Swagger JSON](http://localhost:3000/auditlog/publisher/v1/swagger.json) | [Enterprise API Swagger JSON](http://localhost:3000/auditlog/enterprise/v1/swagger.json) | [Admin API Swagger JSON](http://localhost:3000/auditlog/admin/v1/swagger.json)
diff --git a/docs/retraced/apis/publisher-api.md b/docs/retraced/apis/publisher-api.md
new file mode 100644
index 0000000..263de37
--- /dev/null
+++ b/docs/retraced/apis/publisher-api.md
@@ -0,0 +1,65 @@
+---
+title: Publisher API
+sidebar_label: Publisher API
+description: Publisher API
+---
+
+# Publisher API
+
+### [Swagger JSON](http://localhost:3000/auditlog/publisher/v1/swagger.json) | [API Console](https://retraced.readme.io/v1.0/reference)
+
+The Publisher API is the API that most applications will embed into a production system. This API contains the methods necessary to send new events into Retraced, create [viewer tokens](/docs/retraced/getting-started/embedded-viewer) and to programmatically search events when the embedded viewer is not being used.
+
+When possible, it's recommended to use one of the supported [SDKs](/docs/retraced/sdks/available-sdks) as these provide an easier way to get started.
+
+To consume the Publisher API directly, we publish a Swagger spec that is both [documented](https://retraced.readme.io/reference) and available in a [raw json object](http://localhost:3000/auditlog/publisher/v1/swagger.json).
+The endpoints for reporting events are `/project/{project_id}/event` and `/project/{project_id}/event/bulk`. The bulk endpoint is for reporting multiple events in a single call. Clients using the bulk endpoint should expect longer response times when submitting large numbers of events.
+
+## Body
+
+We send an event json to `/project/{project_id}/event` API.
+
+Following are the `mandatory` fields.
+
+```json
+{
+ "action": "action-name",
+ "crud": "c" | "r" | "u" | "d",
+ "actor": {
+ "id": "actor-id",
+ "name": "actor-name"
+}
+```
+
+In case of `/project/{project_id}/event/bulk` API we will send an array of events like below,
+
+```json
+{
+ "events": [
+ {
+ "action": "action-name",
+ "crud": "c" | "r" | "u" | "d",
+ "actor": {
+ "id": "actor-id",
+ "name": "actor-name"
+ },
+ },
+ {
+ "action": "action-name",
+ "crud": "c" | "r" | "u" | "d",
+ "actor": {
+ "id": "actor-id",
+ "name": "actor-name"
+ }
+ }
+ ]
+}
+```
+
+## Authentication
+
+The Publisher API endpoints expect the token to be provided in a header of the form
+
+```
+Authorization: token=YOUR_PUBLISHER_TOKEN
+```
diff --git a/docs/retraced/architecture/hashing-formula.md b/docs/retraced/architecture/hashing-formula.md
new file mode 100644
index 0000000..56badab
--- /dev/null
+++ b/docs/retraced/architecture/hashing-formula.md
@@ -0,0 +1,117 @@
+# Hashing Formula
+
+When both the sender and the receiver of a message independently calculate a digest of the message, it's a proven way to ensure that both sides have the same content. But both sides needs to have a reference that describes how to calculate the digest. This document describes the specification that the Retraced API uses to calculate a message digest.
+
+To calculate the digest, Retraced will build a colon (:) delimited string of all the fields, and then calculate a SHA256 digest. Empty or missing fields are not ignored, but are included in the digest as empty strings. Individual fields are percent-escaped before being added to the string.
+
+The order of the fields is important, and is defined as:
+
+1. `event_id`: The string ID that is returned from the Retraced API when calling create event.
+1. `action`: The [action](/docs/retraced/how-to-audit-log/actions/) parameter provided when creating an event.
+1. `target_id`: The ID of the [target](/docs/retraced/how-to-audit-log/targets/) parameter provided when creating an event. If no target was provided, this is an empty string.
+1. `actor_id`: The ID of the [actor](/docs/retraced/how-to-audit-log/actors/) parameter provided when creating an event. If no actor was provided, this is an empty string.
+1. `group_id`: The ID of the [group]/(/docs/retraced/architecture/groups/) parameter provided when creating an event. If no group was provided, this is an empty string.
+1. `source_ip`: The IP address sent with the event. If no IP address was known, this is an empty string.
+1. `is_failure`: An integer ("1" or "0") representation of the is_failure parameter provided when creating an event. This is required, and will default to "0".
+1. `is_anonymous`: An integer ("1" or "0") representation of the is_anonymous parameter provided when creating an event. This is required, and will default to "0".
+1. `fields`: A semicolon (`;`) separated list of the field=value parameters provided in the event. The fields are sorted alphabetically by the key name before encoding. A trailing `;` is included, if there are fields. If there are no fields, a single colon (`:`) should be appended in place of the fields list.
+
+## Examples
+
+### Simple Event
+
+Given the following login audit event:
+
+```json
+{
+ "action": "user.login",
+ "group": {
+ "id": "group-id",
+ "name": "group-name"
+ },
+ "created": "2017-01-01T00:00:00.000000000Z",
+ "crud": "c",
+ "description": "User \"someone@someplace.com\" logged in",
+ "source_ip": "8.8.8.8",
+ "actor": {
+ "id": "actor-id",
+ "name": "actor-name",
+ "type": "user",
+ "url": "https://my.site.com/account/actor-id"
+ },
+ "is_failure": false,
+ "is_anonymous": false
+}
+```
+
+A string is built with the fields, as described above:
+
+```
+event-id:user.login::actor-id:group-id:8.8.8.8:0:0:
+```
+
+Finally, a SHA256 digest of the above string returns:
+
+```
+1ee7c214a6bc2ab3e4f921b7c98a148357eebb56081fd68d88bd25acdec45332
+```
+
+### With Fields
+
+Given the following audit event:
+
+```json
+{
+ "action": "document.share",
+ "group": {
+ "id": "group-id",
+ "name": "group-name"
+ },
+ "created": "2017-01-01T00:00:00.000000000Z",
+ "crud": "u",
+ "target": {
+ "id": "target-id",
+ "name": "document-name",
+ "type": "document",
+ "url": ""
+ },
+ "description": "Shared document with \"another@user.com\"",
+ "source_ip": "8.8.8.8",
+ "actor": {
+ "id": "actor-id",
+ "name": "a@user.com",
+ "type": "user",
+ "url": "https://my.site.com/account/actor-id"
+ },
+ "fields": {
+ "resulting_permission": "view,edit",
+ "permission_granted": "view"
+ },
+ "is_failure": false,
+ "is_anonymous": false
+}
+```
+
+A string is built with the fields, as described above:
+
+```
+event-id:document.share:target-id:actor-id:group-id:8.8.8.8:0:0:permission_granted=view;resulting_permission=view,edit;
+```
+
+Finally, a SHA256 digest of the above string returns:
+
+```
+e3412f11c1ed3b592d5333441880373ede3b774bc62914ed9317d3affaec9048
+```
+
+### Escaping Hash Parameters
+
+Any values used for hashing should have the following replacements applied:
+
+1. `%` -- any percent symbols (`%`) should be converted to `%25`
+1. `:` -- any colons (`:`) should be converted to `%3A`
+
+Further, any values in the `fields` section should also have the following escapes applied in a second pass:
+
+1. `=` -- any equals signs (`=`) should be converted to `%3D`
+1. `;` -- any semicolons (`;`) should be converted to `%3B`
diff --git a/docs/retraced/architecture/immutability-guarantee.md b/docs/retraced/architecture/immutability-guarantee.md
new file mode 100644
index 0000000..e366ea1
--- /dev/null
+++ b/docs/retraced/architecture/immutability-guarantee.md
@@ -0,0 +1,15 @@
+# Immutability Guarantee
+
+When you send audit events into Retraced, we offer functionality that guarantees the data you sent is the data that was received. We use the same functionality to allow you to, at any time, cryptographically verify that the events have not changed since they were written and no events have been removed.
+
+## Digest of Events
+
+When an event is received by the Retraced API, the methods that receives the event will always synchronously compute a digest hash of the data received, using our publicly documented [hashing formula](/docs/retraced/architecture/hashing-formula). The computed digest is returned, along with the rest of the standard response. It's up to the sender to independently calculate the digest of the event and compare it to the response from the Retraced API. If these digests do not match, the event was not properly decoded or received by the Retraced API.
+
+When using any of the [official Retraced SDKs](/docs/retraced/sdks/available-sdks), this computation and comparison happens automatically. All of our SDKs are open source, and this can be independently verified by examining the relevant source code of the SDK.
+
+## Future Verification of Immutability
+
+When validating immutability for audit events, it's important to both verify that the events have not changed, and to verify that no events were added or deleted. Retraced provides functionality for both of these verifications.
+
+Audited events are not always displayed with every field originally sent. Also, it's possible for an [actor or item to be renamed](/docs/retraced/getting-started/renaming-properties) at some point in the future. Retraced will always store the original event received, and it's possible to retrieve that source. In fact, this source is used to dynamically calculate value to show when displaying an event in the browser or other source.
diff --git a/docs/retraced/architecture/index.md b/docs/retraced/architecture/index.md
new file mode 100644
index 0000000..270f02d
--- /dev/null
+++ b/docs/retraced/architecture/index.md
@@ -0,0 +1,16 @@
+---
+title: Retraced Architecture
+sidebar_label: Overview
+---
+
+# Overview
+
+Retraced is more than a traditional database to store and retrieve objects. The "Architecture" documentation provides an overview of some of the features that Retraced provides to provide immutability and verifiability of your audit log data.
+
+
+
+## Cryptographically Guarantee Immutability
+
+Retraced implements industry standard and provable digest algorithms to ensure the data you send into an audit log is the data that was received. The same algorithms can be used in the future to verify that none of the data has changed since it was written. This works automatically when using our [SDKs](/docs/retraced/sdks/available-sdks), and can be implemented manually if you use the API directly.
+
+Details of how we guarantee immutability are discussed in detail on the [immutability guarantee](/docs/retraced/architecture/immutability-guarantee) page.
diff --git a/docs/retraced/container-signing.md b/docs/retraced/container-signing.md
new file mode 100644
index 0000000..0098423
--- /dev/null
+++ b/docs/retraced/container-signing.md
@@ -0,0 +1,21 @@
+# Container Signing and Verification for Retraced
+
+Retraced container images are signed and can be verified using [cosign](https://github.com/sigstore/cosign).
+
+## Fetching our public key
+
+You can use [oras](https://oras.land/docs/category/cli) (or a similar OCI artifacts tool) to fetch our public key or download it from our website [here](https://boxyhq.com/.well-known/cosign.pub).
+
+```bash
+oras pull ghcr.io/boxyhq/cosign.pub:latest
+```
+
+## Container verification
+
+**Note:** This is supported for all versions >=1.5.0
+
+Our container images are hosted on [Docker Hub](https://hub.docker.com/r/retracedhq/retraced/tags). You can verify it by using the following command.
+
+```bash
+cosign verify --key cosign.pub retracedhq/retraced:
+```
diff --git a/docs/retraced/exposing-retraced-data/enterprise-api.md b/docs/retraced/exposing-retraced-data/enterprise-api.md
new file mode 100644
index 0000000..8c4c5c8
--- /dev/null
+++ b/docs/retraced/exposing-retraced-data/enterprise-api.md
@@ -0,0 +1,163 @@
+# Using The Enterprise API
+
+The Retraced Enterprise API enables users to consume audit log data programmatically and integrate it with an external monitoring or security system.
+
+## Creating and Managing Enterprise Tokens
+
+Enterprise Tokens can be created and managed via the [Embedded Viewer](/docs/retraced/exposing-retraced-data/viewer/)
+
+**Note**: If you're a vendor integrating Retraced as your audit log, you can also manage and distribute Enterprise Tokens using the [Publisher API](/docs/retraced/apis/publisher-api/).
+
+## Graphql
+
+The quickest way to start getting events is using the GraphQL API. Below is an example request:
+
+```sh
+curl -sSL 'http://localhost:3000/auditlog/enterprise/v1/graphql' \
+ -H 'Authorization: token=' \
+ -H 'Content-Type: application/json' \
+ --data-binary '{
+ "variables": {
+ "before": "",
+ "last": 3,
+ "query": "action:document.edit received:2017-11-01,2017-12-01"
+ },
+ "query": "query Search($query: String!, $last: Int, $before: String) { search(query: $query, last: $last, before: $before) { totalCount pageInfo { hasPreviousPage } edges { cursor node { id action crud created actor { name }}}}}"
+}'
+```
+
+There are five things to pay attention to here:
+
+- We send our Enterpise API Token in a header of the form `Authorization: token=...`
+- `variables.last` is the number of events we're requesting, in this case we only want the last 3 events
+- `variables.query` is a free-text or structured search query, as you'd use in [The Embedded Viewer](/docs/retraced/exposing-retraced-data/viewer/#search).
+- `variables.before` allows us to specify a cursor for paging through events. Since we just want the most recent events, we'll leave this blank for now.
+- In the `query` field, we describe the structure and parameters of the GraphQL query.
+
+The response will look something like
+
+```json
+{
+ "data": {
+ "search": {
+ "edges": [
+ {
+ "cursor": "MTUxMDg3MjgwNzAxMyxmMzc4MDNkZDdlOTY0NmUzYTRkZjQyZjdiNGUzOWRjMQ==",
+ "node": {
+ "action": "license.update",
+ "actor": {
+ "name": "customertowne+xyz@mycompany.com"
+ },
+ "created": "2017-11-16T22:53:27Z",
+ "crud": "u",
+ "id": "f37803dd7e9646e3a4df42f7b4e39dc1"
+ }
+ },
+ {
+ "cursor": "MTUxMDg3Mjc5ODUyNiwyZWFiYzA2NDI5NTc0YWEzOWNmNmI4MWYxNTQ1NzFlMQ==",
+ "node": {
+ "action": "license.update",
+ "actor": {
+ "name": "jane.smith@company.com"
+ },
+ "created": "2017-11-16T22:53:18Z",
+ "crud": "u",
+ "id": "2eabc06429574aa39cf6b81f154571e1"
+ }
+ },
+ {
+ "cursor": "MTUxMDg2Nzc3MzMxNiw5Y2M2NTM3ZGRjZTk0ZGEyODI0NTA4ZTc4M2EzOGRjNQ==",
+ "node": {
+ "action": "application.branding.update",
+ "actor": {
+ "name": "john.doe@company.com"
+ },
+ "created": "2017-11-16T21:29:33Z",
+ "crud": "u",
+ "id": "9cc6537ddce94da2824508e783a38dc5"
+ }
+ }
+ ],
+ "pageInfo": {
+ "hasPreviousPage": true
+ },
+ "totalCount": 2411
+ }
+ }
+}
+```
+
+The query itself is in the `query` field of the json body:
+
+```
+query Search($query: String!, $last: Int, $before: String) { search(query: $query, last: $last, before: $before) { totalCount pageInfo { hasPreviousPage } edges { cursor node { id action crud created actor { name }}}}}
+```
+
+The same query is expanded below for readability. In general use, the first few lines won't change for every request, the interesting part is under `node`, where you're able to select which fields you'd like to receive.
+
+```
+query Search($query: String!, $last: Int, $before: String) {
+ search(query: $query, last: $last, before: $before) {
+ totalCount
+ pageInfo {
+ hasPreviousPage
+ }
+ edges {
+ cursor
+ node {
+ id
+ action
+ crud
+ created
+ actor {
+ name
+ }
+ }
+ }
+ }
+}
+```
+
+This example only requests a few event fields: `id`, `action`, `crud`, `created`, and `actor.name`, but there are many other fields available, as described in the [Event Schema](/docs/retraced/apis/graphql/#event).
+
+The GraphQL APIs for consuming events are specified fully in [GraphQL API Guide](/docs/retraced/apis/graphql/). There are example queries and usage in the [Go SDK](https://github.com/retracedhq/retraced-go/blob/master/graphql.go#L216) and the [Javascript SDK](https://github.com/retracedhq/retraced-js/blob/master/src/graphql.ts#L334)
+
+
+
+## Saved Searches
+
+The Enterprise API includes several endpoints for saving a search and maintaining a persistent cursor across search queries.
+
+The general workflow is:
+
+- Create a "Saved Search" with desired query parameters
+- Create an "Active Search" from the saved search's ID
+- Use the "Pump Active Search" endpoint whenever you want to get more events from your search.
+ - Pump active search will always return only the events that occurred since the last time it was queried, so it can be called as often as every few seconds, or as infrequently as every few months
+
+**Note**: Saved Search functionality may not be available in all Retraced environments.
+
+The endpoints for managing Saved Searches are described in the [Enterprise API Guide](/docs/retraced/apis/enterprise-api/). There's also an [OpenAPI/Swagger specification](http://localhost:3000/auditlog/enterprise/v1/swagger.json) and [interactive API console](https://retraced.readme.io/reference#searchactive).
diff --git a/docs/retraced/exposing-retraced-data/overview.md b/docs/retraced/exposing-retraced-data/overview.md
new file mode 100644
index 0000000..ea47b7a
--- /dev/null
+++ b/docs/retraced/exposing-retraced-data/overview.md
@@ -0,0 +1,12 @@
+# Exposing Retraced Data
+
+
+There are two main way to expose your audit log data to your application's users. Users can browse and search events using an embeddable viewer UI, or they can access data programmatically using API tokens.
+
+## Using the embedded viewer
+
+As a vendor, you can [embed the event viewer](/docs/retraced/getting-started/embedded-viewer/) into frontend site. For a guide to viewer features, see [Using the Embedded Viewer](/docs/retraced/exposing-retraced-data/viewer/)
+
+## Using Enterprise IT Integration API Tokens
+
+In addition to the viewer, Audit events can be exposed via the [Enterprise IT Integration API](/docs/retraced/exposing-retraced-data/enterprise-api/)
diff --git a/docs/retraced/exposing-retraced-data/viewer.md b/docs/retraced/exposing-retraced-data/viewer.md
new file mode 100644
index 0000000..714ba85
--- /dev/null
+++ b/docs/retraced/exposing-retraced-data/viewer.md
@@ -0,0 +1,40 @@
+# Using the Retraced Viewer
+
+The Retraced embedded viewer is the easiest way consume and understand your audit log data. This guide will walk you through the viewer's features.
+
+Note -- if you're a Software Vendor and you're looking to embed the viewer into your site, see the [Embedded Viewer Guide](/docs/retraced/getting-started/embedded-viewer/)
+
+## Overview
+
+The viewer exposes four core features:
+
+1. Search
+1. Filters
+1. Export
+1. API Token Management.
+
+
+
+### Search
+
+The search box allows for free-text search of all audit events, but also supports some structured search operators. Some example searches:
+
+- `edit` -- free text search
+- `action:users.list` -- search by action
+- `action:document.* location:Germany` -- search by action and location
+- `actor.id:john.doe@mycompany.com` -- search by actor id
+- `action:user.login,user.logout` -- seach by multiple actions
+
+### Filters
+
+The filters section allows for filtering events by date range, and by Create/Read/Update/Delete actions.
+
+### Export
+
+Save searches and export them to CSV using the "Exports" section.
+
+### API Tokens
+
+Create and Manage Enterprise API tokens using the "API Tokens" section.
+
+For a guide on using API Tokens, see [Using The Enterprise API](/docs/retraced/exposing-retraced-data/enterprise-api)
diff --git a/docs/retraced/getting-started/embedded-viewer.md b/docs/retraced/getting-started/embedded-viewer.md
new file mode 100644
index 0000000..215d8ac
--- /dev/null
+++ b/docs/retraced/getting-started/embedded-viewer.md
@@ -0,0 +1,58 @@
+# Embedded Viewer
+
+Now that you've sent some events into Retraced, it's time to expose them to your end users. Retraced has an advanced, highly customizable log viewer that you can embed on your own site.
+
+Note: Currently, a React-based site is required to embed the viewer, but support for embedding without React will be available soon.
+
+## Installing
+
+There are a few short steps to getting the embedded viewer integrated into your site.
+
+1. Install the `@retracedhq/logs-viewer` package from npm and include in your site.
+1. Request a token from the Retraced API to identify which group/scope the viewer should be limited to. This should be initiated from your backend server, not the browser.
+1. Render the `
+ header="My Audit Log"
+ mount={true} />
+ )
+}
+```
+
+or, without JSX:
+
+```html
+ReactDOM.render( React.createElement( RetracedEventsBrowser, { auditLogToken:
+, mount: true }, ), document.getElementById('main') );
+```
+
+#### Options
+
+The embedded viewer supports quite a few options, but they all have defaults. The table below describes the keys that are possible to override in the component properties.
+
+| Key | Default Value | Value Type | Description |
+| --------------- | ----------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| admin | `true` | `boolean` | A bool to indicate if the admin/settings button is possible to show. This will never force it to show, this setting is provided to completely disable this button at times. |
+| export | `true` | `boolean` | A bool to indicate if the export button should be shown on the footer. |
+| crud | `cud` | `string` | The default search filter options to enable. By default, read items are not shown. |
+| theme | `light` | `string` | The theme to use. Supports `dark` and `light`. |
+| header | `Audit Log` | `string` | A header to show beside the search box. |
+| apiTokenHelpURL | https://boxyhq.com/docs/retraced/exposing-retraced-data/enterprise-api/ | `string` | A help link for the "How to Use Audit Log API Tokens" text in the API tokens modal. |
+| searchHelpURL | https://boxyhq.com/docs/retraced/exposing-retraced-data/viewer/#search | `string` | A help link for the "Get Help With Search" text in search filters modal. |
+| customClass | `` | `string` | One or more space-separated CSS classes to apply to the outermost viewer `` |
+| host | `http://localhost:3000/auditlog` | `string` | Retraced API host to use. Only needs to change for on-premise Retraced instances. |
+| mount | `false` | `boolean` | Determines whether to mount the component. Handy if you need to wait until a token is returned from your backend. |
diff --git a/docs/retraced/getting-started/first-audit-event.md b/docs/retraced/getting-started/first-audit-event.md
new file mode 100644
index 0000000..f44f0df
--- /dev/null
+++ b/docs/retraced/getting-started/first-audit-event.md
@@ -0,0 +1,23 @@
+# The First Audit Event
+
+Getting started with Retraced is easy. The best way to start is to pick a single event to start sending to confirm that everything is set up right. If your site has a login event, it's a perfect first event because it covers most of the scenarios that can be tricky when starting to audit log. Login events can have both a successful and failed response, it can be anonymous or authenticated and it may or may not belong to a group.
+
+Remembering the basics of [how to audit log](/docs/retraced/how-to-audit-log), you should find a place in your code that is guaranteed to be executed after a login event.
+
+## Publishing Guide
+
+### Getting a Token
+
+First step is to [get a token for the publisher api](/docs/retraced/apis/publisher-api#publisher-api-tokens) from
+the Retraced admin site.
+
+### Sending Events
+
+Next, in your Login API handler, you'll want to add a call to the Publisher API's after each login attempt. The Create Event call can be made using one of the [Retraced SDKs](/docs/retraced/sdks/available-sdks), or by making a request to `POST /publisher/v1/project/{projectId}/event` as described in the [Publisher API Documentation](/docs/retraced/apis/publisher-api) and the [Publisher Swagger Specification](http://localhost:3000/auditlog/publisher/v1/swagger.json).
+
+### Verifying Event Hashes
+
+The response from the Publisher API will include a hash of the received event computed according to the Retraced [event hashing formula](/docs/retraced/architecture/hashing-formula). You can choose to verify this hash to ensure
+the event your api sent is identical to the one received by Retraced. If you are using one of the [Retraced SDKs](/docs/retraced/sdks/available-sdks), you can take advantage of built-in functionality for verifying event hashes.
+
+
diff --git a/docs/retraced/getting-started/renaming-properties.md b/docs/retraced/getting-started/renaming-properties.md
new file mode 100644
index 0000000..0e423b3
--- /dev/null
+++ b/docs/retraced/getting-started/renaming-properties.md
@@ -0,0 +1,9 @@
+# Renaming Properties
+
+Some properties of an audit event can be renamed after the event is received. There is a limited amount of these and the original event is still [immutable](/docs/retraced/how-to-audit-log/immutable/). But data can change over time, and it's important to be able to link to and find events later.
+
+## Actor
+
+When sending an event, an [actor](/docs/retraced/how-to-audit-log/actors/) is a required field. The `id` property of the actor is immutable and is linked and cross referenced in Retraced to make it possible to search for and find all events that a specific actor performed. An actor object has additional fields including name, url and any other data you include. These fields are mutable and the values sent with an event will replace the global values for the actor in Retraced.
+
+When requesting the [original events](/docs/retraced/architecture/immutability-guarantee/#future-verification-of-immutability), the original values sent when the event was created will be returned.
diff --git a/docs/retraced/getting-started/retraced-basics.md b/docs/retraced/getting-started/retraced-basics.md
new file mode 100644
index 0000000..eaadb73
--- /dev/null
+++ b/docs/retraced/getting-started/retraced-basics.md
@@ -0,0 +1,15 @@
+# Retraced Basics
+
+At it's core, Retraced consists of 3 components:
+
+- The [Publisher API](/docs/retraced/apis/publisher-api), which is used by a
+ vendor application to report audit events to Retraced.
+
+- A [Logs Viewer](/docs/retraced/getting-started/embedded-viewer) which
+ can be embedded in the frontend of a vendor application to allow end customers
+ to view, search, and export logs.
+
+- The [Enterprise IT Integration API](/docs/retraced/apis/enterprise-api) which
+ be used by end customers to consume audit log events programmatically.
+
+The first step in any Retraced integration is [sending an event to the Publisher API](/docs/retraced/getting-started/first-audit-event). Once events have been published to Retraced, they can be consumed either by embedding the logs viewer or by accessing the Enterprise IT Integration API.
diff --git a/docs/retraced/getting-started/searching-for-events.md b/docs/retraced/getting-started/searching-for-events.md
new file mode 100644
index 0000000..1f60998
--- /dev/null
+++ b/docs/retraced/getting-started/searching-for-events.md
@@ -0,0 +1,24 @@
+# Searching For Events
+
+The Retraced interface supports searching for events. While it's presented as a single, simple input field, the Retraced search interface supports complex structured queries.
+
+## Free Text Search
+
+By default, the search query you type in the search box will seach all fields for this value.
+
+## Structured (Advanced) Search
+
+If you use the advanced search syntax, you can perform very specific and exact searches to find the data you are looking for. The syntax for this is `key:value`. For example, to search for all events that have an action that starts with `user.` you could enter the following query: `action:user.*`
+
+This table shows the supported advanced searches:
+
+| Key | Description | Examples |
+|---|---|---|
+| action | Matches events with the action equal to the value. This supports trailing wildcards. | `action:user.login`
`action:user.*` |
+| crud | Matches events with crud type equal to any of the values. | `crud:c,u,d`
`crud:r` |
+| received | Matches events with the received field in the range. This accepts two comma-separated ISO 8601 datetimes. Either start or end may be omitted to search an unbounded time range.| `received:2017-05-01,2017-06-01`
`received:2017-05-01T12:30+07,2017-05-01T13:30+07`
`received:,2017-01-01`
`received:2017-01-01,` |
+| created | Matches events with the created field in the range. | created:2017-05-01,2017-05-02 |
+| actor.name | Matches events performed by an actor whose name contains the value. | actor:Smith |
+| actor.id | Matches events performed by the actor with the exact id value. | actor:b82c4cfa428342ac822c42c1f6b89200 |
+| description | Matches events with a description containing the terms in the value. | description:"elevated escalated" |
+| location | Matches events performed in a geographic region equal to the value. | location:"Los Angeles" |
diff --git a/docs/retraced/getting-started/time-synchronization.md b/docs/retraced/getting-started/time-synchronization.md
new file mode 100644
index 0000000..9843f4e
--- /dev/null
+++ b/docs/retraced/getting-started/time-synchronization.md
@@ -0,0 +1,5 @@
+# Reporting Event Timing
+
+## Recording Event Timing in Retraced
+
+Retraced allows clients to specify a `created` time for any event. In addition to allowing clients to report event timing, the Retraced Publisher API will record an NTP-synchronized `received` timestamp for all events.
diff --git a/docs/retraced/how-to-audit-log/actions.md b/docs/retraced/how-to-audit-log/actions.md
new file mode 100644
index 0000000..b095c55
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/actions.md
@@ -0,0 +1,3 @@
+# Actions
+
+Actions are the events that the actors performed that should be audited. In the spreadsheet example application, some of the most obvious actions might include `sheet.create` and `sheet.delete`. Sometimes it's important to create new objects to wrap events. For example, if a user is editing a spreadsheet and the sheet saves every second, you don't want to create a `sheet.update` event each second. Wrap these events into a session and create a single `sheet.update` event for the entire edit session.
diff --git a/docs/retraced/how-to-audit-log/actors.md b/docs/retraced/how-to-audit-log/actors.md
new file mode 100644
index 0000000..a4c1003
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/actors.md
@@ -0,0 +1,4 @@
+# Actors
+
+An actor in the spreadsheet application is any authenticated identity that's interacting with the spreadsheet. This includes the users who are logged in and editing, deleting, and creating new spreadsheets. It also includes any API tokens that are performing operations on the spreadsheets programatically.
+
diff --git a/docs/retraced/how-to-audit-log/exportable.md b/docs/retraced/how-to-audit-log/exportable.md
new file mode 100644
index 0000000..265ffe2
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/exportable.md
@@ -0,0 +1,3 @@
+# Exportability
+
+Most users of audit logs will want to connect it into systems that aggregate audit logs from different systems (such as Splunk).
diff --git a/docs/retraced/how-to-audit-log/immutable.md b/docs/retraced/how-to-audit-log/immutable.md
new file mode 100644
index 0000000..7f24226
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/immutable.md
@@ -0,0 +1,3 @@
+# Immutability
+
+A fundamental tenant of any audit log is that it must be absolutely immutable. Once an event has occured, it must always be recorded and there must be no possible way to alter this event.
diff --git a/docs/retraced/how-to-audit-log/index.md b/docs/retraced/how-to-audit-log/index.md
new file mode 100644
index 0000000..07a39f9
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/index.md
@@ -0,0 +1,87 @@
+---
+title: Audit Logging Basics
+sidebar_label: Overview
+---
+
+# Audit Logging Basics
+
+An audit log is a centralized stream of all user activity in an application.
+
+The JSON structure looks like this
+
+```typescript
+{
+ "action": string,
+ "group"?: {
+ "id": string,
+ "name"?: string,
+ },
+ "crud"?: string,
+ "created"?: Date,
+ "actor"?: {
+ "id": string,
+ "name"?: string,
+ "href"?: string,
+ "fields"?: {
+ [key: string]: string
+ },
+ },
+ "target"?: {
+ "id": string,
+ "name"?: string,
+ "href"?: string,
+ "type"?: string,
+ "fields"?: {
+ [key: string]: string
+ },
+ },
+ "source_ip"?: string,
+ "description"?: string,
+ "is_failure"?: boolean,
+ "is_anonymous"?: boolean,
+ "fields"?: {
+ [key: string]: string
+ },
+}
+```
+
+You can see the example below,
+
+```json
+{
+ "action": "some.record.created",
+ "teamId": "boxyhq",
+ "group": {
+ "id": "boxyhq",
+ "name": "BoxyHQ"
+ },
+ "crud": "c",
+ "created": "2023-01-13T11:24:07.575Z",
+ "source_ip": "127.0.0.1",
+ "actor": {
+ "id": "jackson@boxyhq.com",
+ "name": "Jackson"
+ },
+ "target": {
+ "id": "100",
+ "name": "tasks",
+ "type": "Tasks"
+ }
+}
+```
+
+An audit log event is a single line that represents an [action](/docs/retraced/how-to-audit-log/actions) that an [actor](/docs/retraced/how-to-audit-log/actors) took, most often on a [target](/docs/retraced/how-to-audit-log/targets).
+
+Sometimes it's easiest to think about this with a concrete example. Let's consider a multi-user, collaborative spreadsheet application.
+
+## Actors
+
+An actor in the spreadsheet application is any authenticated identity that's interacting with the spreadsheet. This includes the users who are logged in and editing, deleting, and creating new spreadsheets. It also includes any API tokens that are performing operations on the spreadsheets programatically.
+
+## Actions
+
+Actions are the events that the actors performed that should be audited. In the spreadsheet example application, some of the most obvious actions might include `sheet.create` and `sheet.delete`. Sometimes it's important to create new objects to wrap events. For example, if a user is editing a spreadsheet and the sheet saves every second, you don't want to create a `sheet.update` event each second. Wrap these events into a session and create a single `sheet.update` event for the entire edit session.
+
+## Targets
+
+Targets are the objects in a system that have an action taken on them. In the spreadsheet example application, the primary target is the sheets themselves. But there are additional, less obvious targets. If the sheet application has implemented it's own authentication system, another target is the user accounts. For example, when a user changes their password, it should create an audit event for `password.update`.
diff --git a/docs/retraced/how-to-audit-log/searchable.md b/docs/retraced/how-to-audit-log/searchable.md
new file mode 100644
index 0000000..cd2b6bc
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/searchable.md
@@ -0,0 +1,3 @@
+# Searchability
+
+A good Audit log needs to be searchable. Proper indexing on actors, actions, and targets is essential to being able to isolate and drill down into the history of application objects and events.
\ No newline at end of file
diff --git a/docs/retraced/how-to-audit-log/segments.md b/docs/retraced/how-to-audit-log/segments.md
new file mode 100644
index 0000000..a05d3d0
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/segments.md
@@ -0,0 +1,13 @@
+# Segments
+
+## Project
+
+A project represents a distinct application offered by a vendor. A vendor that only offers a single application, such as spreadsheets, would only need one project, while a vendor offering spreadsheets and calendars would have two projects. You can find your project IDs on the [Retraced Admin Portal](../../admin-portal/audit-logs.md).
+
+## Environment
+
+An environment represents a deployment target for a project. Retraced generates Production and Staging environments for each new project. You can manage your project's environments with the [Admin API](/docs/retraced/apis/admin-api) or the [Admin Portal](../../admin-portal/audit-logs.md).
+
+## Group
+
+A group is an end customer in your multi-tenant application. You can segment your audit log into groups by adding a `group.id` to each event. Then you may provide your end customers read access to their segment with the [Enterprise API](/docs/retraced/apis/enterprise-api).
diff --git a/docs/retraced/how-to-audit-log/targets.md b/docs/retraced/how-to-audit-log/targets.md
new file mode 100644
index 0000000..a208044
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/targets.md
@@ -0,0 +1,4 @@
+# Targets
+
+
+Targets are the objects in a system that have an action taken on them. In the spreadsheet example application, the primary target is the sheets themselves. But there are additional, less obvious targets. If the sheet application has implemented it’s own authentication system, another target is the user accounts. For example, when a user changes their password, it should create an audit event for `password.update`.
\ No newline at end of file
diff --git a/docs/retraced/how-to-audit-log/time-synced.md b/docs/retraced/how-to-audit-log/time-synced.md
new file mode 100644
index 0000000..5b0438f
--- /dev/null
+++ b/docs/retraced/how-to-audit-log/time-synced.md
@@ -0,0 +1,24 @@
+# Time Synchronization
+
+
+A good audit log should record a synchronized timestamp that allows an end customer to determine with a high level of confidence:
+
+* The human-readable time an event occured,for example:
+
+`sheet.create occurred at 2017-01-01 17:45:22.011`
+
+* The ordering of events, for example
+
+`sheet.create occured before sheet.update`
+
+
+## Wall Time vs. Causal Ordering
+
+
+It's not always possible to have both a human-readable "wall time" and a causally consistent sequencing of events. When forced to trade between a human-readable wall time and a causally consistent sequencing of events, an Audit Log should favor causal consistency over a precise wall time. In a best-case scenario, protocols like Network Time Protocol (NTP) can allow for a high level of accuracy in both.
+
+
+## Recording Time in Retraced
+
+
+Retraced allows clients to specify a `created` time for any event. In addition to allowing clients to report event timing, the Retraced Publisher API will record an NTP-synchronized `received` timestamp for all events.
\ No newline at end of file
diff --git a/docs/retraced/overview.md b/docs/retraced/overview.md
new file mode 100644
index 0000000..cc8d557
--- /dev/null
+++ b/docs/retraced/overview.md
@@ -0,0 +1,40 @@
+---
+title: Introduction To Retraced
+sidebar_label: Overview
+---
+
+# Introduction To Retraced
+
+Retraced provides an audit log feature for your application; one that meets all of the principles of [what makes a good audit log](/docs/retraced/how-to-audit-log). Retraced provides both an API to send audit events to, and several different methods for your customers to view and extract their events.
+
+Brought to you by BoxyHQ and [Replicated](https://www.replicated.com/). Check out our [GitHub repo](https://github.com/retracedhq/retraced)
+
+## About Retraced
+
+### Own your own data
+
+- An open-source solution that allows you to keep control of your data
+- Supports Postgres for now
+- Built-in support for Elasticsearch (optional, Postgres search can be used instead)
+
+### Flexible and easy to use
+
+- Designed to work with REST APIs
+- Integrates with your existing applications
+- Comes with an embedded viewer that you can use with your React applications
+
+### Support
+
+Reach out to the maintainer at one of the following places:
+
+- [GitHub Issues](https://github.com/retracedhq/retraced/issues)
+- The email which is located [in GitHub profile](https://github.com/deepakprabhakara)
+
+### Community
+
+- [Discord](https://discord.gg/uyb7pYt4Pa)
+- [Twitter](https://twitter.com/boxyhq)
+
+### License
+
+[Apache 2.0 License](https://github.com/retracedhq/retraced/blob/master/LICENSE)
diff --git a/docs/retraced/sbom.md b/docs/retraced/sbom.md
new file mode 100644
index 0000000..bc49a9b
--- /dev/null
+++ b/docs/retraced/sbom.md
@@ -0,0 +1,60 @@
+# Software Bill Of Materials (SBOM) Reports for Retraced
+
+[SBOM](https://en.wikipedia.org/wiki/Software_bill_of_materials) is a list of components in a piece of software. It is like a list of ingredients of a product. Is it quickly becoming a standard for software supply chain risk and the ecosystem is growing with tools that help you verify, scan and monitor all your dependencies.
+
+## Report Standards
+
+SBOM reports primarily use [SPDX](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange) & [CycloneDX](https://cyclonedx.org/) standards.
+
+## Reports for Retraced
+
+**Note:** This is supported for all versions >=1.5.3
+
+You can find the SBOM reports as artifacts in our container registry at the locations below. They are updated every time there is change in the codebase and tagged by the exact version we release.
+
+| Location | Files | Context |
+| ---------------------------------------------------- | ----------------------------- | --------------------------------- |
+| `ghcr.io/retracedhq/retraced/sbom:service-` | `sbom.spdx`, `sbom.cyclonedx` | Retraced service |
+| `ghcr.io/retracedhq/retraced/sbom:docker-` | `sbom.spdx`, `sbom.cyclonedx` | Docker Image for Retraced service |
+
+You can use [oras](https://oras.land/docs/category/cli) (or a similar OCI artifacts tool) to retrieve these files.
+
+```bash
+oras pull ghcr.io/retracedhq/retraced/sbom:service-
+```
+
+## Reports for Javascript SDK
+
+Located at [https://www.npmjs.com/package/@retracedhq/retraced](https://www.npmjs.com/package/@retracedhq/retraced)
+
+**Note:** This is supported for all versions >=0.6.2
+
+You can find the SBOM reports as artifacts in our container registry at the locations below. They are updated every time there is change in the codebase and tagged by the exact version we release.
+
+| Location | Files | Context |
+| --------------------------------------------------- | ----------------------------- | --------------- |
+| `ghcr.io/retracedhq/retraced-js/sbom:npm-` | `sbom.spdx`, `sbom.cyclonedx` | Retraced JS SDK |
+
+You can use [oras](https://oras.land/docs/category/cli) (or a similar OCI artifacts tool) to retrieve these files.
+
+```bash
+oras pull ghcr.io/retracedhq/retraced-js/sbom:npm-
+```
+
+## Reports for React Logs Viewer
+
+Located at [https://www.npmjs.com/package/@retracedhq/logs-viewer](https://www.npmjs.com/package/@retracedhq/logs-viewer)
+
+**Note:** This is supported for all versions >=2.4.6
+
+You can find the SBOM reports as artifacts in our container registry at the locations below. They are updated every time there is change in the codebase and tagged by the exact version we release.
+
+| Location | Files | Context |
+| --------------------------------------------------- | ----------------------------- | ------------------ |
+| `ghcr.io/retracedhq/logs-viewer/sbom:npm-` | `sbom.spdx`, `sbom.cyclonedx` | Retraced React SDK |
+
+You can use [oras](https://oras.land/docs/category/cli) (or a similar OCI artifacts tool) to retrieve these files.
+
+```bash
+oras pull ghcr.io/retracedhq/logs-viewer/sbom:npm-
+```
diff --git a/docs/retraced/sdks/available-sdks.md b/docs/retraced/sdks/available-sdks.md
new file mode 100644
index 0000000..da09c38
--- /dev/null
+++ b/docs/retraced/sdks/available-sdks.md
@@ -0,0 +1,13 @@
+---
+title: Retraced SDKs
+sidebar_label: Overview
+---
+
+# Integrate Retraced
+
+It's possible to use Retraced completely with the [documented API](/docs/retraced/apis/overview/). But that can often be a little tedious, so we've created easy-to-use SDKs for popular languages and frameworks. If you don't see your stack on here, [reach out](https://github.com/retracedhq/retraced/issues) to send a request and we'll see how we can help!
+
+## Official libraries
+
+- [Go](golang.md)
+- [Node.js](nodejs.md)
diff --git a/docs/retraced/sdks/golang.md b/docs/retraced/sdks/golang.md
new file mode 100644
index 0000000..ef6cf74
--- /dev/null
+++ b/docs/retraced/sdks/golang.md
@@ -0,0 +1,53 @@
+---
+title: Retraced Go SDK
+sidebar_label: Go
+---
+
+# Go
+
+On this page, we get you up and running with Retraced's Go SDK in your application.
+
+## Installation
+
+```bash
+go get github.com/retracedhq/retraced-go
+```
+
+## Basic Usage
+
+Error handling omitted for brevity.
+
+### Initialize a client
+
+```go
+import "github.com/retracedhq/retraced-go"
+
+client, _ := retraced.NewClient("The host, defaults to http://localhost:3000/auditlog", "You Retraced project id goes here", "Your Retraced Publisher API token goes here")
+```
+
+### Report an event
+
+```go
+event := &retraced.Event{
+ Created: time.Now(),
+ CRUD: "r",
+ Action: "user.login",
+ Description: "User Alice logged in",
+ SourceIP: "102.109.10.1",
+ Actor: &retraced.Actor{ID: "alice@bigcorp.com", Name: "Alice"},
+ Group: &retraced.Group{ID: "bigcorp.com"},
+}
+
+resp, _ := client.ReportEvent(event)
+```
+
+### Verify the event receipt hash
+
+```go
+err := event.VerifyHash(resp)
+if err != nil {
+ // hashes did not match
+} else {
+ // event reported successfully
+}
+```
diff --git a/docs/retraced/sdks/nodejs.md b/docs/retraced/sdks/nodejs.md
new file mode 100644
index 0000000..e8c48b4
--- /dev/null
+++ b/docs/retraced/sdks/nodejs.md
@@ -0,0 +1,61 @@
+---
+title: Retraced NodeJS SDK
+sidebar_label: NodeJS
+---
+
+# NodeJS
+
+On this page, we get you up and running with Retraced's NodeJS SDK in your application.
+
+## Installation
+
+The Retraced NodeJS SDK can be installed with npm:
+
+```bash
+npm install -s @retracedhq/retraced
+```
+
+## Basic Usage
+
+### Initialize a client
+
+```javascript
+import * as Retraced from 'retraced';
+
+const retraced = new Retraced.Client({
+ apiKey: 'your api key goes here',
+ projectId: 'your project id goes here',
+});
+```
+
+### Report an event
+
+```javascript
+const event = {
+ action: "some.record.created",
+ teamId: "My Rad Customer",
+ crud: "C",
+ source_ip: request.ip,
+ actor: {
+ id: "ultra.employee@customertowne.xyz",
+ displayName: "Ultra Employee",
+ url: "https://customertowne.xyz/employees/123456",
+ },
+ target: {
+ id: newRecord.id,
+ displayName: newRecord.name,
+ url: "https://customertowne.xyz/records/" + newRecord.id,
+ },
+};
+
+// The Retraced client's methods are asynchronous.
+// You can "fire and forget" them.
+retraced.reportEvent(event);
+
+await retraced.reportEvent(event);
+
+retraced.reportEvent(event)
+ .then(() => { console.log("Finished reporting!"); })
+ .catch((err) => handleError(err));
+}
+```
diff --git a/docs/retraced/self-host/aws.md b/docs/retraced/self-host/aws.md
new file mode 100644
index 0000000..812ca97
--- /dev/null
+++ b/docs/retraced/self-host/aws.md
@@ -0,0 +1,9 @@
+---
+title: Self-host Audit Logs on AWS
+sidebar_label: AWS
+description: Self-host Audit Logs on AWS
+---
+
+# AWS
+
+Coming soon.
diff --git a/docs/retraced/self-host/digitalocean.md b/docs/retraced/self-host/digitalocean.md
new file mode 100644
index 0000000..28272e2
--- /dev/null
+++ b/docs/retraced/self-host/digitalocean.md
@@ -0,0 +1,9 @@
+---
+title: Self-host Audit Logs on DigitalOcean
+sidebar_label: DigitalOcean
+description: Self-host Audit Logs on DigitalOcean
+---
+
+# DigitalOcean
+
+Coming soon.
diff --git a/docs/retraced/self-host/docker.md b/docs/retraced/self-host/docker.md
new file mode 100644
index 0000000..06836f6
--- /dev/null
+++ b/docs/retraced/self-host/docker.md
@@ -0,0 +1,34 @@
+---
+title: Self-host Audit Logs on Docker
+sidebar_label: Docker
+---
+
+# Docker
+
+Docker is the most effortless way to get started with the self-hosted Retraced instance.
+
+## Prerequisite
+
+You need the following installed in your system:
+
+- [Docker](https://www.docker.com/) and [Docker compose](https://docs.docker.com/compose/)
+- [Git](https://git-scm.com/)
+
+## Install
+
+Please see the docker directory in the Retraced repo.
+
+```bash
+# Get the code
+git clone https://github.com/retracedhq/retraced.git
+
+# Go to the root folder
+cd retraced
+
+# Start the Docker compose
+docker-compose up
+```
+
+At this stage, you've got a running Retraced instance. You can now start publishing the audit logs using the Publisher API endpoints.
+
+The base URL would be `http://localhost:3000/auditlog/publisher/v1/project/{project-id}/event`
diff --git a/docs/retraced/self-host/env-variables.md b/docs/retraced/self-host/env-variables.md
new file mode 100644
index 0000000..54ff0c0
--- /dev/null
+++ b/docs/retraced/self-host/env-variables.md
@@ -0,0 +1,335 @@
+---
+title: Environment Variables (Audit Logs)
+sidebar_label: Environment Variables
+description: Environment Variables for Audit Logs
+---
+
+# Environment Variables (Audit Logs)
+
+The environment variables are set in `.env` or `docker-compose` files.
+
+The service always respects `.env` file but in case of compose based deployments you can override the variables using docker-compose file `x-common-variables` section.
+
+The codebase has most of the things configured, we expect users to configure `ADMIN_ROOT_TOKEN` variable for security reasons.
+
+So just set the `ADMIN_ROOT_TOKEN` and you are good to go for your first run of Audit log service.
+
+You can check the complete list of environment variables below,
+
+## General configuration
+
+### **API_BASE_URL_PATH**
+
+The string to be added to the retraced API path.
+Default: `""`
+
+### **RETRACED_API_BASE**
+
+The Retraced API base path.
+Default: `localhost:3000`
+
+### **HMAC_SECRET_ADMIN**
+
+The secret to be used to encode & decode the [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) for [Admin APIs](/docs/retraced/apis/admin-api).
+
+### **HMAC_SECRET_VIEWER**
+
+The secret to be used to encode & decode the [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) for [Viewer APIs](/docs/retraced/getting-started/embedded-viewer).
+
+### **LOG_LEVEL**
+
+Sets the logging level of the application logs. Supported values `trace`, `debug`, `info`, `warn`, `error`
+
+Default: `warn`
+
+### **EXPORT_PAGE_SIZE_INTERNAL**
+
+The `Page Size` to be used to fetch Audit Logs from `ElasticSearch` for the `Saved Export Report`.
+
+Default: `10000`
+
+### **PG_SEARCH**
+
+If set `true` Retraced will use Postgres to `index & search` the audit logs instead of `Elasticsearch`.
+
+Default: `false`
+
+### **RETRACED_API_LOG_FILE**
+
+If set to a valid file path, Retraced will use the file to save `Retraced API` logs.
+
+### **RETRACED_PROCESSOR_LOG_FILE**
+
+If set to a valid file path, Retraced will use the file to save `Retraced processor` logs.
+
+### **RETRACED_API_SCHEMES**
+
+The api schema to used for swagger.
+
+Default: `http,https`
+
+### **PROCESSOR_NORMALIZE_REPAIRER_MIN_AGE_MS**
+
+The minimum age in microseconds used by processor to select audit logs to process.
+
+Default: `120000`
+
+### **PROCESSOR_NORMALIZE_REPAIRER_MAX_EVENTS**
+
+The maximum number of events processor will select to process.
+
+Default: `10000`
+
+### **RETRACED_DB_NO_CACHE**
+
+If set to true, Retraced disables db level caching.
+Caching is used for `Actor`, `Target` & `Groups` SELECT queries of audit log.
+
+### **MAXMIND_GEOLITE2_LICENSE_KEY**
+
+The `MaxMind` license key to fetch `"GeoLite2"` data.
+
+### **TMPDIR**
+
+The path of the temporary folder used for Geo data sync.
+Retraced looks for `"GeoLite2` files to import IP address and location data.
+
+### **RETRACED_APP_BASE**
+
+The base path of the Retraced instance which is used for links in the emails.
+
+## [Postgres](https://www.postgresql.org/) Configuration
+
+### **POSTGRES_HOST**
+
+The hostname to use for Postgres connection.
+
+Default: `""`
+
+### **POSTGRES_PORT**
+
+The port to use for Postgres connection.
+
+Default: `""`
+
+### **POSTGRES_USER**
+
+The user to use for Postgres connection.
+
+Default: `""`
+
+### **POSTGRES_PASSWORD**
+
+The password to use for Postgres connection.
+
+Default: `""`
+
+### **POSTGRES_DATABASE**
+
+The Postgres database name to use for Retraced.
+
+Default: `""`
+
+### **POSTGRES_POOL_SIZE**
+
+The number of connections to be used for Postgres pool.
+
+Default: `20`
+
+## [NSQD](https://github.com/nsqio/nsq) Configuration
+
+### **NSQD_HTTP_PORT**
+
+The http port to use for nsqd connection.
+
+Default: `4151`
+
+### **NSQD_HOST**
+
+The hostname to use for nsqd connection.
+
+Default: `""`
+
+### **NSQD_TCP_PORT**
+
+The tcp port to use for nsqd connection.
+
+Default: `4150`
+
+### **NSQ_CIRCUIT_BREAKER_THRESHOLD**
+
+The circuit breaker threshold used for NSQ client.
+
+## [Elasticsearch](https://www.elastic.co/) Configuration
+
+### **ELASTICSEARCH_NODES**
+
+Elasticsearch node address or a `comma seperated` list of Elasticsearch nodes.
+
+Ex:
+`https://localhost:9200`
+or
+`https://localhost:9200,https://localhost:9201,https://localhost:9202`
+
+### **ELASTICSEARCH_CAFILE**
+
+The CA file to use when connecting with `SSL enabled Elasticsearch`.
+
+### **ELASTICSEARCH_REQUEST_RETRIES**
+
+Max retries for Elasticsearch client.
+
+### **ELASTICSEARCH_REQUEST_TIMEOUT**
+
+Request timeout for Elasticsearch client.
+
+### **ELASTICSEARCH_BACKOFF**
+
+The backoff interval for retries used by `internal wrapper of Elasticsearch`.
+
+### **ELASTICSEARCH_TOTAL_TIMEOUT**
+
+The total timeout used by wrapper for `all Elasticsearch requests` & `retries with backoffs`.
+
+## Headless Mode configuration
+
+`Headless mode bootstraps the db configuration required for a tenant to use Retraced right away.`
+
+### **HEADLESS_ENV_ID**
+
+Environment Id to be used in the headless mode.
+
+### **HEADLESS_API_KEY**
+
+API key to be used in the headless mode.
+
+### **HEADLESS_PROJECT_ID**
+
+Project Id to be used in the headless mode.
+
+### **HEADLESS_PROJECT_ENV**
+
+Environment Id to be used for Project in the headless mode.
+
+## [Bugsnag](https://www.bugsnag.com) configuration ([Error Reporting](https://docs.bugsnag.com/api/error-reporting/))
+
+### **BUGSNAG_TOKEN**
+
+Token to be used for bugsnag [error reporting](https://docs.bugsnag.com/api/error-reporting/).
+
+### **STAGE**
+
+[ReleaseStage](https://docs.bugsnag.com/product/releases/#configuring-the-release-stage) configuration to be used for bugsnag.
+
+## [Signal Sciences](https://www.signalsciences.com/) configuration
+
+`Signal Sciences is used for edge security & API protection`
+
+### **SIGSCI_RPC_ADDRESS**
+
+The RPC address to be used for Signal Sciences API protection.
+
+## **ADMIN_ROOT_TOKEN**
+
+When this is set, Retraced makes api `/admin/v1/user/_login` available.
+Admin can make a post request to above api with `token=` in Authorization Header to create users.
+
+## SSL configuration
+
+Used to enable https mode of Retraced.
+
+### **SSL_SERVER_CERT_PATH**
+
+The path of the ssl certificate file.
+
+### **SSL_SERVER_KEY_PATH**
+
+The path of the ssl private key file.
+
+## Statsd Reporter configuration
+
+### **STATSD_HOST**
+
+The hostpath for the statsd reporter.
+
+### **STATSD_PORT**
+
+The port for the statsd reporter.
+
+
+
+## Opentelemetry configuration
+
+Retraced supports observability via OpenTelemetry. The following env vars are available for configuration (along with the rest of the [supported ones](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md))
+
+### **OTEL_EXPORTER_OTLP_ENDPOINT** or **OTEL_EXPORTER_OTLP_METRICS_ENDPOINT**
+
+Target URL to which the exporter is going to send metrics.
+
+Example: `https://ingest.lightstep.com:443/metrics/otlp/v0.6`
+
+### **OTEL_EXPORTER_OTLP_HEADERS** or **OTEL_EXPORTER_OTLP_METRICS_HEADERS**
+
+Headers relevant for the endpoint, useful for specifying authentication details for providers.
+
+Example: `lightstep-access-token=,...`
+
+### **OTEL_EXPORTER_OTLP_PROTOCOL** or **OTEL_EXPORTER_OTLP_METRICS_PROTOCOL**
+
+The transport protocol. Options MUST be one of: `grpc`, `http/protobuf` or `http/json`.
+
+### **OTEL_EXPORTER_DEBUG**
+
+Set this to `true` to enable debug logs for Opentelemetry. This is only meant for purposes of debugging otel locally.
+
+## Email configuration
+
+### **EMAIL_FROM**
+
+The email address to be used to send email from Retraced.
+
+Default: `Retraced `
+
+### **SMTP_CONNECTION_URL**
+
+SMTP connection url to be used to send emails using [nodemailer](https://www.npmjs.com/package/nodemailer).
+
+### **MANDRILL_KEY**
+
+The API key to be used to send emails using [Mandrill By Mailchimp](https://mailchimp.com/en-gb/features/transactional-email/?utm_source=mandrill&utm_medium=mc-site&utm_campaign=aoc_product-mktg_tnx_redirect_wld_20200515).
+
+## Publisher configuration
+
+### **PUBLISHER_BULK_CREATE_MAX_EVENTS**
+
+The limit of the events that can be created using bulk api.
+
+default: `50`
+
+### **PUBLISHER_CREATE_EVENT_TIMEOUT**
+
+The timeout used by publisher for delay while registering events.
+
+default: `1000`
+
+## [Analytics-node](https://segment.com/docs/connections/sources/catalog/libraries/server/node/) configuration
+
+### **SEGMENT_WRITE_KEY**
+
+The write keys used for [Analytics](https://segment.com/docs/connections/sources/catalog/libraries/server/node/#identify). Reports the project as a `user segment`.
+
+## Anonymous Analytics
+
+### **RETRACED_NO_TELEMETRY** or **DO_NOT_TRACK**
+
+Set one of these to `1` or `true` to turn off our anonymous analytics. We only track usage events once per day and it does not contain any information that can identify you in any form.
diff --git a/docs/retraced/self-host/index.md b/docs/retraced/self-host/index.md
new file mode 100644
index 0000000..d6d7dfa
--- /dev/null
+++ b/docs/retraced/self-host/index.md
@@ -0,0 +1,20 @@
+---
+title: Self-host Audit Logs
+sidebar_label: Overview
+---
+
+# Self Hosting
+
+Getting a production environment of Retraced up and running is probably one of the first things you want to do! This section goes through the different options available depending on where you'll be hosting Retraced.
+
+Self-hosting Retraced means managing the service yourself and taking care of upgrades, scaling, security etc.
+
+The docker container can be found at [retracedhq/retraced](https://hub.docker.com/r/retracedhq/retraced/tags). It is preferable to use a specific version instead of the `latest` tag.
+
+## Deployment options
+
+- [Docker](docker.md)
+- [DigitalOcean](digitalocean.md)
+- [AWS](aws.md)
+- [Kubernetes](kubernetes.md)
+- [Skaffold](skaffold.md)
diff --git a/docs/retraced/self-host/kubernetes.md b/docs/retraced/self-host/kubernetes.md
new file mode 100644
index 0000000..b1fef0e
--- /dev/null
+++ b/docs/retraced/self-host/kubernetes.md
@@ -0,0 +1,9 @@
+---
+title: Self-host Audit Logs on Kubernetes
+sidebar_label: Kubernetes
+description: Self-host Audit Logs on Kubernetes
+---
+
+# Kubernetes
+
+Coming soon.
diff --git a/docs/retraced/self-host/local.md b/docs/retraced/self-host/local.md
new file mode 100644
index 0000000..6c8b366
--- /dev/null
+++ b/docs/retraced/self-host/local.md
@@ -0,0 +1,61 @@
+---
+title: Running Locally
+description: Running Locally
+---
+
+# Running Locally
+
+## Clone the project
+
+`git clone https://github.com/retracedhq/retraced && cd retraced`
+
+## Install Dependancies
+
+`yarn install` or `npm i`
+
+## Set the environment variables
+
+Use `.env` file to set the [Environment Variables](./env-variables).
+
+## Tools (DBs, queues, etc.)
+
+Make sure the tools configured in `.env` file are up & running.
+
+### [Postgres](./env-variables#postgres-configuration)
+
+### [NSQ](./env-variables#nsqd-configuration)
+
+### [Elasticsearch](./env-variables#elasticsearch-configuration)
+
+### [Supercronic](./env-variables#supercronic-configuration)
+
+### [Redis](./env-variables#redis-configuration)
+
+## Postgres Migration
+
+Create tables and indexes required for Retraced in Postgres.
+
+`node -r ts-node/register src/_db/runner-lite.ts pg`
+
+## Elastic Migration
+
+Create tables and indexes required for Retraced in Elasticsearch.
+
+`node -r ts-node/register src/_db/runner-lite.ts es`
+
+## Bootstrap dev environment
+
+`node -r ts-node/register src/retracedctl.ts bootstrap --projectName dev --projectId dev --environmentId dev --apiKey dev`
+
+## Start the API
+
+`node -r ts-node/register src/index.ts`
+
+## Start the processor
+
+`node -r ts-node/register src/_processor/index.ts`
+
+## See it in action
+
+Use the postman collection located at `./postman/Retraced.postman_collection.json`.
+You can import the json file in postman and use the API calls to test Retraced.
diff --git a/docs/retraced/self-host/skaffold.md b/docs/retraced/self-host/skaffold.md
new file mode 100644
index 0000000..278718f
--- /dev/null
+++ b/docs/retraced/self-host/skaffold.md
@@ -0,0 +1,23 @@
+---
+title: Skaffold
+description: Skaffold
+---
+
+# Skaffold
+
+## Clone the project
+
+`git clone https://github.com/retracedhq/retraced && cd retraced`
+
+You can change the environment variables from `/kustomize/overlays/dev/secrets.yaml`.
+
+## Run Retraced
+
+`skaffold dev --status-check=false --force=true`
+
+## See it in action
+
+Use the postman collection located at `./postman/Retraced.postman_collection.json`.
+You can import the json file in postman and use the API calls to test Retraced.
+
+`Make sure that the bootstrap & migrations are finished before makeing api calls.`
diff --git a/docs/代码库管理/WebIDE.md b/docs/代码库管理/WebIDE.md
deleted file mode 100644
index 33b3b06..0000000
--- a/docs/代码库管理/WebIDE.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-sidebar_label: 'WebIDE'
-sidebar_position: 9
----
-
-### **1. 语言服务**
-● 支持近 40 种语言的语法高亮
-● 支持 JavaScript/TypeScript、HTML、CSS、JSON、Markdown 的基于 LSP (Language Server Protocol) 语言特性功能，具备智能提示和大纲信息以及单文件内跳转。
-● 支持 Java、Go、Python、C++、Php 的基于 Tree Sitter 的在线语言服务能力，提供查看引用、符号搜索等特性
-
-### **2. WebIDE 入口**
-从 Gitlink 仓库首页 ，点击Web IDE 按键即可进入
-
-
-### **3. 分支**
-支持分支切换：点击左下角分支名即可切换分支。
-
-
-### **4. 搜索**
-当前支持 Gitlink 仓库内代码搜索（支持单词匹配和文件过滤）和文件搜索。
-
-
-### **5. 行高亮**
-支持单行或多行高亮，点击行号即可高亮行，按住 Shift 可选中连续多行。
-
-
-### **6. Blame**
-支持查看单行 blame 信息，hover 后可展示详细信息。
-
-
-### **7. Graph**
-支持 graph 视图，可查看分支 commits 历史以及每个 commit 详细文件变更，并支持文件 diff 查看。底部状态栏左下角点击 Git Graph 或在命令面板输入 View Git Graph，即可打开 Git Graph 视图。
-
-
-### **8. WebSCM**
-可以在极速版新建分支，修改代码后在 SCM 面板看到变更文件列表，写完 commit message 后提交到 Gitlink 上。如果想快速修改一些文件可以不用在本地修改，直接通过极速版修改代码一次性提交。
-
-### **9. 代码在线运行**
-● 集成了基于 skypack 的更加轻量的 CodeSwing 插件，可以在极速版去运行前端代码。
-● 集成了基于 Pyodide 的 Code-Runner-For-Web 插件，可以将 Python 的运行搬到浏览器上。
-
\ No newline at end of file
diff --git a/docs/代码库管理/Webhook.md b/docs/代码库管理/Webhook.md
deleted file mode 100644
index 33bc170..0000000
--- a/docs/代码库管理/Webhook.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-sidebar_label: 'Webhook'
-sidebar_position: 8
----
- ### **1. Webhook模块入口**
- 在项目主页，点击“仓库设置”按键，再点击“网络钩子”按键，即可进入仓库的Webhook模块。
- 
-
- ### **2. 添加Webhook**
- 单击“添加Webhook”按键，可进入配置Webhook页面：
-
- 
- 
-
- ### **3. 编辑Webhook**
- 添加Webhook后，如下图所示，可以通过点击右侧”编辑“按键来对每个Webhook进行编辑操作。
-
- 
-
- ### **4. 删除Webhook**
- 添加Webhook后，如下图所示，可以通过点击右侧”删除“按键来对每个Webhook进行删除操作。
-
- 
-
- ### **5. Webhook支持的事件类型**
- 在GitLink中，Webhook支持的事件类型如下：
- - 推送：git推送到存储库
- - 代码库：创建或删除代码库
- - 创建：创建分支或标签
- - 删除：删除分支或标签
- - 合并请求：合并请求被打开、被关闭、被重新打开或被编辑
- - 合并请求分配：合并请求被分配或取消分配
- - 合并请求收入里程碑：合并请求被记录或取消记录于里程碑中
- - 合并请求被评论：合并请求评论被创建、编辑或删除
- - 合并请求标签：合并请求的标签被更新或清除
- - 合并请求审查：合并请求被批准、拒绝或提出审查意见，审查人员的修改，审查线程已解决或未解决
- - 合并请求被同步：合并请求被同步
-
\ No newline at end of file
diff --git a/docs/代码库管理/_category_.json b/docs/代码库管理/_category_.json
deleted file mode 100644
index 82c9af5..0000000
--- a/docs/代码库管理/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "代码库管理",
- "position": 2
-}
diff --git a/docs/代码库管理/仓库创建.md b/docs/代码库管理/仓库创建.md
deleted file mode 100644
index e17cd76..0000000
--- a/docs/代码库管理/仓库创建.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-sidebar_label: '仓库创建'
-sidebar_position: 1
----
- ### **1. 仓库创建入口**
-用户可以通过平台主页右上角的按键以及个人主页参与项目模块的“新建”按键来创建仓库。
-
-
- ### **2. 填写项目基本信息**
-进入新建项目页面后，如下图所示，填写拥有者、项目名称、项目标识等信息，单击”创建项目“按键即可完成创建。
-
\ No newline at end of file
diff --git a/docs/代码库管理/仓库设置.md b/docs/代码库管理/仓库设置.md
deleted file mode 100644
index 6e31214..0000000
--- a/docs/代码库管理/仓库设置.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-sidebar_label: '仓库设置'
-sidebar_position: 2
----
-### **1. 仓库设置入口**
-在仓库主页，点击“仓库设置”按键即可进入仓库设置模块。仓库设置中可以修改项目的基本信息、进行成员管理、配置webhook、设置分支以及安装bot。
-
-
-### **2. 基本设置**
-进入仓库设置模块后，单击”基本设置“按键，进入基本设置模块，如下图所示，可以对项目的项目名称、项目标识、项目简介、项目类别、项目语言等基本信息进行修改。单击“转移”按键可以将仓库转移给其他用户和组织，单击“删除本仓库“按键可以删除本仓库。
-
\ No newline at end of file
diff --git a/docs/代码库管理/代码提交.md b/docs/代码库管理/代码提交.md
deleted file mode 100644
index 11b6835..0000000
--- a/docs/代码库管理/代码提交.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '代码提交'
-sidebar_position: 3
----
\ No newline at end of file
diff --git a/docs/代码库管理/分支管理.md b/docs/代码库管理/分支管理.md
deleted file mode 100644
index f543748..0000000
--- a/docs/代码库管理/分支管理.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '分支管理'
-sidebar_position: 5
----
\ No newline at end of file
diff --git a/docs/代码库管理/成员管理.md b/docs/代码库管理/成员管理.md
deleted file mode 100644
index cbf6199..0000000
--- a/docs/代码库管理/成员管理.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_label: '成员管理'
-sidebar_position: 7
----
-### **1. 成员管理入口**
-在仓库主页，点击“仓库设置”按键，再点击”成员管理“按键，即可进入成员管理模块，如下图所示。
-
-
-### **2. 筛选、搜索项目成员**
-进入成员管理模块后，可以通过”角色筛选“按键来筛选项目成员类型，通过”搜索“按键可以检索具体的项目成员，如下图所示。
-
-
-### **3. 筛选、搜索项目成员**
-进入成员管理模块后，可以通过”添加成员“按键来添加项目成员，左侧搜索框检索到具体用户并选中后，单击”添加成员“按键即可成功添加项目成员。
-
-
-### **4. 项目成员权限管理**
-进入成员管理模块后，单击项目成员右侧的角色栏，可以选择赋予该名项目成员的权限等级，如下图所示。
-
-
-### **5. 删除项目成员**
-进入成员管理模块后，单击项目成员右侧的”删除“按键，可以删除改名项目成员，如下图所示。
-
diff --git a/docs/代码库管理/文件管理.md b/docs/代码库管理/文件管理.md
deleted file mode 100644
index af8c755..0000000
--- a/docs/代码库管理/文件管理.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '文件管理'
-sidebar_position: 4
----
\ No newline at end of file
diff --git a/docs/代码库管理/标签和发行版管理.md b/docs/代码库管理/标签和发行版管理.md
deleted file mode 100644
index 44e0ae7..0000000
--- a/docs/代码库管理/标签和发行版管理.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-sidebar_label: '标签和发行版管理'
-sidebar_position: 6
----
-### **1. 标签和发行版管理入口**
-在仓库主页，点击“代码库”按键，再点击”标签“按键，即可进入标签和发行版管理模块，如下图所示。
-
-
-### **2. 删除标签**
-进入标签和发行版管理模块后，点击标签右侧“删除”按键，即可实现对标签的删除操作，如下图所示。
-
-
-### **3. 查看发行版**
-进入标签和发行版管理模块后，点击”发行版”按键即可查看项目的发行版，如下图所示。
-
-
-### **4. 创建发行版**
-进入标签和发行版管理模块后，点击标签右侧”创建发行版”按键，即可快速创建绑定该标签的发行版，如下图所示。
-
-
-### **5. 修改发行版**
-进入标签和发行版管理模块后，点击发行版右侧的修改按键，即可进入发行版的修改页面，如下图所示。完成发行版的修改后，单击”保存发行版“按键即可保存修改内容。
-
-
-
-### **6. 删除发行版**
-进入标签和发行版管理模块后，点击发行版右侧的删除按键，即可进入发行版的删除页面，如下图所示。
-
-
\ No newline at end of file
diff --git a/docs/合并请求/_category_.json b/docs/合并请求/_category_.json
deleted file mode 100644
index 15eab23..0000000
--- a/docs/合并请求/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "合并请求(PR)",
- "position": 5
-}
diff --git a/docs/合并请求/代码评审.md b/docs/合并请求/代码评审.md
deleted file mode 100644
index 9b4aefb..0000000
--- a/docs/合并请求/代码评审.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-sidebar_label: '代码评审'
-sidebar_position: 3
----
-
-# 代码评审
\ No newline at end of file
diff --git a/docs/合并请求/创建合并请求.md b/docs/合并请求/创建合并请求.md
deleted file mode 100644
index ce7059e..0000000
--- a/docs/合并请求/创建合并请求.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-sidebar_label: '创建合并请求'
-sidebar_position: 2
----
-
-# 创建合并请求
-
-1. 进入需要发起合并请求的项目的“**合并请求(PR)**”界面，点击上方的“**新建合并请求**”按钮后，进入合并请求发布界面，如下所示：
-
-
-
-
-
-2. 选择需要合并的**源分支**和**目标分支**，其中源分支为已完成代码开发、需要合并其代码变更的分支，目标分支为要并入代码变更的分支，既可以是同一仓库下的其他分支（branch），也可以是被复刻的源仓库下的分支；
-
-3. 选中分支后，填写本次合并请求的标题和描述内容，为审查者提供辅助理解本次合并请求的信息，进而加快合并请求审查过程（见 ***代码评审*** 一节）；
-
-4. 此外，用户还可以在右侧边栏中指定审查人员、添加里程碑、标记以及优先级（合并请求本质上是一个疑修，这些操作与疑修模块中的操作含义相同或相近，所以可以参照疑修章节中的介绍辅助理解）；
-
-5. 最后信息填写完毕后，点击底部的“**创建**”按钮即可提交您的第一个合并请求了🎉🎉🎉！
-
-
\ No newline at end of file
diff --git a/docs/合并请求/合并模式简介.md b/docs/合并请求/合并模式简介.md
deleted file mode 100644
index c8d0750..0000000
--- a/docs/合并请求/合并模式简介.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-sidebar_label: '合并模式简介'
-sidebar_position: 4
----
-
-# 合并模式简介
-
-在审阅人审查完开发者提交的代码变更后，便可以决定是否将这些提交合并进主分支`master`中。
-
-然而，对于不同分支间的提交合并，存在多种合并模式，下图为GitLink中支持的合并模式，包括**合并请求**、**变基并合并**、**变基合并 --no-ff**以及**压缩提交并合并**四种。
-
-
-
-1. **合并请求**
-
-**合并请求**是最常用的合并模式，以下图为例，开发者在主分支`master`的提交3处拉取了开发分支`dev`，然后分别提交了A、B、C，然后在`master`分支上进行合并。
-
-快进合并前：
-
-
-
-快进合并后：
-
-
-
-**注意**：可以看到，合并的过程就是直接把`master`指针移动到了`dev`指针处，这种合并被称为**快进（fast-forward）**，之所以出现这种情形是因为在提交3之后，`master`分支上没有新的提交，所以通过直接快进`master`指针就可以完成合并；但如果在`master`分支上也有新的提交，就需要进行实质性的合并了，如下面两幅图所示：
-
-在合并前，`dev`分支上提交A之后、提交B之前，`master`分支上提交了4，这时合并`dev`分支就不能简单地快进移动，而是要比较两个分支上更改的内容，然后进行合并；
-
-非快进合并前：
-
-
-
-
-合并之后，提交A、B、C都会按时间线加入`master`的提交记录中，并且会生成一个新的提交D，用于记录合并这件事情；此外，如果合并过程中发生了冲突，即两个分支对同一个文件进行了修改，则需要手动处理冲突；这种合并方式就是**非快进（no fast-forward）**，这也是**合并请求**模式下的默认方式！
-
-非快进合并后：
-
-
-
-为了方便理解，可以以线性方式查看合并后的`master`分支上的提交记录
-
-
-
-**总结**：在**合并请求**模式下，默认采用**非快进**合并开发分支到`master`分支上，而**非快进**方式会生成一个特殊的提交用于记录此次合并事件！
-
-2. **变基并合并**
-
-从**合并请求**后`master`分支上的提交记录可以看出，两个分支的提交记录可能会交叉在一起，这可能会给后续开发带来困扰，而**变基并合并**可以解决这个问题。
-
-**变基并合并**包括两个操作：**变基**、**合并**。首先是变基，以下图为例，`dev`分支是从提交3处拉取出来的，所以提交3就是`dev`的基，而变基操作就是改变`dev`的基，使其变为`master`分支上最新的一次提交。当然，变基过程中可能会出现冲突，则需要手动处理。
-
-变基前：
-
-
-
-变基后、合并前：
-
-
-
-
-`dev`分支变基之后，`master`分支就没有“更新”的提交了，所以此时进行合并，就得到了如下的结果
-
-合并后：
-
-
-
-**总结**：在**变基并合并**模式下，开发分支`dev`可以先进行变基操作，使其上的提交看起来都是在`master`分支最新的提交基础上进行的，然后再通过**快进**方式合并回`master`分支，从而起到整理提交记录的作用！
-
-3. **变基合并 --no-ff**
-
-因为**变基并合并**进行合并操作时，默认采用**快进**方式，这样在`master`分支上就没有一个特殊的提交用于记录这次合并事件，所以可以使用`--no-ff`（**no fast-forward**）选项申明采用**非快进**方式进行合并。
-
-`--no-ff`合并前：
-
-
-
-`--no-ff`合并后：
-
-
-
-**总结**：通过`--no-ff`选项，可以显式声明在合并时采用**非快进**方式，这样就可以在`master`分支中添加一个记录合并事件的提交！
-
-4. **压缩提交并合并**
-
-在`dev`或者`feature`这样的开发分支中，开发者为了完成某个需求会进行多次提交，然而这些琐碎的提交信息在合并回`master`分支后，会使`master`上的提交记录臃肿混乱，所以需要在合并前，对这些提交进行压缩。如图所示，压缩操作是在`master`分支上进行的，本质是将`dev`分支上进行的变更施加到`master`分支维护的文件上，然后将这些修改用新的提交5保存，最后提交。
-
-压缩前：
-
-
-
-压缩后、提交前：
-
-
-
-提交后：
-
-
-
-**总结**：在合并前，先对开发分支上的琐碎提交进行压缩，可以使`master`分支上的提交信息更简洁，但是要注意，这种合并模式本质上是`master`分支一次性保存`dev`上的变更，并创建新的提交记录这些变更，所以提交者发生了变化！
\ No newline at end of file
diff --git a/docs/合并请求/合并请求关联疑修.md b/docs/合并请求/合并请求关联疑修.md
deleted file mode 100644
index ac29313..0000000
--- a/docs/合并请求/合并请求关联疑修.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-sidebar_label: '合并请求关联疑修'
-sidebar_position: 5
----
-
-# 合并请求关联疑修
\ No newline at end of file
diff --git a/docs/合并请求/合并请求简介.md b/docs/合并请求/合并请求简介.md
deleted file mode 100644
index c0ac142..0000000
--- a/docs/合并请求/合并请求简介.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-sidebar_label: '合并请求简介'
-sidebar_position: 1
----
-
-# 合并请求简介
-
-**合并请求(PR)** 模块提供合并请求创建和管理两方面的功能：
-
-- 一方面支持向源项目或者同一个项目其他分支创建（发起）代码合并请求（Pull Request，PR）；
-
-- 另一方面也为项目管理者对他人发送到本项目的合并请求进行管理、审阅并最终确定是否纳入项目。
-
-如下图所示为合并请求(PR)管理模块：
-
-
\ No newline at end of file
diff --git a/docs/平台公告/_category_.json b/docs/平台公告/_category_.json
deleted file mode 100644
index a6b5159..0000000
--- a/docs/平台公告/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "平台公告",
- "position": 11
-}
diff --git a/docs/平台公告/平台公告.md b/docs/平台公告/平台公告.md
deleted file mode 100644
index 3b451a8..0000000
--- a/docs/平台公告/平台公告.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '平台公告'
-sidebar_position: 1
----
\ No newline at end of file
diff --git a/docs/快速开始/_category_.json b/docs/快速开始/_category_.json
deleted file mode 100644
index c826d66..0000000
--- a/docs/快速开始/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "快速开始",
- "position": 1
-}
diff --git a/docs/快速开始/创建第一个开源项目.md b/docs/快速开始/创建第一个开源项目.md
deleted file mode 100644
index b18cc64..0000000
--- a/docs/快速开始/创建第一个开源项目.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-sidebar_label: '创建第一个开源项目'
-sidebar_position: 2
----
-
-# 创建第一个开源项目
-
-## 1. 新建项目
-
-平台提供了“新建”按钮，用户可以通过点击快速从零开始创建新的公开或者私有项目。
-
-
-
-## 2. 填写项目信息
-
-填写项目基本信息。
-
-
-
-## 3. 创建成功
-
-点击创建项目，创建成功后进入项目主页。
-
-
diff --git a/docs/快速开始/导入GitHub等第三方Git项目.md b/docs/快速开始/导入GitHub等第三方Git项目.md
deleted file mode 100644
index 20be5ce..0000000
--- a/docs/快速开始/导入GitHub等第三方Git项目.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-sidebar_label: '导入GitHub等第三方Git项目'
-sidebar_position: 5
----
-
-# 导入GitHub等第三方Git项目
-
-## 1. 导入项目
-
-在首页选择**导入项目**
-
-
-
-## 2. 填写信息
-
-填写完需要导入的第三方Git项目地址后和项目信息后，点击导入项目
-
-
-
-## 3. 导入成功
-
-提示正在从第三方Git项目地址迁移
-
-
-
-迁移成功则导入项目成功
-
-
\ No newline at end of file
diff --git a/docs/快速开始/提交第一行代码.md b/docs/快速开始/提交第一行代码.md
deleted file mode 100644
index 1436b02..0000000
--- a/docs/快速开始/提交第一行代码.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-sidebar_label: '提交第一行代码'
-sidebar_position: 3
----
-
-# 提交第一行代码
-
-# 1. 编辑代码
-
-点击编辑按钮，开始编辑代码。
-
-
-
-# 2. 提交代码
-
-在编辑框中编写代码，编写完成后填写变更信息后提交变更。
-
-
-
-## 3. 代码更新成功
-
-提交成功后代码代码更新成功。
\ No newline at end of file
diff --git a/docs/快速开始/搜索开源项目.md b/docs/快速开始/搜索开源项目.md
deleted file mode 100644
index d584762..0000000
--- a/docs/快速开始/搜索开源项目.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-sidebar_label: '搜索开源项目'
-sidebar_position: 4
----
-
-# 搜索开源项目
-
-## 1. 开源项目页面介绍
-
-项目”模块汇聚和管理了所有 GitLink 平台上的托管项目和镜像项目，用户可以输入项目名称关键字进行搜索，也可以根据项目类别对项目进行筛选。
-
-进入“项目”模块，左侧列出了项目类型和项目类别。其中，项目类型主要包括开源托管项目和开源镜像项目两类。项目类别主要包括：云计算、大数据、区块链、物联网、机器学习、人工智能、智慧医疗、其他。
-
-
-
-右侧展示了所有项目的基本信息，包括创建者、项目名、项目简介、浏览量、项目类别、更新时间、点赞数量、Fork 数量等信息，用户可以通过关键字搜索查找特定的项目，也可以按照更新时间、创建时间、Fork 数量、点赞数量等对项目进行排序。
-
-
-
-用户点击项目名称，即可进入到项目详情，查看和参与开源项目开发。
-
-## 2. 搜索开源项目
-
-有两处搜索框可以搜索
-
-### 开源项目搜索框
-
-搜索项目：
-
-
-
-搜索结果：
-
-
-
-### 菜单栏搜索框
-
-搜索项目：
-
-
-
-搜索结果：
-
-
\ No newline at end of file
diff --git a/docs/快速开始/注册GitLink账号.md b/docs/快速开始/注册GitLink账号.md
deleted file mode 100644
index 5b3cadf..0000000
--- a/docs/快速开始/注册GitLink账号.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-sidebar_label: '注册GitLink账号'
-sidebar_position: 1
----
-
-# 注册GitLink账号
-
-## 1. 点击**立即注册**按钮
-
-
-
-## 2. 填写注册信息
-
-- 手机号注册
-
- 
-
-- 邮箱注册
-
- 
-
-## 3. 注册完成
-
-填写完所需信息后点击注册，注册成功后则进入个人主页
-
-
-
diff --git a/docs/服务协议/GitLink服务协议.md b/docs/服务协议/GitLink服务协议.md
deleted file mode 100644
index 607cc59..0000000
--- a/docs/服务协议/GitLink服务协议.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-sidebar_label: 'GitLink服务协议'
-sidebar_position: 1
----
-
-尊敬的用户，您好！
-
-欢迎使用GitLink平台，在您使用GitLink平台前，请您认真阅读并遵守《GitLink服务协议》（以下简称”本协议”），请您务必审慎阅读、充分理解协议的各条款内容。
-当您在注册过程中点击查看”看过并同意本服务协议”，按照注册流程成功注册为GitLink平台的用户即表示您已充分阅读、理解并完全接受本协议中的全部条款。您承诺接受并遵守本协议的约定，届时您不应以未阅读本协议的内容等理由，主张本协议无效或本协议中的某些条款无效，或要求撤销本协议。
-
-## 一、GitLink平台权利和义务
-1. 尊重用户隐私：尊重用户隐私，保障用户隐私安全是GitLink平台的一项基本政策；
-2. 管理平台用户：GitLink平台依据国家法律、地方法律和国际法律等的标准以及本行业的规则来管理平台注册用户；
-3. 处理用户反馈：GitLink平台的相关人员会及时处理用户反馈的问题并给予及时回复。
-
-## 二、用户权利和义务
-用户在使用GitLink平台的过程中，必须遵守如下原则：
-
-1. 遵守中国的有关法律和法规；
-2. 使用网络服务不作非法用途；
-3. 不干扰和混乱网络服务；
-4. 遵守所有使用网络服务的网络协议、规定、程序和惯例；
-5. 不传输任何非法的、骚扰性的、中伤他人的、辱骂性的、恐吓性的、伤害性的、庸俗的，淫秽等信息资料；
-6. 不传输任何教唆他人构成犯罪行为的资料；
-7. 用户不得故意或者过失损害GitLink平台合法权利和利益。
-
-## 三、关于责任
-鉴于网络服务的特殊性，用户同意GitLink团队有权在事先通知的情况下，变更、中断、升级部分网络服务。GitLink团队不担保网络服务不会中断，但承诺在用户可承受的时间内快速恢复服务，同时确保用户数据的安全性和可靠性。
-
-## 四、服务条款的修改
-GitLink团队保留在必要时对本协议修改的权利，一旦发生变动，这些条款可由GitLink团队及时更新，且毋须另行通知，修改后的条款一旦在网页上公布即有效代替原来的服务条款。您可随时查阅最新版服务条款。
-
-
-本协议最终解释权归GitLink团队所有。
\ No newline at end of file
diff --git a/docs/服务协议/_category_.json b/docs/服务协议/_category_.json
deleted file mode 100644
index c6b6703..0000000
--- a/docs/服务协议/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "服务协议",
- "position": 12
-}
diff --git a/docs/疑修/_category_.json b/docs/疑修/_category_.json
deleted file mode 100644
index 71829c3..0000000
--- a/docs/疑修/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "疑修(Issue)",
- "position": 4
-}
diff --git a/docs/疑修/标记管理.md b/docs/疑修/标记管理.md
deleted file mode 100644
index 3217988..0000000
--- a/docs/疑修/标记管理.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-sidebar_label: '标记管理'
-sidebar_position: 6
----
-
-# 标记管理
-
-在疑修的内容编辑页面可以根据疑修的类型对其设置标记，标记的存在方便了在疑修列表中筛选目标疑修，提高项目开发管理效率。
-GitLink默认疑修共有缺陷、功能、疑问、支持、任务、协助、搁置、文档、测试和重复共计十种标记类型，分别具有不同的含义和颜色标志：
-
-- **缺陷：** 表示存在意外问题或错误；
-- **功能：** 表示新功能申请；
-- **疑问：** 表示存在疑惑；
-- **支持：** 表示特定功能或特定需求；
-- **任务：** 表示需要分配的任务；
-- **协助：** 表示需要社区用户协助；
-- **搁置：** 表示此问题暂时不会继续处理；
-- **文档：** 表示文档材料补充；
-- **测试：** 表示需要测试的需求；
-- **重复：** 表示已存在类似的疑修。
-
-另外，**项目成员**可以根据需求或习惯，进行标记含义或颜色标志的修改、新建标记和删除标记操作。
\ No newline at end of file
diff --git a/docs/疑修/疑修列表.md b/docs/疑修/疑修列表.md
deleted file mode 100644
index 5ac8734..0000000
--- a/docs/疑修/疑修列表.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-sidebar_label: '疑修列表'
-sidebar_position: 4
----
-# 疑修列表
-
-对于项目开发过程中创建的所有疑修，可以在**疑修(Issue)** 界面统一查看，如下图所示为[确实开源](https://www.gitlink.org.cn/Gitlink/forgeplus)项目下的疑修列表。
-
-
-
-+ **创建疑修**：在疑修列表界面下，点击“**创建疑修**”按钮，同样可以创建疑修，具体见 ***疑修创建*** 一节；
-
-+ **筛选疑修**：疑修列表支持不同条件筛选，包括发布人、标记（见 ***标记管理*** 一节）、里程碑（见 ***里程碑管理*** 一节），负责人、状态和开始/结束日期等；同时支持关键字搜索，以及按多种排序规则对疑修进行排序。
\ No newline at end of file
diff --git a/docs/疑修/疑修创建.md b/docs/疑修/疑修创建.md
deleted file mode 100644
index 69e3423..0000000
--- a/docs/疑修/疑修创建.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-sidebar_label: '疑修创建'
-sidebar_position: 2
----
-# 疑修创建
-
-1. 进入需要发布疑修的项目的“**代码库**”界面，点击上方的“**+疑修**”按钮即可进入疑修发布界面，如下图所示：
-
-
-
-2. 开始创建疑修，包括疑修标题、内容，输入疑修内容时既可以采用简单灵活的[Markdown语法](https://markdown.com.cn/)，同时可以点击上方的功能按钮；然后上传需要的附件内容；最后点击“**创建**”按钮提交你的第一个疑修🎉🎉🎉
-
-
\ No newline at end of file
diff --git a/docs/疑修/疑修状态变更.md b/docs/疑修/疑修状态变更.md
deleted file mode 100644
index 7984618..0000000
--- a/docs/疑修/疑修状态变更.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-sidebar_label: '疑修状态变更'
-sidebar_position: 3
----
-# 疑修状态变更
-
-**疑修**本质上是开发任务，而开发任务随着开发活动的进行，其状态也会发生改变，而“**状态**”便是用于跟踪记录开发活动的变更。如图所示，GitLink中疑修的**状态**包括“新增”、“正在解决”、“已解决”、“关闭”和“拒绝“五类，用于表示开发任务的处理进度。
-
-
-
-+ **新增**：新创建的疑修默认状态为“新增”；
-
-+ **正在解决**：若已创建的疑修处在解决过程中，此时可将疑修状态修改为“正在解决”；
-
-+ **已解决**：疑修被开发者解决，此时可将其状态改为“已解决”✅；
-
-+ **关闭**：已被解决或者没有必要继续开启的疑修，可被设置为“关闭”；
-
-+ **拒绝**：若被指派解决疑修的开发者拒绝处理该疑修，则可把疑修设置为“拒绝”状态❌。
\ No newline at end of file
diff --git a/docs/疑修/疑修简介.md b/docs/疑修/疑修简介.md
deleted file mode 100644
index fec3dc0..0000000
--- a/docs/疑修/疑修简介.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-sidebar_label: '疑修简介'
-sidebar_position: 1
----
-# 疑修简介
-
-**疑修（Issue）** 管理模块主要为项目组成员提供**开发任务**发布、指派、跟踪等功能服务。
-
-
-
-**说明事项**
-
-1. **疑修**是一个可以追踪开发任务进度的帖子，因此支持参与者回复与评论等功能，见 ***评论及操作记录*** 一节；
-
-2. **疑修**的默认类型（标记）包括缺陷、功能、任务、支持、周报等，具体见 ***标记管理*** 一节；
-
-3. 可以为**疑修**设置开始和结束时间，并指定负责解决该任务的负责人，在疑修截止日期的前一天，系统将自动为任务的发布者和被指派人发送提醒消息。
diff --git a/docs/疑修/评论及操作记录.md b/docs/疑修/评论及操作记录.md
deleted file mode 100644
index 36f3054..0000000
--- a/docs/疑修/评论及操作记录.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-sidebar_label: '评论及操作记录'
-sidebar_position: 5
----
-
-# 评论及操作记录
-### 评论
-每个疑修都相当于一个可以进度追踪的帖子，因此支持评论和回复，不仅仅是项目成员，所有人都可以在某个疑修下进行评论和回复，发表疑问或是见解，进行交流。
-### 操作记录
-所有人都可以创建疑修，但是要注意，非项目成员仅可以修改自己创建的疑修，而项目成员有权限修改所有的疑修。
-对于某个疑修的所有编辑操作，包括**创建疑修、添加负责人、移除负责人、更改状态、更改优先级、添加标记、移除标记、添加里程碑、移除里程碑、设置关联分支、移除关联分支、设置开始日期和设置结束日期**，均被记录在操作记录中。
\ No newline at end of file
diff --git a/docs/疑修/里程碑管理.md b/docs/疑修/里程碑管理.md
deleted file mode 100644
index 9790e35..0000000
--- a/docs/疑修/里程碑管理.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-sidebar_label: '里程碑管理'
-sidebar_position: 7
----
-
-# 里程碑管理
-
-### 里程碑简介
-里程碑主要用于项目组对项目开发和版本发布提供支持，每一个里程碑可以关联多个开发任务。
-
-### 创建里程碑
-项目成员可以基于以下步骤创建里程碑：
-1. 进入目标项目的 **“里程碑”** 界面，此时界面所示为已创建的里程碑的列表，所有已创建里程碑分为 **“已关闭”** 和 **“开启中”** 两类；
-2. 点击上方的 **“+创建里程碑”** 按钮即可进入里程碑创建界面；
-3. 填写标题（必填）、描述（必填）、截止日期（选填）后，点击右下角的 **“创建里程碑”** 即可以完成一个新的里程碑的创建。
-
-### 关联里程碑
-项目成员可以将疑修关联到里程碑，从而使里程碑包含明确的疑修列表，主要步骤如下：
-1. 在疑修列表中点击目标疑修；
-2. 编辑“里程碑”属性，选择需要关联的里程碑。
-
-
-### 其他操作
-- **开启里程碑**
-- **关闭里程碑**
-- **编辑里程碑**
-- **删除里程碑**
-
-上述操作均可以在里程碑列表中，对目标里程碑进行处理实现。
\ No newline at end of file
diff --git a/docs/第三方服务/WebIDE.md b/docs/第三方服务/WebIDE.md
deleted file mode 100644
index 3d152e9..0000000
--- a/docs/第三方服务/WebIDE.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-sidebar_label: 'WebIDE'
-sidebar_position: 9
-
----
-## WebIDE背景
-传统的代码托管平台提供了代码仓库的 Git/SVN 的管理，可以在平台上做代码浏览、代码评审、缺陷管理、CI 流水线等和代码相关的活动。其中代码浏览、代码评审所用的编辑器组件一般为 CodeMirror，代码高亮使用 highlight.js，常常只提供了读代码的场景。蚂蚁研发效能部门云研发团队通过自研的 OpenSumi 框架及基于 OpenSumi 框架做的专门针对于 Web IDE（无远程容器）场景的极速版 Web IDE 框架，与内部代码托管平台碰撞出了创新型的、只依赖浏览器的、IDE 风格的代码阅读、代码编写、代码提交、代码运行、代码评审等场景，极大的提高了用户在代码托管平台阅读代码、代码评审、轻研发等场景的效率。本次蚂蚁研发效能云研发团队和 CCF（中国计算机学会）GitLink 代码托管平台合作，将内部极速版 Web IDE 应用到了 Gitlink 代码托管平台上，解决了长久以来的用户反馈的很多体验问题。
-
-## Web IDE 核心能力
-对标有容器的标准版，极速版 IDE 主要在读、写、运行、提交等方面进行了探索：
-
- **1. 读：**
- - a. 适配了多种代码托管平台，例如 Gitlink、Github、Gitlab 等代码托管平台，业务可以非常方便的使用代码服务的能力
- - b. 内置了包括 Java、TS/JS、C++、Go、Python、Rust 等几十种常见语言的语法高亮支持
- - c. 支持了如 Git Blame、GitGraph 等代码阅读辅助插件
-
- **2. 写：**
- - a. 支持 HTML/CSS/JS/Markdown 等在线语言服务能力，支持错误诊断能力
- - b. 浏览器文件系统
-
- **3. 运行：**
- - a. 支持基于 Skypack 的前端代码运行方案
- - b. 支持基于 Pyodide 的 Python 运行
-
- **4. 提交：**
- - a. 支持 WebSCM，提供分支切换/新增、代码提交等能力
-
-如果说以 CodeMirror、Monaco 为代表的浏览器 IDE 组件为 Web IDE 1.0，那拥有上述能力的极速版 Web IDE 就是 Web IDE 2.0。极速版 Web IDE 方案在蚂蚁内部与 2021 年 4 月上线，承接了代码阅读、代码评审、在线笔试、代码检查结果反馈、轻量在线研发等众多场景，同年 8 月 vscode.dev 和 github.dev 上线，与之相比，极速版 Web IDE 利用 OpenSumi 框架的高扩展性，业务可以更加深度的定制模块与插件，让业务有多的想象空间。
-
-## 代码阅读
-在代码托管平台上进行代码阅读时经常需要查看当前方法在哪里被引用、当前接口在哪里被实现，极速版 Web IDE 提供编辑器 + 插件的能力，解决了上述用户需求：
-
-
-代码引用查看
-Gitlink 通过实现 Blame 插件，完成了编辑器 Blame 查看的能力：
-
-
-当前代码行作者、修改日期查看
-
-
-## 代码评审
-代码评审功能用户长久以来一直反馈以下几个问题：
-
-- 1.语言服务缺失，阅读效率低：缺少代码高亮、提示、跳转、查看引用及大纲功能
-- 2.大 PR 浏览体验不佳：统计显示 Gitlink PR 平均有 14-17 个变更文件，传统代码评审交互一般为代码 Diff 组件流式展示，对于一些变更文件多、文件内部较大的场景 Review 体验不佳，常常要等待很久。
-- 3.代码修改流程重，耗时久：代码 Diff 组件只有读能力，无法快速修改一些拼写或 lint 错误，需要在本地找到对应文件后修改提交 针对于上述需求，蚂蚁云研发团队和 Gitlink 打造了 IDE 风格的代码评审场景：
-
-
-IDE模式的代码评审
-- 1.变更树 a. 提供平铺和树状两种浏览方式 b. 变更树使用 OpenSumi Recycle 组件，对于大 PR 也能通过虚拟滚动高性能的查看变更文件
-- 2.工具栏 a. 提供 IDE 编辑器基础设置，如字体大小、编码、忽略收尾空格等 b. 快速切换当前分支历史版本与基线的对比 c. 变更文件快速定位、设置已查看，并支持快捷键快速执行
-- 3.编辑器 a. 通过 monaco fold 能力完成非变更内容的折叠 b. 自定义评论组件嵌入编辑器
-- 4.插件 a. 复用代码浏览 Blame 插件能力进行代码行 Git 信息查看 除了上述能力，Gitlink 还支持了在代码评审时快速修改代码：
-
-
-代码评审时可修改代码
-
-## Gitlink Web IDE
-Gitlink 代码阅读场景虽然接入极速版 IDE 编辑器，但文件树、代码搜索、快捷键、IDE 皮肤、等均和平时开发时使用习惯的 IDE 差异较大，更有大部分用户仅仅是为了代码阅读将代码克隆到本地，尽管保证了一致的体验，但整个链路繁琐费时。
-基于这个洞察，蚂蚁云研发团队和 Gitlink 推出 Gitlink Web IDE，可以一键快速打开 Web IDE 访问阅读项目仓库代码，实现项目与 IDE 的无缝衔接，保持研发同学的日常偏好习惯，同时完美兼容 Gitlink 代码托管平台。更重要的是，通过无容器在浏览器上直接运行一个极速版 IDE，确保「秒开」的即时体验。
-
-#### **1. 快速体验**
-从 Gitlink 仓库首页 Web IDE 入口即可体验
-
-Gitlink WebIDE 入口
-
-#### **2. 代码浏览体验**
-与传统 IDE 一致的代码浏览体验。文件树、皮肤样式、快捷键一应俱全。
-#### **3. 语言功能**
-- 1.支持近 40 种语言的语法高亮
-- 2.支持 JavaScript/TypeScript、HTML、CSS、JSON、Markdown 的基于 LSP (Language Server Protocol) 语言特性功能，具备智能提示和大纲信息以及单文件内跳转。
-
-JS语言服务提示
-
-- 3. 提供了 Java、Go、Python、C++、Php 的在线语言服务能力，支持简单的定义跳转、查找引用等功能，让大家更加方便的阅读代码
-
-
-Python 查看引用
-
-#### **4. 分支新建与切换**
-点击左下角分支名即可新建/切换分支。
-
-
-分支新建与切换
-
-
-#### **5. 文件搜索**
-使用 CMD/Ctrl + P 唤起文件搜索面板
-
-
-文件搜索面板
-
-#### **6. 行高亮**
-持单行或多行高亮，点击行号即可高亮行，按住 Shift 可选中连续多行。
-
-多选行高亮
-
-#### **7. Blame**
-支持查看单行 blame 信息，hover 后可展示详细信息。
-
-Blame详细信息
-
-#### **8. Graph**
-支持 graph 视图，可查看分支 commits 历史以及每个 commit 详细文件变更，并支持文件 diff 查看。底部状态栏左下角点击 Git Graph 或在命令面板输入 View Git Graph，即可打开 Git Graph 视图。
-
-Graph 详细信息
-
-
-#### **9.WebSCM**
-对于开发来说日常多个需求并行开发是非常常见的事，经常修改一些很小但必要的逻辑，而也许你本地环境已经在开发下一个需求，频繁的分支切换并行修改又容易出错。通过 Gitlink Web IDE 极速切换分支修改提交一气呵成，无需打断本地开发流程。
-
-WebSCM
-
-
-#### **10.代码在线运行**
-目前如果在没有容器的情况下，大部分应用只能运行前端代码。Gitlink Web IDE 集成了基于 skypack 的更加轻量的 CodeSwing 插件，可以在极速版去运行前端代码，并且代码版本是使用 Gitlink 来管理。结合上述 WebSCM 能力，甚至能在一分钟完成前端代码初始化、编写、预览和代码提交。
-
-前端代码运行
-
-随着 Webassembly 技术的发展，一些后端语言也可以运行在浏览器里，在 2021 年 Google IO 大会上，StackBlitz 展示了他们最近做的技术：WebContainer，该能力可以将语言运行时编译为 Webassembly 从而运行在浏览器上。Code-Runner-For-Web 插件结合 Pyodide，已经将 Python 的运行搬到了浏览器上，新版极速版也默认集成了该插件。
-
-Python代码运行
\ No newline at end of file
diff --git a/docs/第三方服务/_category_.json b/docs/第三方服务/_category_.json
deleted file mode 100644
index a1d9d5b..0000000
--- a/docs/第三方服务/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "第三方服务",
- "position": 9
-}
diff --git a/docs/第三方服务/跨平台代码同步.md b/docs/第三方服务/跨平台代码同步.md
deleted file mode 100644
index 3330e5b..0000000
--- a/docs/第三方服务/跨平台代码同步.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '跨平台代码同步'
-sidebar_position: 2
----
\ No newline at end of file
diff --git a/docs/第三方服务/重睛鸟代码溯源.md b/docs/第三方服务/重睛鸟代码溯源.md
deleted file mode 100644
index 420351b..0000000
--- a/docs/第三方服务/重睛鸟代码溯源.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-sidebar_label: '重睛鸟代码溯源'
-sidebar_position: 1
----
-
-## 代码分析入口
-
-
-代码分析入口
-
-页面说明：
-- 1、在"维基"与"动态"之间加入"服务"菜单，并设计前置icon。
-- 2、用户可点击"服务"菜单 tab 进入服务页面。
-- 3、仓库管理员可在"仓库设置" tab 中项目导航处开启／关闭代码分析菜单可见性，如下图：
-
-
-项目导航
-
-## 代码分析检测
-
-代码分析检测
-
-页面说明：
-- 1、此页面为暂无历史分析记录时页面展示。
-- 2、"新建分析"按钮仅对仓库管理员可见。仓库开发者、观察者、游客访问此页面时，"新建分析"按钮不可见。
-- 3、点击"新建分析"按钮，需判断该仓库是否已签订协议（是否开启代码分析功能）。
-
-## 代码分析协议签订
-
-代码分析协议签订
-
-页面说明：
-- 1、用户点击"新建分析"按钮，需判断该仓库是否已签订协议（是否开启代码分析功能），若未签订协议，则弹出签订协议弹窗。
-- 2、签订协议流程：
-①用户将垂直滚动条拉至最底部。
-②勾选阅读并同意协议条款。
-③点击同意协议（若未勾选"我已阅读并同意《用户协议及声明条款》"，则"同意协议"按钮置灰）。
-- 3、用户勾选 CheckBox ，并点击"同意协议"按钮，逻辑上等同于代码溯源系统中新建一个账户。在页面交互上，相当于点击"新建分析"按钮弹出分支选择弹窗。
-
-## 分支选择
-
-分支选择
-
-页面说明:
-- 1、用户点击“新建分析”按钮，弹出新建分析需要选择填写分支。
-- 2、图中检测类型、检测参数均为默认值，不允许用户修改，此处展示在界面上，仅起到提示用户，让用户知晓作用。
-- 3、点击此处“开始检测”即开启基于选中分支的检测，新建一个检测列表。
-
-## 列表展示
-
-列表展示
-
-页面说明:
-- 1、当检测列表行数超过一行时，“新建分析”按钮左侧提供分支名称的筛选下拉框，下拉框内选项为列表中分支的集合。若本仓库有分支1、2、3、4、5，此列表中有分支3、4，则此处下拉框中分支类型仅为3、4。
-- 2、当新建分析任务正在检测中时，检测状态处有百分比进度条展示现有进度。
-- 3、点击“重新扫描”按钮，将弹出一条新建分析的弹窗，此弹窗保存所有上次已配置的分支信息，检测分支不可修改(分支下拉选中框置灰)。确认新建后，将新增一条检测数据。
-- 4、点击删除将出现二次确认弹框:“此操作将永久删除该检测记录，是否继续?”，用户点击确认后，此条检测记录将从列表中移除。
-
-## 结果展示
-
-结果展示
-页面说明：
-- 1、用户在代码检测"操作"列表点击"查看"按钮，将在当前页面展开结果展示页面。当用户再次点击"查看"按钮后，结果展示页面收回；当用户点击其他检测记录"查看"按钮后，将展开其他检测记录的结果页，收回当前已展开的结果展示页；
-- 2、当检测状态为"失败"状态，或当前处于"正在检测"状态时，"查看"按钮将置灰，处于无法点击状态；
-- 3、结果展示页取代码溯源已有页面，嵌入至 GitLink 即可，无需再次设计。
-
-## 用户操作流程
-
-用户操作流程
-
-
diff --git a/docs/组织管理/_category_.json b/docs/组织管理/_category_.json
deleted file mode 100644
index bb58afa..0000000
--- a/docs/组织管理/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "组织管理",
- "position": 3
-}
diff --git a/docs/组织管理/组织创建及设置.md b/docs/组织管理/组织创建及设置.md
deleted file mode 100644
index b39a71b..0000000
--- a/docs/组织管理/组织创建及设置.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-sidebar_label: '组织创建及设置'
-sidebar_position: 2
----
-# 组织创建（Organization Creation）
-
- 在 *https://www.gitlink.org.cn* 页面点击顶部导航栏的“+”符号可以进行组织新建操作。
-
- 
-
- 在新建页面中输入**组织账号**、**组织名称**、**组织描述**、**所在地区**、**可见性**以及**组织头像**等信息后，点击“**创建组织**”按钮完成组织的创建。
-
- 
-
-## 组织账号
-
- 
-
- **注**：只能使用以字母、数字开头，包含字母、数字、下划线、横杠等，长度4到20个字符
-
-## 组织名称与组织描述
-
- 
-
- **注**：此处为必填项，不得为空
-
-## 可见性
-
- 
-
- **注**：可见性预设三类组织：公开、受限（仅对登录用户可见）、私有（仅对组织成员可见）。
diff --git a/docs/组织管理/组织团队管理.md b/docs/组织管理/组织团队管理.md
deleted file mode 100644
index ce0c356..0000000
--- a/docs/组织管理/组织团队管理.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-sidebar_label: '组织团队管理'
-sidebar_position: 3
----
-# 组织团队管理
-
-## 创建组织团队
-点击组织信息页面中的“新建团队”按钮可以创建属于该组织的团队（平台默认创建“Owners”团队，成员为组织的创建者）。
-
-在团队新建页面，输入团队标识、团队名称、团队描述、项目权限以及版本库权限等信息后，点击“新建团队”完成团队的创建。
-
- 
-
-## 查看组织团队
-
-点击组织信息页面中的某个团队名称可以查看该团队的详细信息，该页面包括团队的名称、描述等信息，此外还会列出该团队关联的成员以及项目。
-
- 
-
-## 管理组织团队
-
-点击团队信息页面中的“团队设置”按钮可以对团队进行管理
-
- - 基本设置：修改项目的基本信息，如名称和描述等。
- 
-
- - 团队成员管理：为该团队添加新成员或者移除已有成员。
- 
-
- - 团队项目管理：为该团队关联新项目（该组织已经创建的项目）或者移除已关联项目。
- 
-
-
-
diff --git a/docs/组织管理/组织成员管理.md b/docs/组织管理/组织成员管理.md
deleted file mode 100644
index b178a64..0000000
--- a/docs/组织管理/组织成员管理.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '组织成员管理'
-sidebar_position: 4
----
\ No newline at end of file
diff --git a/docs/组织管理/组织简介.md b/docs/组织管理/组织简介.md
deleted file mode 100644
index 469b59d..0000000
--- a/docs/组织管理/组织简介.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-sidebar_label: ‘组织简介’
-sidebar_position: 1
----
-
-# 组织简介
-
-组织是共享帐户，其中业务和开源项目可同时跨多个项目进行协作，具有复杂的安全性和管理功能。多个个人帐户可以通过加入同一组织帐户来协作处理共享项目。
-
-您的团队可以通过使用组织帐户在 GitLink 上进行协作，组织帐户充当共享工作的容器，并为工作赋予独特的名称和品牌。同时，平台支持组织在“组织详情”页面发布新闻动态，显示项目概览和仓库详情等内容
-
- 
-
-## 作为组织拥有者
-
-有效管理组织，是您的使命。
-
-组织提供了一个集中式的合作与共享中心，让您的团队一起工作，共享资源并实现更有效地沟通。
-
-为了简化访问管理并增强协作，您可以创建能体现组结构的嵌套团队。您可以根据他们的角色或项目将人员分组，并分配任务。
-
- 
-
-平台同时支持组织拥有者管理对数据访问的自定义设置。
-
-## 作为组织成员
-
-您可以通过组织与无限数量的人在多个项目中协作，与志同道合的人一起，通过分工和写作，参与开发流程，发布或处理问题。
diff --git a/docs/组织管理/组织项目管理.md b/docs/组织管理/组织项目管理.md
deleted file mode 100644
index 2253db7..0000000
--- a/docs/组织管理/组织项目管理.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-sidebar_label: '组织项目管理'
-sidebar_position: 5
----
- ## 创建组织项目
-
-点击组织信息页面中的“新建项目”按钮可以创建属于该组织的托管项目或者镜像项目。
-
- 
-
- **注**：在“拥有者”一栏的下拉选项中，可以选择：个人、组织、团队
-
diff --git a/docs/维基/_category_.json b/docs/维基/_category_.json
deleted file mode 100644
index 9072bcc..0000000
--- a/docs/维基/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "维基(Wiki)",
- "position": 7
-}
diff --git a/docs/维基/模板导入及导出.md b/docs/维基/模板导入及导出.md
deleted file mode 100644
index 0901b17..0000000
--- a/docs/维基/模板导入及导出.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '模板导入及导出'
-sidebar_position: 2
----
\ No newline at end of file
diff --git a/docs/维基/维基页面管理.md b/docs/维基/维基页面管理.md
deleted file mode 100644
index 1ed56fc..0000000
--- a/docs/维基/维基页面管理.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_label: '维基页面管理'
-sidebar_position: 1
----
\ No newline at end of file
diff --git a/docs/通知/_category_.json b/docs/通知/_category_.json
deleted file mode 100644
index aabbf21..0000000
--- a/docs/通知/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "通知",
- "position": 10
-}
diff --git a/docs/通知/通知简介.md b/docs/通知/通知简介.md
deleted file mode 100644
index 278389b..0000000
--- a/docs/通知/通知简介.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-sidebar_label: '通知简介'
-sidebar_position: 1
----
-
-# 确实开源帮助中心
-
-## 通知简介
-#### 1.通知类型
-GitLink将通知分为“系统通知”和“@我”的两种类型：
-* 系统通知包括“我的状态”、“我创建的或负责的”、“我管理的仓库”三种类型的通知:
-
-| 系统通知类型 | 具体通知内容 |
-| ----------- | ----------- |
-| 我的状态 | 账号有权限变更；被拉入或移出组织；被拉入或移出项目；有新的疑修指派给我；有新的合并请求指派给我；|
-| 我创建的或负责的 | 疑修状态变更；合并请求状态变更；|
-| 我管理的仓库 | 有新的疑修；有新的合并请求；有成员变动；仓库设置被更改；|
-* “@我”的通知目前支持在用户首页、课程首页、项目首页的动态列表中使用@功能对用户进行通知：
- 例，在项目首页提交疑修时，输入@后可以通过下拉列表选择@其他用户。
- 
-
-#### 2.查看通知
-登录后在平台右上角个人头像旁即可查看收到的通知数量；移动光标至通知按钮出现下拉列表可以分别查看“系统通知”和“@我”的通知；下拉列表右下角可以对所有消息进行一键已读；点击通知即可跳转至通知详情界面。
-
-
-
-
-点击通知按钮可以进入消息通知界面，“我的通知”界面可以进行“进查看未读消息”和“所有消息一键已读”的选择。
-
\ No newline at end of file
diff --git a/docs/通知/通知设置.md b/docs/通知/通知设置.md
deleted file mode 100644
index 37f798c..0000000
--- a/docs/通知/通知设置.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-sidebar_label: '通知设置'
-sidebar_position: 2
----
-
-
-# 确实开源帮助中心
-
-## 通知设置
-#### 1.进入通知设置界面
-通过点击首页的通知按钮进入通知设置界面；
-
-
-或在头像下拉列表中选择设置可以进入消息通知设置界面；
-
-
-#### 2.进行通知设置
-通过“通知管理”可以对接受通知的方式进行设置，默认所有通知都是通过站内信的方式接受，可以通过勾选为重要的通知类型增加邮件接受方式。
-
-
\ No newline at end of file
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 77d8b56..99680f0 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -1,129 +1,220 @@
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const copyright = '2021-present © BoxyHQ Inc.';
/** @type {import('@docusaurus/types').DocusaurusConfig} */
module.exports = {
- title: 'gitlink',
- tagline: 'gitlink帮助中心',
- onBrokenLinks: 'ignore',
- onBrokenMarkdownLinks: 'warn',
- favicon: 'img/icon.ico',
- url: 'https://luffyzh.github.io',
+ title: 'Security Building Blocks for Developers',
+ tagline:
+ 'BoxyHQ helps startups enable enterprise features in any SaaS app with just a few lines of code. Integrate SAML, Audit Logs, Privacy Vault and Role Based Access in minutes. Open source and free.',
+ url: 'https://boxyhq.com',
baseUrl: '/',
- organizationName: 'luffyZh', // Usually your GitHub org/user name.
- projectName: 'docusaurus-luffyzh-website', // Usually your repo name.
+ onBrokenLinks: 'throw',
+ onBrokenMarkdownLinks: 'throw',
+ favicon: 'img/favicon.ico',
+ organizationName: 'boxyhq', // Usually your GitHub org/user name.
+ projectName: 'website', // Usually your repo name.
+ scripts: [],
+ // stylesheets: ['styles/dark-mode.css'],
themeConfig: {
+ prism: {
+ theme: require('prism-react-renderer/themes/dracula'),
+ additionalLanguages: ['php'],
+ },
+ zoom: {
+ selector: '.markdown :not(em) > img',
+ config: {
+ background: {
+ light: 'rgb(255, 255, 255)',
+ dark: 'rgb(50, 50, 50)',
+ },
+ },
+ },
+ announcementBar: {
+ id: 'announcement-bar',
+ content:
+ '⭐ Star Enterprise SSO on GitHub ⭐ Star Audit Logs on GitHub',
+ isCloseable: false,
+ },
+ image: 'img/website-preview-image.png',
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: true,
},
- aloglia:{
- apiKey: '0f9f28b9ab9efae89810921a351753b5',
- indexName: 'github',
- },
navbar: {
- style:"dark",
- title: '',
+ title: 'BoxyHQ',
logo: {
- alt: 'gitlink',
- src: 'img/gitlink.png'
+ alt: 'BoxyHQ',
+ width: '32px',
+ height: '32px',
+ src: 'img/logo.png',
+ srcDark: 'img/logo-dark.png',
},
items: [
{
- type: 'doc',
- docId: 'intro',
- position: 'left',
- label: '帮助中心',
- }
- ]
+ label: 'Products',
+ type: 'dropdown',
+ items: [
+ {
+ to: '/enterprise-sso',
+ label: 'Enterprise SSO',
+ },
+ {
+ to: '/directory-sync',
+ label: 'Directory Sync',
+ },
+ {
+ to: '/audit-logs',
+ label: 'Audit Logs',
+ },
+ {
+ to: '/privacy-vault',
+ label: 'Privacy Vault',
+ },
+ { to: '/saas-registration', label: 'SaaS Early Access' },
+ ],
+ },
+ {
+ label: 'Developers',
+ type: 'dropdown',
+ items: [
+ { to: '/docs', label: 'Docs' },
+ { to: '/guides', label: 'Guides' },
+ { to: '/enterprise-readiness', label: 'Enterprise Readiness' },
+ {
+ href: 'https://mocksaml.com',
+ label: 'Mock SAML',
+ },
+ {
+ href: 'https://github.com/boxyhq/saas-starter-kit',
+ label: 'Enterprise SaaS Starter Kit',
+ },
+ {
+ href: 'https://awesome-oss-devsec.boxyhq.com',
+ label: 'Developer Security Tools',
+ },
+ ],
+ },
+ { to: '/blog', label: 'Blog' },
+ { to: '/pricing', label: 'Pricing' },
+ {
+ label: 'Company',
+ type: 'dropdown',
+ position: 'right',
+ items: [
+ {
+ to: '/careers',
+ label: 'Careers',
+ },
+ {
+ to: '/team',
+ label: 'Team',
+ },
+ {
+ to: '/pledge',
+ label: 'Pledge',
+ },
+ ],
+ },
+ {
+ href: 'https://github.com/boxyhq',
+ position: 'right',
+ className: 'header-github-link',
+ },
+ ],
},
footer: {
style: 'dark',
- logo:{
- src:"img/gitlink.png"
- },
links: [
{
- title: '社区',
+ title: 'Community',
items: [
{
- label: '网站首页',
- to: 'https://www.gitlink.org.cn',
+ label: 'GitHub',
+ href: 'https://github.com/boxyhq',
},
{
- label: '关于我们',
- to: 'https://www.gitlink.org.cn/aboutus',
+ label: 'Discord',
+ href: 'https://discord.boxyhq.com',
},
{
- label: '教学实践',
- to: 'https://www.gitlink.org.cn/educoder',
+ label: 'Twitter',
+ href: 'https://twitter.com/boxyhq',
},
{
- label: '合作伙伴',
- to: 'https://forum.trustie.net/forums/5030/detail',
+ label: 'OSS Friends',
+ href: 'https://boxyhq.com/oss-friends',
},
],
},
{
- title: '支持与服务',
+ title: 'Social',
items: [
{
- label: 'API文档',
- to: 'https://forgeplus.trustie.net/docs/api',
+ label: 'LinkedIn',
+ href: 'https://www.linkedin.com/company/boxyhq',
},
{
- label: 'Git常用命令',
- to: 'https://git-scm.com',
+ label: 'Facebook',
+ href: 'https://www.facebook.com/boxyhq',
},
{
- label: '引擎使用手册',
- to: 'https://forum.gitlink.org.cn/forums/7487/detail',
- },
- {
- label: '服务协议',
- to: 'https://forum.trustie.net/forums/5029/detail',
+ label: 'Instagram',
+ href: 'https://www.instagram.com/boxyhq',
},
],
},
{
- title: '加入我们',
+ title: 'Legal',
items: [
{
- label: '官网邮箱：gitlink@ccf.org.cn',
- to:"https://www.gitlink.org.cn"
+ label: 'Privacy & Cookies Policy',
+ href: '/privacy.html',
},
{
- label:'QQ群',
- to:'https://www.gitlink.org.cn'
+ label: 'Terms',
+ href: '/terms.html',
+ target: '_blank',
+ },
+ ],
+ },
+ {
+ title: 'Company',
+ items: [
+ {
+ label: 'Careers',
+ href: '/careers',
},
{
- label:'公众号',
- to:'https://www.gitlink.org.cn'
- }
+ label: 'Team',
+ href: '/team',
+ },
],
},
],
- copyright: `©Copyright ${new Date().getFullYear()} CCF 开源发展委员会
Powered by Trustie& IntelliDE 京ICP备13000930号
`,
- },
- prism: {
- theme: lightCodeTheme,
- darkTheme: darkCodeTheme,
+ copyright,
},
},
presets: [
[
- //此为docusaurus的默认界面风格
'@docusaurus/preset-classic',
{
- //此为docs的侧边栏修饰
docs: {
sidebarPath: require.resolve('./sidebars.js'),
- //此为网页左下的Edit this page 链接地址
- editUrl:'https://www.gitlink.org.cn/Gitlink/gitlink_help_center/tree/master/',
- routeBasePath: "/",
},
- //修饰的css文件格式
+ blog: {
+ blogTitle: 'Blog',
+ blogDescription:
+ 'The BoxyHQ blog is where our team shares our thoughts and ideas about everything from our products to industry news and insights. We also welcome guest posts so please do get in touch if you have any thoughts you would like to share on our blog.',
+ showReadingTime: true,
+ feedOptions: {
+ type: 'all',
+ copyright,
+ },
+
+ blogSidebarTitle: 'Recent posts',
+ blogSidebarCount: 5,
+ postsPerPage: 'ALL',
+ },
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
@@ -131,10 +222,70 @@ module.exports = {
],
],
plugins: [
- ['@cmfcmf/docusaurus-search-local', {}]
+ [
+ require.resolve('docusaurus-gtm-plugin'),
+ {
+ id: 'GTM-N9999D3', // GTM Container ID
+ },
+ ],
+ [
+ '@docusaurus/plugin-content-blog',
+ {
+ /**
+ * Required for any multi-instance plugin
+ */
+ id: 'careers',
+ /**
+ * URL route for the blog section of your site.
+ * *DO NOT* include a trailing slash.
+ */
+ routeBasePath: 'careers',
+ /**
+ * Path to data on filesystem relative to site dir.
+ */
+ path: './careers',
+ blogTitle: 'Careers',
+ blogDescription:
+ 'Join us on our mission to help startups simplify the development of compliance and data security-related features in their products. Check out our open roles.',
+ },
+ ],
+ [
+ '@docusaurus/plugin-content-docs',
+ {
+ id: 'guides',
+ path: 'guides',
+ routeBasePath: 'guides',
+ sidebarPath: require.resolve('./sidebars_guides.js'),
+ },
+ ],
+ ['@cmfcmf/docusaurus-search-local', {}],
+ require.resolve('docusaurus-plugin-image-zoom'),
+ [
+ '@docusaurus/plugin-client-redirects',
+ {
+ redirects: [
+ {
+ from: '/docs/jackson/admin-ui',
+ to: '/docs/admin-portal/enterprise-sso',
+ },
+ {
+ from: '/docs/directory-sync/admin-ui',
+ to: '/docs/admin-portal/directory-sync',
+ },
+ {
+ from: '/docs/jackson/saml-flow',
+ to: '/docs/jackson/sso-flow',
+ },
+ {
+ from: '/docs/jackson/configure-saml-idp',
+ to: '/docs/jackson/sso-providers',
+ },
+ {
+ from: '/docs/jackson/deploy/pre-loaded-configuration',
+ to: '/docs/jackson/deploy/pre-loaded-connections',
+ },
+ ],
+ },
+ ],
],
- i18n: {
- defaultLocale: 'zh-cn',
- locales: ['zh-cn'],
- },
};
diff --git a/guides/directory-sync/frameworks/express.md b/guides/directory-sync/frameworks/express.md
new file mode 100644
index 0000000..de0efc6
--- /dev/null
+++ b/guides/directory-sync/frameworks/express.md
@@ -0,0 +1,178 @@
+---
+title: Implement Directory Sync (SCIM) to your Express.js App using Jackson
+sidebar_label: Express.js
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Express.js
+
+This guide will teach you to implement SCIM Provisioning in your Express.js app.
+
+## Quickstart
+
+Directory sync helps organizations automate the provisioning and de-provisioning of their users in the Enterprise SaaS app. 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.
+
+### Install SAML Jackson
+
+Let’s start by installing SAML Jackson to your Express.js app.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+### Initialize SAML Jackson
+
+Please note that the initialization of `@boxyhq/saml-jackson` is async, you cannot run it at the top level. Run this in a function where you initialize the express server.
+
+```javascript
+let directorySyncController;
+
+const opts = {
+ externalUrl: `http://localhost:3000/`,
+ samlPath: '/',
+ scimPath: '/api/scim',
+ db: {
+ engine: 'sql',
+ type: 'postgres',
+ url: 'postgres://username:password@localhost:5432/your-database-name',
+ },
+};
+
+async function init() {
+ const ret = await require('@boxyhq/saml-jackson').controllers(opts);
+
+ directorySyncController = ret.directorySyncController;
+}
+```
+
+### Create the Directory
+
+The first step towards the integration is creating a directory for a tenant.
+
+Directory Sync providers (Identity Providers) require you to provide a **SCIM Base URL** and **SCIM Auth token**. Both are unique for each directory your app users create.
+
+```javascript
+const { data, error } = await directorySyncController.directories.create({
+ name: 'any-name',
+ type: 'okta-scim-v2',
+ tenant: "tenant-identifier"
+ product: "product-identifier"
+});
+```
+
+The response will looks like as below:
+
+```javascript
+{
+ "data": {
+ "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
+ "name": "any-name",
+ "tenant": "tenant-identifier",
+ "product": "product-identifier",
+ "type": "okta-scim-v2",
+ "log_webhook_events": false,
+ "scim": {
+ "path": "/api/scim/58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
+ "secret": "IJzAoevjD_liiiy-VkDtXg",
+ "endpoint": "http://localhost:5225/api/scim/58b5cd9dfaa39d47eb8f5f88631f9a629a232016"
+ },
+ "webhook": {
+ "endpoint": "",
+ "secret": ""
+ }
+ },
+ "error": null
+}
+```
+
+Note the keys `scim.endpoint` and `scim.secret` from the above JSON. Your users need these values while configuring SCIM app on their Identity Provider.
+
+Typically you'll have to provide some UI where the users can create the directory for their providers and display `SCIM Base URL` and `SCIM Auth Token` for the directory the user created. Usually, this UI comes under organization settings or team settings.
+
+For example, see the demo below.
+
+
+
+You can retrieve the supported list of Directory Sync providers by calling the method `directorySyncController.providers()`.
+
+### Understand SCIM API Requests
+
+A key piece to implementing SCIM is building a RESTful API that IdP's SCIM provisioning can call to provision users and groups to your app. The requests will come to the `SCIM Base URL (scim.endpoint)`.
+
+Here are the calls your API should be able to receive from IdP SCIM provisioning for a given `SCIM Base URL (scim.endpoint)`.
+
+#### Users Provisioning
+
+| Route | Methods |
+| ---------- | ---------- |
+| /Users | POST |
+| /Users/:id | GET |
+| /Users/:id | PUT, PATCH |
+| /Users/:id | DELETE |
+
+#### Push Groups and Group Memberships
+
+| Route | Methods |
+| ----------- | ---------- |
+| /Groups | POST |
+| /Groups/:id | GET |
+| /Groups/:id | PUT, PATCH |
+| /Groups/:id | DELETE |
+
+### Handle SCIM API Requests
+
+Now let's add the route to handle the incoming requests from the Directory Sync providers.
+
+```javascript
+router.all(
+ '/api/scim/:directoryId/:resourceType/:resourceId?',
+ async (req, res, next) => {
+ const { params, method, body, headers, query } = req;
+ const { directoryId, resourceType, resourceId } = params;
+
+ const authToken = headers.authorization.split(' ')[1];
+
+ // Construct the event
+ const request = {
+ method: method,
+ body: body ? JSON.parse(body) : undefined,
+ directoryId: directoryId,
+ resourceId: resourceId,
+ resourceType: resourceType.toLowerCase(),
+ apiSecret: authToken,
+ query: {
+ count: query.count ? parseInt(query.count) : undefined,
+ startIndex: query.startIndex ? parseInt(query.startIndex) : undefined,
+ filter: query.filter,
+ },
+ };
+
+ // Handle the requests
+ // highlight-start
+ const { status, data } = await directorySyncController.requests.handle(
+ request,
+ async (event) => {
+ console.log(event); // Do something with the event
+ }
+ );
+ // highlight-end
+
+ // Send the response back
+ return res.status(status).json(data);
+ }
+);
+```
+
+`router.all('/api/scim/:directoryId/:resourceType/:resourceId?', async (req, res, next) => {...})` is a catch all paths route. Matched parameters will be sent as a parameter to the route.
+
+Look at the highlighted lines, and you can pass an async callback method to the `directorySyncController.requests.handle` as a second argument. This method will be called with SCIM event as the first argument.
+
+Checkout the documentation for [SCIM events and Types](/docs/directory-sync/events) to understand more about the events.
+
+Use these events to trigger actions in your application, such as creating a new user in your application, or updating a user in your application based on the changes made in the directory.
+
+### Configure the Identity Provider
+
+Your users should typically do this step at their end. We've [detailed documentation](/docs/directory-sync/providers/) for each Directory Sync provider.
diff --git a/guides/directory-sync/frameworks/nextjs.md b/guides/directory-sync/frameworks/nextjs.md
new file mode 100644
index 0000000..502c601
--- /dev/null
+++ b/guides/directory-sync/frameworks/nextjs.md
@@ -0,0 +1,200 @@
+---
+title: Implement Directory Sync (SCIM) to your Next.js App using Jackson
+sidebar_label: Next.js
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Next.js
+
+This guide will teach you to implement SCIM Provisioning in your Next.js app.
+
+## Quickstart
+
+Directory sync helps organizations automate the provisioning and de-provisioning of their users in the Enterprise SaaS app. 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.
+
+### Install SAML Jackson
+
+Let’s start by installing SAML Jackson to your Next.js app.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+### Initialize SAML Jackson
+
+Create a new file, `jackson.ts` that holds the Jackson initialization.
+
+```javascript title="lib/jackson.ts"
+import type { JacksonOption, IDirectorySyncController } from '@boxyhq/saml-jackson';
+import jackson from '@boxyhq/saml-jackson';
+
+let directorySyncController: IDirectorySyncController;
+
+const g = global as any;
+
+const opts = {
+ externalUrl: `http://localhost:3000/`,
+ samlPath: '/',
+ scimPath: '/api/scim',
+ db: {
+ engine: 'sql',
+ type: 'postgres',
+ url: "postgres://username:password@localhost:5432/your-database-name",
+ },
+} as JacksonOption;
+
+export default async function init() {
+ if (!g.directorySyncController) {
+ const ret = await jackson(opts);
+
+ directorySyncController = ret.directorySyncController;
+ g.directorySyncController = directorySyncController;
+ } else {
+ directorySyncController = g.directorySyncController;
+ }
+
+ return {
+ directorySyncController,
+ };
+}
+```
+
+### Create the Directory
+
+The first step towards the integration is creating a directory for a tenant.
+
+Directory Sync providers (Identity Providers) require you to provide a **SCIM Base URL** and **SCIM Auth token**. Both are unique for each directory your app users create.
+
+```javascript
+const { data, error } = await directorySyncController.directories.create({
+ name: 'any-name',
+ type: 'okta-scim-v2',
+ tenant: "tenant-identifier"
+ product: "product-identifier"
+});
+```
+
+The response will looks like as below:
+
+```javascript
+{
+ "data": {
+ "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
+ "name": "any-name",
+ "tenant": "tenant-identifier",
+ "product": "product-identifier",
+ "type": "okta-scim-v2",
+ "log_webhook_events": false,
+ "scim": {
+ "path": "/api/scim/58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
+ "secret": "IJzAoevjD_liiiy-VkDtXg",
+ "endpoint": "http://localhost:5225/api/scim/58b5cd9dfaa39d47eb8f5f88631f9a629a232016"
+ },
+ "webhook": {
+ "endpoint": "",
+ "secret": ""
+ }
+ },
+ "error": null
+}
+```
+
+Note the keys `scim.endpoint` and `scim.secret` from the above JSON. Your users need these values while configuring SCIM app on their Identity Provider.
+
+Typically you'll have to provide some UI where the users can create the directory for their providers and display `SCIM Base URL` and `SCIM Auth Token` for the directory the user created. Usually, this UI comes under organization settings or team settings.
+
+For example, see the demo below.
+
+
+
+You can retrieve the supported list of Directory Sync providers by calling the method `directorySyncController.providers()`.
+
+### Understand SCIM API Requests
+
+A key piece to implementing SCIM is building a RESTful API that IdP's SCIM provisioning can call to provision users and groups to your app. The requests will come to the `SCIM Base URL (scim.endpoint)`.
+
+Here are the calls your API should be able to receive from IdP SCIM provisioning for a given `SCIM Base URL (scim.endpoint)`.
+
+#### Users Provisioning
+
+| Route | Methods |
+| ---------- | ---------- |
+| /Users | POST |
+| /Users/:id | GET |
+| /Users/:id | PUT, PATCH |
+| /Users/:id | DELETE |
+
+#### Push Groups and Group Memberships
+
+| Route | Methods |
+| ----------- | ---------- |
+| /Groups | POST |
+| /Groups/:id | GET |
+| /Groups/:id | PUT, PATCH |
+| /Groups/:id | DELETE |
+
+### Handle SCIM API Requests
+
+Now let's add the route to handle the incoming requests from the Directory Sync providers.
+
+```javascript title="pages/api/scim/[...directory].ts"
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { DirectorySyncRequest, HTTPMethod, DirectorySyncEvent } from '@boxyhq/saml-jackson';
+
+import jackson from '../../../lib/jackson';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+ const { directorySyncController } = await jackson();
+
+ const { method, query, body } = req;
+
+ const directory = query.directory as string[];
+ const [directoryId, path, resourceId] = directory; // Extract the params
+
+ // Construct the event
+ const request: DirectorySyncRequest = {
+ method: method as HTTPMethod,
+ body: body ? JSON.parse(body) : undefined,
+ directoryId: directoryId,
+ resourceId: resourceId,
+ resourceType: path === 'Users' ? 'users' : 'groups',
+ apiSecret: extractAuthToken(req),
+ query: {
+ count: req.query.count ? parseInt(req.query.count as string) : undefined,
+ startIndex: req.query.startIndex ? parseInt(req.query.startIndex as string) : undefined,
+ filter: req.query.filter as string,
+ },
+ };
+
+ // Handle the requests
+ // highlight-start
+ const { status, data } = await directorySyncController.requests.handle(request, async (event: DirectorySyncEvent) => {
+ console.log(event); // Do something with the event
+ });
+ // highlight-end
+
+ // Send the response back
+ return res.status(status).json(data);
+}
+
+// Fetch the auth token from the request headers
+const extractAuthToken = (req: NextApiRequest): string | null => {
+ const authHeader = req.headers.authorization || null;
+
+ return authHeader ? authHeader.split(' ')[1] : null;
+};
+```
+
+`pages/api/scim/[...directory].ts` is a catch all paths route. Matched parameters will be sent as a query parameter to the page, and it will always be an array.
+
+Look at the highlighted lines, and you can pass an async callback method to the `directorySyncController.requests.handle` as a second argument. This method will be called with SCIM event as the first argument.
+
+Checkout the documentation for [SCIM events and Types](/docs/directory-sync/events) to understand more about the events.
+
+Use these events to trigger actions in your application, such as creating a new user in your application, or updating a user in your application based on the changes made in the directory.
+
+### Configure the Identity Provider
+
+Your users should typically do this step at their end. We've [detailed documentation](/docs/directory-sync/providers/) for each Directory Sync provider.
diff --git a/guides/directory-sync/overview.md b/guides/directory-sync/overview.md
new file mode 100644
index 0000000..2d91d52
--- /dev/null
+++ b/guides/directory-sync/overview.md
@@ -0,0 +1,27 @@
+---
+title: Directory Sync Guide
+hide_table_of_contents: true
+slug: /directory-sync
+---
+
+# Framework Guides
+
+This guide describes how to add Directory Sync to different languages & frameworks.
+
+import GuideSection from '../../src/components/GuideSection.js';
+const frameworks = [
+ {
+ name: 'Next.js',
+ href: '/guides/directory-sync/frameworks/nextjs',
+ },
+ {
+ name: 'Express.js',
+ href: '/guides/directory-sync/frameworks/express',
+ }
+];
+
+
+
+ Enterprise SSO
+
+ An SAML SSO service designed as an OAuth 2.0 or OpenID Connect flow.
+ Integrate SAML and OIDC with just a few lines of code.
+
+
+
+
+
+
+
+ Directory Sync (SCIM 2.0)
+
+ Directory Sync service that helps organizations automate the
+ provisioning and de-provisioning of their users.
+
+
+
+
+
+
diff --git a/guides/jackson/configuring-saml-sso.md b/guides/jackson/configuring-saml-sso.md
new file mode 100644
index 0000000..1fb6b19
--- /dev/null
+++ b/guides/jackson/configuring-saml-sso.md
@@ -0,0 +1,67 @@
+---
+title: UI Best Practices for Configuring SAML Single Sign-On
+description: UI Best Practices for Configuring SAML Single Sign-On
+sidebar_label: Configuring SAML SSO
+---
+
+# Configuring SAML Single Sign-On
+
+For an overview of our SAML SSO, read [SSO Building blocks](/blog/sso-building-blocks).
+
+This guide aims to give you some ideas about configuring the SAML SSO for your tenants and the best practices you can follow while implementing the same.
+
+## SSO connection identifier
+
+A multi-tenant enterprise app must attach SSO connections to a **tenant identifier**. For example, an app can use any of the following as its tenant identifier.
+
+- Email domain
+- Organization Id or Organization slug
+- Team Id or Team slug
+- Other unique identifiers
+
+Typically, the app asks users to enter their tenant identifier to initiate the authentication flow. Then the app tries to find the proper SSO connection based on the tenant identifier. Finally, the app redirects users to their Identity Provider if a valid SSO connection is found, or the app displays an appropriate error message if the connection is not found.
+
+If your app asks for the work email address, it must extract the domain part and use it as the tenant identifier.
+
+Let's see what other apps use to identify the SSO Connections:
+
+- Airtable uses the Email domain
+- Vercel uses the Team slug
+- Netlify uses the Team Id
+- Sentry uses the Organization Id
+
+Read more about [UI Best Practices for login with SAML Single Sign-On](/guides/jackson/login-with-saml-sso).
+
+## SSO settings UI
+
+An app should allow each tenant to configure SAML SSO for their users.
+
+Depending on your application's tenant architecture, you can put the SAML SSO configuration page under the organization or team settings page.
+
+Since the SAML SSO is an exclusive security-facing feature for enterprises, the best place to put the configuration page is under the **Security** tab.
+
+Here is how Sentry does the SAML SSO configuration for their customers.
+
+
+ 
+
+
+To create an [SSO connection with SAML Jackson](/docs/jackson/sso-flow/#2-sso-connection-api), you must pass the tenant identifier, product name, and XML metadata. So your settings page UI must display a form to capture the XML Metadata.
+
+Typically, an Administrator user with a higher privilege does the SAML SSO configuration for their tenant.
+
+## Additional SSO settings
+
+You can consider a few additional settings while implementing the SAML SSO into your app.
+
+**Enforcing SAML**
+
+For additional security, SAML SSO can be enforced for a tenant so that all tenant members must authenticate via an identity provider (IdP).
+
+**Default role**
+
+Allow the tenants to choose a default role. Every member who creates a new account via SSO will be assigned the default role that has been set.
diff --git a/guides/jackson/deployments/heroku.md b/guides/jackson/deployments/heroku.md
new file mode 100644
index 0000000..eef11d3
--- /dev/null
+++ b/guides/jackson/deployments/heroku.md
@@ -0,0 +1,36 @@
+---
+title: Deploy Enterprise SSO on Heroku
+sidebar_label: Heroku
+---
+
+# Heroku
+
+This guide will walk you through the configuration and deployment of SAML Jackson on Heroku. We'll be using the **Deploy to Heroku** button that enables users to deploy apps to Heroku without leaving the web browser and with little or no configuration.
+
+If you don’t have a Heroku account, create one [here](https://signup.heroku.com/).
+
+## Deploy SAML Jackson
+
+- Fork the the SAML Jackson [GitHub repository](https://github.com/boxyhq/jackson/fork).
+- Go to the forked repo and click the **Deploy to Heroku** button from the README section.
+- Give your new application a **name**.
+- Fill the **Config Vars** as per the [documentation](/docs/jackson/deploy/env-variables).
+- After you've filled everything click the **Deploy app** button.
+
+### Verify deployment
+
+You can visit the path `/api/hello` on your app to see if the Jackson was started successfully! If the installation was successful, you'll see the following output on the screen.
+
+```javascript
+{
+ name: 'Jules Winnfield';
+}
+```
+
+## Next steps
+
+At this stage you have a functional SAML Jackson instance running on your server!
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+- [Sign into Admin Portal](/docs/admin-portal/overview#sign-into-admin-portal)
+- [Add SAML Configurations](/docs/admin-portal/enterprise-sso)
diff --git a/guides/jackson/deployments/mogenius.md b/guides/jackson/deployments/mogenius.md
new file mode 100644
index 0000000..69ac8da
--- /dev/null
+++ b/guides/jackson/deployments/mogenius.md
@@ -0,0 +1,33 @@
+---
+title: Deploy Enterprise SSO on mogenius
+sidebar_label: mogenius
+---
+
+# mogenius
+
+This guide will walk you through the configuration and deployment of SAML Jackson on mogenius. mogenius is the easiest way for developers to run any application in the cloud. They have a template for SAML Jackson, so that you can deploy it on their fully automated cloud infrastructure in minutes.
+
+If you don’t have a mogenius account, create one [here](https://studio.mogenius.com/user/registration). They have an extensive [guide](https://docs.mogenius.com/getting-started/quickstart) to get you started.
+
+## Deploy SAML Jackson
+
+- Head over to [mogenius](https://docs.mogenius.com/services/various/saml-jackson) and follow the instructions to deploy SAML Jackson as a docker container.
+- You should deploy the latest version from [Docker Hub](https://hub.docker.com/r/boxyhq/jackson/tags) and please keep your image up to date for additional security.
+
+### Verify deployment
+
+You can visit the path `/api/hello` on your app to see if the Jackson was started successfully! If the installation was successful, you'll see the following output on the screen.
+
+```javascript
+{
+ name: 'Jules Winnfield';
+}
+```
+
+## Next steps
+
+At this stage you have a functional SAML Jackson instance running on your server!
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+- [Sign into Admin Portal](/docs/admin-portal/overview#sign-into-admin-portal)
+- [Add SAML Configurations](/docs/admin-portal/enterprise-sso)
diff --git a/guides/jackson/deployments/vercel.md b/guides/jackson/deployments/vercel.md
new file mode 100644
index 0000000..03c5d3a
--- /dev/null
+++ b/guides/jackson/deployments/vercel.md
@@ -0,0 +1,37 @@
+---
+title: Deploy Enterprise SSO on Vercel
+sidebar_label: Vercel
+---
+
+# Vercel
+
+This guide will walk you through the configuration and deployment of SAML Jackson on Vercel. We'll be using the Vercel **Deploy Button** that enables users to deploy apps to Vercel without leaving the web browser and with little or no configuration.
+
+If you don’t have a Vercel account, create one [here](https://vercel.com/signup).
+
+## Deploy SAML Jackson
+
+- Fork the the SAML Jackson [GitHub repository](https://github.com/boxyhq/jackson/fork).
+- Go to the forked repo and click the **Deploy** button from the README section.
+- Select your username under **GIT SCOPE**.
+- Enter a **name** for your project, choose whether you want your repo `private` or `public`, and click **Create**.
+- Fill the **Environment Variables** as per the [documentation](/docs/jackson/deploy/env-variables).
+- After you've filled everything click the **Deploy** button.
+
+### Verify deployment
+
+You can visit the path `/api/hello` on your app to see if the Jackson was started successfully! If the installation was successful, you'll see the following output on the screen.
+
+```javascript
+{
+ name: 'Jules Winnfield';
+}
+```
+
+## Next steps
+
+At this stage you have a functional SAML Jackson instance running on your server!
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
+- [Sign into Admin Portal](/docs/admin-portal/overview#sign-into-admin-portal)
+- [Add SAML Configurations](/docs/admin-portal/enterprise-sso)
diff --git a/guides/jackson/frameworks/adonis.md b/guides/jackson/frameworks/adonis.md
new file mode 100644
index 0000000..67e1755
--- /dev/null
+++ b/guides/jackson/frameworks/adonis.md
@@ -0,0 +1,329 @@
+---
+title: Add SAML SSO to AdonisJS App with BoxyHQ
+description: Add SAML SSO to AdonisJS App with BoxyHQ
+sidebar_label: AdonisJS
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to AdonisJS App
+
+This guide assumes that you have a AdonisJS app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/jackson-examples/tree/main/apps/adonisjs) to see the source code for the AdonisJS SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure SAML Single Sign-On
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focus more on the SSO authentication side.
+
+### Install SAML Jackson
+
+To get started with SAML Jackson, use the Node Package Manager to add the package to your project's dependencies.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+### Setup SAML Jackson
+
+Setup the SAML Jackson to work with AdonisJS app.
+
+```js title="lib/jackson.ts"
+import { type JacksonOption } from '@boxyhq/saml-jackson';
+
+export const appUrl = 'https://your-app.com';
+export const samlAudience = 'https://saml.boxyhq.com';
+export const redirectUrl = `${appUrl}/sso/callback`;
+
+export const options: JacksonOption = {
+ externalUrl: appUrl,
+ samlAudience,
+ samlPath: '/sso/acs',
+ db: {
+ engine: 'sql',
+ type: 'postgres',
+ url: 'postgres://postgres:postgres@localhost:5432/postgres',
+ },
+};
+```
+
+`samlPath` is where the identity provider POST the SAML response after authenticating the user and `redirectUrl` is where the SAML Jackson redirects the user after authentication.
+
+Create a new custom Provider `JacksonProvider` that relies on the `@boxyhq/saml-jackson`. The `boot` method initializes the SAML Jackson and returns a singleton.
+
+```js title="providers/JacksonProvider.ts"
+import type { ApplicationContract } from '@ioc:Adonis/Core/Application';
+
+import { options } from '../lib/jackson';
+
+export default class JacksonProvider {
+ constructor(protected app: ApplicationContract) {}
+
+ public async boot() {
+ const jackson = await require('@boxyhq/saml-jackson').default(options);
+
+ this.app.container.singleton('BoxyHQ/Jackson', () => {
+ const { connectionAPIController, oauthController } = jackson;
+
+ return {
+ connectionAPIController,
+ oauthController,
+ };
+ });
+ }
+
+ public register() {
+ // Register your own bindings
+ }
+
+ public async ready() {
+ // App is ready
+ }
+
+ public async shutdown() {
+ // Cleanup, since app is going down
+ }
+}
+```
+
+Create a declaration file if you are working with TypeScript.
+
+```js title="contracts/jackson.ts"
+declare module '@ioc:BoxyHQ/Jackson' {
+ import { type IOAuthController, type IConnectionAPIController } from '@boxyhq/saml-jackson';
+
+ export const connectionAPIController: IConnectionAPIController;
+ export const oauthController: IOAuthController;
+}
+```
+
+### Make Authentication Request
+
+Let's add a route to begin the authenticate flow; this route initiates the SAML SSO flow by redirecting the users to their configured Identity Provider.
+
+```js title="start/routes.ts"
+import LoginController from 'App/Controllers/Http/LoginController';
+
+Route.post('/login', async (ctx) => {
+ return new LoginController().store(ctx);
+});
+```
+
+The `store` method of `LoginController` takes care of redirecting the user to the Identity Provider.
+
+
+
+
+```js title="app/Controllers/Http/LoginController.ts"
+import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
+
+import { oauthController } from '@ioc:BoxyHQ/Jackson';
+import { type OAuthReq } from '@boxyhq/saml-jackson';
+import { redirectUrl } from '../../../lib/jackson';
+
+export default class LoginController {
+ public async store({ request, response }: HttpContextContract) {
+ const tenant = 'boxyhq.com'; // The user's tenant
+ const product = 'saml-demo.boxyhq.com'; // Your app or product name
+ const state = 'a-random-state-value'; // You can use the `state` parameter to restore application state between redirects.
+
+ const { redirect_url } = await oauthController.authorize({
+ tenant,
+ product,
+ state,
+ redirect_uri: redirectUrl,
+ } as OAuthReq);
+
+ return response.redirect(redirect_url as string);
+ }
+}
+```
+
+
+
+
+
+```js title="app/Controllers/Http/LoginController.ts"
+import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
+
+import { oauthController } from '@ioc:BoxyHQ/Jackson';
+import { type OAuthReq } from '@boxyhq/saml-jackson';
+import { redirectUrl } from '../../../lib/jackson';
+
+export default class LoginController {
+ public async store({ request, response }: HttpContextContract) {
+ const clientId = '123456789'; // The tenant's client ID
+
+ const { redirect_url } = await oauthController.authorize({
+ client_id: clientId,
+ state: 'a-random-state-value', // You can use the `state` parameter to restore application state between redirects.
+ redirect_uri: redirectUrl,
+ } as OAuthReq);
+
+ return response.redirect(redirect_url as string);
+ }
+}
+```
+
+
+
+
+### Receives SAML Response
+
+After successful authentication, Identity Provider POST the SAML response to the Assertion Consumer Service (ACS) URL.
+
+Let's add a route to handle the SAML response. Ensure the route matches the value of the `samlPath` you configured while initializing the SAML Jackson library and should be able to receives POST request.
+
+```js title="start/routes.ts"
+import SSOController from 'App/Controllers/Http/SSOController';
+
+Route.post('/sso/acs', async (ctx) => {
+ return new SSOController().acs(ctx);
+});
+```
+
+The `acs` method of `SSOController` takes care of handling the SAML response from the Identity Provider and redirecting the users to the `redirectUrl`.
+
+```js title="app/Controllers/Http/SSOController.ts"
+import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
+
+import { oauthController } from '@ioc:BoxyHQ/Jackson';
+
+export default class SSOController {
+ public async acs({ request, response }: HttpContextContract) {
+ const relayState = request.input('RelayState');
+ const samlResponse = request.input('SAMLResponse');
+
+ const { redirect_url } = await oauthController.samlResponse({
+ RelayState: relayState,
+ SAMLResponse: samlResponse,
+ });
+
+ return response.redirect(redirect_url as string);
+ }
+}
+```
+
+### Request Access Token
+
+Let's add another route for receiving the callback after the authentication. Ensure the route matches the value of the `redirectUrl` you configured previously.
+
+```js title="apps/adonisjs/start/routes.ts"
+import SSOController from 'App/Controllers/Http/SSOController';
+
+Route.get('/sso/callback', async (ctx) => {
+ return new SSOController().callback(ctx);
+});
+```
+
+The application requests an `access_token` by passing the authorization `code` along with authentication details, including the `client_id`, `client_secret`, and `redirect_uri`.
+
+The `callback` method of `SSOController` take care of this.
+
+
+
+
+```js title="app/Controllers/Http/SSOController.ts"
+import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
+
+import { oauthController } from '@ioc:BoxyHQ/Jackson';
+import { type OAuthTokenReqWithCredentials } from '@boxyhq/saml-jackson';
+import { redirectUrl } from '../../../lib/jackson';
+
+export default class SSOController {
+ public async callback({ request, response, auth }: HttpContextContract) {
+ const { code, state } = request.qs();
+
+ const tenant = 'boxyhq.com'; // The user's tenant
+ const product = 'saml-demo.boxyhq.com'; // Your app or product name
+
+ const clientId = `tenant=${tenant}&product=${product}`;
+ const clientSecret = 'dummy';
+
+ // Exchange the `code` for `access_token`
+ const { access_token } = await oauthController.token({
+ code,
+ client_id: clientId,
+ client_secret: clientSecret,
+ redirect_uri: redirectUrl,
+ } as OAuthTokenReqWithCredentials);
+ }
+}
+```
+
+
+
+
+
+```js title="app/Controllers/Http/SSOController.ts"
+import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
+
+import { oauthController } from '@ioc:BoxyHQ/Jackson';
+import { type OAuthTokenReqWithCredentials } from '@boxyhq/saml-jackson';
+import { redirectUrl } from '../../../lib/jackson';
+
+export default class SSOController {
+ public async callback({ request, response, auth }: HttpContextContract) {
+ const { code, state } = request.qs();
+
+ const clientId = '123456789'; // The tenant's client ID
+ const clientSecret = 'dUdSOmGoxr'; // The tenant's client Secret
+
+ // Exchange the `code` for `access_token`
+ const { access_token } = await oauthController.token({
+ code,
+ client_id: clientId,
+ client_secret: clientSecret,
+ redirect_uri: redirectUrl,
+ } as OAuthTokenReqWithCredentials);
+ }
+}
+```
+
+
+
+
+### Fetch User Profile
+
+Once the `access_token` has been fetched, you can use it to retrieve the user profile from the Identity Provider. The `userInfo` method returns a response containing the user profile if the authorization is valid.
+
+```js
+const user = await oauthController.userInfo(access_token);
+```
+
+The entire response will look something like this:
+
+```json
+{
+ "id":"",
+ "email": "jackson@coolstartup.com",
+ "firstName": "SAML",
+ "lastName": "Jackson",
+ "requested": {
+ "tenant": "",
+ "product": "",
+ "client_id": "",
+ "state": ""
+ },
+ "raw": {
+ ...
+ }
+}
+```
+
+### Authenticate User
+
+Once the user has been retrieved from the Identity Provider, you may determine if the user exists in your application and authenticate the user. If the user does not exist in your application, you will typically create a new record in your database to represent the user.
diff --git a/guides/jackson/frameworks/django.md b/guides/jackson/frameworks/django.md
new file mode 100644
index 0000000..95ba23d
--- /dev/null
+++ b/guides/jackson/frameworks/django.md
@@ -0,0 +1,32 @@
+---
+title: Add SAML SSO to Django App with BoxyHQ
+description: Add SAML SSO to Django App with BoxyHQ
+sidebar_label: Django
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to Django App
+
+This guide assumes that you have a Django app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/jackson-examples/tree/main/apps/adonisjs) to see the source code for the Django SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure SAML Single Sign-On
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focuses more on the SSO authentication side.
+
+[WIP - Coming Soon]
diff --git a/guides/jackson/frameworks/express.md b/guides/jackson/frameworks/express.md
new file mode 100644
index 0000000..a4a9ee8
--- /dev/null
+++ b/guides/jackson/frameworks/express.md
@@ -0,0 +1,239 @@
+---
+title: Add SAML SSO to Express.js App with BoxyHQ
+description: Add SAML SSO to Express.js App with BoxyHQ
+sidebar_label: Express.js
+image: https://1755-103-146-175-95.in.ngrok.io/img/sso/og-image.png
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to Express.js App
+
+This guide assumes that you have a Express.js app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/jackson-examples/tree/main/apps/express) to see the source code for the Express.js SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure SAML Single Sign-On
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focuses more on the SSO authentication side.
+
+### Install SAML Jackson
+
+To get started with SAML Jackson, use the Node Package Manager to add the package to your project's dependencies.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+### Setup SAML Jackson
+
+Setup the SAML Jackson to work with Express.js app.
+
+```js title="jackson.js"
+const baseUrl = 'https://your-app.com';
+const samlAudience = 'https://saml.boxyhq.com';
+const product = 'saml-demo.boxyhq.com';
+const samlPath = '/sso/acs';
+const redirectUrl = `${baseUrl}/sso/callback`;
+
+// SAML Jackson options
+const options = {
+ externalUrl: baseUrl,
+ samlAudience,
+ samlPath,
+ db: {
+ engine: 'sql',
+ type: 'postgres',
+ url: 'postgres://postgres:postgres@localhost:5432/postgres',
+ },
+};
+
+module.exports = {
+ baseUrl,
+ product,
+ samlPath,
+ redirectUrl,
+ samlAudience,
+ options,
+};
+```
+
+`samlPath` is where the identity provider POST the SAML response after authenticating the user and `redirectUrl` is where the SAML Jackson redirects the user after authentication.
+
+Initialize the SAML Jackson as below.
+
+Please note that the initialization of `@boxyhq/saml-jackson` is async. Therefore, you cannot run it at the top level. Instead, run this in a function where you initialize the express server.
+
+```js title="routes/index.js"
+const { options, product, redirectUrl } = require('../jackson');
+
+let apiController;
+let oauthController;
+
+(async function init() {
+ const jackson = await require('@boxyhq/saml-jackson').controllers(options);
+
+ apiController = jackson.connectionAPIController;
+ oauthController = jackson.oauthController;
+})();
+```
+
+### Make Authentication Request
+
+Let's add a route to begin the authenticate flow; this route initiates the SAML SSO flow by redirecting the users to their configured Identity Provider.
+
+
+
+
+```js title="/routes/index.js"
+router.post('/sso', async (req, res, next) => {
+ const tenant = 'boxyhq.com'; // The user's tenant
+
+ const { redirect_url } = await oauthController.authorize({
+ tenant,
+ product,
+ state: 'a-random-state-value',
+ redirect_uri: redirectUrl,
+ });
+
+ res.redirect(redirect_url);
+});
+```
+
+
+
+
+
+```js title="/routes/index.js"
+router.post('/sso', async (req, res, next) => {
+ const clientId = '123456789'; // The tenant's client ID
+
+ const { redirect_url } = await oauthController.authorize({
+ client_id: clientId,
+ state: 'a-random-state-value', // You can use the `state` parameter to restore application state between redirects.
+ redirect_uri: redirectUrl,
+ });
+
+ res.redirect(redirect_url);
+});
+```
+
+
+
+
+### Receives SAML Response
+
+After successful authentication, Identity Provider POST the SAML response to the Assertion Consumer Service (ACS) URL.
+
+Let's add a route to handle the SAML response. Ensure the route matches the value of the `samlPath` you configured while initializing the SAML Jackson library and should be able to receives POST request.
+
+```js title="/routes/index.js"
+router.post('/sso/acs', async (req, res, next) => {
+ const { RelayState, SAMLResponse } = req.body;
+
+ const { redirect_url } = await oauthController.samlResponse({
+ RelayState,
+ SAMLResponse,
+ });
+
+ res.redirect(redirect_url);
+});
+```
+
+### Request Access Token
+
+Let's add another route for receiving the callback after the authentication. Ensure the route matches the value of the `redirectUrl` you configured previously.
+
+The application requests an `access_token` by passing the authorization `code` along with authentication details, including the `client_id`, `client_secret`, and `redirect_uri`.
+
+
+
+
+```js title="/routes/index.js"
+router.get('/sso/callback', async (req, res, next) => {
+ const { code, state } = req.query;
+
+ const tenant = 'boxyhq.com'; // The user's tenant
+ const product = 'saml-demo.boxyhq.com'; // Your app or product name
+
+ const clientId = `tenant=${tenant}&product=${product}`;
+ const clientSecret = 'dummy';
+
+ // Exchange the `code` for `access_token`
+ const { access_token } = await oauthController.token({
+ code,
+ client_id: clientId,
+ client_secret: clientSecret,
+ redirect_uri: redirectUrl,
+ });
+});
+```
+
+
+
+
+
+```js title="/routes/index.js"
+router.get('/sso/callback', async (req, res, next) => {
+ const { code, state } = req.query;
+
+ const clientId = '123456789'; // The tenant's client ID
+ const clientSecret = 'dUdSOmGoxr'; // The tenant's client Secret
+
+ // Exchange the `code` for `access_token`
+ const { access_token } = await oauthController.token({
+ code,
+ client_id: clientId,
+ client_secret: clientSecret,
+ redirect_uri: redirectUrl,
+ });
+});
+```
+
+
+
+
+### Fetch User Profile
+
+Once the `access_token` has been fetched, you can use it to retrieve the user profile from the Identity Provider. The `userInfo` method returns a response containing the user profile if the authorization is valid.
+
+```js
+const user = await oauthController.userInfo(access_token);
+```
+
+The entire response will look something like this:
+
+```json
+{
+ "id":"",
+ "email": "jackson@coolstartup.com",
+ "firstName": "SAML",
+ "lastName": "Jackson",
+ "requested": {
+ "tenant": "",
+ "product": "",
+ "client_id": "",
+ "state": ""
+ },
+ "raw": {
+ ...
+ }
+}
+```
+
+### Authenticate User
+
+Once the user has been retrieved from the Identity Provider, you may determine if the user exists in your application and authenticate the user. If the user does not exist in your application, you will typically create a new record in your database to represent the user.
diff --git a/guides/jackson/frameworks/laravel.md b/guides/jackson/frameworks/laravel.md
new file mode 100644
index 0000000..71626c6
--- /dev/null
+++ b/guides/jackson/frameworks/laravel.md
@@ -0,0 +1,238 @@
+---
+title: Add SAML SSO to Laravel App with BoxyHQ
+description: Add SAML SSO to Laravel App with BoxyHQ
+sidebar_label: Laravel
+---
+
+# Add SAML SSO to Laravel App
+
+This guide assumes that you have a Laravel app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/php-examples/tree/main/laravel-enterprise-sso) to see the source code for the Laravel SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure SAML Single Sign-On
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focus more on the SSO authentication side.
+
+### Install SAML Jackson
+
+The first step is to deploy the SAML Jackson service. Follow the [deployment docs](/docs/jackson/deploy/service) to install and configure the SAML Jackson.
+
+### Setup SAML Jackson
+
+We'll use the Laravel Socialite for the integration. Socialite provides an expressive, fluent interface to OAuth authentication with external authentication providers.
+
+Create a new config file to hold the SAML Jackson configuration values.
+
+```php title="config/jackson.php"
+ 'http://localhost:5225', // SAML Jackson service URL
+ 'product' => 'your-app-name',
+ 'client_id' => 'dummy', // Keep this as `dummy`, we'll pass the tenant & product as dynamic params
+ 'client_secret' => 'dummy', // Keep this as `dummy`, we'll pass the tenant & product as dynamic params
+ 'redirect' => env('APP_URL') . '/sso/callback'
+];
+```
+
+Set `host` to URL of running SAML Jackson service.
+
+Let's add a custom provider to the Laravel Socialite for the SAML Jackson.
+
+```php title="app/BoxyHQ/JacksonProvider.php"
+host = rtrim($host, '/');
+ }
+
+ return $this;
+ }
+
+ protected function getAuthUrl($state)
+ {
+ return $this->buildAuthUrlFromBase($this->host . '/api/oauth/authorize', $state);
+ }
+
+ protected function getTokenUrl()
+ {
+ return $this->host . '/api/oauth/token';
+ }
+
+ protected function getUserByToken($token)
+ {
+ $response = $this->getHttpClient()->get($this->host . '/api/oauth/userinfo', [
+ RequestOptions::QUERY => ['access_token' => $token],
+ ]);
+
+ return json_decode($response->getBody(), true);
+ }
+
+ protected function mapUserToObject(array $user)
+ {
+ return (new User)->setRaw($user)->map([
+ 'id' => $user['id'],
+ 'email' => $user['email'],
+ 'name' => $user['firstName'].' '.$user['lastName'],
+ 'first_name' => $user['firstName'],
+ 'last_name' => $user['lastName'],
+ 'requested' => $user['requested'],
+ 'nickname' => null,
+ 'avatar' => null,
+ ]);
+ }
+}
+```
+
+Bootstrap the `JacksonProvider` in the `AppServiceProvider`.
+
+```php title="app/Providers/AppServiceProvider.php"
+app->make('Laravel\Socialite\Contracts\Factory');
+
+ $socialite->extend(
+ 'jackson',
+ function ($app) use ($socialite) {
+ $config = config('jackson');
+
+ return $socialite->buildProvider(JacksonProvider::class, $config)
+ ->setHost($config['host'] ?? null);
+ }
+ );
+ }
+}
+```
+
+### Make Authentication Request
+
+Let's add a route to begin the authenticate flow; this route initiates the SAML SSO flow by redirecting the users to their configured Identity Provider.
+
+```php title="routes/web.php"
+input('tenant');
+
+ return Socialite::driver('jackson')
+ ->with(['tenant' => $tenant, 'product' => $jackson['product']])
+ ->redirect();
+ }
+}
+```
+
+### Fetch User Profile
+
+Let's add another route for receiving the callback after the authentication. Ensure the route matches the value of the `redirect` you configured previously.
+
+```php title="routes/web.php"
+user();
+
+ // $user has all the properties you need. Do your business logic here.
+ }
+}
+```
+
+### Authenticate User
+
+Once the user has been retrieved from the Identity Provider, you may determine if the user exists in your application and authenticate the user. If the user does not exist in your application, you will typically create a new record in your database to represent the user.
diff --git a/guides/jackson/frameworks/nextjs.md b/guides/jackson/frameworks/nextjs.md
new file mode 100644
index 0000000..5129768
--- /dev/null
+++ b/guides/jackson/frameworks/nextjs.md
@@ -0,0 +1,305 @@
+---
+title: Add SAML SSO to Next.js App with BoxyHQ
+description: Add SAML SSO to Next.js App with BoxyHQ
+sidebar_label: Next.js
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to Next.js App
+
+This guide assumes that you have a Next.js app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/saas-starter-kit) to see the source code for the Next.js SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure SAML Single Sign-On
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focus more on the SSO authentication side.
+
+### Install SAML Jackson
+
+To get started with SAML Jackson, use the Node Package Manager to add the package to your project's dependencies.
+
+```bash
+npm i --save @boxyhq/saml-jackson
+```
+
+### Setup SAML Jackson
+
+Setup the SAML Jackson to work with Next.js app.
+
+```bash title=".env"
+NEXTAUTH_URL=https://your-app.com
+NEXTAUTH_SECRET= #A random string is used to hash tokens, sign/encrypt cookies and generate cryptographic keys.
+```
+
+```js title="lib/jackson.ts"
+import jackson, {
+ type IOAuthController,
+ type JacksonOption,
+} from "@boxyhq/saml-jackson";
+
+const samlAudience = "https://saml.boxyhq.com";
+const samlPath = "/api/auth/saml/acs";
+
+const opts: JacksonOption = {
+ externalUrl: `${process.env.NEXTAUTH_URL}`,
+ samlAudience,
+ samlPath,
+ db: {
+ engine: "sql",
+ type: "postgres",
+ url: "postgres://postgres:postgres@localhost:5432/postgres",
+ },
+};
+
+let oauthController: IOAuthController;
+
+const g = global as any;
+
+export default async function init() {
+ if (!g.oauthController) {
+ const ret = await jackson(opts);
+
+ oauthController = ret.oauthController;
+ g.oauthController = oauthController;
+ } else {
+ oauthController = g.oauthController;
+ }
+
+ return {
+ oauthController,
+ };
+}
+```
+
+`samlPath` is where the identity provider POST the SAML response after authenticating the user.
+
+We'll use [NextAuth.js](https://next-auth.js.org/) for the authentication. NextAuth is a complete open-source authentication solution for Next.js applications.
+
+```bash
+npm install next-auth
+```
+
+Let's add a custom provider called `saml-jackson` to the NextAuth.
+
+```js title="pages/api/auth/[...nextauth].ts"
+import NextAuth, { type NextAuthOptions } from 'next-auth';
+
+export const authOptions: NextAuthOptions = {
+ providers: [
+ {
+ id: 'saml-jackson',
+ name: 'BoxyHQ',
+ type: 'oauth',
+ checks: ['pkce', 'state'],
+ authorization: {
+ url: `${process.env.NEXTAUTH_URL}/api/auth/saml/authorize`,
+ params: {
+ scope: '',
+ response_type: 'code',
+ provider: 'saml',
+ },
+ },
+ token: {
+ url: `${process.env.NEXTAUTH_URL}/api/auth/saml/token`,
+ params: { grant_type: 'authorization_code' },
+ },
+ userinfo: `${process.env.NEXTAUTH_URL}/api/auth/saml/userinfo`,
+ profile: (profile) => {
+ return {
+ id: profile.id || '',
+ firstName: profile.firstName || '',
+ lastName: profile.lastName || '',
+ email: profile.email || '',
+ name: `${profile.firstName || ''} ${profile.lastName || ''}`.trim(),
+ email_verified: true,
+ };
+ },
+ options: {
+ clientId: 'dummy',
+ clientSecret: 'dummy',
+ },
+ },
+ ],
+ session: {
+ strategy: 'jwt',
+ },
+};
+
+export default NextAuth(authOptions);
+```
+
+### Make Authentication Request
+
+Let's add a route to begin the authenticate flow; this route initiates the SAML SSO flow by redirecting the users to their configured Identity Provider.
+
+```js title="pages/api/auth/saml/authorize.ts"
+import type { NextApiRequest, NextApiResponse } from "next";
+import type { OAuthReq } from "@boxyhq/saml-jackson";
+
+import jackson from "../../../../lib/jackson";
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ const { oauthController } = await jackson();
+
+ const { redirect_url } = await oauthController.authorize(
+ req.query as unknown as OAuthReq
+ );
+
+ return res.redirect(302, redirect_url as string);
+}
+```
+
+### Receives SAML Response
+
+After successful authentication, Identity Provider POST the SAML response to the Assertion Consumer Service (ACS) URL.
+
+Let's add a route to handle the SAML response. Ensure the route matches the value of the `samlPath` you configured while initializing the SAML Jackson library and should be able to receives POST request.
+
+```js title="pages/api/auth/saml/acs.ts"
+import type { NextApiRequest, NextApiResponse } from "next";
+
+import jackson from "../../../../lib/jackson";
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ const { oauthController } = await jackson();
+
+ const { RelayState, SAMLResponse } = req.body;
+
+ const { redirect_url } = await oauthController.samlResponse({
+ RelayState,
+ SAMLResponse,
+ });
+
+ return res.redirect(302, redirect_url as string);
+}
+```
+
+### Request Access Token
+
+Let's add another route for receiving the callback after the authentication.
+
+The NextAuth requests an `access_token` by passing the authorization `code` along with authentication details, including the `grant_type`, `redirect_uri`, and `code_verifier`.
+
+```js title="pages/api/auth/saml/token.ts"
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+import jackson from '../../../../lib/jackson';
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ const { oauthController } = await jackson();
+
+ const response = await oauthController.token(req.body);
+
+ return res.json(response);
+}
+```
+
+### Fetch User Profile
+
+Once the `access_token` has been fetched, NextAuth can use it to retrieve the user profile from the Identity Provider. The `userInfo` method returns a response containing the user profile if the authorization is valid.
+
+```js title="pages/api/auth/saml/userinfo.ts"
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+import jackson from '../../../../lib/jackson';
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ const { oauthController } = await jackson();
+
+ const authHeader = req.headers['authorization'];
+
+ if (!authHeader) {
+ throw new Error('Unauthorized');
+ }
+
+ const token = authHeader.split(' ')[1];
+
+ const user = await oauthController.userInfo(token);
+
+ return res.json(user);
+}
+```
+
+The entire response will look something like this:
+
+```json
+{
+ "id":"",
+ "email": "jackson@coolstartup.com",
+ "firstName": "SAML",
+ "lastName": "Jackson",
+ "requested": {
+ "tenant": "",
+ "product": "",
+ "client_id": "",
+ "state": ""
+ },
+ "raw": {
+ ...
+ }
+}
+```
+
+### Authenticate User
+
+Once the user has been retrieved from the Identity Provider, you may determine if the user exists in your application and authenticate the user. If the user does not exist in your application, you will typically create a new record in your database to represent the user.
+
+### Starts OAuth sign-in flow
+
+You can use NextAuth's `signIn` method to initiate the authentication with `saml-jackson` provider.
+
+You can pass the `tenant` and `product` as additional parameters to the `/api/auth/saml/authorize` endpoint through the third argument of `signIn()`.
+
+```js title="pages/login.tsx"
+import type { NextPage } from 'next';
+import { useSession, signIn } from 'next-auth/react';
+
+const Login: NextPage = () => {
+ const { data: session, status } = useSession();
+
+ if (status === 'loading') {
+ return <>Loading...;
+ }
+
+ if (status === 'authenticated') {
+ return <>Authenticated;
+ }
+
+ // Starts OAuth sign-in flow
+ signIn('saml-jackson', undefined, {
+ tenant: 'boxyhq.com',
+ product: 'saml-demo.boxyhq.com',
+ });
+
+ return <>Unauthenticated;
+};
+
+export default Login;
+```
diff --git a/guides/jackson/frameworks/rails.md b/guides/jackson/frameworks/rails.md
new file mode 100644
index 0000000..e7c6412
--- /dev/null
+++ b/guides/jackson/frameworks/rails.md
@@ -0,0 +1,542 @@
+---
+title: Add SAML SSO to Ruby on Rails App with BoxyHQ
+description: Add SAML SSO to Ruby on Rails App with BoxyHQ
+sidebar_label: Ruby on Rails
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to Ruby on Rails App
+
+This guide assumes that you have a Ruby on Rails app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+Visit the [GitHub repository](https://github.com/boxyhq/ruby-examples/tree/main/rails-enterprise-sso) to see the source code for the Ruby on Rails SAML SSO integration.
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure Enterprise SSO on Rails
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focus more on the SSO authentication side.
+
+### Deploy SAML Jackson
+
+The first step is to deploy the SAML Jackson service. Follow the [deployment docs](/docs/jackson/deploy/service) to install and configure the SAML Jackson.
+
+### Setup SAML Jackson Integration
+
+We will dive into Jackson integration with two popular authentication libraries:
+
+- [Sorcery](#with-sorcery)
+- [OmniAuth](#with-omniauth)
+
+#### With Sorcery
+
+First, we need to install and configure [sorcery](https://github.com/Sorcery/sorcery).
+
+##### Install Dependencies
+
+Install the `sorcery` gem using
+
+```shell
+bundle add sorcery
+```
+
+##### Configure the database
+
+```shell title="Generate migration scripts for sorcery"
+ bin/rails g sorcery:install external --only-submodules
+```
+
+```shell title="Run migration scripts"
+ bin/rake db:migrate
+```
+
+```shell title="Generate the Authentication model"
+ bin/rails generate model Authentication --migration=false
+```
+
+```shell title="Modify the user schema"
+ # remove the unused columns from the user table, we won't need the password field as the login is external
+ bin/rails generate migration RemoveColumnsFromUsers crypted_password:string salt:string
+ # add the new columns
+ bin/rails generate migration AddColumnsToUsers firstName:string lastName:string uid:string
+ # run the migrations
+ bin/rake db:migrate
+```
+
+##### Add a custom provider for Jackson
+
+Add a custom sorcery provider for Jackson. We will name it `Boxyhqsso`.
+
+We rely on the `Protocols::Oauth2` mixin from the sorcery package. In a nutshell, here we are wiring up the OAuth 2.0 flow with Jackson. Jackson will redirect to the configured IdP connection based on the tenant/product.
+
+:::info
+By including the file in the `app/lib` folder, rails will autoload the provider class.
+:::
+
+```ruby title="app/lib/sorcery/providers/boxyhqsso.rb"
+ module Sorcery
+ module Providers
+ # This class adds support for OAuth2.0 SSO flow with Jackson service.
+ #
+ # config.boxyhqsso.site =
+ # config.boxyhqsso.key =
+ # config.boxyhqsso.secret =
+ # ...
+ #
+ class Boxyhqsso < Base
+ include Protocols::Oauth2
+
+ attr_reader :parse
+ attr_accessor :auth_url, :token_url, :user_info_path
+
+ def initialize
+ super
+
+ @site = ENV['JACKSON_URL']
+ @auth_url = '/api/oauth/authorize'
+ @token_url = '/api/oauth/token'
+ @user_info_path = '/api/oauth/userinfo'
+ @parse = :json
+ # @state = SecureRandom.hex(16)
+ end
+
+ def get_user_hash(access_token)
+ response = access_token.get(user_info_path)
+ body = JSON.parse(response.body)
+ auth_hash(access_token).tap do |h|
+ h[:user_info] = body
+ h[:uid] = body['id']
+ end
+ end
+
+ # calculates and returns the url to which the user should be redirected,
+ # to get authenticated at the external provider's site.
+ def login_url(params, _session)
+ add_param(authorize_url(authorize_url: auth_url),
+ [
+ { name: 'tenant', value: params[:tenant] },
+ { name: 'product', value: params[:product] }
+ ])
+ end
+
+ # tries to login the user from access token
+ def process_callback(params, _session)
+ args = {}.tap do |a|
+ a[:code] = params[:code] if params[:code]
+ end
+ get_access_token(args, token_url: token_url, token_method: :post, auth_scheme: :request_body)
+ end
+
+ def add_param(url, query_params)
+ uri = URI(url)
+ qp = URI.decode_www_form(uri.query || [])
+ query_params.each do |param|
+ qp << [param[:name], param[:value]]
+ end
+ uri.query = URI.encode_www_form(qp)
+ uri.to_s
+ end
+ end
+ end
+ end
+
+```
+
+##### Configure the custom sorcery provider
+
+Add an initializer file to configure the sorcery module. Here we tell sorcery to load the `:external` submodule and also add `boxyhqsso` custom provider from the previous step to the `external_providers` list. Also, see the inline comments for `boxyhqsso` provider settings.
+
+```ruby title="config/initializers/sorcery.rb"
+ Rails.application.config.sorcery.submodules = [:external]
+
+ # Here you can configure each submodule's features.
+ Rails.application.config.sorcery.configure do |config|
+
+ config.external_providers = [:boxyhqsso]
+
+ # URL of Jackson service
+ config.boxyhqsso.site = ENV['JACKSON_URL']
+ # This translates to client_id in OAuth 2.0. Setting it to dummy will allow us to use `tenant` and product` params instead
+ config.boxyhqsso.key = 'dummy'
+ # The url of the rails app to which Jackson sends back the authorization code
+ config.boxyhqsso.callback_url = 'http://localhost:3366/oauth/callback'
+ # This will be passed to Jackson token endpoint as part of credentials
+ config.boxyhqsso.secret = ENV['CLIENT_SECRET_VERIFIER']
+ # Takes care of converting the user info from the provider (Jackson) into the attributes of the User.
+ config.boxyhqsso.user_info_mapping = { email: 'email', uid: 'id', firstName: 'firstName', lastName: 'lastName'}
+
+ # --- user config ---
+ config.user_config do |user|
+
+ # -- external --
+ user.authentications_class = Authentication
+
+ end
+ # This line must come after the 'user config' block.
+ # Define which model authenticates with sorcery.
+ config.user_class = User
+
+ end
+```
+
+##### Routes and Controllers
+
+Finally, we need to add the routes and controller files that initiate the login flow and handle the callback from the Jackson service.
+
+:::info
+The login flow is initiated by posting to `/sso`
+:::
+
+
+
+
+```ruby title="config/routes.rb"
+ Rails.application.routes.draw do
+ ...
+ # Renders the login page
+ get 'sso', to: 'logins#index', as: :login
+ # Initiates the OAuth 2.0 redirect to Jackson SSO service
+ post 'sso', to: 'sorcery#oauth'
+ # logout the user
+ delete 'logout' => 'logins#destroy', as: :logout
+ # handles the redirect back from Jackson SSO service, exchanges code with access_token and then fetches userprofile. Sorcery creates the user if not present in database, else return the one in the db.
+ resource :oauth do
+ get :callback, to: 'sorcery#callback', on: :collection
+ end
+ # Show profile data
+ get 'profile', to: 'profiles#index', as: :profile
+
+ ...
+ end
+
+```
+
+
+
+
+
+
+The `oauth` action initiates the OAuth 2.0 flow to Jackson SSO service. In the `callback` action, sorcery exchanges the code for access_token and user profile. If a user exists in the database, then the value of `@current_user` is loaded from the database. Else a new user is created in the database and returned.
+
+```ruby title="app/controllers/sorcery_controller.rb"
+ class SorceryController < ApplicationController
+ skip_before_action :require_login, raise: false
+
+ def oauth
+ login_at('boxyhqsso', state: SecureRandom.hex(16))
+ end
+
+ # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+ def callback
+ provider = 'boxyhqsso'
+ if @user = login_from(provider)
+ redirect_to profile_path, notice: "Logged in from #{provider.titleize}!"
+ else
+ begin
+ @user = create_from(provider)
+
+ reset_session # protect from session fixation attack
+ auto_login(@user)
+ redirect_to profile_path, notice: "Logged in from #{provider.titleize}!"
+ rescue
+ redirect_to root_path, alert: "Failed to login from #{provider.titleize}!"
+ end
+ end
+ rescue ::OAuth2::Error => e
+ Rails.logger.error e
+ Rails.logger.error e.code
+ Rails.logger.error e.description
+ Rails.logger.error e.message
+ Rails.logger.error e.backtrace
+ end
+
+ end
+
+```
+
+
+
+
+
+```ruby title="app/controllers/logins_controller.rb"
+ class LoginsController < ApplicationController
+ skip_before_action :require_login
+
+ def index; # render login view
+ end
+
+ def destroy
+ logout
+ redirect_to(root_path, notice: 'Logged out!')
+ end
+
+ end
+
+```
+
+
+
+
+
+```ruby title="app/controllers/profiles_controller.rb"
+ class ProfilesController < ApplicationController
+ def index; end # display profile information
+ end
+
+```
+
+
+
+
+
+
+#### With OmniAuth
+
+:::info
+Unlike sorcery, omniauth does not automatically associate with a User model nor persist the user in the database.
+:::
+
+First, we need to install and configure [omniauth](https://github.com/omniauth/omniauth).
+
+##### Install Dependencies
+
+```shell
+ bin/bundle add omniauth
+ bin/bundle add omniauth-rails_csrf_protection # Used to protect against CSRF vulnerability
+ bin/bundle add omniauth-oauth2 # generic OAuth2 strategy for OmniAuth that we will inherit from
+```
+
+##### Add a custom strategy for Jackson
+
+Add a custom omniauth strategy for Jackson. We will name it `Boxyhqsso`.
+By inheriting from `OmniAuth::Strategies::OAuth2`, we can wire up the OAuth 2.0 flow with Jackson. Jackson will redirect to the configured IdP connection based on the tenant/product.
+
+```ruby title="app/lib/omniauth/strategies/boxyhqsso.rb"
+ module OmniAuth
+ module Strategies
+ class Boxyhqsso < OmniAuth::Strategies::OAuth2
+ # strategy name
+ option :name, "boxyhqsso"
+
+ args %i[
+ client_id
+ client_secret
+ domain
+ ]
+
+ # Setup client URLs used during authentication
+ def client
+ options.client_options.site = domain_url
+ options.client_options.authorize_url = '/api/oauth/authorize'
+ options.client_options.token_url = '/api/oauth/token'
+ options.client_options.userinfo_url = '/api/oauth/userinfo'
+ options.client_options.auth_scheme = :request_body
+ options.token_params = { :redirect_uri => full_host + '/auth/boxyhqsso/callback' }
+ super
+ end
+
+ # These are called after authentication has succeeded. If
+ # possible, you should try to set the UID without making
+ # additional calls (if the user id is returned with the token
+ # or as a URI parameter). This may not be possible with all
+ # providers.
+ uid{ raw_info['id'] }
+
+ # Define the parameters used for the /authorize endpoint
+ def authorize_params
+ params = super
+ %w[connection connection_scope prompt screen_hint login_hint organization invitation ui_locales tenant product].each do |key|
+ params[key] = request.params[key] if request.params.key?(key)
+ end
+
+ # Generate nonce
+ params[:nonce] = SecureRandom.hex
+
+ # Store authorize params in the session for token verification
+ session['authorize_params'] = params.to_hash
+
+ params
+ end
+
+ extra do
+ {
+ 'raw_info' => raw_info
+ }
+ end
+
+ # Declarative override for the request phase of authentication
+ def request_phase
+ if no_client_id?
+ # Do we have a client_id for this Application?
+ fail!(:missing_client_id)
+ elsif no_client_secret?
+ # Do we have a client_secret for this Application?
+ fail!(:missing_client_secret)
+ elsif no_domain?
+ # Do we have a domain for this Application?
+ fail!(:missing_domain)
+ else
+ # All checks pass, run the Oauth2 request_phase method.
+ super
+ end
+ end
+
+ def raw_info
+ userinfo_url = options.client_options.userinfo_url
+ @raw_info ||= access_token.get(userinfo_url).parsed
+ end
+
+ # Check if the options include a client_id
+ def no_client_id?
+ ['', nil].include?(options.client_id)
+ end
+
+ # Check if the options include a client_secret
+ def no_client_secret?
+ ['', nil].include?(options.client_secret)
+ end
+
+ # Check if the options include a domain
+ def no_domain?
+ ['', nil].include?(options.domain)
+ end
+
+ # Normalize a domain to a URL.
+ def domain_url
+ domain_url = URI(options.domain)
+ domain_url = URI("https://#{domain_url}") if domain_url.scheme.nil?
+ domain_url.to_s
+ end
+ end
+ end
+ end
+
+```
+
+##### Configure the custom omniauth provider
+
+Add an initializer file to insert omniauth into the rack middleware pipeline. `OmniAuth::Builder` allows us to load multiple strategies.
+
+```ruby title="config/initializers/omniauth.rb"
+ Rails.application.config.middleware.use OmniAuth::Builder do
+ provider(
+ :boxyhqsso,
+ 'dummy',
+ ENV['CLIENT_SECRET_VERIFIER'],
+ ENV['JACKSON_URL'],
+ callback_path: '/auth/boxyhqsso/callback',
+ authorize_params: {
+ scope: 'openid'
+ }
+ )
+
+ end
+```
+
+##### Routes and Controllers
+
+Finally, we need to add the routes and controller files that initiate the login flow and handle the callback from the Jackson service. We also use a controller `concern` to control access to protected routes such as the profile page.
+
+:::info
+The login flow is initiated by posting to `/auth/boxyhqsso` which is handled by omniauth in the rack middleware pipeline.
+:::
+
+
+
+
+
+```ruby title="config/routes.rb"
+ Rails.application.routes.draw do
+ # Renders the login page
+ get 'sso', to: 'logins#index', as: :login
+ # handles the redirect back from Jackson SSO service, exchanges code with access_token and then fetches userprofile.
+ get 'auth/boxyhqsso/callback', to: 'omniauth#callback'
+ # Show profile data
+ get 'omniauth/profile', to: 'omniauth_profiles#show', as: :omniauth_profile
+ # logout the user
+ delete 'omniauth/logout' => 'omniauth#logout', as: :omniauth_logout
+ end
+```
+
+
+
+
+
+
+
+
+
+After omniauth handles the callback from Jackson SSO service, it sets an authentication hash (`omniauth.auth`) on the rack environment of a request to `/auth/boxyhqsso/callback`. This contains the information about the logged-in user. We then set this value in the session which can then be displayed on the profile page.
+
+```ruby title="app/controllers/omniauth_controller.rb"
+ class OmniauthController < ApplicationController
+ skip_before_action :require_login, raise: false
+
+ def callback
+ user_info = request.env['omniauth.auth']
+ session[:userinfo] = user_info['extra']['raw_info']
+ redirect_to omniauth_profile_path, notice: "Logged in using omniauth!"
+ end
+
+ def logout
+ reset_session
+ redirect_to root_path, notice: "Logged out from Omniauth!"
+ end
+ end
+```
+
+
+
+
+
+Here we set the instance variable `@user` from the session. This can then be referenced in the profile view. Also by using the concern `OmniauthSecured`, we ensure that the profile view is rendered only if a user is logged in, else we redirect to the login page.
+
+```ruby title="app/controllers/omniauth_profiles_controller.rb"
+ class OmniauthProfilesController < ApplicationController
+ skip_before_action :require_login, raise: false
+ include OmniauthSecured
+
+ def show
+ @user = session[:userinfo]
+ end
+ end
+```
+
+
+
+
+
+
+
+
+```ruby title="app/controllers/concerns/omniauth_secured.rb"
+ module OmniauthSecured
+ extend ActiveSupport::Concern
+
+ included do
+ before_action :logged_in_using_omniauth?
+ end
+
+ def logged_in_using_omniauth?
+ redirect_to login_path, notice: "⚠️ Please login using omniauth" unless session[:userinfo].present?
+ end
+ end
+```
+
+
+
+
diff --git a/guides/jackson/frameworks/react.md b/guides/jackson/frameworks/react.md
new file mode 100644
index 0000000..81a067d
--- /dev/null
+++ b/guides/jackson/frameworks/react.md
@@ -0,0 +1,468 @@
+---
+title: Add SAML SSO to React App with BoxyHQ
+description: Add SAML SSO to React App with BoxyHQ
+sidebar_label: React
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to React App
+
+This guide assumes that you have a React app and want to enable SAML Single Sign-On authentication for your enterprise customers. By the end of this guide, you'll have an app that allows you to authenticate the users using SAML Single Sign-On.
+
+If you wish to dive straight into the source, Checkout: https://github.com/boxyhq/jackson-examples/tree/main/apps/react
+
+:::info
+We use an express backend with the React Single Page App. The code for this can be found at https://github.com/boxyhq/jackson-examples/tree/main/apps/express-api
+:::
+
+Integrating SAML SSO into an app involves the following steps.
+
+- Configure SAML Single Sign-On
+- Authenticate with SAML Single Sign-On
+
+## Configure Enterprise SSO on React
+
+This step allows your tenants to configure SAML connections for their users. Read the following guides to understand more about this.
+
+- [UI Best Practices for Configuring SAML Single Sign-On](/guides/jackson/configuring-saml-sso)
+- [SSO Connection API](/docs/jackson/sso-flow/)
+
+## Authenticate with SAML Single Sign-On
+
+Once you add a SAML connection, the app can use this SAML connection to initiate the SSO authentication flow using SAML Jackson. The following sections focus more on the SSO authentication side.
+
+### Deploy SAML Jackson
+
+The first step is to deploy the SAML Jackson service. Follow the [deployment docs](/docs/jackson/deploy/service) to install and configure the SAML Jackson.
+
+### Setup SAML Jackson Integration
+
+We'll use the client library `@bity/oauth2-auth-code-pkce` to implement the authentication process. It is a zero-dependency OAuth 2.0 client implementing the authorization code grant with PKCE for client-side protection.
+
+```bash
+npm i --save @bity/oauth2-auth-code-pkce
+```
+
+Let's configure the `OAuth2AuthCodePKCE` client to use the SAML Jackson service for authentication. Here we use a custom hook so that the `oauthClient` can be used elsewhere in the app.
+
+```ts title="src/hooks/useOAuthClient.ts"
+import { OAuth2AuthCodePKCE } from '@bity/oauth2-auth-code-pkce';
+import { useEffect, useState } from 'react';
+
+const JACKSON_URL = process.env.REACT_APP_JACKSON_URL;
+
+interface OauthClientOptions {
+ redirectUrl: string;
+}
+export default function useOAuthClient({
+ redirectUrl,
+}: OauthClientOptions): OAuth2AuthCodePKCE | null {
+ const [oauthClient, setOauthClient] = useState(
+ null
+ );
+
+ useEffect(() => {
+ setOauthClient(
+ new OAuth2AuthCodePKCE({
+ authorizationUrl: `${JACKSON_URL}/api/oauth/authorize`,
+ tokenUrl: `${JACKSON_URL}/api/oauth/token`,
+ // Setting the clientId dummy here. We pass additional query params for
+ // tenant and product in the authorize request.
+ clientId: 'dummy',
+ redirectUrl,
+ scopes: [],
+ onAccessTokenExpiry(refreshAccessToken) {
+ console.log('Expired! Access token needs to be renewed.');
+ alert(
+ 'We will try to get a new access token via grant code or refresh token.'
+ );
+ return refreshAccessToken();
+ },
+ onInvalidGrant(refreshAuthCodeOrRefreshToken) {
+ console.log(
+ 'Expired! Auth code or refresh token needs to be renewed.'
+ );
+ alert('Redirecting to auth server to obtain a new auth grant code.');
+ //return refreshAuthCodeOrRefreshToken();
+ },
+ })
+ );
+ }, [redirectUrl]);
+
+ return oauthClient;
+}
+```
+
+### Setup global Authentication primitives
+
+#### AuthContext
+
+We need a way to make the logged-in `user` as well as the `signIn`, `signOut` methods accessible globally. These, along with the `setTenant` (method used to select the tenant for the SSO flow) and `authStatus` (boolean which helps us to conditionally render content based on whether the authenticated status is fully known or being loaded) are made available throughout the application by using `AuthContext`.
+
+```tsx title="src/lib/AuthProvider.tsx"
+import React, { useState, useEffect, ReactNode, createContext } from 'react';
+import { useLocation } from 'react-router-dom';
+import useOAuthClient from '../hooks/useOAuthClient';
+import { authenticate, getProfileByJWT } from './backend';
+
+interface ProviderProps {
+ children: ReactNode;
+}
+
+interface AuthContextInterface {
+ setTenant?: React.Dispatch>;
+ authStatus: 'UNKNOWN' | 'FETCHING' | 'LOADED';
+ user: any;
+ signIn: () => void;
+ signOut: (callback: VoidFunction) => void;
+}
+
+// localstorage key to store from url
+const APP_FROM_URL = 'appFromUrl';
+
+export const AuthContext = createContext(null!);
+```
+
+We also create a custom hook that returns a handle to the `AuthContext`.
+
+```ts title="src/hooks/useAuth.ts"
+import { useContext } from 'react';
+import { AuthContext } from '../lib/AuthProvider';
+
+const useAuth = () => {
+ return useContext(AuthContext);
+};
+
+export default useAuth;
+```
+
+#### AuthProvider
+
+We will wire up the flow inside the AuthProvider.
+
+1. Once the app shell is rendered, we run an effect that uses the `authClient` from `useOAuthClient` to conduct the flow. Two scenarios need to be handled here. The first one is the case where we have secured an access_token from the SSO provider (Jackson) in which case we can retrieve the logged-in user profile by passing in the cookie. The second one is the case where the browser gets redirected back to the app, after signing in at IdP. The authorization code in the redirect is exchanged for an access token which is then passed to the app backend to complete the login.
+
+ ```tsx title="src/lib/AuthProvider.tsx"
+ const AuthProvider = ({ children }: ProviderProps) => {
+ const [user, setUser] = useState(null);
+ const [authStatus, setAuthStatus] = useState('UNKNOWN');
+
+ ...
+
+ const redirectUrl = process.env.REACT_APP_APP_URL + from;
+
+ const authClient = useOAuthClient({ redirectUrl });
+
+ useEffect(() => {
+ let didCancel = false;
+
+ const loadUser = async () => {
+ if (!authClient) {
+ return;
+ }
+ setAuthStatus('FETCHING');
+ if (authClient.isAuthorized()) {
+ const { data, error } = await getProfileByJWT();
+ if (!didCancel && !error) {
+ setUser(data);
+ setAuthStatus('LOADED');
+ }
+ } else {
+ try {
+ const hasAuthCode = await authClient?.isReturningFromAuthServer();
+ if (!hasAuthCode) {
+ devLogger('no auth code detected...');
+ } else {
+ const token = !didCancel
+ ? await authClient?.getAccessToken()
+ : null;
+ token && localStorage.removeItem(APP_FROM_URL);
+ // authentication happens at the backend where the above token is used
+ // to retrieve user profile
+ const profile = await authenticate(token?.token?.value);
+ if (!didCancel && profile) {
+ setUser(profile);
+ }
+ }
+ } catch (err) {
+ console.error(err);
+ } finally {
+ setAuthStatus('LOADED');
+ }
+ }
+ };
+
+ loadUser();
+ return () => {
+ didCancel = true;
+ };
+ }, [authClient]);
+
+ ...
+
+ const value = {
+ authStatus,
+ user,
+ };
+
+ return {children} ;
+ };
+
+ export { AuthContext, AuthProvider };
+ ```
+
+2. When someone tries to access protected/private routes they will be redirected to the login page. Before we do this we save the current location they were trying to access in the history state. This logic is encapsulated in the `RequireAuth` wrapper component. Use it to protect routes that require authentication.
+
+ ```tsx title="src/components/RequireAuth.tsx"
+ const RequireAuth = ({ children }: { children: JSX.Element }) => {
+ let { user, authStatus } = useAuth();
+ let location = useLocation();
+
+ if (authStatus !== 'LOADED') {
+ return null;
+ }
+
+ if (!user) {
+ // Redirect them to the /login page, but save the current location they were
+ // trying to go to when they were redirected. This allows us to send them
+ // along to that page after they login, which is a nicer user experience
+ // than dropping them off on the home page.
+ return {children}
+ );
+ ```
+
+### Make Authentication Request
+
+Let's add a page to begin the authenticate flow. This page initiates (by calling `signIn` from the `AuthContext`) the SAML SSO flow by redirecting the users to their configured Identity Provider (via Jackson).
+
+The user will be redirected to the IdP when clicking the "Continue with SAML SSO" button.
+
+```js title="src/pages/Login.tsx"
+import React from 'react';
+import { Navigate, useLocation } from 'react-router-dom';
+import useAuth from '../hooks/useAuth';
+
+const Login = () => {
+ let location = useLocation();
+
+ let from = location.state?.from?.pathname || '/profile';
+
+ const { signIn, setTenant, authStatus, user } = useAuth();
+
+ if (authStatus !== 'LOADED') {
+ return null;
+ }
+
+ if (authStatus === 'LOADED' && user) {
+ return Log in to App
+
+
+
+
+
+
+
+ );
+};
+
+export default Login;
+```
+
+### Fetch User Profile
+
+Once the `accessToken` has been fetched, the React app can use it to retrieve the user profile from the Identity Provider.
+
+Typically you would use your backend service (Eg: Express.js) to call the SAML Jackson API to fetch the user profile using the `accessToken`.
+
+Here are the express.js routes that return the user profile either on login or by parsing the JWT from the client-side cookie.
+
+```js
+app.get('/api/authenticate', async function (req, res, next) {
+ const accessToken = req.query.access_token;
+
+ if (!accessToken) {
+ throw new Error('Access token not found.');
+ }
+
+ const response = await fetch(
+ `${jacksonUrl}/api/oauth/userinfo?access_token=${accessToken}`,
+ {
+ method: 'GET',
+ }
+ );
+
+ const profile = await response.json();
+
+ // Once the user has been retrieved from the Identity Provider,
+ // you may determine if the user exists in your application and authenticate the user.
+ // If the user does not exist in your application, you will typically create a new record in your database to represent the user.
+
+ const token = jsonwebtoken.sign(
+ {
+ id: profile.id,
+ email: profile.email,
+ firstName: profile.firstName,
+ lastName: profile.lastName,
+ },
+ jwtSecret
+ );
+
+ res.cookie('sso-token', token, { httpOnly: true });
+ res.json(profile);
+});
+
+app.get('/api/profile', async function (req, res, next) {
+ const token = req.cookies['sso-token'];
+
+ if (!token) {
+ return res
+ .status(401)
+ .json({ data: null, error: { message: 'Missing JWT' } });
+ }
+
+ // You may fetch the user profile from your database using the user id.
+
+ const payload = jsonwebtoken.verify(token, jwtSecret);
+
+ return res.json({ data: payload, error: null });
+});
+```
+
+The profile will look something like this:
+
+```json
+{
+ "id":"",
+ "email": "jackson@coolstartup.com",
+ "firstName": "SAML",
+ "lastName": "Jackson",
+ "requested": {
+ "tenant": "",
+ "product": "",
+ "client_id": "",
+ "state": ""
+ },
+ "raw": {
+ ...
+ }
+}
+```
+
+In the React app, we call the `getProfileByJWT` if an access_token is already in possession or we call the `authenticate` when returning back from SSO provider with the authorization code.
+
+```ts title="src/lib/backend.ts"
+const apiUrl = process.env.REACT_APP_API_URL;
+
+export const authenticate = async (token: string | undefined) => {
+ if (!token) {
+ throw new Error('Access token not found.');
+ }
+
+ const response = await fetch(
+ `${apiUrl}/api/authenticate?access_token=${token}`,
+ {
+ method: 'GET',
+ credentials: 'include',
+ }
+ );
+ if (response.ok) {
+ return await response.json();
+ }
+ return null;
+};
+
+export const getProfileByJWT = async () => {
+ const response = await fetch(`${apiUrl}/api/profile`, {
+ method: 'GET',
+ credentials: 'include',
+ });
+
+ return await response.json();
+};
+```
+
+## Ready to go
+
+That's it, your react app is ready for Single Sign-On. 🎉
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/frameworks/remix.md b/guides/jackson/frameworks/remix.md
new file mode 100644
index 0000000..ecf0391
--- /dev/null
+++ b/guides/jackson/frameworks/remix.md
@@ -0,0 +1,552 @@
+---
+title: Add SAML SSO to Remix App with BoxyHQ
+description: Add SAML SSO to Remix App with BoxyHQ
+sidebar_label: Remix
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Add SAML SSO to Remix App
+
+Let's look at how to authenticate users in a remix app using Enterprise Single-Sign-On (SSO).
+
+If you wish to dive straight into the source, Checkout: https://github.com/boxyhq/jackson-remix-auth
+
+:::info
+This guide shows how to embed Single Sign-On (SSO) feature using Jackson, and thereby does not require you to host Jackson separately.
+:::
+
+## Getting Started
+
+### Create remix app
+
+```bash
+npx create-remix@latest
+```
+
+You can go with the Remix App Server as the deployment target. Feel free to choose either 'Typescript' or "Javascript". All the code samples in this guide are in typescript.
+
+### Install the dependencies
+
+```bash
+npm i remix-auth @boxyhq/remix-auth-sso
+```
+
+[`remix-auth`](https://github.com/sergiodxa/remix-auth) is a complete open-source authentication solution for Remix applications. [`@boxyhq/remix-auth-sso`](https://github.com/boxyhq/remix-auth-sso) provides a remix-auth strategy to interact with the SSO Service provider.
+
+## Set up remix-auth
+
+First, we need an `Authenticator` instance from `remix-auth`. `Authenticator` exposes the API for login and logout.
+
+### Create sessionStorage for `Authenticator`
+
+app/sessions.server.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/sessions.server.ts
+
+> **NOTE: We will be relying on cookie-based sessions See: [createCookieSessionStorage](https://remix.run/docs/en/v1/api/remix#createcookiesessionstorage) from remix. **
+
+```typescript
+import { createCookieSessionStorage } from 'remix';
+
+const sessionStorage = createCookieSessionStorage({
+ cookie: {
+ name: '__session',
+ httpOnly: true,
+ path: '/',
+ sameSite: 'lax',
+ secrets: process.env.COOKIE_SECRETS!.split(','),
+ secure: process.env.NODE_ENV === 'production',
+ },
+});
+
+const { getSession, commitSession, destroySession } = sessionStorage;
+const JACKSON_ERROR_COOKIE_KEY = 'jackson_error';
+
+export default sessionStorage;
+export { getSession, commitSession, destroySession, JACKSON_ERROR_COOKIE_KEY };
+```
+
+### Create the `Authenticator` instance
+
+app/auth.server.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/auth.server.ts
+
+> **NOTE: We haven't initialised the strategy use yet. That will be done in following sections**
+
+```typescript
+import { Authenticator } from 'remix-auth';
+import {
+ BoxyHQSSOStrategy,
+ type BoxyHQSSOProfile,
+} from '@boxyhq/remix-auth-sso';
+import invariant from 'tiny-invariant';
+import sessionStorage from './sessions.server';
+
+let auth: Authenticator;
+declare global {
+ var __auth: Authenticator | undefined;
+}
+
+function createAuthenticator() {
+ const auth = new Authenticator(sessionStorage);
+
+ // Strategy use for the hosted saml service provider goes here
+
+ // Strategy use for the embedded saml service provider goes here
+
+ return auth;
+}
+
+if (process.env.NODE_ENV === 'production') {
+ auth = createAuthenticator();
+} else {
+ // In development we don't want to recreate the Authenticator for every change
+ if (!global.__auth) {
+ global.__auth = createAuthenticator();
+ }
+ auth = global.__auth;
+}
+
+export { auth };
+```
+
+## Set up Jackson SSO feature
+
+We'll be using SAML Jackson npm to setup some API routes ([resource routes](https://remix.run/docs/en/v1/guides/resource-routes) in remix terminology).
+
+### Install jackson
+
+Install `@boxyhq/saml-jackson` first:
+
+```bash
+npm i @boxyhq/saml-jackson
+```
+
+Before you proceed,set up a [database](../../../docs/jackson/deploy/service#database) for jackson. Refer to [db environment variables](../../../docs/jackson/deploy/env-variables#database-configuration) for the npm library options.
+
+### Setup `JacksonProvider`
+
+app/auth.jackson.server.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/auth.jackson.server.ts
+
+> **NOTE: [clientSecretVerifier](../../../docs/jackson/deploy/env-variables#client_secret_verifier) set below will be matched against client_secret coming from Authenticator **
+
+```typescript
+ const opts = {
+ ...
+ db: {
+ engine: "sql",
+ url: "postgresql://postgres:postgres@localhost:5432/postgres",
+ type: "postgres",
+ },
+ clientSecretVerifier: process.env.CLIENT_SECRET_VERIFIER
+ ...
+ }
+
+ ...
+
+ async function JacksonProvider({
+ appBaseUrl,
+ }: {
+ appBaseUrl: string;
+ }): Promise<{
+ connectionAPIController: IConnectionAPIController;
+ oauthController: IOAuthController;
+ }> {
+ const _opts = { ...opts, externalUrl: appBaseUrl, samlAudience: appBaseUrl };
+ // this is needed because in development we don't want to restart
+ // the server with every change, but we want to make sure we don't
+ // create a new connection to the DB with every change either.
+ if (process.env.NODE_ENV === "production") {
+ const controllers = await jackson(_opts);
+ connectionAPIController = controllers.connectionAPIController;
+ oauthController = controllers.oauthController;
+ } else {
+ if (!global.__connectionAPIController && !global.__oauthController) {
+ const controllers = await jackson(_opts);
+ global.__connectionAPIController = controllers.connectionAPIController;
+ global.__oauthController = controllers.oauthController;
+ }
+ connectionAPIController = global.__connectionAPIController;
+ oauthController = global.__oauthController;
+ }
+
+ return { connectionAPIController, oauthController };
+ }
+
+ ...
+
+```
+
+### Resource routes to handle OAuth 2.0 and SSO Connections
+
+Next, create the api files for [OAuth 2.0 flow](../../../docs/jackson/sso-flow/#3-oauth-20-flow) and [SSO Connection](../../../docs/jackson/sso-flow/#2-sso-connection-api):
+
+```bash
+app/routes $ mkdir api && cd api
+routes/api $ touch oauth.\$slug.ts v1.connections.ts
+```
+
+oauth.$slug.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/api/oauth.%24slug.ts
+
+```typescript
+...
+
+// Handles GET /api/oauth/authorize, GET /api/oauth/userinfo
+export const loader: LoaderFunction = async ({ params, request }) => {
+
+ ... // Some validation logic
+ const operation = params.slug;
+ const url = new URL(request.url);
+
+ const { oauthController } = await JacksonProvider({
+ appBaseUrl: url.origin,
+ });
+
+ // rightmost query param will win in case of multiple ones with same name
+ const queryParams = Object.fromEntries(url.searchParams.entries());
+
+ switch (operation) {
+ case "authorize": {
+ ...
+ try {
+ const { redirect_url, authorize_form } =
+ await oauthController.authorize(
+ queryParams as unknown as OAuthReqBody
+ );
+ ...
+ } catch (err: any) {
+ ... // error handling, redirect to /error page
+ }
+ }
+ case "oidc": {
+ try {
+ const { redirect_url } = await oauthController.oidcAuthzResponse(
+ queryParams as unknown as OIDCAuthzResponsePayload
+ );
+ if (redirect_url) {
+ return redirect(redirect_url, 302);
+ }
+ } catch (err: any) {
+ ... // error handling, redirect to /error page
+ }
+ }
+ case "userinfo": {
+ ... // token validation
+ try {
+ const profile = await oauthController.userInfo(token);
+ return json(profile);
+ } catch (error: any) {
+ ... // error handling
+ }
+ }
+ }
+};
+
+// Handles POST /api/oauth/saml, POST /api/oauth/token
+export const action: ActionFunction = async ({ params, request }) => {
+
+ ... // Some validation logic
+ const operation = params.slug;
+ const url = new URL(request.url);
+
+ const { oauthController } = await JacksonProvider({
+ appBaseUrl: url.origin,
+ });
+ switch (operation) {
+ case "saml": {
+ try {
+ const { redirect_url } = await oauthController.samlResponse(body);
+ return redirect(redirect_url, 302);
+ } catch (err: any) {
+ ... // error handling
+ }
+ }
+ case "token": {
+ try {
+ const tokenRes = await oauthController.token(body);
+ return json(tokenRes);
+ } catch (error: any) {
+ ... // error handling
+ }
+ }
+ }
+};
+```
+
+v1.connections.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/api/v1.connections.ts
+
+```typescript
+ export const loader: LoaderFunction = async ({ request }) => {
+ const url = new URL(request.url);
+ const queryParams = Object.fromEntries(
+ url.searchParams.entries()
+ ) as unknown as { clientID?: string; tenant?: string; product?: string };
+ ...// Validate apiKey
+ const { connectionAPIController } = await JacksonProvider({ appBaseUrl: url.origin });
+
+ try {
+ return json(await connectionAPIController.getConnections(queryParams));
+ } catch (error: any) {
+ ... // error handling
+ }
+ };
+
+ export const action: ActionFunction = async ({ request }) => {
+ const url = new URL(request.url);
+ const contentType = request.headers.get("Content-Type");
+ ... // Validate body,apiKey
+ const { connectionAPIController } = await JacksonProvider({ appBaseUrl: url.origin });
+
+ try {
+ switch (request.method) {
+ case "POST":
+ return json(await connectionAPIController.createSAMLConnection(body));
+ case "PATCH":
+ await connectionAPIController.updateSAMLConnection(body);
+ return new Response(null, { status: 204 });
+ case "DELETE":
+ await connectionAPIController.deleteConnections(body);
+ return new Response(null, { status: 204 });
+ }
+ } catch (error: any) {
+ ... // error handling
+ }
+ };
+```
+
+### Initialise BoxyHQSSOStrategy
+
+Use the strategy with the `Authenticator` as shown below. The `clientID/Secret` values are expected to be set dynamically from the client side. For now set them to the value `dummy`.
+
+Point the `issuer` to the app url.
+
+auth.server.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/auth.server.ts
+
+> **BOXYHQSSO_ISSUER in env is set to point to the app url: http://localhost:3366 or the actual url once hosted. Take a look at [.env.example](https://github.com/boxyhq/jackson-remix-auth/blob/main/.env.example) file **
+
+```typescript
+invariant(process.env.BASE_URL, 'Expected BASE_URL to be set in env');
+invariant(
+ process.env.BOXYHQSSO_ISSUER,
+ 'Expected BOXYHQSSO_ISSUER to be set in env'
+);
+
+const BASE_URL = process.env.BASE_URL;
+const BOXYHQSSO_ISSUER = process.env.BOXYHQSSO_ISSUER;
+// Strategy use for the embedded sso service provider goes here
+auth.use(
+ new BoxyHQSSOStrategy(
+ {
+ issuer: BOXYHQSSO_ISSUER, //same as the APP URL
+ clientID: 'dummy',
+ clientSecret: process.env.CLIENT_SECRET_VERIFIER || 'dummy',
+ callbackURL: new URL('/auth/sso/embed/callback', BASE_URL).toString(),
+ },
+ async ({ profile }) => {
+ return profile;
+ }
+ ),
+ 'boxyhq-sso-embed'
+);
+```
+
+### Routes to handle login and callback from IdP
+
+We need 2 routes:
+
+~> [/auth/sso/embed](https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/auth.sso.embed.tsx) - Action handler for login
+~> [/auth/sso/embed/callback](https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/auth.sso.embed.callback.tsx) - After successful authorization, user is redirected here with the authorization code. The `code` is then exchanged to get the `token` and further the user profile.
+
+Create the following files under `app/routes`:
+
+app/routes/auth.sso.embed.tsx: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/auth.sso.embed.tsx
+
+```tsx
+...
+export const action: ActionFunction = async ({ request }) => {
+ const formData = await request.formData();
+ const email = formData.get("email");
+ const product = formData.get("product");
+
+ ... // Add some validation logic
+
+ // extracting the tenant from email is one way to set it
+ const tenant = email.split("@")[1];
+
+ return await auth.authenticate("boxyhq-sso-embed", request, {
+ successRedirect: "/private",
+ failureRedirect: "/login",
+ context: {
+ clientID: `tenant=${tenant}&product=${product}`,
+ clientSecret: process.env.CLIENT_SECRET_VERIFIER || "dummy",
+ },
+ });
+};
+```
+
+app/routes/auth.sso.embed.callback.tsx: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/auth.sso.embed.callback.tsx
+
+```tsx
+...
+export const loader: LoaderFunction = async ({ request, params }) => {
+ return auth.authenticate("boxyhq-sso-embed", request, {
+ successRedirect: "/private",
+ failureRedirect: "/login",
+ });
+};
+```
+
+## Add an SSO Connection
+
+[Add a SAML SSO connection](../../../docs/jackson/sso-flow/#21-add-connection) for [mocksaml.com](https://mocksaml.com). You can start the app and call the connection API as shown below:
+
+
+Below adds a SAML SSO connection for https://mocksaml.com
+
+curl --location --request POST 'http://localhost:3366/api/v1/connections'
+--header 'Authorization: Api-Key __JACKSON_API_KEY__'
+--header 'Content-Type: application/x-www-form-urlencoded'
+--data-urlencode 'encodedRawMetadata=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjxFbnRpdHlEZXNjcmlwdG9yIHhtbG5zOm1kPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6bWV0YWRhdGEiIGVudGl0eUlEPSJodHRwczovL3NhbWwuZXhhbXBsZS5jb20vZW50aXR5aWQiIHZhbGlkVW50aWw9IjIwMjYtMDYtMjJUMTg6Mzk6NTMuMDAwWiI+CiAgPElEUFNTT0Rlc2NyaXB0b3IgV2FudEF1dGhuUmVxdWVzdHNTaWduZWQ9ImZhbHNlIiBwcm90b2NvbFN1cHBvcnRFbnVtZXJhdGlvbj0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOnByb3RvY29sIj4KICAgIDxLZXlEZXNjcmlwdG9yIHVzZT0ic2lnbmluZyI+CiAgICAgIDxLZXlJbmZvIHhtbG5zOmRzPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwLzA5L3htbGRzaWcjIj4KICAgICAgICA8WDUwOURhdGE+CiAgICAgICAgICA8WDUwOUNlcnRpZmljYXRlPk1JSUM0akNDQWNvQ0NRQzMzd255YlQ1UVpEQU5CZ2txaGtpRzl3MEJBUXNGQURBeU1Rc3dDUVlEVlFRR0V3SlYKU3pFUE1BMEdBMVVFQ2d3R1FtOTRlVWhSTVJJd0VBWURWUVFEREFsTmIyTnJJRk5CVFV3d0lCY05Nakl3TWpJNApNakUwTmpNNFdoZ1BNekF5TVRBM01ERXlNVFEyTXpoYU1ESXhDekFKQmdOVkJBWVRBbFZMTVE4d0RRWURWUVFLCkRBWkNiM2g1U0ZFeEVqQVFCZ05WQkFNTUNVMXZZMnNnVTBGTlREQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQUQKZ2dFUEFEQ0NBUW9DZ2dFQkFMR2ZZZXR0TXNjdDFUNnRWVXdUdWROSkg1UG5iOUdHbmtYaTlady9lNng0NUREMApSdVJPTmJGbEoyVDRSakFFL3VHK0FqWHhYUThvMlNaZmI5K0dnbUNIdVRKRk5nSG9aMW5GVlhDbWIvSGc4SHBkCjR2T0FHWG5kaXhhUmVPaXEzRUg1WHZwTWpNa0ozKzgrOVZZTXpNWk9qa2dRdEFxTzM2ZUFGRmZOS1g3ZFRqM1YKcHdMa3Z6Ni9LRkNxOE9Bd1krQVVpNGVabTVKNTdEMzFHempId2ZqSDlXVGVYME15bmRtbk5CMXFWNzVxUVIzYgoyL1c1c0dIUnYrOUFhcmdnSmtGK3B0VWtYb0x0VkE1MXdjZlltNmhJTHB0cGRlNUZRQzhSV1kxWXJzd0JXQUVaCk5meXJSNEplU3dlRWxOSGc0TlZPczRUd0dqT1B3V0dxelRmZ1RsRUNBd0VBQVRBTkJna3Foa2lHOXcwQkFRc0YKQUFPQ0FRRUFBWVJsWWZsU1hBV29acEZmd05pQ1FWRTVkOXpaMERQek5kV2hBeWJYY1R5TWYwejVtRGY2RldCVwo1R3lvaTl1M0VNRURuekxjSk5rd0pBQWMzOUFwYTRJMi90bWwrSnkyOWRrOGJUeVg2bTkzbmdtQ2dkTGg1WmE0CmtodVUzQU0zTDYzZzdWZXhDdU83a3dramgvK0xxZGNJWHNWR082WERmdTJRT3MxWHBlOXpJekxwd20vUk5ZZVgKVWpiU2o1Y2UvamVrcEF3N3F5VlZMNHhPeWg4QXRVVzFlazN3SXcxTUp2RWdFUHQwZDE2b3NoV0pwb1MxT1Q4TApyLzIyU3ZZRW8zRW1TR2RUVkdnazN4M3MrQTBxV0FxVGN5anI3UTRzL0dLWVJGZm9tR3d6MFRaNEl3MVpOOTlNCm0wZW8yVVNsU1JUVmw3UUhSVHVpdVNUaEhwTEtRUT09CjwvWDUwOUNlcnRpZmljYXRlPgogICAgICAgIDwvWDUwOURhdGE+CiAgICAgIDwvS2V5SW5mbz4KICAgIDwvS2V5RGVzY3JpcHRvcj4KICAgIDxOYW1lSURGb3JtYXQ+dXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6MS4xOm5hbWVpZC1mb3JtYXQ6ZW1haWxBZGRyZXNzPC9OYW1lSURGb3JtYXQ+CiAgICA8U2luZ2xlU2lnbk9uU2VydmljZSBCaW5kaW5nPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YmluZGluZ3M6SFRUUC1SZWRpcmVjdCIgTG9jYXRpb249Imh0dHBzOi8vbW9ja3NhbWwuY29tL2FwaS9zYW1sL3NzbyIvPgogICAgPFNpbmdsZVNpZ25PblNlcnZpY2UgQmluZGluZz0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOmJpbmRpbmdzOkhUVFAtUE9TVCIgTG9jYXRpb249Imh0dHBzOi8vbW9ja3NhbWwuY29tL2FwaS9zYW1sL3NzbyIvPgogIDwvSURQU1NPRGVzY3JpcHRvcj4KPC9FbnRpdHlEZXNjcmlwdG9yPg=='
+--data-urlencode 'defaultRedirectUrl=http://localhost:3366'
+--data-urlencode 'redirectUrl=["http://localhost:3366/*"]'
+--data-urlencode 'tenant=boxyhq.com'
+--data-urlencode 'product=saml-demo.boxyhq.com'
+--data-urlencode 'name=demo-config'
+--data-urlencode 'description=Demo SAML config'
+
+
+
+## App routes
+
+### Login/Logout
+
+For the `Login` page we need a form that can accept email (for deriving tenant) and product. We also change the form action for the `embedded SAML provider` button.
+
+**login.tsx: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/login.tsx **
+
+```tsx
+ export const loader: LoaderFunction = async ({ request }) => {
+ // check if authenticated then redirect to /private
+ await auth.isAuthenticated(request, { successRedirect: "/private" });
+ // return form error data from session
+ }
+
+ export default function Login() {
+ return (
+ ...
+
+ ...
+ )
+```
+
+**logout.ts: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/logout.ts **
+
+```typescript
+export const loader: LoaderFunction = async ({ request }) => {
+ await auth.logout(request, { redirectTo: '/login' });
+};
+```
+
+### Private
+
+This page renders the logged-in user profile.
+
+**private.tsx: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/private.tsx **
+
+```tsx
+export const loader: LoaderFunction = async ({ request }) => {
+ const profile = await auth.isAuthenticated(request, {
+ failureRedirect: '/login',
+ });
+
+ return json({ profile });
+};
+
+export default function Private() {
+ const { profile } = useLoaderData();
+ return (
+ <>
+ Raw profile
+
+ {JSON.stringify(profile, null, 2)}
+
+
+ );
+}
+```
+
+### Error page
+
+For errors occuring in the SAML flow (/api/oauth/authorize and /api/oauth/saml), the user get's [redirected](https://github.com/boxyhq/jackson-remix-auth/blob/e75cb4a9c340b088749ec63d6932f2f4b206a07d/app/routes/api/oauth.%24slug.ts#L63) to an error page.
+
+Create one at `/error`:
+
+**error.tsx: https://github.com/boxyhq/jackson-remix-auth/blob/main/app/routes/error.tsx **
+
+```tsx
+export const loader: LoaderFunction = async ({ request }) => {
+ const session = await getSession(request.headers.get('Cookie'));
+ const { statusCode, message } = session.get(JACKSON_ERROR_COOKIE_KEY) || {
+ statusCode: null,
+ message: '',
+ };
+ return json({ statusCode, message });
+};
+
+export default function Error() {
+ const { statusCode, message } = useLoaderData();
+
+ let statusText = '';
+ if (typeof statusCode === 'number') {
+ if (statusCode >= 400 && statusCode <= 499) {
+ statusText = 'client-side error';
+ }
+ if (statusCode >= 500 && statusCode <= 599) {
+ statusText = 'server error';
+ }
+ }
+
+ if (statusCode === null) {
+ return null;
+ }
+
+ return (
+
+
+
+ {statusCode}
+ {statusText}
+ SAML error:
+ {message}
+
+
+ );
+}
+```
+
+## Ready to go
+
+That's it, your remix app is ready for Single Sign-On. 🎉
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/integrations/auth0.md b/guides/jackson/integrations/auth0.md
new file mode 100644
index 0000000..066a280
--- /dev/null
+++ b/guides/jackson/integrations/auth0.md
@@ -0,0 +1,16 @@
+---
+title: BoxyHQ SAML as Auth0 Social provider
+sidebar_label: Auth0
+---
+
+# Auth0
+
+[Auth0](https://auth0.com) doesn't need any introduction, it is one of the most popular Auth products out there. After the Okta acquisition though there's been pressure on Auth0 to focus on the Enterprise segment and unfortunately this has meant that as a startup you only get three Enterprise SSO connections (SAML or OIDC) for your apps before they try and get you onto a very expensive plan.
+
+As an early-stage startup this makes Enterprise SSO integration unaffordable, this is why we have created a seamless way to continue using Auth0 for auth but plug-in BoxyHQ for Enterprise SSO directly from Auth0. Your user management stays entirely in Auth0 but using BoxyHQ's OAuth 2.0 skin you can make Enterprise SAML or OIDC logins available to your customers.
+
+Visit our [GitHub repo](https://github.com/boxyhq/jackson-examples/tree/main/apps/auth0-user-store) to see the source code for the Auth0 integration.
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/integrations/bubble.md b/guides/jackson/integrations/bubble.md
new file mode 100644
index 0000000..cb83f66
--- /dev/null
+++ b/guides/jackson/integrations/bubble.md
@@ -0,0 +1,150 @@
+---
+title: BoxyHQ SAML SSO Bubble Plugin
+sidebar_label: Bubble.io
+---
+
+# SAML SSO Bubble Plugin
+
+This guide will help you setup the BoxyHQ SAML SSO Bubble Plugin to add SAML SSO authentication to your Bubble application.
+
+There is no easy way to add SAML SSO authentication to a Bubble application. This plugin provides a way to add SAML SSO authentication to your Bubble application with minimal effort.
+
+This plugin contains API calls and Actions for connecting a Bubble.io application with the BoxyHQ SAML Jackson instance for SSO authentication.
+
+Please note that you need a self-hosted instance of SAML Jackson to use this plugin. BoxyHQ does not provide a hosted instance of SAML Jackson at this time.
+
+Please follow the instructions in the [SAML Jackson Deployment Guides](https://boxyhq.com/guides/jackson#deployment-guides) to setup your SAML Jackson instance.
+
+Try the [Example Bubble App](https://boxyhq-saml-sso.bubbleapps.io/version-test) to see the plugin in action.
+
+## Install the plugin
+
+Here are the quick steps to install the plugin from the Bubble editor:
+
+- Go to your application's Plugins tab from left navigation.
+- Click on the **Add plugins** button from the top right corner.
+- Search for **BoxyHQ SAML SSO** and click on the **Install** button.
+
+## Configure the plugin
+
+Next step is to configure the plugin. Make sure you add the following values in the plugin settings:
+
+- `BoxyHQ Instance URL`: The URL of your SAML Jackson instance.
+
+- `Callback URL`: The URL where the user will be redirected after successful authentication with the IdP. This URL should be the same as the URL you have configured while adding the SAML connection in SAML Jackson.
+
+- `Client Secret Verifier`: This is optional. If you have configured a client secret verifier in SAML Jackson, you can add it here. If you have not configured a client secret verifier, you can leave this field blank.
+
+
+
+Now you are ready to setup Workflows in your application to use the plugin.
+
+## Plugin Actions
+
+The plugin consists of the following Actions:
+
+### Get Authorization URL
+
+This action returns the URL to initiate the SAML SSO authentication flow. After successful authentication with the IdP, the user will be redirected to the `Callback URL` which you can configure in the plugin settings.
+
+### Fetch User Profile
+
+This action returns the user profile of the authenticated user. This action should be used after the user is redirected to the `Callback URL` after successful authentication with the IdP.
+
+## Setup Workflows
+
+Go to your application's **Workflows** tab from left navigation. You need to add 2 workflows to your application to use the plugin:
+
+### Login Workflow
+
+This workflow will be triggered when the user clicks on SAML SSO login button on your application.
+
+Choose **BoxyHQ - Get Authorization URL** from the list of Actions.
+
+
+
+Add the following values in the Action:
+
+- `tenant`: A multi-tenant enterprise app must attach SSO connections to a tenant identifier. For example, an app can use any of the following as its tenant identifier: `domain`, `organization id`, `team id` or other unique identifier. This value will be used to fetch the SAML connection from SAML Jackson. For example: `boxyhq`.
+
+- `product`: The unique identifier of the your application. This vaue can be static if you are using a single product with SAML Jackson. For example: `my-bubble-app`.
+
+- `state`: A random string that will be used to verify the state of the request. This value will be passed back to your application in the `Callback URL`. You can use this value to verify the authenticity of the request.
+
+
+
+This action will return `Authorization URL` which you can use to redirect the user to the IdP for authentication.
+
+
+
+### SSO Callback Workflow
+
+This workflow will be triggered when the user is redirected back to your application after successful authentication with the IdP.
+
+Make sure you have added a new page in your application and configured the `Callback URL` in the plugin settings to point to this page. For example: `https://my-bubble-app.com/sso-callback`.
+
+The callback URL will contain the following query parameters:
+
+- `code`: The authorization code that can be used to fetch the user profile from SAML Jackson.
+- `state`: The state value that was passed in the `Login Workflow`.
+
+Here is an example of the callback URL: `https://my-bubble-app.com/sso-callback?code=52d7d591ba2c2e6efa4a8595edf9ac718b3658a7&state=random-state`
+
+:::info
+You can verify the authenticity of the request by comparing the `state` value in the query parameters with the `state` value that was passed in the `Login Workflow`. If the values of the `state` match, you can proceed to fetch the user profile from SAML Jackson.
+
+This verification is out of scope of this plugin. You can skip this step if you don't want to verify the authenticity of the request. However, it is recommended to verify the authenticity of the request.
+:::
+
+Let's add the following Actions to the `SSO Callback Workflow`:
+
+#### Action: BoxyHQ - Fetch User Profile
+
+Choose **BoxyHQ - Fetch User Profile** from the list of Actions.
+
+Add the following values in the Action:
+
+`code`: The authorization code that was passed in the query parameters. You can use the dynamic value `Get data from page URL` to fetch the value of the `code` query parameter.
+
+The Action will return the following values:
+
+- `profile id` - The unique identifier of the user in IdP.
+- `profile email` - The email address of the user.
+- `profile first name` - The first name of the user.
+- `profile last name` - The last name of the user.
+- `requested tenant` - The tenant identifier that was passed in the `Login Workflow`.
+- `requested product` - The product identifier that was passed in the `Login Workflow`.
+- `profile raw attributes` - The raw attributes that was returned by the IdP. This value will be a JSON string.
+
+
+
+#### Action: Create an user account for someone else
+
+You can use the **Create an user account for someone else** Action to create a new user account in your application. This Action will create a new user account in your application if the user does not already exist. If the user already exists, it will update the user account with the new values.
+
+Make sure you checked the **Return the user if the account already exists** checkbox in the Action.
+
+You can configure the values as per your requirements.
+
+
+
+#### Action: Assign a temp password to a user
+
+Bubble requires a password to be set for a user to login to the application. To overcome this limitation, we can set a temporary password for the user account and use that password to login to the application. You can choose the **Assign a temp password to a user** Action to set a temporary password for the user account.
+
+#### Action: Log the user in
+
+You can use the **Log the user in** Action to login the user to your application.
+
+Add the following values in the Action:
+
+- `Email`: The email address of the user. You can use the dynamic value `profile email` to fetch the email address from the `Fetch User Profile` Action.
+- `Password`: The temporary password that was set for the user account. You can use the dynamic value `temp password` to fetch the temporary password from the `Assign a temp password to a user` Action.
+
+#### Action: Redirect to a page
+
+You can use the **Redirect to a page** Action to redirect the user to an authenticated page in your application.
+
+## Next Steps
+
+Please reach out to our team for any questions or help with the setup. We are happy to help!
diff --git a/guides/jackson/integrations/firebase.md b/guides/jackson/integrations/firebase.md
new file mode 100644
index 0000000..67d1991
--- /dev/null
+++ b/guides/jackson/integrations/firebase.md
@@ -0,0 +1,16 @@
+---
+title: BoxyHQ SAML with Firebase user store
+sidebar_label: Firebase
+---
+
+# Firebase
+
+[Firebase](https://firebase.google.com/) is Google's Backend-as-a-Service that can scale quickly to support millions of users. Originally developed as a realtime database, Firebase now helps us solve common app development challenges like authentication, storage and messaging to name a few.
+
+With our Enterprise SSO integration, you can have your users managed as part of the Firebase user store. The Enterprise SAML or OIDC identities of your customer can then be authorised to access other services like CloudStorage.
+
+Visit our [GitHub repo](https://github.com/boxyhq/jackson-examples/tree/main/apps/firebase-user-store) to see the source code for the Firebase integration.
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/integrations/nextauth.md b/guides/jackson/integrations/nextauth.md
new file mode 100644
index 0000000..bdae52a
--- /dev/null
+++ b/guides/jackson/integrations/nextauth.md
@@ -0,0 +1,18 @@
+---
+title: BoxyHQ SAML as NextAuth OAuth provider
+sidebar_label: NextAuth
+---
+
+# NextAuth
+
+[NextAuth](https://next-auth.js.org/) is a complete open source authentication solution for Next.js applications.
+
+NextAuth supports SAML Jackson as an OAuth Provider.
+
+Follow [this documentation](https://next-auth.js.org/providers/boxyhq-saml) to learn about how to use SAML Jackson with NextAuth.
+
+Visit our [GitHub repo](https://github.com/boxyhq/jackson-examples/tree/main/apps/next-auth) to see the source code for the NextAuth SAML SSO integration.
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/integrations/supertokens.md b/guides/jackson/integrations/supertokens.md
new file mode 100644
index 0000000..e8c9e84
--- /dev/null
+++ b/guides/jackson/integrations/supertokens.md
@@ -0,0 +1,18 @@
+---
+title: SuperTokens
+sidebar_label: SuperTokens
+---
+
+# SuperTokens
+
+[SuperTokens](https://supertokens.com/) is an open core alternative to proprietary login providers like Auth0 or AWS Cognito.
+
+SuperTokens allows you to use SAML Jackson as a custom OAuth provider.
+
+Follow [this documentation](https://supertokens.com/docs/thirdpartyemailpassword/common-customizations/saml/with-boxyhq/integration-steps) to learn about how to use SAML Jackson with SuperTokens.
+
+Visit our [GitHub repo](https://github.com/supertokens/jackson-supertokens-express) to see the source code for the SuperTokens SAML SSO integration. We also have a [Next.js + Supertokens + Jackson](https://github.com/nadilas/jackson-next-supertokens) integration for you to draw inspiration from.
+
+## Next steps
+
+- Got a question? [Ask here](https://discord.gg/uyb7pYt4Pa)
diff --git a/guides/jackson/login-with-saml-sso.md b/guides/jackson/login-with-saml-sso.md
new file mode 100644
index 0000000..edce0ec
--- /dev/null
+++ b/guides/jackson/login-with-saml-sso.md
@@ -0,0 +1,95 @@
+---
+title: UI Best Practices for Log in with SAML Single Sign-On
+description: UI Best Practices for Log in with SAML Single Sign-On
+sidebar_label: Log in with SAML SSO
+---
+
+# Log in with SAML Single Sign-On
+
+Let's see how enterprise apps have implemented the SAML SSO into their authentication flow.
+
+## Service Provider Initiated SSO
+
+You can use several approaches while implementing your app's SP-initiated SAML SSO login.
+
+- Dedicated page for SAML SSO
+- Dynamic password fields
+- Subdomain for tenants
+- Separate the email and password fields
+
+### Dedicated page for SAML SSO
+
+With this approach, you would put a button on your login page for `Login with SAML SSO`. Users are taken to the SAML SSO page when they click the button.
+
+**Postman** takes this approach to enable SAML SSO for their enterprise users.
+
+
+
+
+
+The user flow would be something similar to the one below.
+
+- Users visit the login page.
+- Click the button "Login with SAML SSO"
+- The app redirects the user to the SAML SSO page.
+- The user enters their email address or tenant ID.
+- The app examines the domain or tenant ID to see if SSO is enabled.
+- If SSO is enabled, the app redirects the user to their IdP.
+
+### Dynamic password fields
+
+This approach hides the password field if SSO is enabled for a domain.
+
+You can see this approach on the **Dropbox** login form.
+
+
+
+
+
+The user flow would be something similar to the one below.
+
+- Users visit the login page.
+- The user enters their email address.
+- The app examines the domain to see if SSO is enabled.
+- If SSO is enabled, the app hides the password field from the login form.
+- The user submits the login form.
+- The app redirects the user to their IdP.
+
+### Subdomain for tenants
+
+One approach you can take is to configure a subdomain for each tenant. First, display a form to enter the tenant ID, and then the application redirects users to the subdomain page to show the available authentication mechanism enabled for the tenant.
+
+You can see this approach on the **Freshchat or Freshworks** login form.
+
+
+
+
+ 
+
+
+The user flow would be something similar to the one below.
+
+- Users visit the login page.
+- The user enters their tenant name.
+- The app examines the tenant's existence and redirects the user to the tenant's subdomain page.
+- The subdomain page display a login form with the authentication mechanisms enabled for the tenant.
+- If SSO is enabled, the user can choose "Login with SAML SSO".
+
+### Separate the email and password fields
+
+This approach splits the login process into multiple stages. First, the login form displays an email field without a password field. Next, a user enters their email address, and the application checks to see which authentication mechanism is enabled for the current user.
+
+**Box** uses this approach for its authentication flow.
+
+
+
+The user flow would be something similar to the one below.
+
+- Users visit the login page.
+- The user enters their email address and submit the login form.
+- The app examines the email address to see if SSO is enabled.
+- If SSO is enabled, the app redirects the users to their IdP instead of taking them to a password flow.
diff --git a/guides/jackson/overview.mdx b/guides/jackson/overview.mdx
new file mode 100644
index 0000000..5e49a47
--- /dev/null
+++ b/guides/jackson/overview.mdx
@@ -0,0 +1,107 @@
+---
+title: Enterprise SSO Guide
+hide_table_of_contents: true
+slug: /jackson
+---
+
+# Enterprise SSO Guide
+
+The documentation is divided into 3 sections.
+
+import GuideSection from '../../src/components/GuideSection.js';
+const frameworks = [
+ {
+ name: 'AdonisJS',
+ href: '/guides/jackson/frameworks/adonis',
+ },
+ {
+ name: 'Express.js',
+ href: '/guides/jackson/frameworks/express',
+ },
+ {
+ name: 'Next.js',
+ href: '/guides/jackson/frameworks/nextjs',
+ },
+ {
+ name: 'React',
+ href: '/guides/jackson/frameworks/react',
+ },
+ {
+ name: 'Remix',
+ href: '/guides/jackson/frameworks/remix',
+ },
+ {
+ name: 'Laravel',
+ href: '/guides/jackson/frameworks/laravel',
+ },
+ {
+ name: 'Ruby on Rails',
+ href: '/guides/jackson/frameworks/rails',
+ },
+];
+const integrations = [
+ {
+ name: 'Auth0',
+ href: '/guides/jackson/integrations/auth0',
+ },
+ {
+ name: 'Firebase',
+ href: '/guides/jackson/integrations/firebase',
+ },
+ {
+ name: 'NextAuth',
+ href: '/guides/jackson/integrations/nextauth',
+ },
+ {
+ name: 'SuperTokens',
+ href: '/guides/jackson/integrations/supertokens',
+ },
+ {
+ name: 'Bubble.io',
+ href: '/guides/jackson/integrations/bubble',
+ },
+];
+const deployments = [
+ {
+ name: 'Heroku',
+ href: '/guides/jackson/deployments/heroku',
+ },
+ {
+ name: 'Vercel',
+ href: '/guides/jackson/deployments/vercel',
+ },
+ {
+ name: 'mogenius',
+ href: '/guides/jackson/deployments/mogenius',
+ },
+];
+
+## Deployment Guides
+
+If you want to self host SAML Jackson, the recommended approach is to use one of the recommended one click installation options.
+
+
+
+
+
+ {benefits.map(({ title, description, icon }, idx) => (
+
+
+
+
+
+
+
+ {title}
+ {description}
+
+
+
+
+
+ ))}
+
+
+ );
+};
+
+export default BenefitsSection;
diff --git a/src/components/Card.js b/src/components/Card.js
new file mode 100644
index 0000000..9485206
--- /dev/null
+++ b/src/components/Card.js
@@ -0,0 +1,61 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+import SvgIcon from './SvgIcon';
+
+const Card = ({ idx, icon, title, description, url, btnText, colClass }) => {
+ return (
+
+
+
+
+
+
+
+
+ {title}
+
+
+ {description}
+
+
+
+
+ {btnText}
+
+
+
+
+
+ );
+};
+
+export default Card;
diff --git a/src/components/CustomersSection.js b/src/components/CustomersSection.js
new file mode 100644
index 0000000..8946ad3
--- /dev/null
+++ b/src/components/CustomersSection.js
@@ -0,0 +1,58 @@
+import React from 'react';
+
+import SvgIcon from './SvgIcon';
+import SectionLayout from './SectionLayout';
+
+const customersList = [
+ {
+ url: 'https://cal.com',
+ logo: require('../../static/img/customers/cal.svg').default,
+ quote: `It let our team focus on what we do best (democratizing scheduling for everyone) without getting distracted by the needs of our enterprise customers. Did I mention it's open-source and free?`,
+ },
+ {
+ url: 'https://supertokens.com',
+ logo: require('../../static/img/customers/supertokens.svg').default,
+ quote: `We at SuperTokens needed to provide SAML login to our users, and instead of building it from scratch, we found the perfect open source project - BoxyHQ!`,
+ },
+ {
+ url: 'https://www.salita.no',
+ logo: require('../../static/img/customers/salita.svg').default,
+ quote: `BoxyHQ helped us implement single sign-on for our government customers in record time, it was exactly what we were looking for. Absolute pleasure working with Deepak and the BoxyHQ team.`,
+ },
+ {
+ url: 'https://www.unosecur.com',
+ logo: require('../../static/img/customers/unosecur.svg').default,
+ quote: `With BoxyHQ, we can focus on building our core product without worrying too much about the enterprise readiness features. The integration was seamless.`,
+ },
+];
+
+const CustomersSection = () => {
+ return (
+
+
+ {customersList.map(({ quote, logo, url }, idx) => (
+
+
+
+
+ {quote}
+
+
+
+
+ ))}
+
+
+ );
+};
+
+export default CustomersSection;
diff --git a/src/components/DeveloperCommunitySection.js b/src/components/DeveloperCommunitySection.js
new file mode 100644
index 0000000..0a45e9f
--- /dev/null
+++ b/src/components/DeveloperCommunitySection.js
@@ -0,0 +1,43 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+
+import SectionLayout from './SectionLayout';
+
+const DeveloperCommunitySection = () => {
+ return (
+
+
+
+ Follow on Twitter
+
+
+ Star on GitHub
+
+
+ Join Discord
+
+
+
+ );
+};
+
+export default DeveloperCommunitySection;
diff --git a/src/components/FeatureSection.js b/src/components/FeatureSection.js
new file mode 100644
index 0000000..3e17bcb
--- /dev/null
+++ b/src/components/FeatureSection.js
@@ -0,0 +1,68 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+
+import SvgIcon from './SvgIcon';
+
+const FeatureSection = ({
+ title,
+ image,
+ btnText,
+ btnLink,
+ direction = 'left',
+ children,
+}) => {
+ return (
+
+
+
+
+
+
+
+ {title}
+ {children ? {children} : null}
+
+ {btnText}
+
+
+
+
+
+
+
+
+
+ );
+};
+
+export default FeatureSection;
diff --git a/src/components/GuideSection.js b/src/components/GuideSection.js
new file mode 100644
index 0000000..6e4fb2b
--- /dev/null
+++ b/src/components/GuideSection.js
@@ -0,0 +1,26 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import ArrowIcon from '../../static/img/arrow.svg';
+
+export default function GuideSection({ items }) {
+ return (
+ <>
+ {items.map((item) => (
+
+
+
+ {item.name}
+
+
+
+ ))}
+
+ );
+}
diff --git a/src/components/HeroSection.js b/src/components/HeroSection.js
new file mode 100644
index 0000000..17a8fe2
--- /dev/null
+++ b/src/components/HeroSection.js
@@ -0,0 +1,59 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+const HeroSection = ({ title, description, image, buttons, icon = null }) => {
+ const Icon = icon;
+
+ return (
+
+
+
+
+
+ {Icon && {title}
+
+ {description}
+
+ {buttons.map(({ href, title, className, onClick }, idx) =>
+ onClick ? (
+
+ {title}
+
+ ) : (
+
+ {title}
+
+ )
+ )}
+
+
+
+
+
+
+ 
+
+
+
+
+
+ );
+};
+
+export default HeroSection;
diff --git a/src/components/HomepageFeatures.js b/src/components/HomepageFeatures.js
deleted file mode 100644
index 4c0441d..0000000
--- a/src/components/HomepageFeatures.js
+++ /dev/null
@@ -1,64 +0,0 @@
-import React from 'react';
-import clsx from 'clsx';
-import styles from './HomepageFeatures.module.css';
-
-const FeatureList = [
- {
- title: 'next-antd-scaffold',
- repo: 'https://github.com/luffyZh/next-antd-scaffold',
- src: require('../../static/img/next-antd-scaffold.jpg').default,
- description: (
- <>
- A simple scaffold based on Next.js for quick use with ant-design, redux, redux-saga, fetch and pm2.
-
- ),
- },
- {
- title: 'dynamic-antd-theme',
- repo: 'https://github.com/luffyZh/dynamic-antd-theme',
- src: require('../../static/img/dynamic-antd-theme.png').default,
- description: (
- <>
- A simple plugin to dynamic change ant-design theme whether less or css.
-
- ),
- },
- {
- title: 'mini-dynamic-antd-theme',
- repo: 'https://github.com/luffyZh/mini-dynamic-antd-theme',
- src: require('../../static/img/mini-dynamic-antd-theme.png').default,
- description: (
- <>
- A simple plugin to dynamic change ant-design || ant-design-vue theme whether less or css.
-
- ),
- },
-];
-
-function Feature({src, title, description, repo}) {
- return (
-
-
- 
-
-
- {title}
- {description}
-
-
- );
-}
-
-export default function HomepageFeatures() {
- return (
-
-
-
- {FeatureList.map((props, idx) => (
-
- );
-}
diff --git a/src/components/HomepageFeatures.module.css b/src/components/HomepageFeatures.module.css
deleted file mode 100644
index b89d087..0000000
--- a/src/components/HomepageFeatures.module.css
+++ /dev/null
@@ -1,13 +0,0 @@
-/* stylelint-disable docusaurus/copyright-header */
-
-.features {
- display: flex;
- align-items: center;
- padding: 2rem 0;
- width: 100%;
-}
-
-.featureSvg {
- width: 100%;
- height: 200px;
-}
diff --git a/src/components/HubSpotForm.js b/src/components/HubSpotForm.js
new file mode 100644
index 0000000..3e5d944
--- /dev/null
+++ b/src/components/HubSpotForm.js
@@ -0,0 +1,33 @@
+import React, { useEffect } from 'react';
+
+const HubSpotForm = ({ region, portalId, formId }) => {
+ useEffect(() => {
+ const script = document.createElement('script');
+
+ script.src = 'https://js.hsforms.net/forms/shell.js';
+ document.body.appendChild(script);
+
+ script.addEventListener('load', () => {
+ if (window.hbspt) {
+ window.hbspt.forms.create({
+ region,
+ portalId,
+ formId,
+ target: '#hubspotForm',
+ });
+ }
+ });
+ }, []);
+
+ return (
+
+ Loading...
+
+ );
+};
+
+export const HubSpotPricingContactForm = ({ formId }) => {
+ if (!formId) return null;
+
+ return
+
+ {InvestorsList.map(({ url, logo }, idx) => (
+
+
+
+
+ 
+
+
+
+
+ ))}
+
+
+ );
+};
+
+export default InvestorsSection;
diff --git a/src/components/Modal.js b/src/components/Modal.js
new file mode 100644
index 0000000..98f11c4
--- /dev/null
+++ b/src/components/Modal.js
@@ -0,0 +1,51 @@
+import React from 'react';
+import ReactModal from 'react-modal';
+
+const reactModalStyles = {
+ overlay: {
+ position: 'fixed',
+ top: '80px',
+ backgroundColor: 'rgb(78 78 78 / 75%)',
+ display: 'flex',
+ justifyContent: 'center',
+ },
+ content: {
+ position: 'absolute',
+ border: '1px solid #ccc',
+ background: '#fff',
+ overflow: 'auto',
+ WebkitOverflowScrolling: 'touch',
+ borderRadius: '4px',
+ outline: 'none',
+ padding: '30px',
+ margin: 'auto',
+ },
+};
+
+export const Modal = ({ children, title, opened, setOpened }) => {
+ return (
+
+
+
+ {title}
+
+
+ {children}
+
+
+ );
+};
diff --git a/src/components/NewsSection.js b/src/components/NewsSection.js
new file mode 100644
index 0000000..0d65122
--- /dev/null
+++ b/src/components/NewsSection.js
@@ -0,0 +1,56 @@
+import React from 'react';
+
+import SvgIcon from './SvgIcon';
+import SectionLayout from './SectionLayout';
+
+const NewsList = [
+ {
+ title: 'BoxyHQ brings ‘enterprise readiness’ to any SaaS app',
+ url: 'https://venturebeat.com/2022/02/23/boxyhq-brings-enterprise-readiness-to-any-saas-app/',
+ logo: require('../../static/img/news/vb-logo.svg').default,
+ },
+ {
+ title:
+ 'This tech startup helps SaaS companies make their products enterprise-ready',
+ url: 'https://yourstory.com/2022/03/boxyhq-tech-startup-helps-saas-companies-add-features-enterprise',
+ logo: require('../../static/img/news/yourstory-logo.svg').default,
+ },
+];
+
+const NewsSection = () => {
+ return (
+
+
+ {NewsList.map(({ title, url, logo }, idx) => (
+
+
+
+ {title}
+
+
+ ))}
+
+
+ );
+};
+
+export default NewsSection;
diff --git a/src/components/Pricing/ContactUs.js b/src/components/Pricing/ContactUs.js
new file mode 100644
index 0000000..ba31153
--- /dev/null
+++ b/src/components/Pricing/ContactUs.js
@@ -0,0 +1,15 @@
+import React from 'react';
+
+export const ContactUsBtn = ({ setOpened, setFormId, formId }) => {
+ return (
+ {
+ setFormId(formId);
+ setOpened(true);
+ }}
+ className="button--link cursor"
+ >
+ Contact us
+
+ );
+};
diff --git a/src/components/Pricing/Icons.js b/src/components/Pricing/Icons.js
new file mode 100644
index 0000000..ab62dc5
--- /dev/null
+++ b/src/components/Pricing/Icons.js
@@ -0,0 +1,41 @@
+import React from 'react';
+
+export const IconYes = () => {
+ return (
+
+ );
+};
+
+export const IconNo = () => {
+ return (
+
+ );
+};
diff --git a/src/components/Pricing/PricingSectionDesktop.js b/src/components/Pricing/PricingSectionDesktop.js
new file mode 100644
index 0000000..9a3251f
--- /dev/null
+++ b/src/components/Pricing/PricingSectionDesktop.js
@@ -0,0 +1,74 @@
+import React from 'react';
+
+import { pricingPlans } from './pricingPlans';
+import { TextToComponent } from './TextToComponent';
+
+export const PricingSectionDesktop = ({ setOpened, setFormId }) => {
+ return (
+
+
+
+
+ Self-Hosted
+ Self-Hosted Premium
+ SaaS (hosted by us)
+ Enterprise
+
+
+
+ {pricingPlans.map((pricingPlan) => {
+ return (
+
+
+
+ {pricingPlan.feature}
+
+
+
+
+
+
+
+
+
+
+ {pricingPlan.lineBreak && (
+
+
+ )}
+
+ );
+ })}
+
+
+
+ );
+};
diff --git a/src/components/Pricing/PricingSectionMobile.js b/src/components/Pricing/PricingSectionMobile.js
new file mode 100644
index 0000000..04cb56c
--- /dev/null
+++ b/src/components/Pricing/PricingSectionMobile.js
@@ -0,0 +1,70 @@
+import React from 'react';
+
+import { pricingPlans } from './pricingPlans';
+import { TextToComponent } from './TextToComponent';
+
+export const PricingSectionMobile = ({ setOpened, setFormId }) => {
+ return (
+
+
+
+
+
+ {title}
+
+
+
+
+ {pricingPlans.map((pricingPlan) => (
+
+
+ {pricingPlan.feature}
+
+
+
+
+ ))}
+
+
+ );
+};
diff --git a/src/components/Pricing/TextToComponent.js b/src/components/Pricing/TextToComponent.js
new file mode 100644
index 0000000..995e8ee
--- /dev/null
+++ b/src/components/Pricing/TextToComponent.js
@@ -0,0 +1,22 @@
+import React from 'react';
+
+import { IconNo, IconYes } from './Icons';
+import { ContactUsBtn } from './ContactUs';
+
+export const TextToComponent = ({ text, setOpened, setFormId }) => {
+ const parts = text.split(':');
+
+ const componentsMap = {
+ yes:
+
+ {products
+ .slice(0, 2)
+ .map(({ title, description, url, icon, btnText }, idx) => (
+
+ );
+};
+
+export default ProductsSection;
diff --git a/src/components/Profile.js b/src/components/Profile.js
new file mode 100644
index 0000000..05bda66
--- /dev/null
+++ b/src/components/Profile.js
@@ -0,0 +1,50 @@
+import React from 'react';
+import styles from './Profile.module.css';
+
+export default function Profile({
+ img,
+ name,
+ bio,
+ subtitle,
+ github,
+ linkedin,
+ twitter,
+}) {
+ return (
+
+
+
+ 
+
+
+
+
+ {name}
+ {bio}
+
+ {subtitle}
+
+
+
+ {github ? 'GitHub' : 'LinkedIn'}
+ {' '}
+ ·{' '}
+
+ Twitter
+
+
+
+
+
+
+
+ );
+}
diff --git a/src/components/Profile.module.css b/src/components/Profile.module.css
new file mode 100644
index 0000000..c76b3ff
--- /dev/null
+++ b/src/components/Profile.module.css
@@ -0,0 +1,8 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+.center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+ width: 50%;
+}
diff --git a/src/components/SectionLayout.js b/src/components/SectionLayout.js
new file mode 100644
index 0000000..9458c62
--- /dev/null
+++ b/src/components/SectionLayout.js
@@ -0,0 +1,24 @@
+import React from 'react';
+
+const SectionLayout = ({ title, description, children, style, titleStyle }) => {
+ return (
+
+
+
+ {title}
+
+ {description && (
+
+ {description}
+
+ )}
+ {children}
+
+
+ );
+};
+
+export default SectionLayout;
diff --git a/src/components/SvgFeature.js b/src/components/SvgFeature.js
new file mode 100644
index 0000000..2c03b67
--- /dev/null
+++ b/src/components/SvgFeature.js
@@ -0,0 +1,48 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './SvgFeature.module.css';
+
+export default function SvgFeature({
+ Svg,
+ png,
+ quote,
+ url,
+ colSize,
+ quotes,
+ title,
+ loading,
+}) {
+ return (
+
+ {Svg ? (
+
+
+
+
+
+ ) : png ? (
+
+
+ 
+
+
+ ) : null}
+ {quotes ? (
+
+ {quote}
+
+ ) : null}
+
+
+ {url ? (
+
+ {title}
+
+ ) : (
+ title
+ )}
+
+
+
+ );
+}
diff --git a/src/components/SvgFeature.module.css b/src/components/SvgFeature.module.css
new file mode 100644
index 0000000..0adf848
--- /dev/null
+++ b/src/components/SvgFeature.module.css
@@ -0,0 +1,14 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+.svgFeature {
+ height: 50px;
+ width: 150px;
+}
+
+.pngFeature {
+ width: 150px;
+}
+
+.pFeature {
+ color: #444950;
+}
\ No newline at end of file
diff --git a/src/components/SvgIcon.js b/src/components/SvgIcon.js
new file mode 100644
index 0000000..901dac2
--- /dev/null
+++ b/src/components/SvgIcon.js
@@ -0,0 +1,17 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+const SvgIcon = ({ icon, url, size, className }) => {
+ const Icon = icon;
+
+ return url ? (
+
+ {title}
+
+ );
+}
diff --git a/src/css/custom.css b/src/css/custom.css
index 41b1aaf..b653209 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -7,7 +7,7 @@
/* You can override the default Infima variables here. */
:root {
- --ifm-color-primary: #466aff;
+ --ifm-color-primary: #25c2a0;
--ifm-color-primary-dark: rgb(33, 175, 144);
--ifm-color-primary-darker: rgb(31, 165, 136);
--ifm-color-primary-darkest: rgb(26, 136, 112);
@@ -15,121 +15,194 @@
--ifm-color-primary-lighter: rgb(102, 212, 189);
--ifm-color-primary-lightest: rgb(146, 224, 208);
--ifm-code-font-size: 95%;
+ --ifm-navbar-height: 5rem;
+
+ --aa-input-border-color-rgb: 190, 195, 201 !important;
+ --aa-selected-color-rgb: 141, 148, 158 !important;
+ --aa-muted-color-rgb: 37, 194, 160 !important;
+ --aa-primary-color-rgb: 37, 194, 160 !important;
}
-.navbar{
- background-color: rgba(27, 36, 64, 1);
-}
-.navbar__link--active,a:hover,.menu__link--active{
- color: rgba(70, 106, 255, 1)!important;
-}
-.navbar__link{
- color: #fff;
-}
-.table-of-contents__link--active{
- color: #466aff;
-}
-html[data-theme=light] .menu{
- background-image:linear-gradient(180deg,#f3f5f8 0%,#ffffff 100%);
- box-shadow:8px 6px 18px rgba(171, 202, 255, 0.24) inset;
- margin-bottom: 0px!important;
+
+body[data-theme='dark'] {
+ --aa-input-border-color-rgb: 190, 195, 201 !important;
+ --aa-background-color-rgb: 27, 27, 29 !important;
+ --aa-selected-color-rgb: 190, 195, 201 !important;
+ --aa-muted-color-rgb: 37, 194, 160 !important;
+ --aa-primary-color-rgb: 37, 194, 160 !important;
}
+
.docusaurus-highlight-code-line {
- background-color: rgba(0, 0, 0, 0.1);
+ background-color: rgb(72, 77, 91);
display: block;
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
}
-html[data-theme='dark'] .docusaurus-highlight-code-line {
- background-color: rgba(0, 0, 0, 0.3);
+.navbar__brand {
+ height: 3.5rem;
}
-.footer{
- height: 473px;
- position: relative;
- background: #1e1e1e;
+
+/* GitHub */
+.header-github-link:hover {
+ opacity: 0.6;
}
-.container{
- height: 100%;
+
+.header-github-link:before {
+ content: '';
+ width: 24px;
+ height: 24px;
display: flex;
- flex-direction: column;
- justify-content: space-around;
+ background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+ no-repeat;
}
-.footer__bottom .margin-bottom--sm{
- position: absolute;
- margin-top: -150px;
- top:50%
+
+html[data-theme='dark'] .header-github-link:before {
+ background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+ no-repeat;
}
-.footer__links .footer__title{
- height: 25px;
- font-size: 18px;
- font-weight: 600;
- color: #fff;
- line-height: 25px;
- margin-bottom: 20px;
+
+.card {
+ border: 1px solid #333;
+ box-shadow: none;
+ border-radius: 5px;
+ text-decoration: none !important;
+ color: var(--ifm-color-content);
}
-.footer__links .footer__col:last-child .footer__items:last-child{
+
+.markdown h1:first-child {
+ --ifm-h1-font-size: 2.3rem;
+}
+
+/* v2 CSS */
+
+.intro__buttons {
display: flex;
flex-wrap: wrap;
+ gap: 1rem;
}
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item{
- width: 50%;
-}
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item:nth-child(2){
- background-image: url(../../static/img/gitlink-qq.png);
- background-size: 100% 100%;
- height: 90px;
- width: 90px;
- background-color: #fff;
- border-radius: 4px;
- position: relative;
-}
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item:nth-child(3){
- background-image: url(../../static/img/gongzhong.png);
- background-size: 100% 100%;
- height: 90px;
- width: 90px;
- background-color: #fff;
- border-radius: 4px;
- position: relative;
- margin-left: 34px;
-}
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item:nth-child(2) a,
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item:nth-child(3) a{
- position: absolute;
- top: 95px;
- left: 50%;
- margin-left: -17px;
-}
-.footer__links .footer__col:last-child .footer__items:last-child .footer__item:first-child{
+
+.page__section {
+ border-top: 1px solid var(--ifm-color-emphasis-200);
width: 100%;
+ padding: 40px 10px 40px;
}
-.container .footer__links{
- margin-left: 420px;
+
+.red {
+ border: 1px solid red;
}
-.container .footer__links .footer__col .footer__item{
- color: #bdc2d1;
+
+.section__header {
+ font-size: 30px;
+ margin: 0%;
+}
+
+.card__description {
font-size: 14px;
- font-weight: 400;
- line-height: 20px;
- height: 20px;
- margin-bottom: 15px;
}
-.footer__bottom .margin-bottom--sm img{
- width: 300px;
- max-width: unset;
+
+.card {
+ border: 1px solid #e3dbdb !important;
}
-.container .footer__copyright{
- position: absolute;
+
+.hero__title {
+ font-size: 2.25rem;
+ margin: 0%;
+}
+
+.hero__subtitle {
+ font-size: 1.25rem;
+}
+
+.hero__image {
+ display: none;
+ justify-content: center;
+}
+
+.product__dropdown__link {
+ display: flex;
+ align-items: center;
+ column-gap: 5px;
+}
+
+.center {
+ display: flex;
+ justify-content: center;
+ flex-wrap: wrap;
+}
+
+.cursor {
+ cursor: pointer;
+}
+
+/* Pricing page */
+
+.pricing__table {
width: 100%;
- left: 0px;
- font-size: 12px;
- font-weight: 400;
- color: #bdc2d1;
- line-height: 28px;
- padding: 15px 0;
- text-align: center;
- background-color: #1b212c;
+ display: inline-table !important;
+ table-layout: fixed;
+ margin-top: 20px;
+ border: 1px solid #f1f3f5;
+}
+
+.pricing__table td,
+.pricing__table th {
+ padding: 10px;
+ text-align: center;
+ border: 1px solid #f1f3f5;
+ border-left: 0px;
+ border-right: 0px;
+}
+
+.pricing__table tr,
+.pricing__table tr:nth-child(2n) {
+ background: none;
+}
+
+.pricing__section__desktop {
+ display: none;
+}
+
+.pricing__table .highlight {
+ background: rgb(37 194 160 / 31%);
+}
+
+.modal__close__btn {
+ position: absolute;
+ top: 10px;
+ right: 10px;
+ border: none;
+ background: transparent;
+ font-size: 25px;
+ cursor: pointer;
+}
+
+/* Override "react-model" container width */
+.ReactModal__Content {
+ width: 80%;
+}
+
+/* Mobile view */
+
+@media screen and (min-width: 996px) {
+ .row.is-multiline .col {
+ margin-top: var(--ifm-spacing-horizontal) !important;
+ margin-bottom: var(--ifm-spacing-horizontal) !important;
+ }
+
+ .hero__image {
+ display: flex;
+ }
+
+ .pricing__section__desktop {
+ display: block;
+ }
+
+ .pricing__section__mobile {
+ display: none;
+ }
+
+ .ReactModal__Content {
+ width: 500px;
+ height: 550px;
+ }
}
-.container .footer__copyright p{
- margin-bottom: 0px!important;
-}
\ No newline at end of file
diff --git a/src/pages/.index.js b/src/pages/.index.js
deleted file mode 100644
index 6b0266d..0000000
--- a/src/pages/.index.js
+++ /dev/null
@@ -1,33 +0,0 @@
-import React from 'react';
-import clsx from 'clsx';
-import Layout from '@theme/Layout';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import styles from './index.module.css';
-import HomepageFeatures from '../components/HomepageFeatures';
-
-function HomepageHeader() {
- const {siteConfig} = useDocusaurusContext();
- return (
-
-
- {siteConfig.title}
- {siteConfig.tagline}
- 车到山前必有路，船到桥头自然直～
-
-
- );
-}
-
-export default function Home() {
- const {siteConfig} = useDocusaurusContext();
- return (
-
-
-
-
- );
-}
diff --git a/src/pages/audit-logs.js b/src/pages/audit-logs.js
new file mode 100644
index 0000000..c3036b5
--- /dev/null
+++ b/src/pages/audit-logs.js
@@ -0,0 +1,98 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+
+import HeroSection from '../components/HeroSection';
+import FeatureSection from '../components/FeatureSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+
+const title = 'Audit Logs';
+const description =
+ 'With BoxyHQ’s Audit Logs we have created the easiest way for you to integrate compliant audit logs into your application';
+const ProductIcon =
+ require('../../static/img/products/audit-logs/logo.svg').default;
+
+const Icon1 =
+ require('../../static/img/products/audit-logs/cloud_docs.svg').default;
+
+const Icon2 =
+ require('../../static/img/products/audit-logs/reviewed_docs.svg').default;
+
+const Icon3 =
+ require('../../static/img/products/audit-logs/export_files.svg').default;
+
+const AuditLogs = () => {
+ return (
+
+
+
+ With Audit Logs by BoxyHQ, you provide enterprise customers with the
+ ability to record and search events that happen on your application.
+ With our simple integration, you can become compliant fast and save
+ your team from building complex solutions from scratch.
+
+
+
+
+
+ For all companies but in particular large companies, the ability to
+ monitor the flow of data and be alerted to any breaches is essential.
+ Audit logs help to pinpoint any misuse of information and ensure that
+ data policies are followed. Many larger enterprise customers will
+ demand this as a requirement if you plan to sell to them.
+
+
+
+
+
+ Our out-the-box solution is designed not only to make you compliant
+ but give your customers all the functionality and safety they need -
+ exportable, immutable, time synced and searchable audit logs.
+
+
+
+
+ );
+};
+
+export default AuditLogs;
diff --git a/src/pages/boxyhq-vs-workos.js b/src/pages/boxyhq-vs-workos.js
new file mode 100644
index 0000000..b502c2e
--- /dev/null
+++ b/src/pages/boxyhq-vs-workos.js
@@ -0,0 +1,227 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+import SectionLayout from '../components/SectionLayout';
+import { IconNo, IconYes } from '../components/Pricing/Icons';
+
+const title = 'BoxyHQ vs WorkOS';
+const description =
+ 'BoxyHQ is a flexible, secure, open-source alternative to WorkOS that brings enterprise readiness capabilities to your SaaS applications. It integrates with your tech stack no matter how bespoke.';
+
+const AuditLogs = () => {
+ return (
+
+
+
+
+
+
+ {title}
+
+ {description}
+
+
+
+
+
+ {/* Section 1 */}
+
+
+
+
+
+
+
+
+ Your product, your rules
+
+ Make your app enterprise-ready, with just a few lines of
+ code. Through its open-source approach, BoxyHQ’s users
+ are free to make any customizations and changes to their
+ features, while also avoiding vendor lock-in.
+
+
+
+
+
+
+
+
+
+
+
+ Resource efficient
+
+ Instead of paying thousands of dollars for the large
+ number of connections that your app will have, use
+ BoxyHQ's free open-source solution. Allocate resources
+ to your core value proposition and maximize the benefits
+ for your customers.
+
+
+
+
+
+
+
+
+
+
+ {/* Section 2 */}
+
+
+
+
+ BoxyHQ
+ WorkOS
+
+
+
+
+ License
+ Open Source
+ Proprietary
+
+
+ Enterprise SSO
+
+
+
+
+
+
+ Directory Sync
+
+
+
+
+
+
+ Audit Logs
+
+
+
+
+
+
+ Data Privacy Vault
+
+
+
+
+
+
+ Admin Portal
+
+
+
+
+
+
+ Custom deployment
+
+
+
+
+
+
+ Self-Hosted & SaaS
+ SaaS
+
+
+
+
+
+ {/* Section 3 */}
+
+
+
+
+
+
+
+
+
+ -
+
+
+ -
+
+
+ -
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+};
+
+export default AuditLogs;
diff --git a/src/pages/directory-sync.js b/src/pages/directory-sync.js
new file mode 100644
index 0000000..ec11677
--- /dev/null
+++ b/src/pages/directory-sync.js
@@ -0,0 +1,97 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+
+import HeroSection from '../components/HeroSection';
+import FeatureSection from '../components/FeatureSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+
+const title = 'Directory Sync';
+const description =
+ 'One simple integration to automate user and group provisioning. Supports SCIM 2.0 protocol for most major providers';
+
+const ProductIcon = require('../../static/img/products/dsync/logo.svg').default;
+
+const Icon1 =
+ require('../../static/img/products/dsync/meet_the_team.svg').default;
+
+const Icon2 =
+ require('../../static/img/products/dsync/data_points.svg').default;
+
+const DSync = () => {
+ return (
+
+
+
+ Enterprise customers already use directories to manage user access. By
+ allowing them to use their active directory in your product you enable
+ them to have higher security standards and centrally manage their
+ user's access lifecycle. With Directory Sync by BoxyHQ, you can enable
+ this with our simple API.
+
+
+
+
+
+
+ With our simple integration, you can enable directory sync in your
+ application in days instead of months and seamlessly connect to
+ almost any directory service. With our API you can:
+
+
+ Custom Mapping
+
+ Easily fetch in the attributes that you need to use and map them
+ against the data you need.
+
+ Bespoke requests
+
+ Fetch and manipulate data from different entities as you need.
+
+ Streamline Data
+
+ Access data and integrate it seamlessly so you can standardize it
+ across the board
+
+
+
+
+
+ );
+};
+
+export default DSync;
diff --git a/src/pages/enterprise-readiness.js b/src/pages/enterprise-readiness.js
new file mode 100644
index 0000000..faf5b52
--- /dev/null
+++ b/src/pages/enterprise-readiness.js
@@ -0,0 +1,136 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+import NewsSection from '../components/NewsSection';
+import HeroSection from '../components/HeroSection';
+import ProductsSection from '../components/ProductsSection';
+import InvestorsSection from '../components/InvestorsSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+
+const title = 'BoxyHQ for Startups';
+const description =
+ 'Enterprise readiness for B2B SaaS startups, straight out of the box';
+
+const EnterpriseReadiness = () => {
+ return (
+
+
+
+
+
+
+
+
+
+
+ Become Enterprise Ready
+
+
+
+
+ As a startup you need to build fast, test and make sure
+ your solution achieves product-market fit. But if you
+ are planning to sell to enterprises you will need to
+ implement security and compliance features that could be
+ expensive and time consuming.
+
+
+ Here is a good guide on what becoming enterprise ready
+ means:{' '}
+
+ EnterpriseReady - Build SaaS features enterprises love
+
+
+
+
+
+ Book a free enterprise-readiness session
+
+
+
+
+
+
+
+
+
+
+
+
+ Build or buy?
+
+
+
+
+ Save time and money with BoxyHQ's free open-source
+ solution. Available under an Apache 2.0 license, our
+ solutions make it easy for developers to collaborate and
+ innovate, without the need for custom building or
+ expensive fees.
+
+
+ Our solutions run in your environment, giving you full
+ control. We simply provide the building blocks to help
+ you succeed.
+
+
+
+
+ Contact Us
+
+
+
+
+
+
+
+
+
+
+
+ );
+};
+
+export default EnterpriseReadiness;
diff --git a/src/pages/enterprise-sso.js b/src/pages/enterprise-sso.js
new file mode 100644
index 0000000..6bdb5c7
--- /dev/null
+++ b/src/pages/enterprise-sso.js
@@ -0,0 +1,169 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import HeroSection from '../components/HeroSection';
+import FeatureSection from '../components/FeatureSection';
+import BenefitsSection from '../components/BenefitsSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+import SectionLayout from '../components/SectionLayout';
+
+const title = 'Quickly integrate Enterprise SSO';
+const description =
+ 'Save hundreds of development hours by easily integrating SSO into your SaaS app. Our solution supports SAML & OIDC.';
+
+const ProductIcon =
+ require('../../static/img/products/saml-jackson/logo.svg').default;
+
+const Icon1 =
+ require('../../static/img/products/saml-jackson/connected_world.svg').default;
+
+const Icon2 =
+ require('../../static/img/products/saml-jackson/time_management.svg').default;
+
+const Icon3 =
+ require('../../static/img/products/saml-jackson/building.svg').default;
+
+const benefits = [
+ {
+ title: 'Improved Security',
+ description: `By deploying SAML SSO, you can enable your customers to manage
+ access control on their own systems. This helps prevent password sharing,
+ ensures that staff have the correct access, and allows them to easily grant
+ and revoke access from a central location.`,
+ icon: require('../../static/img/products/icons/security.svg').default,
+ },
+ {
+ title: 'Enhanced user experience',
+ description: `Improving the login experience is crucial for providing a good
+ user experience. By allowing your customers to log in to your product via
+ their IdP dashboard with a single click, you can significantly improve their
+ experience with your product.`,
+ icon: require('../../static/img/products/icons/futuristic_interface.svg')
+ .default,
+ },
+ {
+ title: 'Reduced costs',
+ description: `In addition to the cost savings of using an out-of-the-box
+ solution instead of building a custom version, implementing SAML can also
+ save you money by eliminating the need to maintain account information
+ across multiple services. With SAML, this is all managed by the IdP.`,
+ icon: require('../../static/img/products/icons/savings.svg').default,
+ },
+];
+
+const EnterpriseSSO = () => {
+ return (
+
+
+
+
+
+
+
+ 
+
+
+ 
+
+
+
+
+
+
+
+
+
+ Our open-source solution makes it easy to deploy Enterprise SSO with a
+ simple integration that connects to all Identity Providers. You can
+ integrate with our product using just a few lines of code.
+
+
+ Since our solution is self-hosted, you maintain complete control over
+ your data.
+
+
+
+
+
+ Creating a custom SAML or OpenID Connect integration for each IdP can
+ be very time-consuming and require a significant amount of resources.
+ This can lead to months of development time spent building custom
+ integrations for each IdP your customers use.
+
+
+ Our SSO solution allows you to go from the first line of code to
+ deployment in just a few days, saving you time and effort. Plus, we
+ offer custom integration support to help you every step of the way.{' '}
+
+
+
+
+
+ Most enterprises already use an IdP, so they prefer solution providers
+ with an Enterprise SSO integration. This is because they are already
+ using SAML or OpenID Connect for access management and security, so
+ anything outside of this workflow will be inconvenient for them.
+
+
+
+
+ );
+};
+
+export default EnterpriseSSO;
diff --git a/src/pages/index.js b/src/pages/index.js
new file mode 100644
index 0000000..670f1ce
--- /dev/null
+++ b/src/pages/index.js
@@ -0,0 +1,149 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+import NewsSection from '../components/NewsSection';
+import HeroSection from '../components/HeroSection';
+import ProductsSection from '../components/ProductsSection';
+import InvestorsSection from '../components/InvestorsSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+import FeatureSection from '../components/FeatureSection';
+
+const Icon3 = require('../../static/img/home-buildingblocks.svg').default;
+
+const title = 'BoxyHQ';
+const description = 'Security Building Blocks for Developers';
+
+const IndexPage = () => {
+ return (
+
+
+
+
+
+
+
+
+
+
+ The Importance of Developer Security
+
+
+
+
+ Cyber crimes are predicted to cost $10.5 trillion
+ annually by 2025, but time pressures often cause 70% of
+ development teams to skip crucial security steps.
+
+
+ In today's world, it is no longer sufficient to
+ prioritize productivity alone. The faster a developer
+ moves, the more potential security holes will be left
+ unaddressed.{' '}
+
+
+
+
+ Book a free developer-security session
+
+
+
+
+
+
+
+
+
+
+
+
+ Build or buy?
+
+
+
+
+ Save time and money with BoxyHQ's free open-source
+ solution. Available under an Apache 2.0 license, our
+ solutions make it easy for developers to collaborate and
+ innovate, without the need for custom building or
+ expensive fees.
+
+
+ Our solutions run in your environment, giving you full
+ control. We simply provide the building blocks to help
+ you succeed.
+
+
+
+
+ Contact Us
+
+
+
+
+
+
+
+
+
+
+
+
+ We have curated a list of awesome open-source developer security
+ tools.
+
+
+ It includes security principles and controls relevant to popular
+ compliance certifications (like ISO27001, SOC2, MVSP, etc.)
+
+
+
+
+ );
+};
+
+export default IndexPage;
diff --git a/src/pages/index.module.css b/src/pages/index.module.css
deleted file mode 100644
index 8225037..0000000
--- a/src/pages/index.module.css
+++ /dev/null
@@ -1,26 +0,0 @@
-/* stylelint-disable docusaurus/copyright-header */
-
-/**
- * CSS files with the .module.css suffix will be treated as CSS modules
- * and scoped locally.
- */
-
-.heroBanner {
- padding: 4rem 0;
- text-align: center;
- position: relative;
- overflow: hidden;
- background-color: #25c2a0;
-}
-
-@media screen and (max-width: 966px) {
- .heroBanner {
- padding: 2rem;
- }
-}
-
-.buttons {
- display: flex;
- align-items: center;
- justify-content: center;
-}
diff --git a/src/pages/markdown-page.md b/src/pages/markdown-page.md
deleted file mode 100644
index 9756c5b..0000000
--- a/src/pages/markdown-page.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: Markdown page example
----
-
-# Markdown page example
-
-You don't need React to write simple standalone pages.
diff --git a/src/pages/oss-friends.js b/src/pages/oss-friends.js
new file mode 100644
index 0000000..536a85e
--- /dev/null
+++ b/src/pages/oss-friends.js
@@ -0,0 +1,155 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+import TitleHeader from '../components/TitleHeader';
+
+const title = 'Our Open-source Friends';
+const description = 'Open-source projects and tools for an open world.';
+
+const friends = [
+ {
+ name: 'Cal.com',
+ description:
+ 'Cal.com is a scheduling tool that helps you schedule meetings without the back-and-forth emails.',
+ href: 'https://cal.com',
+ },
+ {
+ name: 'Crowd.dev',
+ description:
+ 'Centralize community, product, and customer data to understand which companies are engaging with your open source project.',
+ href: 'https://www.crowd.dev',
+ },
+ {
+ name: 'Documenso',
+ description:
+ 'The Open-Source DocuSign Alternative. We aim to earn your trust by enabling you to self-host the platform and examine its inner workings.',
+ href: 'https://documenso.com',
+ },
+ {
+ name: 'Erxes',
+ description:
+ 'The Open-Source HubSpot Alternative. A single XOS enables to create unique and life-changing experiences that work for all types of business.',
+ href: 'https://erxes.io',
+ },
+ {
+ name: 'Formbricks',
+ description:
+ 'Survey granular user segments at any point in the user journey. Gather up to 6x more insights with targeted micro-surveys. All open-source.',
+ href: 'https://formbricks.com',
+ },
+ {
+ name: 'GitWonk',
+ description:
+ 'GitWonk is an open-source technical documentation tool, designed and built focusing on the developer experience.',
+ href: 'https://gitwonk.com',
+ },
+ {
+ name: 'Hanko',
+ description:
+ 'Open-source authentication and user management for the passkey era. Integrated in minutes, for web and mobile apps.',
+ href: 'https://www.hanko.io',
+ },
+ {
+ name: 'HTMX',
+ description:
+ 'HTMX is a dependency-free JavaScript library that allows you to access AJAX, CSS Transitions, WebSockets, and Server Sent Events directly in HTML.',
+ href: 'https://htmx.org',
+ },
+ {
+ name: 'Infisical',
+ description:
+ 'Open source, end-to-end encrypted platform that lets you securely manage secrets and configs across your team, devices, and infrastructure.',
+ href: 'https://infisical.com',
+ },
+ {
+ name: 'Novu',
+ description:
+ 'The open-source notification infrastructure for developers. Simple components and APIs for managing all communication channels in one place.',
+ href: 'https://novu.co',
+ },
+ {
+ name: 'OpenBB',
+ description:
+ 'Democratizing investment research through an open source financial ecosystem. The OpenBB Terminal allows everyone to perform investment research, from everywhere.',
+ href: 'https://openbb.co',
+ },
+ {
+ name: 'Sniffnet',
+ description:
+ 'Sniffnet is a network monitoring tool to help you easily keep track of your Internet traffic.',
+ href: 'https://www.sniffnet.net',
+ },
+ {
+ name: 'Typebot',
+ description:
+ 'Typebot gives you powerful blocks to create unique chat experiences. Embed them anywhere on your apps and start collecting results like magic.',
+ href: 'https://typebot.io',
+ },
+ {
+ name: 'Webiny',
+ description:
+ 'Open-source enterprise-grade serverless CMS. Own your data. Scale effortlessly. Customize everything.',
+ href: 'https://www.webiny.com',
+ },
+ {
+ name: 'Webstudio',
+ description: 'Webstudio is an open source alternative to Webflow',
+ href: 'https://webstudio.is',
+ },
+];
+
+const OSSFriends = () => {
+ return (
+
+
+
+ {friend.name}
+
+
+
+ {friend.description}
+
+
+
+ Learn More
+
+
+
+
+
+
+ ))}
+
+ ))}
+
+
+
+
+ );
+};
+
+export default OSSFriends;
diff --git a/src/pages/pledge.js b/src/pages/pledge.js
new file mode 100644
index 0000000..1bb6b92
--- /dev/null
+++ b/src/pages/pledge.js
@@ -0,0 +1,72 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import TitleHeader from '../components/TitleHeader';
+
+const title = 'BoxyHQ pledges to keep our core open-source code open';
+const description = 'BoxyHQ pledges to keep our core open-source code open';
+
+function Team() {
+ return (
+
+
+
+ As long-time users and contributors to the open-source ecosystem, we
+ want to do the right thing for the community. That means we will make
+ sure that our core open-source code stays open. We will also strive to
+ use open standards where possible. We want to collaborate with the
+ community to build towards our vision to make security, compliance and
+ privacy easy for developers so they can focus on their core product
+ while being compliant.
+
+
+ BoxyHQ will need to have a viable way of making money soon since we
+ are a commercial company at the end of the day. But we’d like to do
+ this without having to do things that alienate our community, like
+ removing or blocking previously free and open features. We will
+ separate the Enterprise features from the open features with
+ intentionality, transparency and community inclusion in our
+ decision-making logic – focused on building Enterprise products that
+ are built to address complex, production-sensitive requirements, and
+ keeping the vast majority of end-user empowering capabilities in the
+ upstream open-source project. We will also do our best to be
+ transparent about which features are free and open source, and which
+ are not.
+
+
+ Of course, open-source code sometimes becomes obsolete. So, it can
+ stay open source but not viable. If we ever need to stop maintaining a
+ release of our open-source code, we will work with the community to
+ transition it to another maintainer. But in any case, we won’t stop
+ maintaining our open-source code without giving the community
+ reasonable notice of the transition. And we will do our best to
+ maintain backward compatibility for our enterprise features for a
+ reasonable lifespan.
+
+
+ We hope this pledge will give you peace of mind when using our
+ technologies. We do not want to put you at risk of becoming locked in
+ with us. We instead want you to happily and thoughtfully choose to
+ join our community, contribute to our projects, use our technologies,
+ and also buy from us in the future because of the value we provide and
+ not out of compulsion because you were left with no other choice.
+
+ Sincerely,
+ The BoxyHQ Team
+
+
+
+ * Inspired by{' '}
+ Ferymon
+
+
+
+ * Thanks to JJ and Heather from OSS Capital for reviewing drafts of
+ this post
+
+
+
+
+ );
+}
+export default Team;
diff --git a/src/pages/pricing.js b/src/pages/pricing.js
new file mode 100644
index 0000000..e1b9146
--- /dev/null
+++ b/src/pages/pricing.js
@@ -0,0 +1,38 @@
+import React, { useState } from 'react';
+import Layout from '@theme/Layout';
+
+import { Modal } from '../components/Modal';
+import { HubSpotPricingContactForm } from '../components/HubSpotForm';
+import { PricingSectionDesktop } from '../components/Pricing/PricingSectionDesktop';
+import { PricingSectionMobile } from '../components/Pricing/PricingSectionMobile';
+
+const title = 'Pricing for teams and companies of all sizes';
+const description =
+ 'BoxyHQ is proudly open-source and all of our solutions are available to self-host for free.';
+
+const Pricing = () => {
+ const [opened, setOpened] = useState(false);
+ const [formId, setFormId] = useState('');
+
+ return (
+
+
+ {title}
+
+ {description}
+
+
+
+
+ );
+};
+
+export default Pricing;
diff --git a/src/pages/privacy-vault.js b/src/pages/privacy-vault.js
new file mode 100644
index 0000000..f137b08
--- /dev/null
+++ b/src/pages/privacy-vault.js
@@ -0,0 +1,126 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+
+import HeroSection from '../components/HeroSection';
+import FeatureSection from '../components/FeatureSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+import SectionLayout from '../components/SectionLayout';
+
+const title = 'Data Privacy Vault';
+const description =
+ "Protect your customer's data and your customer's trust with an open-source solution that keeps your data safe.";
+
+const ProductIcon =
+ require('../../static/img/products/privacy-vault/logo.svg').default;
+
+const Icon1 =
+ require('../../static/img/products/privacy-vault/hacker_mind.svg').default;
+
+const Icon2 =
+ require('../../static/img/products/privacy-vault/security.svg').default;
+
+const PrivacyVault = () => {
+ return (
+
+
+
+ Companies like yours are collecting more and more sensitive data these
+ days and with cybercrime at an all-time high, customers are more
+ worried than ever about how their data is secured. GDPR was a big step
+ in how customers' data is collected and used, but safeguarding this
+ data is ultimately what your customers are most worried about.
+
+
+
+
+
+
+
+
+
+ Taking the best practices from companies like Google, Apple
+ and Facebook who have internally built privacy data vaults,
+ BoxyHQ offers an open-source solution to centralize, isolate
+ and govern all the sensitive data you collect.
+
+ With our Privacy Vault you can:
+
+ -
+ Identify and store all sensitive data from their application
+ database and move it to the vault
+
+ -
+ Replace the sensitive data in their application database
+ with opaque tokens that can then be exchanged with the
+ actual data from the vault at the point it's really needed
+
+ -
+ Gain control over where the sensitive data goes and who has
+ access to it and for how long
+
+ -
+ Create access policies that adhere to data regulations and
+ geographic regulations
+
+ -
+ Be equipped with the ability to respond to DSRs (Data
+ Subject Requests) from customers
+
+ - Create Healthcare, Fintech or generic PII vaults
+
+
+
+
+
+
+
+
+
+ By using a privacy vault even if you were attacked the hacker would
+ only gain access to opaque identifiers. The hacker would have then to
+ attach both your vault and your key store to successfully decrypt the
+ opaque tokens they possess.
+
+
+ Apart from this, you get full governance over who has access to the
+ sensitive data and for how long, this simplifies all sorts of
+ compliance certifications and regulations like GDPR, PCI, HIPAA, ISO
+ 27001, SOC2, etc.
+
+
+
+
+ );
+};
+
+export default PrivacyVault;
diff --git a/src/pages/privacy.html.js b/src/pages/privacy.html.js
new file mode 100644
index 0000000..89723dd
--- /dev/null
+++ b/src/pages/privacy.html.js
@@ -0,0 +1,48 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import { useColorMode } from '@docusaurus/theme-common';
+
+const title = '';
+const description = 'Privacy & Cookies Policy';
+
+const IFrame = () => {
+ const { colorMode } = useColorMode();
+
+ return (
+
+ );
+};
+
+function Privacy() {
+ if (typeof window !== 'undefined') {
+ window.addEventListener(
+ 'message',
+ (event) => {
+ if (event.data) {
+ const { message, contentHeight } = event.data;
+ if (message === 'Updating content height') {
+ var _doc = document.getElementById('privacy-policy-iframe');
+ if (!_doc) return false;
+ _doc.style.height = contentHeight;
+ }
+ }
+ },
+ false
+ );
+ }
+
+ return (
+
+
+
+
+
+ );
+}
+export default Privacy;
diff --git a/src/pages/saas-registration.js b/src/pages/saas-registration.js
new file mode 100644
index 0000000..4871a71
--- /dev/null
+++ b/src/pages/saas-registration.js
@@ -0,0 +1,180 @@
+import React, { useState } from 'react';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+import { Modal } from '../components/Modal';
+import { HubSpotSaasContactForm } from '../components/HubSpotFormSaaS';
+import NewsSection from '../components/NewsSection';
+import HeroSection from '../components/HeroSection';
+import InvestorsSection from '../components/InvestorsSection';
+import CustomersSection from '../components/CustomersSection';
+import DeveloperCommunitySection from '../components/DeveloperCommunitySection';
+import SectionLayout from '../components/SectionLayout';
+
+const title = 'BoxyHQ for Startups';
+const description = 'SaaS Signup';
+
+const SaasRegistration = () => {
+ const [opened, setOpened] = useState(false);
+ const [formId, setFormId] = useState('05572d01-d7b6-4a83-b654-2e6135b95bd');
+
+ return (
+
+ {
+ setFormId(formId);
+ setOpened(true);
+ },
+ className: 'button--primary',
+ },
+ ]}
+ />
+
+
+
+
+
+
+
+ -
+ Reduce time to market: Build and ship
+ enterprise-grade products
+
+ -
+ Cost Savings: Save money optimizing development costs
+
+ -
+ Develop secure applications: Our APIs integrate
+ security best practices into your development process
+
+ -
+ Enhanced Efficiency: With an intuitive interface and
+ powerful features, businesses can automate tasks, optimize
+ workflows, and maximize efficiency
+
+ -
+ Full Support: BoxyHQ is committed to providing
+ exceptional support to its customers, ensuring a smooth
+ onboarding process and continued assistance throughout their
+ journey
+
+ -
+ Advanced Security: BoxyHQ prioritizes data security,
+ employing robust measures to safeguard sensitive information
+ and ensure peace of mind
+
+ -
+ Seamless Integrations: Integrate with the most
+ popular SSO providers such as Okta, Azure AD, Auth0, Google
+ and more
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Special Offer
+
+
+
+
+ To celebrate the launch, we are offering an exclusive
+ opportunity to join the waitlist for the SaaS platform
+ and enjoy a remarkable 50% off the first year's
+ subscription. By signing up before August 1, businesses
+ can take advantage of this limited-time offer and unlock
+ the full potential of our solution.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Join the Pre-Launch Waitlist
+
+
+
+
+ To secure your spot and claim this irresistible offer,
+ interested businesses are encouraged to fill out the
+ form. Simply provide your Name, Email, Product of
+ interest, and potential date of implementation. Don't
+ miss out on this opportunity to transform your business!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+};
+
+export default SaasRegistration;
diff --git a/src/pages/team.js b/src/pages/team.js
new file mode 100644
index 0000000..d28fa94
--- /dev/null
+++ b/src/pages/team.js
@@ -0,0 +1,91 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+import Profile from '../components/Profile';
+import TitleHeader from '../components/TitleHeader';
+
+const title = 'Team';
+const description =
+ 'At BoxyHQ we are a diverse team of individuals from all over the world who share a passion for building a simpler and more open way to be enterprise-ready.';
+
+function Team() {
+ return (
+
+
+
+
+ );
+}
+export default Team;
diff --git a/src/theme/BlogListPage/Author/index.js b/src/theme/BlogListPage/Author/index.js
new file mode 100644
index 0000000..6e0b615
--- /dev/null
+++ b/src/theme/BlogListPage/Author/index.js
@@ -0,0 +1,45 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+
+import styles from './styles.module.css';
+
+const Author = ({ authors, name, title, url, image }) => {
+ return (
+
+ {authors && authors.length > 1 ? (
+ <>
+
+ ![{authors[0].name}]({authors[0].image_url})
+
+
+ ![{authors[1].name}]({authors[1].image_url})
+
+
+ ) : (
+ <>
+
+
+
+
+ {name}
+
+
+
+ {title}
+
+
+
+ )}
+
+ );
+};
+
+export default Author;
diff --git a/src/theme/BlogListPage/Author/styles.module.css b/src/theme/BlogListPage/Author/styles.module.css
new file mode 100644
index 0000000..5a2d81a
--- /dev/null
+++ b/src/theme/BlogListPage/Author/styles.module.css
@@ -0,0 +1,8 @@
+.authorUrl {
+ color: var(--theme-text-color);
+}
+
+.avatarSubtitle {
+ overflow: hidden;
+ height: 25px;
+}
diff --git a/src/theme/BlogListPage/ListItem/index.js b/src/theme/BlogListPage/ListItem/index.js
new file mode 100644
index 0000000..bd10be3
--- /dev/null
+++ b/src/theme/BlogListPage/ListItem/index.js
@@ -0,0 +1,49 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+
+import styles from './styles.module.css';
+import Author from '../Author';
+
+const ListItem = ({ content }) => {
+ const { frontMatter, metadata } = content;
+
+ const { authors, author, author_title, author_url, author_image_url } =
+ frontMatter;
+
+ const imageUrl = frontMatter.image ?? '/img/default-blog-post-banner.png';
+
+ return (
+
+
+
+
+
+
+ 
+
+
+
+ {metadata.formattedDate}
+
+ {metadata.title}
+
+
+
+ {blogTitle}
+ {blogDescription}
+
+ {posts.map(({ content }) => (
+
+
+ );
+}
diff --git a/src/theme/BlogListPage/styles.module.css b/src/theme/BlogListPage/styles.module.css
new file mode 100644
index 0000000..08d7e4b
--- /dev/null
+++ b/src/theme/BlogListPage/styles.module.css
@@ -0,0 +1,16 @@
+.root {
+ max-width: var(--ifm-container-width);
+ margin: 2rem auto;
+ padding: 0 1rem;
+}
+
+.description {
+ line-height: 35px;
+ font-size: 1.2rem;
+ font-weight: normal;
+}
+@media screen and (min-width: 900px) {
+ .root {
+ margin-top: 5rem;
+ }
+}
diff --git a/src/theme/CodeBlock/index.js b/src/theme/CodeBlock/index.js
new file mode 100644
index 0000000..58c5265
--- /dev/null
+++ b/src/theme/CodeBlock/index.js
@@ -0,0 +1,14 @@
+import React from 'react';
+import CodeBlock from '@theme-original/CodeBlock';
+
+import Prism from 'prism-react-renderer/prism';
+(typeof global !== 'undefined' ? global : window).Prism = Prism;
+require('prismjs/components/prism-ruby');
+
+export default function CodeBlockWrapper(props) {
+ return (
+ <>
+ 
Terms and Conditions 1BoxyHQ IncTerms and ConditionsEffective as of August 9, 2021.This agreement constitutes a binding legal contract between BoxyHQ Inc. (“BoxyHQ Inc.”) (sometimes referred to as “we”, “us” or “our”) and you, with respect to your use of https://boxyhq.com and all websites, applications and communications that post a link to this agreement (collectively, the “Site”)(“Terms and Conditions”).We reserve our right to change these Terms and Conditions in the future. Except as explicitly stated otherwise, your continued use of the Site will constitute deemed acceptance of our updated Terms and Conditions. 1. Site(a) We may from time to time, at our sole and absolute discretion and without notice to you, update the Site (or any part of it). We will not be liable to you or any third party for any modification, variation, interruption, suspension or discontinuation of the Site. (b) The Site may provide links to third party websites that are not owned, managed or controlled by us. You expressly acknowledge and agree that we are not responsible for the content of those third party websites. You are encouraged to read that third party’s terms and conditions, privacy policy and any other document that governs your relationship with that third party. (c) The Site uses cookies in accordance with our Cookies Policy, which can be found here: https://boxyhq.com/privacy.2. Account
+
Terms and Conditions 2(a) To access certain features on the Site, you may be required to create an account with us in the form provided by us. (b) You agree that by registering an account with us that you: ; all information you provide to us during the registration process is true and accurate to the best of your belief; you are at least 18 years of age; and you have capacity to enter into contractual arrangements.(c) You agree that you are solely responsible for your account and all activities conducted on your account. You must keep your password and any other login information private and secure. Your account is registered to you, and you may not assign, transfer or otherwise dispose of your interest in your account without our express written permission.(d) We may, from time to time, provide rules that govern your activities whilst using your account (“Account Rules”). You expressly acknowledge and agree that you will abide by these Rules. Should you be in breach of the Account Rules, we may (at our absolute and sole discretion) restrict, prohibit, suspend or terminate your account. Should your account be terminated in accordance with this clause, we are not liable to you, or any third party, for any loss or damage suffered. (e) You may terminate your account, for any reason, by notifying us. You agree, however, that by terminating your account, your experience on the Site may be limited. We are not liable to you, or any third party, for any loss or damage suffered because of this. 3. Communications(a) By using the Site and providing your e-mail address, you agree to subscribe to newsletters, marketing or promotional materials and other information we may send. You may unsubscribe from these emails at any time. 4. User Submitted Content(a) The Site may allow you to publish, share, store and otherwise make available certain information, text, graphics, videos, or other content (“Content”).(b) We cannot guarantee the accuracy, integrity or quality of Content posted by users of the Site.(c) We are not liable for any statements, representations, or Content provided by Site
+
Terms and Conditions 3users. Any opinions, advice or recommendations expressed therein are those of the users providing such Content and not those of BoxyHQ Inc..(d) You represent and warrant that you own or otherwise control the Content you post on the Site, and that the sharing of your Content on or through the Site does not violate the privacy rights, publicity rights, copyrights, contract rights or any other rights of any person or entity. (e) We take no responsibility and assume no liability for Content you or any third party posts on or through the Site. However, by posting Content you grant us a perpetual, worldwide, irrevocable, unrestrictive, non-exclusive royalty-free licence to use any Content in any manner whatsoever without compensation or attribution to you.5. Prohibited UsesUnless explicitly agreed by us, you acknowledge and agree that you may not use our Site for the following purposes: use the Site in any way that violates any applicable local, national or international law or regulationimpersonate or attempt to impersonate any person or entityengage in any conduct that restricts or inhibits anyone’s use or enjoyment of the Sitemonitor or copy any of the material on the Site for any unauthorized purpose without our prior written consentattempt to gain unauthorized access to, interfere with, damage or disrupt any parts of the Siteuse the Site in any manner that could disable, overburden, damage, or impair the Siteattempt to interfere with the proper working of the Site in any way whatsoever6. Fees and Payment(a) You may be required to purchase or pay a fee to access some features of the Site. You agree to pay all fees due and payable to us (including all applicable taxes) at the prices then in effect for your purchases. (b) You represent and warrant that the information you provide to us is true, correct
+
Terms and Conditions 4and complete. (c) Where payments are processed through our Site using third party payment processors, you also agree to any terms and conditions set by those payment processors.7. Free TrialWhere we provide you with a free trial to use the Site, for the duration of the free trial period, we may at our sole discretion: (i) limit your ability to access certain features; (ii) limit any technical support to you that may usually be available to paying users; (iii) without notice to you, stop your free trial.8. Specifications(a) We may, from time to time, set certain minimum specifications required to access our Site to ensure all users have the best possible experience. You are solely responsible to obtain, keep and maintain all equipment and other software that meets our minimum specifications to enable you to have the best possible experience of our Site. (b) We may from time to time, at our sole discretion and without notice to you, make variations, modifications, alterations or updates to our Site (“Enhancements”). These Enhancements may be made to improve our Site to you or to comply with relevant legal requirements.(c) We will use reasonable endeavors to notify you of any scheduled disruptions to our Site, including those due to any Enhancements. However, regardless of whether a disruption is scheduled or not, we are not liable to you or any third party for any loss or damage caused by any disruption to our Site.9. Copyrights and Trademarks(a) Except as expressly stated otherwise, you acknowledge and agree that the original content on the Site, and the software, features and functionality comprising the Site are the exclusive property of BoxyHQ Inc. (the “Materials”) and its licensors.(b) You agree you will not copy, reproduce, create derivative works from, transmit or distribute the Materials in any way without our prior written consent. 10. Limitation of Liability, Indemnities and Warranties
+
Terms and Conditions 5(a) Except as expressly provided by law, we shall not be liable to you or any third parties for any loss, damage, expenses or any other liability arising directly or indirectly from the performance of our services to you. To the fullest extent permitted by law, all warranties or conditions implied by statute, at law, by trade, custom or otherwise are excluded. (b) You acknowledge and agree that you assume sole and entire responsibility for, and indemnify and hold us harmless from, any and all claims, liabilities, losses, expenses, responsibilities and damages by reason of any claim, proceedings, action, liability or injury arising out of or as a result of (i) your conduct in relation to these Terms and Conditions; (ii) your use of any material, advice or other results of the services provided to you; (iii) your relations with your clients and/or other third parties; or (iv) any breach of these Terms and Conditions by you. 11. Term and Termination(a) These Terms and Conditions will remain in full force and effect while you use the Site.(b) We may, without notice to you, immediately stop providing any services to you at our sole discretion for any reason whatsoever. (c) Where these Terms and Conditions are terminated in accordance with these Terms and Conditions, they will terminate without prejudice to any rights either party may have had against the other prior to termination. Further, all provisions of which by their nature should survive termination shall survive termination, including, without limitation: (i) all intellectual property you have granted us under these Terms and Conditions; and (ii) your obligation to pay any fees due to us at the time of termination; and (iii) warranty disclaimers, indemnity and limitations of liability. 12. Assignment(a) These Terms and Conditions will bind and inure for the benefit of the parties, including their respective successors, permitted assigns and legal representatives.(b) We may, without notice to you, immediately stop providing any services to you at our sole discretion for any reason whatsoever. (c) Provided your rights are not affected under these Terms and Conditions, we will be permitted to assign our interest in these Terms and Conditions without prior notice to you. However, you may not assign, transfer, novate or other dispose of
+
Terms and Conditions 6your rights and obligations under these Terms and Conditions without our express written approval (which we may withhold in our sole discretion). 13. PrivacyYou acknowledge that you have read and understood the terms of BoxyHQ Inc.’s Privacy Policy, which can be found here: https://boxyhq.com/privacy. You agree that we may use your information (including disclosure to third parties) in accordance with the terms of our Privacy Policy.14. Non-WaiverOur failure to exercise, or delay in exercising, our rights under these Terms and Conditions does not operate as a waiver of that right.15. Exclusion of Implied RelationshipsNothing in these Terms and Conditions shall be deemed or construed to constitute any party a partner, agent, representative, employer or employee of another party or to create any trust or commercial partnership unless specifically otherwise provided. We do not owe you any duty of good faith under these Terms and Conditions. 16. SeverabilityIf any part of these Terms and Conditions are held to be illegal, invalid, or unenforceable, then that part shall be deemed deleted and shall not affect the validity and enforceability of the remaining provisions of these Terms and Conditions. 17. Entire AgreementThese Terms and Conditions constitute the entire agreement between the parties with respect to the Company’s services and supersede all previous versions of the Terms and Conditions, understandings, arrangements, agreements, and communications, whether verbal or written, between the parties.18. Applicable Law and JurisdictionThese Terms and Conditions shall be governed by and construed in accordance with Delaware law. Both parties agree to submit to the jurisdiction of the courts of
+
Terms and Conditions 7Delaware with respect to any claim or dispute arising out of these Terms and Conditions.
+
+
+
+
+
+
diff --git a/static/videos/create-directory.gif b/static/videos/create-directory.gif
new file mode 100644
index 0000000..425ad83
Binary files /dev/null and b/static/videos/create-directory.gif differ
diff --git a/yarn.lock b/yarn.lock
index 44955ab..17edf77 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1609,7 +1609,7 @@
"@types/react" "*"
prop-types "^15.6.2"
-"@docusaurus/theme-classic@2.4.1", "@docusaurus/theme-classic@^2.4.1":
+"@docusaurus/theme-classic@2.4.1":
version "2.4.1"
resolved "https://registry.npmmirror.com/@docusaurus/theme-classic/-/theme-classic-2.4.1.tgz"
integrity sha512-Rz0wKUa+LTW1PLXmwnf8mn85EBzaGSt6qamqtmnh9Hflkc+EqiYMhtUJeLdV+wsgYq4aG0ANc+bpUDpsUhdnwg==
@@ -1662,7 +1662,7 @@
use-sync-external-store "^1.2.0"
utility-types "^3.10.0"
-"@docusaurus/theme-search-algolia@2.4.1", "@docusaurus/theme-search-algolia@^2.4.1":
+"@docusaurus/theme-search-algolia@2.4.1":
version "2.4.1"
resolved "https://registry.npmmirror.com/@docusaurus/theme-search-algolia/-/theme-search-algolia-2.4.1.tgz"
integrity sha512-6BcqW2lnLhZCXuMAvPRezFs1DpmEKzXFKlYjruuas+Xy3AQeFzDJKTJFIm49N77WFCTyxff8d3E4Q9pi/+5McQ==