mirror of
https://github.com/formbricks/formbricks.git
synced 2026-04-23 05:58:53 -05:00
docs: clarified Roles docs + added 2FA (#6507)
This commit is contained in:
Johannes
+11
-1
@@ -163,7 +163,17 @@
|
||||
"xm-and-surveys/core-features/integrations/webhooks"
|
||||
]
|
||||
},
|
||||
"xm-and-surveys/core-features/user-management",
|
||||
{
|
||||
"group": "User Management",
|
||||
"icon": "user",
|
||||
"pages": [
|
||||
"xm-and-surveys/core-features/user-management",
|
||||
"xm-and-surveys/core-features/user-management/organizations-and-roles",
|
||||
"xm-and-surveys/core-features/user-management/teams-and-roles",
|
||||
"xm-and-surveys/core-features/user-management/invite-members",
|
||||
"xm-and-surveys/core-features/user-management/two-factor-auth"
|
||||
]
|
||||
},
|
||||
"xm-and-surveys/core-features/styling-theme",
|
||||
"xm-and-surveys/core-features/email-customization",
|
||||
"xm-and-surveys/core-features/test-environment"
|
||||
|
||||
@@ -1,157 +1,43 @@
|
||||
---
|
||||
title: "User Management"
|
||||
description: "Assign different roles to organization members to grant them specific rights like creating surveys, viewing responses, or managing organization members."
|
||||
title: "User Management Overview"
|
||||
sidebarTitle: "Key Concepts"
|
||||
description: "Manage organization members, roles, teams, and security settings to control access and collaboration in your Formbricks organization."
|
||||
icon: "user"
|
||||
---
|
||||
|
||||
# Organization Access Roles
|
||||
Formbricks provides comprehensive user management capabilities to help you control access, organize teams, and secure your organization. This section covers everything you need to know about managing users, roles, and permissions.
|
||||
|
||||
Learn about the different organization-level and team-level roles and how they affect permissions in Formbricks.
|
||||
## Key concepts
|
||||
|
||||
## Memberships
|
||||
Formbricks uses a flexible permission system with multiple layers:
|
||||
|
||||
Permissions in Formbricks are broadly handled using organization-level roles, which apply to all teams and projects in the organization. Users on a self-hosting and Enterprise plan, have access to team-level roles, which enable more granular permissions.
|
||||
- **Organization roles** - Control access across the entire organization
|
||||
- **Team roles** - Provide granular permissions within specific teams
|
||||
- **Project permissions** - Fine-tune access to individual projects
|
||||
- **Security features** - Protect accounts with two-factor authentication
|
||||
|
||||
<Note>
|
||||
Access Roles is a feature of the [Enterprise Edition](/self-hosting/advanced/license). In the **Community Edition** and on the **Free**
|
||||
and **Startup** plan in the Cloud you can invite unlimited organization members as `Owner`.
|
||||
Advanced user management features are part of the [Enterprise Edition](/self-hosting/advanced/license). The Community Edition and Free/Startup Cloud plans support unlimited organization members with Owner permissions.
|
||||
</Note>
|
||||
|
||||
Here are the different access permissions, ranked from highest to lowest access
|
||||
## Get started
|
||||
|
||||
1. Owner
|
||||
2. Manager
|
||||
3. Billing
|
||||
4. Member
|
||||
<CardGroup cols={2}>
|
||||
|
||||
### Role Permissions and Privilege Escalation Prevention
|
||||
<Card title="Organizations and roles" icon="building" href="/xm-and-surveys/core-features/user-management/organizations-and-roles">
|
||||
Learn about organization-level roles and how they control access to teams, projects, and data across your Formbricks organization.
|
||||
</Card>
|
||||
|
||||
To prevent privilege escalation, the following rules apply:
|
||||
<Card title="Teams and roles" icon="users" href="/xm-and-surveys/core-features/user-management/teams-and-roles">
|
||||
Understand team-level roles and project permissions that enable granular access control within teams and projects.
|
||||
</Card>
|
||||
|
||||
- **Owners** can:
|
||||
<Card title="Invite members" icon="user-plus" href="/xm-and-surveys/core-features/user-management/invite-members">
|
||||
Learn how to invite new members to your organization individually or in bulk, and manage invitation workflows.
|
||||
</Card>
|
||||
|
||||
- Invite users as owners, managers, or members
|
||||
- Assign roles up to owner
|
||||
<Card title="Two-factor authentication" icon="shield-check" href="/xm-and-surveys/core-features/user-management/two-factor-auth">
|
||||
Secure your account with an additional layer of protection using time-based codes from authenticator apps and backup codes.
|
||||
</Card>
|
||||
|
||||
- **Managers** can:
|
||||
|
||||
- Invite users only as members
|
||||
- Assign roles up to member only, not manager or owner
|
||||
|
||||
- **Members** cannot:
|
||||
- Invite users
|
||||
- Assign roles
|
||||
|
||||
### Organisational level
|
||||
|
||||
All users and their organization-level roles are listed in **Organization Settings > General**. Users can hold any of the following org-level roles:
|
||||
|
||||
- **Owner** have full access to the organization, its data, and settings. Org Owners can perform Team Admin actions without needing to join the team.
|
||||
- **Manager** have full management access to all teams and projects. They can also manage the organization's membership (but can only invite or assign users as members). Org Managers can perform Team Admin actions without needing to join the team. They cannot change other organization settings.
|
||||
- **Billing** users can manage payment and compliance details in the organization.
|
||||
- **Member** can view most data in the organization and act in the projects they are members of. They cannot join projects on their own and need to be assigned.
|
||||
|
||||
### Permissions at project level
|
||||
|
||||
- **Read**: Read access to all resources (except settings) in the project.
|
||||
- **Read & write**: Read & write access to all resources (except settings) in the project.
|
||||
- **Manage**: Read & write access to all resources including settings in the project.
|
||||
|
||||
### Team-level Roles
|
||||
|
||||
- **Team Contributors** can view and act on surveys and responses.
|
||||
- **Team Admins** have additional permissions to manage their team's membership and projects. These permissions are granted at the team-level, and don't apply to teams where they're not a Team Admin.
|
||||
|
||||
For more information on user roles & permissions, see below:
|
||||
|
||||
| | Owner | Manager | Billing | Member |
|
||||
| -------------------------------- | ----- | ------- | ------- | ------ |
|
||||
| **Organization** | | | | |
|
||||
| Update organization | ✅ | ❌ | ❌ | ❌ |
|
||||
| Delete organization | ✅ | ❌ | ❌ | ❌ |
|
||||
| Add new member | ✅ | ✅ | ❌ | ❌ |
|
||||
| Delete member | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update member access | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update billing | ✅ | ✅ | ✅ | ❌ |
|
||||
| **Project** | | | | |
|
||||
| Create project | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update project name | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update project recontact options | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update look & feel | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update survey languages | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Delete project | ✅ | ✅ | ❌ | ❌ |
|
||||
| **Surveys** | | | | |
|
||||
| Create new survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Edit survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| View survey results | ✅ | ✅ | ❌ | ✅ |
|
||||
| **Response** | | | | |
|
||||
| Delete response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Add tags on response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Edit tags on response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Download survey responses (CSV) | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **Actions** | | | | |
|
||||
| Create action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Update action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **API keys** | | | | |
|
||||
| Create API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Delete API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| **Tags** | | | | |
|
||||
| Create tags | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Update tags | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete tags | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| **Contacts** | | | | |
|
||||
| Delete contact | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **Integrations** | | | | |
|
||||
| Manage integrations | ✅ | ✅ | ❌ | ✅\* |
|
||||
|
||||
\* - for the read & write permissions team members
|
||||
|
||||
\*\* - for the manage permissions team members
|
||||
|
||||
## Inviting organization members
|
||||
|
||||
There are two ways to invite organization members: One by one or in bulk.
|
||||
|
||||
### Invite organization members one by one
|
||||
|
||||
1. Go to the `Organization Settings` page via the menu in the lower right corner:
|
||||
|
||||
|
||||
|
||||
2. Click on the `Add member` button:
|
||||
|
||||
|
||||
|
||||
3. In the modal, add the Name, Email and Role of the organization member you want to invite:
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Access Roles is a feature of the **Enterprise Edition**. In the **Community Edition** and on the **Free**
|
||||
and **Startup** plan in the Cloud you can invite unlimited organization members as `Owners`.
|
||||
</Note>
|
||||
|
||||
Formbricks sends an email to the organization member with an invitation link. The organization member can accept the invitation or create a new account by clicking on the link.
|
||||
|
||||
### Invite organization members in bulk
|
||||
|
||||
1. Go to the `Organization Settings` page via the menu in the lower right corner:
|
||||
|
||||
|
||||
|
||||
2. Click on the `Add member` button:
|
||||
|
||||
|
||||
|
||||
3. In the modal, switch to `Bulk Invite`. You can download an example .CSV file to fill in the Name, Email and Role of the organization members you want to invite:
|
||||
|
||||
|
||||
|
||||
4. Upload the filled .CSV file and invite the organization members in bulk ✅
|
||||
|
||||
Formbricks sends an email to each organization member in the CSV. The member can accept the invitation or create a new account by clicking on the link.
|
||||
|
||||
---
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: "Invite members"
|
||||
description: "Learn how to invite new members to your organization individually or in bulk, and manage invitation workflows."
|
||||
icon: "user-plus"
|
||||
---
|
||||
|
||||
Add new members to your Formbricks organization to collaborate on surveys and manage projects together. You can invite members individually or in bulk using CSV uploads.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To invite members, you need:
|
||||
- **Owner** or **Manager** role in the organization
|
||||
- Valid email addresses for the people you want to invite
|
||||
|
||||
|
||||
## Individual invitations
|
||||
|
||||
Use this method when inviting a few people or when you need to carefully control each invitation.
|
||||
|
||||
### Steps to invite individual members
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Organization Settings > Access Control">
|
||||
Go to the organization settings page and click on the "Access Control" tab.
|
||||
</Step>
|
||||
|
||||
<Step title="Start the invitation process">
|
||||
Click on the `Add member` button:
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Fill in member details">
|
||||
In the modal, add the Name, Email and Role of the organization member you want to invite:
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Send the invitation">
|
||||
Click the invite button to send the invitation email.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### What happens next
|
||||
|
||||
1. Formbricks sends an email to the organization member with an invitation link
|
||||
2. The organization member can accept the invitation or create a new account by clicking on the link
|
||||
3. Once accepted, they'll have access based on the role you assigned
|
||||
|
||||
## Bulk invitations
|
||||
|
||||
Use bulk invitations when you need to invite many people at once, such as when onboarding an entire team or department.
|
||||
|
||||
### Steps to invite members in bulk
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Organization Settings">
|
||||
Go to the organization settings page and click on the "Access Control" tab.
|
||||
</Step>
|
||||
|
||||
<Step title="Start the bulk invitation process">
|
||||
Click on the `Add member` button:
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Switch to bulk invite">
|
||||
In the modal, switch to `Bulk Invite`. You can download an example .CSV file to fill in the Name, Email and Role of the organization members you want to invite:
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Prepare your CSV file">
|
||||
The CSV file should include three columns:
|
||||
- **Name**: Full name of the person
|
||||
- **Email**: Valid email address
|
||||
- **Role**: One of the available organization roles (Owner, Manager, Billing, Member)
|
||||
</Step>
|
||||
|
||||
<Step title="Upload and send invitations">
|
||||
Upload the filled .CSV file and invite the organization members in bulk ✅
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### What happens next
|
||||
|
||||
- Formbricks sends an email to each organization member in the CSV
|
||||
- Each member can accept the invitation or create a new account by clicking on the link
|
||||
- All invitations are processed simultaneously
|
||||
|
||||
## Managing invitations
|
||||
|
||||
### Pending invitations
|
||||
|
||||
- View pending invitations in the Organization Settings > Members section
|
||||
- Resend invitations if needed
|
||||
- Cancel pending invitations before they're accepted
|
||||
|
||||
### Invitation status
|
||||
|
||||
Monitor the status of your invitations:
|
||||
- **Pending**: Invitation sent but not yet accepted
|
||||
- **Accepted**: User has joined the organization
|
||||
- **Expired**: Invitation has expired and needs to be resent
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
title: "Organizations and roles"
|
||||
description: "Understand organization-level roles and how they control access to teams, projects, and data across your Formbricks organization."
|
||||
icon: "building"
|
||||
---
|
||||
|
||||
Organization-level roles apply to all teams and projects within your Formbricks organization. These roles provide broad permissions that determine what users can do across the entire organization.
|
||||
|
||||
<Note>
|
||||
Access Roles is a feature of the [Enterprise Edition](/self-hosting/advanced/license). In the **Community Edition** and on the **Free**
|
||||
and **Startup** plan in the Cloud you can invite unlimited organization members as `Owner`.
|
||||
</Note>
|
||||
|
||||
## Role hierarchy
|
||||
|
||||
Here are the different access permissions, ranked from highest to lowest access:
|
||||
|
||||
1. **Owner** - Full organizational control
|
||||
2. **Manager** - Management access with some restrictions
|
||||
3. **Billing** - Billing and payment management only
|
||||
4. **Member** - Basic access to assigned projects
|
||||
|
||||
### Role Permissions and Privilege Escalation Prevention
|
||||
|
||||
To prevent privilege escalation, the following rules apply:
|
||||
|
||||
- **Owners** can:
|
||||
- Invite users as owners, managers, or members
|
||||
- Assign roles up to owner level
|
||||
|
||||
- **Managers** can:
|
||||
- Invite users only as members
|
||||
- Assign roles up to member only, not manager or owner
|
||||
|
||||
- **Members** cannot:
|
||||
- Invite users
|
||||
- Assign roles
|
||||
|
||||
## Organization-level roles
|
||||
|
||||
All users and their organization-level roles are listed in **Organization Settings > Access Control**. Users can hold any of the following org-level roles:
|
||||
|
||||
### Owner
|
||||
- Have full access to the organization, its data, and settings
|
||||
- Can perform Team Admin actions without needing to join the team
|
||||
- Can manage all aspects of the organization including billing, integrations, and member management
|
||||
|
||||
### Manager
|
||||
- Have full management access to all teams and projects
|
||||
- Can manage the organization's membership (but can only invite or assign users as members)
|
||||
- Can perform Team Admin actions without needing to join the team
|
||||
- Cannot change other organization settings like billing or delete the organization
|
||||
|
||||
### Billing
|
||||
- Can manage payment and compliance details in the organization
|
||||
- Have access to billing settings and subscription management
|
||||
- Cannot access other organizational data or settings
|
||||
|
||||
### Member
|
||||
- Can view most data in the organization and act in the projects they are members of
|
||||
- Cannot create or join projects on their own and need to be assigned by owners or managers
|
||||
- Have limited permissions that depend on their project-level access
|
||||
|
||||
## Detailed permissions matrix
|
||||
|
||||
| | Owner | Manager | Billing | Member |
|
||||
| -------------------------------- | ----- | ------- | ------- | ------ |
|
||||
| **Organization** | | | | |
|
||||
| Update organization | ✅ | ❌ | ❌ | ❌ |
|
||||
| Delete organization | ✅ | ❌ | ❌ | ❌ |
|
||||
| Add new member | ✅ | ✅ | ❌ | ❌ |
|
||||
| Delete member | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update member access | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update billing | ✅ | ✅ | ✅ | ❌ |
|
||||
| **Project** | | | | |
|
||||
| Create project | ✅ | ✅ | ❌ | ❌ |
|
||||
| Update project name | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update project recontact options | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update look & feel | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update survey languages | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Delete project | ✅ | ✅ | ❌ | ❌ |
|
||||
| **Surveys** | | | | |
|
||||
| Create new survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Edit survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete survey | ✅ | ✅ | ❌ | ✅\* |
|
||||
| View survey results | ✅ | ✅ | ❌ | ✅ |
|
||||
| **Response** | | | | |
|
||||
| Delete response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Add tags on response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Edit tags on response | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Download survey responses (CSV) | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **Actions** | | | | |
|
||||
| Create action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Update action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete action | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **API keys** | | | | |
|
||||
| Create API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Update API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| Delete API key | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| **Tags** | | | | |
|
||||
| Create tags | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Update tags | ✅ | ✅ | ❌ | ✅\* |
|
||||
| Delete tags | ✅ | ✅ | ❌ | ✅\*\* |
|
||||
| **Contacts** | | | | |
|
||||
| Delete contact | ✅ | ✅ | ❌ | ✅\* |
|
||||
| **Integrations** | | | | |
|
||||
| Manage integrations | ✅ | ✅ | ❌ | ✅\* |
|
||||
|
||||
\* - for the read & write permissions team members
|
||||
|
||||
\*\* - for the manage permissions team members
|
||||
|
||||
## Best practices
|
||||
|
||||
- **Principle of least privilege**: Assign users the minimum role necessary for their responsibilities
|
||||
- **Regular audits**: Periodically review organization members and their roles
|
||||
- **Owner role**: Limit the number of owners to reduce security risk
|
||||
- **Manager role**: Use for team leads who need to manage projects but not organizational settings
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "Teams and roles"
|
||||
description: "Learn about team-level roles and project permissions that enable granular access control within teams and projects."
|
||||
icon: "users"
|
||||
---
|
||||
|
||||
Team-level roles provide more granular permissions within specific teams and projects. These roles work alongside organization-level roles to create a flexible permission system.
|
||||
|
||||
<Note>
|
||||
Team-level roles are a feature of the [Enterprise Edition](/self-hosting/advanced/license). In the Community Edition, all members are Organisation-level "Owners".
|
||||
</Note>
|
||||
|
||||
## Understanding the role hierarchy
|
||||
|
||||
Formbricks uses a two-tier permission system:
|
||||
|
||||
1. **Organization-level roles** - Apply across all teams and projects
|
||||
2. **Team-level roles** - Apply within specific teams and projects
|
||||
|
||||
### How roles interact
|
||||
|
||||
- Organization-level roles (Owner, Manager) can override team-level restrictions
|
||||
- Team-level roles provide granular control for specific teams
|
||||
- Project permissions further refine what users can do within individual projects
|
||||
|
||||
## Team-level roles
|
||||
|
||||
### Team Admins
|
||||
- Have additional permissions to manage their team's membership and projects
|
||||
- Can add or remove team members
|
||||
- Can create and manage projects within their team
|
||||
- Can assign project-level permissions to team members
|
||||
- These permissions are granted at the team-level and don't apply to teams where they're not a Team Admin
|
||||
|
||||
### Team Contributors
|
||||
- Can view and act on surveys and responses within their assigned projects
|
||||
- Cannot manage team membership or create new projects
|
||||
- Permissions depend on their project-level access (Read, Read & Write, or Manage)
|
||||
|
||||
## Project-level permissions
|
||||
|
||||
Within each project, team members can have one of three permission levels:
|
||||
|
||||
### Read
|
||||
- Read access to all resources (except settings) in the project
|
||||
- Can view surveys, responses, and analytics
|
||||
- Cannot create, edit, or delete surveys
|
||||
- Cannot modify project settings
|
||||
|
||||
### Read & Write
|
||||
- Read & write access to all resources (except settings) in the project
|
||||
- Can create, edit, and delete surveys
|
||||
- Can manage responses and tags
|
||||
- Can download survey data
|
||||
- Cannot modify project settings or manage integrations
|
||||
|
||||
### Manage
|
||||
- Read & write access to all resources including settings in the project
|
||||
- Full project control including settings
|
||||
- Can manage API keys and integrations
|
||||
- Can configure project-level settings like recontact options and styling
|
||||
- Can manage project tags and actions
|
||||
|
||||
## Permission examples
|
||||
|
||||
### Scenario 1: Marketing Team Member
|
||||
- **Organization role**: Member
|
||||
- **Team role**: Team Contributor
|
||||
- **Project permission**: Read & Write
|
||||
- **Can do**: Create and edit surveys, view responses, download data
|
||||
- **Cannot do**: Change project settings, manage team membership
|
||||
|
||||
### Scenario 2: Team Lead
|
||||
- **Organization role**: Member
|
||||
- **Team role**: Team Admin
|
||||
- **Project permission**: Manage
|
||||
- **Can do**: Everything within their team including managing members and project settings
|
||||
- **Cannot do**: Access other teams, change organization settings
|
||||
|
||||
### Scenario 3: Department Manager
|
||||
- **Organization role**: Manager
|
||||
- **Team role**: N/A (org role overrides)
|
||||
- **Project permission**: N/A (org role provides access)
|
||||
- **Can do**: Access all teams and projects, manage organization membership
|
||||
- **Cannot do**: Change organization-level settings like billing
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Two-factor authentication"
|
||||
description: "Secure your account with an additional layer of protection using time-based codes from authenticator apps and backup codes."
|
||||
icon: "shield-check"
|
||||
---
|
||||
|
||||
Two-factor authentication (2FA) adds an extra layer of security to user accounts by requiring a second form of verification in addition to the password. This significantly reduces the risk of unauthorized access even if passwords are compromised.
|
||||
|
||||
<Note>
|
||||
Two-factor authentication is part of the [Enterprise Edition](/self-hosting/advanced/license).
|
||||
</Note>
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To use two-factor authentication, users must:
|
||||
|
||||
- Have an account with email-based authentication (third-party login providers like Google SSO are not compatible with 2FA)
|
||||
- Have a TOTP-compatible authenticator app installed on their device (such as Google Authenticator, Authy, or 1Password)
|
||||
|
||||
## Setting up Two-factor authentication
|
||||
|
||||
Users can enable 2FA from their profile settings:
|
||||
|
||||
1. Navigate to **Profile Settings** via the menu in the lower right corner
|
||||
2. In the **Security** section, toggle the **Two-factor authentication** switch
|
||||
3. Follow the setup wizard:
|
||||
|
||||
**Step 1: Confirm Password**
|
||||
- Enter your current password to verify your identity
|
||||
|
||||
**Step 2: Scan QR Code**
|
||||
- Use your authenticator app to scan the displayed QR code
|
||||
- Alternatively, manually enter the provided secret key into your authenticator app
|
||||
|
||||
**Step 3: Verify Setup**
|
||||
- Enter the 6-digit code from your authenticator app to confirm the setup
|
||||
|
||||
**Step 4: Save Backup Codes**
|
||||
- **Important**: Save the 10 backup codes in a secure location
|
||||
- These codes can be used to access your account if you lose access to your authenticator device
|
||||
- Each backup code can only be used once
|
||||
|
||||
<Warning>
|
||||
Store your backup codes in a secure location. If you lose access to both your authenticator device and backup codes, you will need administrator assistance to regain access to your account.
|
||||
</Warning>
|
||||
|
||||
## Logging in with Two-factor authentication
|
||||
|
||||
Once 2FA is enabled, the login process requires an additional step:
|
||||
|
||||
1. Enter your email and password as usual
|
||||
2. When prompted, enter either:
|
||||
- A 6-digit code from your authenticator app, or
|
||||
- One of your backup codes (use format: xxxxx-xxxxx or just the 10-character code)
|
||||
|
||||
## Managing Two-factor authentication
|
||||
|
||||
### Disabling 2FA
|
||||
|
||||
To disable two-factor authentication:
|
||||
|
||||
1. Go to **Profile Settings > Security**
|
||||
2. Toggle off the **Two-factor authentication** switch
|
||||
3. Confirm by entering either:
|
||||
- Your password and a TOTP code from your authenticator app, or
|
||||
- Your password and a backup code
|
||||
|
||||
<Info>
|
||||
When 2FA is disabled, all associated backup codes are permanently deleted for security reasons.
|
||||
</Info>
|
||||
|
||||
### Re-enabling 2FA
|
||||
|
||||
If you need to set up 2FA again (for example, after getting a new device):
|
||||
|
||||
1. Follow the same setup process described above
|
||||
2. New backup codes will be generated
|
||||
3. Old backup codes (if any existed) will be invalidated
|
||||
Reference in New Issue
Block a user