Skip to content

Commit dc1e68e

Browse files
danciaclaradanciaclara
authored
Merge pull request #391 from makeplane/sso-cloud
SSO Cloud
2 parents bb180c7 + 87fe538 commit dc1e68e

4 files changed

Lines changed: 171 additions & 20 deletions

File tree

‎docs/authentication/sso.mdx‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: Single sign-on (SSO)
3+
sidebar_label: Single sign-on (SSO)
4+
hide_title: true
5+
description: Configure SAML or OIDC authentication to let your team sign in to Plane using corporate identity provider credentials.
6+
---
7+
8+
import Tags from "@site/src/components/Tags";
9+
10+
<div className="tag-wrapper">
11+
<h1>Single sign-on (SSO)</h1>
12+
<Tags tags={[{ name: "Business", link: "https://plane.so/pricing", additionalClass: "business" }]} />
13+
</div>
14+
15+
Single sign-on (SSO) lets your team sign in to Plane using your organization's identity provider instead of managing separate passwords. This centralizes authentication, improves security, and simplifies user management.
16+
17+
## Verify your domain
18+
19+
Before configuring SSO, you must verify ownership of your organization's email domain. This ensures only authorized administrators can configure authentication for that domain.
20+
21+
:::caution
22+
Each domain can only be verified in one workspace at a time. If you've already verified a domain in another workspace, you'll need to remove it there first.
23+
:::
24+
25+
### Add your domain
26+
27+
1. Navigate to **Workspace Settings → Identity**.
28+
2. Under **Domain management**, click **Add domain**.
29+
30+
![Add domain](https://media.docs.plane.so/sso/add-domain.webp#hero-tl)
31+
32+
3. Enter your domain (for example, `acme.com`) and click Add domain.
33+
4. In the **Verify your domain** modal that appears, copy the **TXT record value**.
34+
35+
![Verify domain](https://media.docs.plane.so/sso/verify-domain.webp#hero)
36+
:::tip
37+
Click **I'll do it later** if you need time to access your DNS. Your domain will appear with a *Pending* status. To resume verification later, click the **⋯** menu next to your domain and select **Verify**.
38+
:::
39+
40+
### Add the DNS record
41+
1. Sign in to your DNS provider.
42+
2. Create a new TXT record:
43+
- **Host/Name**: `@` (or leave blank for root domain).
44+
- **Value**: Paste the TXT record value from Plane.
45+
- **TTL**: Use default or 3600.
46+
3. Wait a few minutes for DNS propagation.
47+
4. Return to Plane and click **Verify domain**.
48+
49+
Once verified, the status changes to *Verified* and you can configure SSO.
50+
51+
:::tip
52+
DNS propagation times vary by provider. If verification fails immediately, wait a few more minutes and try again. You can check if the TXT record is live using `dig TXT yourdomain.com` or online DNS lookup tools.
53+
:::
54+
55+
## Configure SSO
56+
57+
Plane supports two authentication protocols. Choose the one that matches your identity provider.
58+
59+
### OIDC (OpenID Connect)
60+
61+
OIDC works best with modern cloud identity providers like Google Workspace, Auth0, Okta, and Keycloak.
62+
63+
#### Get Plane connection details
64+
65+
1. Navigate to **Workspace Settings → Identity**.
66+
2. Click **Configure** next to **Enable OIDC**.
67+
3. Click **Get setup details** and copy these values:
68+
- **Origin URL**
69+
- **Redirect URL**
70+
- **Logout URL**
71+
72+
You'll use these when configuring your IdP.
73+
74+
#### Register Plane in your identity provider
75+
76+
The exact steps vary by provider, but generally:
77+
78+
1. Sign in to your identity provider.
79+
2. Create a new **Web Application** or **OIDC Client**.
80+
3. Paste the **Redirect URL** from Plane into the redirect URI field.
81+
4. Configure the application:
82+
- Application type: **Web Application**.
83+
- Enable authorization code flow.
84+
- Request scopes: `openid`, `email`, `profile`.
85+
5. Save and note the **Client ID** and **Client Secret** your IdP generates.
86+
87+
#### Configure OIDC in Plane
88+
89+
![Configure OIDC](https://media.docs.plane.so/sso/configure-oidc.webp#hero)
90+
91+
1. Return to Plane and enter the following details from your identity provider:
92+
93+
| Field | Description |
94+
|-------|-------------|
95+
| **Client ID** | The application ID from your IdP |
96+
| **Client secret** | The secret key for authentication |
97+
| **Authorize URL** | The endpoint where users see the login screen |
98+
| **Token URL** | The endpoint Plane uses to exchange authorization codes for tokens |
99+
| **Users' info URL** | The endpoint that returns user profile information |
100+
| **Logout URL** | *(Optional)* Where users go after signing out |
101+
102+
2. Click **Save changes** to activate OIDC authentication.
103+
104+
### SAML 2.0
105+
106+
SAML works well with traditional enterprise identity providers like Okta, Azure AD, and on-premise Active Directory.
107+
108+
#### Get Plane connection details
109+
110+
1. Navigate to **Workspace Settings → Identity**.
111+
2. Click **Configure** next to **Enable SAML**.
112+
3. Click **Get setup details** and copy these values:
113+
- **Entity ID / Audience / Metadata information**
114+
- **SSO URL**
115+
- **SLO URL**
116+
117+
#### Create a SAML application in your IdP
118+
119+
1. Sign in to your identity provider.
120+
2. Create a new **SAML 2.0 Application**.
121+
3. Configure the service provider settings:
122+
- **Entity ID / Audience**: Paste the Entity ID from Plane.
123+
- **ACS URL / SSO URL**: Paste the SSO URL from Plane.
124+
- **SLO URL**: Paste the SLO URL from Plane.
125+
4. Configure attribute mapping to send the `email` attribute in the SAML assertion. Optionally map `firstName` and `lastName`.
126+
5. Save and copy your IdP's SAML configuration:
127+
- **SSO URL** (sign-in endpoint)
128+
- **Entity ID**
129+
- **X.509 Certificate**
130+
131+
#### Configure SAML in Plane
132+
133+
![Configure SAML](https://media.docs.plane.so/sso/configure-saml.webp#hero)
134+
135+
1. Return to Plane and enter the following details from your identity provider:
136+
137+
| Field | Description |
138+
|-------|-------------|
139+
| **Entity ID** | Your IdP's unique identifier |
140+
| **SSO URL** | The endpoint where Plane redirects users for authentication |
141+
| **Logout URL** | *(Optional)* Where users go after signing out |
142+
| **Certificate** | The X.509 certificate from your IdP |
143+
144+
2. Click **Configure and enable** to activate SAML authentication.
145+
146+
## How SSO works in Plane
147+
148+
Once SSO is enabled:
149+
150+
- When users visit your Plane workspace, they see the **Sign in with Single Sign-On** button.
151+
152+
![Sign in with SSO](https://media.docs.plane.so/sso/sign-in-with-sso.webp#hero)
153+
154+
- Clicking it redirects them to your identity provider.
155+
- After authentication, they're signed in to Plane automatically.
156+
- Their Plane account is created automatically on first sign-in if it doesn't exist.
157+
158+
159+

‎docs/core-concepts/projects/manage-project-members.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Users must be workspace members before you can add them to a project.
2121
![Project members and teamspaces](https://media.docs.plane.so/projects/project-members-teamspaces.webp#hero)
2222

2323
**If the user isn't in your workspace yet:**
24-
1. First, [invite them to the workspace](/core-concepts/workspaces/members#invite-a-member-to-your-workspace).
24+
1. First, [invite them to the workspace](/core-concepts/workspaces/members#invite-members-to-your-workspace).
2525
2. Once they accept the workspace invitation, proceed with adding them to the project.
2626

2727
**Add existing workspace members to your project:**
@@ -163,4 +163,7 @@ Users can become project members in two different ways, and understanding both h
163163

164164
**Teamspace-based membership** happens automatically when your project is linked to a [Teamspace](/core-concepts/workspaces/teamspaces). All members of that teamspace automatically receive `Member` access to your project, making it perfect for teams that collaborate across multiple projects.
165165

166-
Users can have both types of access simultaneously. When this happens, Plane automatically applies whichever role gives them higher permissions. For example, if someone is a `Guest` on your project but joins a linked teamspace, they're automatically upgraded to `Member` access. If they're already an `Admin`, they keep their `Admin` role.
166+
Users can have both types of access simultaneously. When this happens, Plane automatically applies whichever role gives them higher permissions. For example, if someone is a `Guest` on your project but joins a linked teamspace, they're automatically upgraded to `Member` access. If they're already an `Admin`, they keep their `Admin` role.
167+
168+
## See also
169+
- [Manage workspace members](/core-concepts/workspaces/members)

‎docs/core-concepts/workspaces/members.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,3 +129,6 @@ The member loses access to the workspace and all its projects immediately.
129129
:::warning
130130
Removing members doesn't change your seat count or billing. You must [remove seats](/workspaces-and-users/add-remove-seats#remove-unused-seats) separately.
131131
:::
132+
133+
## See also
134+
- [Manage project members](/core-concepts/projects/manage-project-members)

‎sidebars.ts‎

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -67,25 +67,11 @@ const sidebars: SidebarsConfig = {
6767
type: "category",
6868
label: "Authentication",
6969
items: [
70+
"authentication/sso",
7071
{
71-
type: 'link',
72-
label: 'Google OAuth',
73-
href: 'https://developers.plane.so/self-hosting/govern/google-oauth',
74-
},
75-
{
76-
type: 'link',
77-
label: 'GitHub OAuth',
78-
href: 'https://developers.plane.so/self-hosting/govern/github-oauth',
79-
},
80-
{
81-
type: 'link',
82-
label: 'SAML SSO',
83-
href: 'https://developers.plane.so/self-hosting/govern/saml-sso',
84-
},
85-
{
86-
type: 'link',
87-
label: 'OIDC SSO',
88-
href: 'https://developers.plane.so/self-hosting/govern/oidc-sso',
72+
type: 'link',
73+
label: 'Self-hosted authentication',
74+
href: 'https://developers.plane.so/self-hosting/govern/authentication',
8975
},
9076
],
9177
},

0 commit comments

Comments
 (0)