diff --git a/docs/authentication/sso.mdx b/docs/authentication/sso.mdx new file mode 100644 index 0000000..7e473f9 --- /dev/null +++ b/docs/authentication/sso.mdx @@ -0,0 +1,159 @@ +--- +title: Single sign-on (SSO) +sidebar_label: Single sign-on (SSO) +hide_title: true +description: Configure SAML or OIDC authentication to let your team sign in to Plane using corporate identity provider credentials. +--- + +import Tags from "@site/src/components/Tags"; + +
+

Single sign-on (SSO)

+ +
+ +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. + +## Verify your domain + +Before configuring SSO, you must verify ownership of your organization's email domain. This ensures only authorized administrators can configure authentication for that domain. + +:::caution +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. +::: + +### Add your domain + +1. Navigate to **Workspace Settings → Identity**. +2. Under **Domain management**, click **Add domain**. + + ![Add domain](https://media.docs.plane.so/sso/add-domain.webp#hero-tl) + +3. Enter your domain (for example, `acme.com`) and click Add domain. +4. In the **Verify your domain** modal that appears, copy the **TXT record value**. + + ![Verify domain](https://media.docs.plane.so/sso/verify-domain.webp#hero) + :::tip + 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**. + ::: + +### Add the DNS record +1. Sign in to your DNS provider. +2. Create a new TXT record: + - **Host/Name**: `@` (or leave blank for root domain). + - **Value**: Paste the TXT record value from Plane. + - **TTL**: Use default or 3600. +3. Wait a few minutes for DNS propagation. +4. Return to Plane and click **Verify domain**. + +Once verified, the status changes to *Verified* and you can configure SSO. + +:::tip +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. +::: + +## Configure SSO + +Plane supports two authentication protocols. Choose the one that matches your identity provider. + +### OIDC (OpenID Connect) + +OIDC works best with modern cloud identity providers like Google Workspace, Auth0, Okta, and Keycloak. + +#### Get Plane connection details + +1. Navigate to **Workspace Settings → Identity**. +2. Click **Configure** next to **Enable OIDC**. +3. Click **Get setup details** and copy these values: + - **Origin URL** + - **Redirect URL** + - **Logout URL** + + You'll use these when configuring your IdP. + +#### Register Plane in your identity provider + +The exact steps vary by provider, but generally: + +1. Sign in to your identity provider. +2. Create a new **Web Application** or **OIDC Client**. +3. Paste the **Redirect URL** from Plane into the redirect URI field. +4. Configure the application: + - Application type: **Web Application**. + - Enable authorization code flow. + - Request scopes: `openid`, `email`, `profile`. +5. Save and note the **Client ID** and **Client Secret** your IdP generates. + +#### Configure OIDC in Plane + + ![Configure OIDC](https://media.docs.plane.so/sso/configure-oidc.webp#hero) + +1. Return to Plane and enter the following details from your identity provider: + + | Field | Description | + |-------|-------------| + | **Client ID** | The application ID from your IdP | + | **Client secret** | The secret key for authentication | + | **Authorize URL** | The endpoint where users see the login screen | + | **Token URL** | The endpoint Plane uses to exchange authorization codes for tokens | + | **Users' info URL** | The endpoint that returns user profile information | + | **Logout URL** | *(Optional)* Where users go after signing out | + +2. Click **Save changes** to activate OIDC authentication. + +### SAML 2.0 + +SAML works well with traditional enterprise identity providers like Okta, Azure AD, and on-premise Active Directory. + +#### Get Plane connection details + +1. Navigate to **Workspace Settings → Identity**. +2. Click **Configure** next to **Enable SAML**. +3. Click **Get setup details** and copy these values: + - **Entity ID / Audience / Metadata information** + - **SSO URL** + - **SLO URL** + +#### Create a SAML application in your IdP + +1. Sign in to your identity provider. +2. Create a new **SAML 2.0 Application**. +3. Configure the service provider settings: + - **Entity ID / Audience**: Paste the Entity ID from Plane. + - **ACS URL / SSO URL**: Paste the SSO URL from Plane. + - **SLO URL**: Paste the SLO URL from Plane. +4. Configure attribute mapping to send the `email` attribute in the SAML assertion. Optionally map `firstName` and `lastName`. +5. Save and copy your IdP's SAML configuration: + - **SSO URL** (sign-in endpoint) + - **Entity ID** + - **X.509 Certificate** + +#### Configure SAML in Plane + + ![Configure SAML](https://media.docs.plane.so/sso/configure-saml.webp#hero) + +1. Return to Plane and enter the following details from your identity provider: + + | Field | Description | + |-------|-------------| + | **Entity ID** | Your IdP's unique identifier | + | **SSO URL** | The endpoint where Plane redirects users for authentication | + | **Logout URL** | *(Optional)* Where users go after signing out | + | **Certificate** | The X.509 certificate from your IdP | + +2. Click **Configure and enable** to activate SAML authentication. + +## How SSO works in Plane + +Once SSO is enabled: + + - When users visit your Plane workspace, they see the **Sign in with Single Sign-On** button. + + ![Sign in with SSO](https://media.docs.plane.so/sso/sign-in-with-sso.webp#hero) + + - Clicking it redirects them to your identity provider. + - After authentication, they're signed in to Plane automatically. + - Their Plane account is created automatically on first sign-in if it doesn't exist. + + + diff --git a/docs/core-concepts/projects/manage-project-members.mdx b/docs/core-concepts/projects/manage-project-members.mdx index 438e4f9..3607162 100644 --- a/docs/core-concepts/projects/manage-project-members.mdx +++ b/docs/core-concepts/projects/manage-project-members.mdx @@ -21,7 +21,7 @@ Users must be workspace members before you can add them to a project. ![Project members and teamspaces](https://media.docs.plane.so/projects/project-members-teamspaces.webp#hero) **If the user isn't in your workspace yet:** -1. First, [invite them to the workspace](/core-concepts/workspaces/members#invite-a-member-to-your-workspace). +1. First, [invite them to the workspace](/core-concepts/workspaces/members#invite-members-to-your-workspace). 2. Once they accept the workspace invitation, proceed with adding them to the project. **Add existing workspace members to your project:** @@ -163,4 +163,7 @@ Users can become project members in two different ways, and understanding both h **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. -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. \ No newline at end of file +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. + +## See also +- [Manage workspace members](/core-concepts/workspaces/members) \ No newline at end of file diff --git a/docs/core-concepts/workspaces/members.mdx b/docs/core-concepts/workspaces/members.mdx index ceddc60..d50d707 100644 --- a/docs/core-concepts/workspaces/members.mdx +++ b/docs/core-concepts/workspaces/members.mdx @@ -129,3 +129,6 @@ The member loses access to the workspace and all its projects immediately. :::warning Removing members doesn't change your seat count or billing. You must [remove seats](/workspaces-and-users/add-remove-seats#remove-unused-seats) separately. ::: + +## See also +- [Manage project members](/core-concepts/projects/manage-project-members) \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index ff30f9a..ade9696 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -67,25 +67,11 @@ const sidebars: SidebarsConfig = { type: "category", label: "Authentication", items: [ + "authentication/sso", { - type: 'link', - label: 'Google OAuth', - href: 'https://developers.plane.so/self-hosting/govern/google-oauth', - }, - { - type: 'link', - label: 'GitHub OAuth', - href: 'https://developers.plane.so/self-hosting/govern/github-oauth', - }, - { - type: 'link', - label: 'SAML SSO', - href: 'https://developers.plane.so/self-hosting/govern/saml-sso', - }, - { - type: 'link', - label: 'OIDC SSO', - href: 'https://developers.plane.so/self-hosting/govern/oidc-sso', + type: 'link', + label: 'Self-hosted authentication', + href: 'https://developers.plane.so/self-hosting/govern/authentication', }, ], },