Skip to content

Commit d221657

Browse files
msukkarimsukkari
committed
revamp auth docs
1 parent 6191bca commit d221657

File tree

9 files changed

+203
-115
lines changed

9 files changed

+203
-115
lines changed

‎docs/docs.json

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,10 @@
7272
"group": "Authentication",
7373
"pages": [
7474
"docs/configuration/auth/overview",
75-
"docs/configuration/auth/roles-and-permissions"
75+
"docs/configuration/auth/providers",
76+
"docs/configuration/auth/inviting-members",
77+
"docs/configuration/auth/roles-and-permissions",
78+
"docs/configuration/auth/faq"
7679
]
7780
},
7881
"docs/configuration/transactional-emails",

‎docs/docs/configuration/auth/faq.mdx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: FAQ
3+
---
4+
5+
This page covers a range of frequently asked questions about Sourcebot's built-in authentication system.
6+
7+
<AccordionGroup>
8+
<Accordion title="Can I disable the authentication system?">
9+
No, at this time it's not possible to disable the authentication system. If this is preventing you from deploying Sourcebot
10+
within your organization please [reach out](https://www.sourcebot.dev/contact)
11+
</Accordion>
12+
13+
<Accordion title="I don't want to restrict access to my Sourcebot deployment, what should I do?">
14+
Every user must register an account within your Sourcebot deployment. However, this dosn't mean their access
15+
is restricted.
16+
17+
Unless member approval is required, anyone can sign up for an account on your deployment and immediately be granted access.
18+
</Accordion>
19+
20+
<Accordion title="Does any data related to authentication (emails, passwords, etc) leave my deployment?">
21+
**No data related to authentication (or your code) leaves your deployment**. Authentication is handled
22+
purely by your deployment and the authentication providers you configure.
23+
24+
This data does not leave your device and is stored within in the database managed by your deployment. If you're
25+
using credential login, passwords are encrypted at rest and in transit.
26+
</Accordion>
27+
28+
<Accordion title="I'm deploying Sourcebot behind an identity proxy, do I still need to create an account in Sourcebot?">
29+
<Note>Please note that IAP bridges are an enterprise feature</Note>
30+
Sourcebot supports connecting your identity proxy directly into the built-in auth system using an IAP bridge. This allows Sourcebot to
31+
register and authenticate automatically on a successful identity proxy log in.
32+
33+
Sourcebot currently supports [GCP IAP](/docs/configuration/auth/providers#gcp-iap). If you're using a different IAP
34+
and require support, please [reach out](https://www.sourcebot.dev/contact)
35+
</Accordion>
36+
37+
<Accordion title="How does Sourcebot implement authentication?">
38+
Sourcebot uses [Auth.js](https://authjs.dev/) as its underlying authentication framework. Auth.js provides authentication providers
39+
(credientials, Google, GitHub, etc) and an interface to enable user registration and log in. Internally, Auth.js uses JWT to provide
40+
Sourcebot secure and reliable information about user authentication.
41+
</Accordion>
42+
</AccordionGroup>
43+
44+
45+
Have a question that's not answered here? Submit it on our [GitHub discussions](https://github.com/sourcebot-dev/sourcebot/discussions)
46+
page and we'll get back to you as soon as we can!

‎docs/docs/configuration/auth/inviting-members.mdx

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Inviting Members
3+
sidebarTitle: Inviting members
4+
---
5+
6+
There are various ways to configure how members can join a Sourcebot deployment.
7+
8+
**By default, Sourcebot doesn't
9+
require new members to be approved**. This means that new sign ups on your deployment are automatically added to
10+
the organization.
11+
12+
Member approval can be configured by an owner of the deployment by navigating to **Settings -> Members**:
13+
14+
![Member Approval Toggle](/images/member_approval_toggle.png)
15+
16+
## Invite link
17+
18+
If member approval is required, an owner of the deployment can enable an invite link. When enabled, users
19+
can use this invite link to register and be automatically added to the organization without approval:
20+
21+
![Invite Link Toggle](/images/invite_link_toggle.png)

‎docs/docs/configuration/auth/overview.mdx

Lines changed: 16 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -4,118 +4,23 @@ title: Overview
44

55
<Warning>If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/docs/configuration/environment-variables) environment variable.</Warning>
66

7-
Sourcebot has built-in authentication that gates access to your organization. OAuth, email codes, and email / password are supported.
7+
Sourcebot's built-in authentication system gates your deployment, and allows administrators to manage users and their permissions.
8+
9+
<CardGroup cols={2}>
10+
<Card horizontal title="Authentication providers" icon="lock" href="/docs/configuration/auth/providers">
11+
Configure additional authentication providers for your deployment.
12+
</Card>
13+
<Card horizontal title="Inviting members" icon="user" href="/docs/configuration/auth/providers">
14+
Learn how to configure how members join your deployment.
15+
</Card>
16+
<Card horizontal title="Roles and permissions" icon="shield" href="/docs/configuration/auth/roles-and-permissions">
17+
Learn more about the different roles and permissions in Sourcebot.
18+
</Card>
19+
<Card horizontal title="FAQ" icon="question" href="/docs/configuration/auth/faq">
20+
Have a question about Sourcebot's auth system? We might have the answers here.
21+
</Card>
22+
</CardGroup>
823

9-
The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/docs/configuration/auth/overview#approving-new-members) by the owner.
10-
11-
![Login Page](/images/login.png)
12-
13-
14-
# Approving New Members
15-
16-
All account registrations after the first account must be approved by the owner. The owner can see all join requests by going into **Settings -> Members**.
17-
18-
You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/docs/configuration/transactional-emails)
19-
# Authentication Providers
20-
21-
To enable an authentication provider in Sourcebot, configure the required environment variables for the provider. Under the hood, Sourcebot uses Auth.js which supports [many providers](https://authjs.dev/getting-started/authentication/oauth). Submit a [feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas) if you want us to add support for a specific provider.
22-
23-
## Core Authentication Providers
24-
25-
### Email / Password
26-
---
27-
Email / password authentication is enabled by default. It can be **disabled** by setting `AUTH_CREDENTIALS_LOGIN_ENABLED` to `false`.
28-
29-
### Email codes
30-
---
31-
Email codes are 6 digit codes sent to a provided email. Email codes are enabled when transactional emails are configured using the following environment variables:
32-
33-
- `AUTH_EMAIL_CODE_LOGIN_ENABLED`
34-
- `SMTP_CONNECTION_URL`
35-
- `EMAIL_FROM_ADDRESS`
36-
37-
38-
See [transactional emails](/docs/configuration/transactional-emails) for more details.
39-
40-
## Enterprise Authentication Providers
41-
42-
The following authentication providers require an [enterprise license](/docs/license-key) to be enabled.
43-
44-
### GitHub
45-
---
46-
47-
[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github)
48-
49-
**Required environment variables:**
50-
- `AUTH_EE_GITHUB_CLIENT_ID`
51-
- `AUTH_EE_GITHUB_CLIENT_SECRET`
52-
53-
Optional environment variables:
54-
- `AUTH_EE_GITHUB_BASE_URL` - Base URL for GitHub Enterprise (defaults to https://github.com)
55-
56-
### GitLab
57-
---
58-
59-
[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab)
60-
61-
**Required environment variables:**
62-
- `AUTH_EE_GITLAB_CLIENT_ID`
63-
- `AUTH_EE_GITLAB_CLIENT_SECRET`
64-
65-
Optional environment variables:
66-
- `AUTH_EE_GITLAB_BASE_URL` - Base URL for GitLab instance (defaults to https://gitlab.com)
67-
68-
### Google
69-
---
70-
71-
[Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google)
72-
73-
**Required environment variables:**
74-
- `AUTH_EE_GOOGLE_CLIENT_ID`
75-
- `AUTH_EE_GOOGLE_CLIENT_SECRET`
76-
77-
### GCP IAP
78-
---
79-
80-
<Note>If you're running Sourcebot in an environment that blocks egress, make sure you allow the [IAP IP ranges](https://www.gstatic.com/ipranges/goog.json)</Note>
81-
82-
Custom provider built to enable automatic Sourcebot account registration/login when using GCP IAP.
83-
84-
**Required environment variables**
85-
- `AUTH_EE_GCP_IAP_ENABLED`
86-
- `AUTH_EE_GCP_IAP_AUDIENCE`
87-
- This can be found by selecting the ⋮ icon next to the IAP-enabled backend service and pressing `Get JWT audience code`
88-
89-
### Okta
90-
---
91-
92-
[Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta)
93-
94-
**Required environment variables:**
95-
- `AUTH_EE_OKTA_CLIENT_ID`
96-
- `AUTH_EE_OKTA_CLIENT_SECRET`
97-
- `AUTH_EE_OKTA_ISSUER`
98-
99-
### Keycloak
100-
---
101-
102-
[Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak)
103-
104-
**Required environment variables:**
105-
- `AUTH_EE_KEYCLOAK_CLIENT_ID`
106-
- `AUTH_EE_KEYCLOAK_CLIENT_SECRET`
107-
- `AUTH_EE_KEYCLOAK_ISSUER`
108-
109-
### Microsoft Entra ID
110-
111-
[Auth.js Microsoft Entra ID Provider Docs](https://authjs.dev/getting-started/providers/microsoft-entra-id)
112-
113-
**Required environment variables:**
114-
- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_ID`
115-
- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_SECRET`
116-
- `AUTH_EE_MICROSOFT_ENTRA_ID_ISSUER`
117-
118-
---
11924

12025
# Troubleshooting
12126

‎docs/docs/configuration/auth/providers.mdx

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Providers
3+
---
4+
5+
Sourcebot supports a wide range of different authentication providers through it's integration with [Auth.js](https://authjs.dev/). This page
6+
highlights how to configure the various supported providers.
7+
8+
If theres an authentication provider you'd like us to support, please [reach out](https://www.sourcebot.dev/contact).
9+
10+
# Core Authentication Providers
11+
12+
### Email / Password
13+
---
14+
Email / password authentication is enabled by default. It can be **disabled** by setting `AUTH_CREDENTIALS_LOGIN_ENABLED` to `false`.
15+
16+
### Email codes
17+
---
18+
Email codes are 6 digit codes sent to a provided email. Email codes are enabled when transactional emails are configured using the following environment variables:
19+
20+
- `AUTH_EMAIL_CODE_LOGIN_ENABLED`
21+
- `SMTP_CONNECTION_URL`
22+
- `EMAIL_FROM_ADDRESS`
23+
24+
25+
See [transactional emails](/docs/configuration/transactional-emails) for more details.
26+
27+
# Enterprise Authentication Providers
28+
29+
The following authentication providers require an [enterprise license](/docs/license-key) to be enabled.
30+
31+
### GitHub
32+
---
33+
34+
[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github)
35+
36+
**Required environment variables:**
37+
- `AUTH_EE_GITHUB_CLIENT_ID`
38+
- `AUTH_EE_GITHUB_CLIENT_SECRET`
39+
40+
Optional environment variables:
41+
- `AUTH_EE_GITHUB_BASE_URL` - Base URL for GitHub Enterprise (defaults to https://github.com)
42+
43+
### GitLab
44+
---
45+
46+
[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab)
47+
48+
**Required environment variables:**
49+
- `AUTH_EE_GITLAB_CLIENT_ID`
50+
- `AUTH_EE_GITLAB_CLIENT_SECRET`
51+
52+
Optional environment variables:
53+
- `AUTH_EE_GITLAB_BASE_URL` - Base URL for GitLab instance (defaults to https://gitlab.com)
54+
55+
### Google
56+
---
57+
58+
[Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google)
59+
60+
**Required environment variables:**
61+
- `AUTH_EE_GOOGLE_CLIENT_ID`
62+
- `AUTH_EE_GOOGLE_CLIENT_SECRET`
63+
64+
### GCP IAP
65+
---
66+
67+
<Note>If you're running Sourcebot in an environment that blocks egress, make sure you allow the [IAP IP ranges](https://www.gstatic.com/ipranges/goog.json)</Note>
68+
69+
Custom provider built to enable automatic Sourcebot account registration/login when using GCP IAP.
70+
71+
**Required environment variables**
72+
- `AUTH_EE_GCP_IAP_ENABLED`
73+
- `AUTH_EE_GCP_IAP_AUDIENCE`
74+
- This can be found by selecting the ⋮ icon next to the IAP-enabled backend service and pressing `Get JWT audience code`
75+
76+
### Okta
77+
---
78+
79+
[Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta)
80+
81+
**Required environment variables:**
82+
- `AUTH_EE_OKTA_CLIENT_ID`
83+
- `AUTH_EE_OKTA_CLIENT_SECRET`
84+
- `AUTH_EE_OKTA_ISSUER`
85+
86+
### Keycloak
87+
---
88+
89+
[Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak)
90+
91+
**Required environment variables:**
92+
- `AUTH_EE_KEYCLOAK_CLIENT_ID`
93+
- `AUTH_EE_KEYCLOAK_CLIENT_SECRET`
94+
- `AUTH_EE_KEYCLOAK_ISSUER`
95+
96+
### Microsoft Entra ID
97+
98+
[Auth.js Microsoft Entra ID Provider Docs](https://authjs.dev/getting-started/providers/microsoft-entra-id)
99+
100+
**Required environment variables:**
101+
- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_ID`
102+
- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_SECRET`
103+
- `AUTH_EE_MICROSOFT_ENTRA_ID_ISSUER`
104+
105+
---

‎docs/images/invite_link_toggle.png

175 KB
Loading

‎docs/images/member_approval_toggle.png

251 KB
Loading

‎packages/web/src/app/components/authSecurityNotice.tsx

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,15 @@ export const AuthSecurityNotice = ({ closable = false }: AuthSecurityNoticeProps
8282
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z" />
8383
</svg>
8484
<span>
85-
<strong>Security Notice:</strong> Authentication data is managed by your deployment and is encrypted at rest. Zero data leaves your deployment.
85+
<strong>Security Notice:</strong> Authentication data is managed by your deployment and is encrypted at rest. Zero data leaves your deployment.{' '}
86+
<a
87+
href="https://docs.sourcebot.dev/docs/configuration/auth/faq"
88+
target="_blank"
89+
rel="noopener"
90+
className="underline text-[var(--highlight)] hover:text-[var(--highlight)]/80 font-medium"
91+
>
92+
Learn more
93+
</a>
8694
</span>
8795
</p>
8896
</div>

‎packages/web/src/app/onboard/page.tsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,8 @@ export default async function Onboarding({ searchParams }: OnboardingProps) {
7373
icon: <GitBranchIcon className="w-4 h-4" />,
7474
},
7575
{
76-
title: "Setup additional authentication providers",
77-
description: "Learn how to setup additional authentication providers for your organization",
76+
title: "Authentication system",
77+
description: "Learn how to setup additional auth providers, invite members, and more",
7878
href: "https://docs.sourcebot.dev/docs/configuration/auth/overview",
7979
icon: <LockIcon className="w-4 h-4" />,
8080
}

0 commit comments

Comments
 (0)